iter

Documentation

Overview

Package iter provides iterators

SPDX-License-Identifier: Apache-2.0

Index

• Variables
• func CSVIterGen(src goio.Reader) func() ([]string, error)
• func ConcatIterGen[T any](src []Iter[T]) func() (T, error)
• func FibonnaciIterGen() func() (int, error)
• func InfiniteIterGen[T any](iterative func(T) T, initialValues ...T) func() (T, error)
• func MapIterGen[K comparable, V any](m map[K]V) func() (tuple.Two[K, V], error)
• func Maybe[T any](it Iter[T]) union.Result[T]
• func NoValueIterGen[T any]() func() (T, error)
• func ReaderAsLinesIterGen(src goio.Reader) func() (string, error)
• func ReaderAsRunesIterGen(src goio.Reader) func() (rune, error)
• func ReaderIterGen(src goio.Reader) func() (byte, error)
• func SingleValueIterGen[T any](value T) func() (T, error)
• func SliceIterGen[T any](slc []T) func() (T, error)
• func StringAsLinesIterGen(src string) func() (string, error)
• func StringAsRunesIterGen(src string) func() (rune, error)
• type Iter
  • func Concat[T any](iters ...Iter[T]) Iter[T]
  • func Of[T any](items ...T) Iter[T]
  • func OfCSV(src goio.Reader) Iter[[]string]
  • func OfEmpty[T any]() Iter[T]
  • func OfIter[T any](iterFn func() (T, error)) Iter[T]
  • func OfMap[K comparable, V any](items map[K]V) Iter[tuple.Two[K, V]]
  • func OfOne[T any](item T) Iter[T]
  • func OfReader(src goio.Reader) Iter[byte]
  • func OfReaderAsLines(src goio.Reader) Iter[string]
  • func OfReaderAsRunes(src goio.Reader) Iter[rune]
  • func OfSlice[T any](items []T) Iter[T]
  • func OfStringAsLines(src string) Iter[string]
  • func OfStringAsRunes(src string) Iter[rune]
  • func SetError[T any](it Iter[T], err error) Iter[T]
• type IterImpl
  • func (it *IterImpl[T]) Next() (T, error)
  • func (it *IterImpl[T]) Unread(val T)

Variables

var (
	EOI = fmt.Errorf("End of Iteration")
)

var (
	InvalidUTF8EncodingError = fmt.Errorf("Invalid UTF 8 encoding")
)

Error constants

Functions

func CSVIterGen

func CSVIterGen(src goio.Reader) func() ([]string, error)

CSVIterGen generates an iterating function that iterates all the rows of a CSV document provided by an io.Reader. The same []string is returned each time with different content.

func ConcatIterGen

func ConcatIterGen[T any](src []Iter[T]) func() (T, error)

ConcatIterGen generates an iterating function that iterates all the values of all the Iters passed. If a non-nil non-EOI error is returned from an underlying iter, then (zero value, error) is returned. After returning (zero value, non-nil error), all further calls return (zero value, same error).

func FibonnaciIterGen

func FibonnaciIterGen() func() (int, error)

FibonnaciIterGen generates an iterating function that iterates the Fibonacci series 1, 1, 2, 3, 5, 8, 13, ...

func InfiniteIterGen

func InfiniteIterGen[T any](iterative func(T) T, initialValues ...T) func() (T, error)

InfiniteIterGen generates an iterative function based on an iterative function and zero or more initial values. The initial values are handled as follows:

• zero initial values: the zero value of T is used as the seed value
• one initial values: the value given is used as the seed value
• multiple initial values: the first n-1 values are returned from the first n-1 calls to the generated function, and the last value is the seed value

The seed value is used as the argument to the first call of the given function. The generated values are the first n-1 initialValues followed by the inifinite series f(seed), f(f(seed)), f(f(f(seed))), ...

func MapIterGen

func MapIterGen[K comparable, V any](m map[K]V) func() (tuple.Two[K, V], error)

MapIterGen generates an iterating function for a map[K]V First len(m) calls to iterating function return (tuple.Two[K, V]{m key, m value}, nil) All remaining calls return (tuple.Two[K, V] zero value, EOI)

func Maybe

func Maybe[T any](it Iter[T]) union.Result[T]

Maybe converts the result of Next into a Result[T] to represent the result as a single type.

func NoValueIterGen

func NoValueIterGen[T any]() func() (T, error)

NoValueIterGen generates an iterating function that has no values. Always returns (zero value, EOI)

func ReaderAsLinesIterGen

func ReaderAsLinesIterGen(src goio.Reader) func() (string, error)

ReaderAsLinesIterGen generates an iterating function that iterates all the UTF-8 lines of an io.Reader See readLines.

func ReaderAsRunesIterGen

func ReaderAsRunesIterGen(src goio.Reader) func() (rune, error)

ReaderAsRunesIterGen generates an iterating function that iterates all the UTF-8 runes of an io.Reader. Up to four UTF-8 bytes are read to produce a single rune. If the reader returns an EOF, it is translated to an EOI, any other error is returned as is. If the iter is called again after returning a non-nil error, it returns (0, same error).

func ReaderIterGen

func ReaderIterGen(src goio.Reader) func() (byte, error)

ReaderIterGen generates an iterating function that iterates all the bytes of an io.Reader. If the reader returns an EOF, it is translated to an EOI, any other error is returned as is. If the iter is called again after returning a non-nil error, it returns (0, same error). If the given io.Reader is also an io.Closer, then the Close() method is called after the last byte is read.

func SingleValueIterGen

func SingleValueIterGen[T any](value T) func() (T, error)

SingleValueIterGen generates an iterating function that has one value

func SliceIterGen

func SliceIterGen[T any](slc []T) func() (T, error)

SliceIterGen generates an iterating function for a slice of type T First len(slc) calls to iterating function return (slc element, nil) All remaining calls return (T zero value, EOI)

func StringAsLinesIterGen

func StringAsLinesIterGen(src string) func() (string, error)

StringAsLinesIterGen generates an iterating function that iterates all the UTF-8 lines of a String See readLines.

func StringAsRunesIterGen

func StringAsRunesIterGen(src string) func() (rune, error)

StringAsRunesIterGen generates an iterating function that iterates the runes of a string. See ReaderAsRunesIterGen.

Types

type Iter

type Iter[T any] interface {
	Next() (T, error)
	Unread(T)
}

Iter defines iteration for type T, which works as follows: - Next returns (next value, nil) if there is another value, or (zero value, EOI) if there is not.

• It is possible for Next to return (zero value, some other error).
• Next should never return (non zero value, non nil error).
• Once Next returns (zero value, EOI or problem error), Next will continue to return (zero value, EOI or problem error).

- Unread places the given value at the end of a buffer of values

• Next consults the buffer before calling the underlying iterating function
• Next returns values in reverse order of Unreads (eg Unread(1); Unread(2) results in Next returning 2, then 1)

func Concat

func Concat[T any](iters ...Iter[T]) Iter[T]

Concatenate any number of Iter[T] into a single Iter[T] that iterates all the elements of each Iter[T], until the last element of the last iterator has been returned.

func Of

func Of[T any](items ...T) Iter[T]

Of constructs an Iter[T] that iterates the items passed. The intention is hard-coded values are passed.

See SliceIterGen.

func OfCSV

func OfCSV(src goio.Reader) Iter[[]string]

OfCSV constructs an Iter[[]string] that iterates lines of a csv document inan io.Reader.

func OfEmpty

func OfEmpty[T any]() Iter[T]

OfEmpty constructs an Iter[T] that iterates no values.

See NoValueIterGen.

func OfIter

func OfIter[T any](iterFn func() (T, error)) Iter[T]

OfIter constructs an Iter[T] from an iterating function that returns (T, error). The function must return (nextItem, nil) for every item available to iterate, then return (invalid, EOI) on the next call after the last item, where invalid is any value of type T. If some actual error occurs attempting to read the next value, then the function must return (invalid, non-nil non-EOI error). Once the function returns a non-nil error, it will never be called again. Panics if iterFn is nil.

See IterImpl.

func OfMap

func OfMap[K comparable, V any](items map[K]V) Iter[tuple.Two[K, V]]

Of constructs an Iter[tuple.Two[K, V]] that iterates the items passed.

See MapIterGen.

func OfOne

func OfOne[T any](item T) Iter[T]

OfOne constructs an Iter[T] that iterates a single value.

See SingleValueIterGen.

func OfReader

func OfReader(src goio.Reader) Iter[byte]

OfReader constructs an Iter[byte] that iterates the bytes of a Reader.

See ReaderIterGen.

func OfReaderAsLines

func OfReaderAsLines(src goio.Reader) Iter[string]

OfReaderAsLines constructs an Iter[string] that iterates the UTF-8 lines of a Reader.

See ReaderAsLinesIterGen.

func OfReaderAsRunes

func OfReaderAsRunes(src goio.Reader) Iter[rune]

OfReaderAsRunes constructs an Iter[rune] that iterates the UTF-8 runes of a Reader.

See ReaderAsRunesIterGen.

func OfSlice

func OfSlice[T any](items []T) Iter[T]

OfSlice constructs an Iter[T] that iterates the slice values passed. The intention is the slice may be large, and passing the slice by reference is better than using varargs like Of(...).

See SliceIterGen

func OfStringAsLines

func OfStringAsLines(src string) Iter[string]

OfStringAsLines constructs an Iter[rune] that iterates lines of a string.

See ReaderAsLinesIterGen.

func OfStringAsRunes

func OfStringAsRunes(src string) Iter[rune]

OfStringAsRunes constructs an Iter[rune] that iterates runes of a string.

See SliceIterGen.

func SetError

func SetError[T any](it Iter[T], err error) Iter[T]

SetError sets a particular error to occur instead of the first non-nil error the given iterator returns.

type IterImpl

type IterImpl[T any] struct {
	// contains filtered or unexported fields
}

IterImpl is the common implementation of Iter[T], based on an underlying iterating function.

func (*IterImpl[T]) Next

func (it *IterImpl[T]) Next() (T, error)

Next returns (value, nil) if there is another item to be read by Value. When Next returns (zero value, EOI), further calls return (zero value, EOI). Next does not ever return both a value and an error.

func (*IterImpl[T]) Unread

func (it *IterImpl[T]) Unread(val T)

Unread adds the given value to an internal buffer, to be returned by Next in reverse order.