gonumberio

README

Go array reader

Generic library for reading 1D, 2D and 3D slices from a text file.

Example

Suppose that a user wants to read the following text file as a 3D slice of integers.

-1 2 3
0 0 0

-1 -2 -3
-4    -5 -6
7   8 9

0

100 10000
-20132 -2121
-3000           10300 12001 14001
9091        8091 17003
90123

There are 2 approaches.

• User specifies the number of dimensions by specifying the function — Read1D, Read2D or Read3D
• User specifies the whole type as a generic parameter to the function Read and lets the library use reflection to determine the number of dimensions

package main

import (
	"fmt"
	"os"

	nio "github.com/Matej-Chmel/go-number-io"
)

func main() {
	file, err := os.Open("data/int/3D.txt")

	if err != nil {
		fmt.Print(err)
		return
	}

	// data, err := nio.Read3D[int32](file) // Concrete approach
	data, err := nio.Read[[][][]int32](file) // Dynamic approach

	if err != nil {
		fmt.Print(err)
		return
	}

	fmt.Print(data)
}

Output

[[[-1 2 3] [0 0 0]] [[-1 -2 -3] [-4 -5 -6] [7 8 9]] [[0]] [[100 10000] [-20132 -2121] [-3000 10300 12001 14001] [9091 8091 17003] [90123]]]

Custom conversion

The library provides default conversions for bool, byte, float, int and uint types and their bit specific versions. For other types, user has to specify a conversion function to a reading function with Custom suffix.

Conversion function has the following requirements:

• Input is *nio.ByteReader
• Output is (T, uint, error) where T is element of slice
• uint in output represents flags, there 2 important ones:
  • HasNewlineFlag — Newline was found
  • HasValueFlag — An element was found

Input

Suppose that a user wants to read a 2D slice of a custom type that represents a pair of integers. The format is the following.

{1, 1} {2, 2} {3, 3}
{4, 4} {5, 5} {6, 6}
{7, 7} {8, 8} {9, 9}

Code

User specifies a custom conversion function convertIntPair and uses methods of ByteReader — LookAheadFor and SkipByte to process the curly braces.

package main

import (
	"fmt"
	"os"

	nio "github.com/Matej-Chmel/go-number-io"
)

type intPair struct {
	a int
	b int
}

func convertIntPair(r *nio.ByteReader) (intPair, uint, error) {
	if err := r.SkipByte('{'); err != nil {
		return intPair{}, 0, err
	}

	firstInt, err := getIntHelper(r)

	if err != nil {
		return intPair{}, 0, err
	}

	if err := r.SkipByte(','); err != nil {
		return intPair{}, 0, err
	}

	secondInt, err := getIntHelper(r)

	if err != nil {
		return intPair{}, 0, err
	}

	if err := r.SkipByte('}'); err != nil {
		return intPair{}, 0, err
	}

	flags := nio.HasValueFlag
	isNewLine, err := r.LookAheadFor('{')

	if isNewLine {
		flags |= nio.HasNewlineFlag
	}

	return intPair{a: firstInt, b: secondInt}, flags, err
}

func getIntHelper(r *nio.ByteReader) (int, error) {
	data, _, err := nio.ConvertSigned[int](r)

	if err != nil {
		return 0, err
	}

	return data, nil
}

func main() {
	file, err := os.Open("data/intPair/2D.txt")

	if err != nil {
		fmt.Print(err)
		return
	}

	data, err := nio.Read2DCustom(file, nio.DefaultChunkSize, convertIntPair)

	if err != nil {
		fmt.Print(err)
		return
	}

	fmt.Print(data)
}

Output

[[{1 1} {2 2} {3 3}] [{4 4} {5 5} {6 6}] [{7 7} {8 8} {9 9}]]

Documentation

Index

• Constants
• func ConvertBool(r *ByteReader) (bool, uint, error)
• func ConvertByte(r *ByteReader) (byte, uint, error)
• func ConvertFloat[T constraints.Float](r *ByteReader) (T, uint, error)
• func ConvertSigned[T constraints.Signed](r *ByteReader) (T, uint, error)
• func ConvertUnsigned[T constraints.Unsigned](r *ByteReader) (T, uint, error)
• func GetConversion[T any]() func(r *ByteReader) (T, uint, error)
• func Read[T any](reader io.Reader) (T, error)
• func Read0D[T any](r io.Reader) (T, error)
• func Read0DCustom[T any](r io.Reader, chunkSize int, conv func(*ByteReader) (T, uint, error)) (T, error)
• func Read1D[T any](r io.Reader) ([]T, error)
• func Read1DCustom[T any](r io.Reader, chunkSize int, conv func(*ByteReader) (T, uint, error)) ([]T, error)
• func Read2D[T any](r io.Reader) ([][]T, error)
• func Read2DCustom[T any](r io.Reader, chunkSize int, conv func(*ByteReader) (T, uint, error)) ([][]T, error)
• func Read3D[T any](r io.Reader) ([][][]T, error)
• func Read3DCustom[T any](r io.Reader, chunkSize int, conv func(*ByteReader) (T, uint, error)) ([][][]T, error)
• func ReadCustom[T any](reader io.Reader, chunkSize int) (T, error)
• type ByteReader

Constants

const (
	// Newline found when reading current element
	HasNewlineFlag = ite.HasNewline
	// Current element has at least one digit
	HasValueFlag = ite.HasValue
)

const (
	// Default buffer size for ByteReader
	DefaultChunkSize int = 32768
)

Functions

func ConvertBool

func ConvertBool(r *ByteReader) (bool, uint, error)

Conversion function for type bool

func ConvertByte

func ConvertByte(r *ByteReader) (byte, uint, error)

Conversion function for type byte

func ConvertFloat

func ConvertFloat[T constraints.Float](r *ByteReader) (T, uint, error)

Conversion function for type float

func ConvertSigned

func ConvertSigned[T constraints.Signed](r *ByteReader) (T, uint, error)

Conversion function for floats and integers

func ConvertUnsigned

func ConvertUnsigned[T constraints.Unsigned](r *ByteReader) (T, uint, error)

Conversion function for unsigned integers

func GetConversion

func GetConversion[T any]() func(r *ByteReader) (T, uint, error)

Returns conversion function for generic type T

func Read

func Read[T any](reader io.Reader) (T, error)

Reads T from reader. T can be a single element or 1D, 2D or 3D slice.

func Read0D

func Read0D[T any](r io.Reader) (T, error)

Read one element of type T from a Reader

func Read0DCustom

func Read0DCustom[T any](
	r io.Reader, chunkSize int, conv func(*ByteReader) (T, uint, error)) (T, error)

Read one element of type T from a Reader with options

func Read1D

func Read1D[T any](r io.Reader) ([]T, error)

Read a 1D slice of type T from a Reader

func Read1DCustom

func Read1DCustom[T any](
	r io.Reader, chunkSize int, conv func(*ByteReader) (T, uint, error)) ([]T, error)

Read a 1D slice of type T from a Reader with options

func Read2D

func Read2D[T any](r io.Reader) ([][]T, error)

Read a 2D slice of type T from a Reader

func Read2DCustom

func Read2DCustom[T any](
	r io.Reader, chunkSize int, conv func(*ByteReader) (T, uint, error)) ([][]T, error)

Read a 2D slice of type T from a Reader with options

func Read3D

func Read3D[T any](r io.Reader) ([][][]T, error)

Read a 3D slice of type T from a Reader

func Read3DCustom

func Read3DCustom[T any](
	r io.Reader, chunkSize int, conv func(*ByteReader) (T, uint, error)) ([][][]T, error)

Read a 3D slice of type T from a Reader with options

func ReadCustom

func ReadCustom[T any](
	reader io.Reader, chunkSize int) (T, error)

Reads T from reader with options. T can be a single element or 1D, 2D or 3D slice.

Types

type ByteReader

type ByteReader = ite.ByteReader

Exported ByteReader