iterators

README

iterators

Documentation

Index

• func Collect[E any, S ~[]E](ctx context.Context, dst S, iter Iterator[E]) S
• func CollectMap[K comparable, V any, M ~map[K]V](ctx context.Context, dst M, iter Pairs[K, V])
• func CollectN[E any, S ~[]E](ctx context.Context, dst S, iter Iterator[E], n int) S
• func CollectSet[K comparable, V any, M ~map[K]V](ctx context.Context, dst M, iter Iterator[K], value V)
• func Count[E comparable](ctx context.Context, iter Iterator[E], value E) int
• func CountFn[E any](ctx context.Context, iter Iterator[E], fn func(E) bool) int
• func Drain[E any](ctx context.Context, iter Iterator[E])
• func ForEach[E any](ctx context.Context, iter Iterator[E], fn func(value E) bool)
• type Chan
  • func (ch Chan[E]) Len() int
  • func (ch Chan[E]) Next(ctx context.Context) (_ E, ok bool)
• type Fn
  • func (fn Fn[E]) Next(ctx context.Context) (_ E, ok bool)
• type Iterator
  • func Always[E any](value E) Iterator[E]
  • func Chain[E any](iters ...Iterator[E]) Iterator[E]
  • func Compact[E comparable](iter Iterator[E]) Iterator[E]
  • func CompactFn[E any](iter Iterator[E], fn func(a, B E) bool) Iterator[E]
  • func Empty[E any]() Iterator[E]
  • func Filter[E any](iter Iterator[E], fn func(E) bool) Iterator[E]
  • func Range[N Number](from, to N) Iterator[N]
  • func RangeStep[N Number](from, to, step N) Iterator[N]
  • func StopOnCancel[E any](iter Iterator[E]) Iterator[E]
  • func Tap[E any](iter Iterator[E], fn func(E, bool)) Iterator[E]
  • func Transduce[F, T any](iter Iterator[F], fn func(F) T) Iterator[T]
  • func TransduceFilter[F, T any](iter Iterator[F], fn func(F) (T, bool)) Iterator[T]
• type IteratorCloser
  • func Closer[E any](iter Iterator[E]) IteratorCloser[E]
• type IteratorErr
  • func TransduceErr[F, T any](iter Iterator[F], fn func(F) (T, error)) IteratorErr[T]
• type Number
• type Pair
  • func (pair *Pair[A, B]) Unpack() (A, B)
• type Pairs
  • func Enumerate[E any](iter Iterator[E]) Pairs[int, E]
  • func TransduceArg[F, T any](iter Iterator[F], fn func(F) T) Pairs[F, T]
  • func TransduceErrWrap[F, T any](iter Iterator[F], fn func(F) (T, error)) Pairs[T, error]
  • func Zip[A, B any](aa Iterator[A], bb Iterator[B]) Pairs[A, B]
• type PairsSized
  • func Map[K comparable, V any, M ~map[K]V](m M) PairsSized[K, V]
• type Sized
  • func Slice[E any, S ~[]E](slice S) Sized[E]

Functions

func Collect

func Collect[E any, S ~[]E](ctx context.Context, dst S, iter Iterator[E]) S

Collect values into a dst slice. It will run until iter is drained.

func CollectMap

func CollectMap[K comparable, V any, M ~map[K]V](ctx context.Context, dst M, iter Pairs[K, V])

func CollectN

func CollectN[E any, S ~[]E](ctx context.Context, dst S, iter Iterator[E], n int) S

CollectN pulls a most n values from iter into dst slice. It will stop if iter is drained.

func CollectSet

func CollectSet[K comparable, V any, M ~map[K]V](ctx context.Context, dst M, iter Iterator[K], value V)

func Count

func Count[E comparable](ctx context.Context, iter Iterator[E], value E) int

func CountFn

func CountFn[E any](ctx context.Context, iter Iterator[E], fn func(E) bool) int

func Drain

func Drain[E any](ctx context.Context, iter Iterator[E])

Drain will consume values from iter until it is drained.

func ForEach

func ForEach[E any](ctx context.Context, iter Iterator[E], fn func(value E) bool)

ForEach calls fn for each value from provided iterator. It will run until iter is drained.

Types

type Chan

type Chan[E any] <-chan E

Chan wraps a read-only channel.

func (Chan[E]) Len

func (ch Chan[E]) Len() int

Len returns number of unread elements from the channel iterator.

func (Chan[E]) Next

func (ch Chan[E]) Next(ctx context.Context) (_ E, ok bool)

Next implements iterator interface.

type Fn

type Fn[E any] func(ctx context.Context) (_ E, ok bool)

Fn is a the most simple iterator - hook, which can be called multiple times until drained.

func (Fn[E]) Next

func (fn Fn[E]) Next(ctx context.Context) (_ E, ok bool)

Next implements the Iterator interface. Always returns false if Fn is nil.

type Iterator

type Iterator[E any] interface {
	// Next returns false if there is no more values in the sequence.
	// Iterator can ignore provided context or return false if context is canceled.
	Next(ctx context.Context) (_ E, ok bool)
}

Iterator is a generic stateful of values.

func Always

func Always[E any](value E) Iterator[E]

Always return provided value. Returns false if context is canceled.

func Chain

func Chain[E any](iters ...Iterator[E]) Iterator[E]

Chain pulls values from provided iterators. It will return false after last iterator is drained.

func Compact

func Compact[E comparable](iter Iterator[E]) Iterator[E]

func CompactFn

func CompactFn[E any](iter Iterator[E], fn func(a, B E) bool) Iterator[E]

func Empty

func Empty[E any]() Iterator[E]

Empty is a always drained iterator.

func Filter

func Filter[E any](iter Iterator[E], fn func(E) bool) Iterator[E]

Filter pulls values from iter and filters them using provided fn. Output iterator emits only `fn(value)==true` values.

func Range

func Range[N Number](from, to N) Iterator[N]

Range emits a bounded sequence of numbers [from, to). If from<to, then it's equal to RangeStep(from, to, 1). If from>to, then returns an empty iterator.

func RangeStep

func RangeStep[N Number](from, to, step N) Iterator[N]

RangeStep emits a bounded sequence of numbers [from, to). Returns non-empty iterator if from<to && step>0 or from>to && step<0. Returns an empty iterator otherwise. Returns an empty iterator if any of arguments is NaN.

func StopOnCancel

func StopOnCancel[E any](iter Iterator[E]) Iterator[E]

StopOnCancel returns false if context is canceled.

func Tap

func Tap[E any](iter Iterator[E], fn func(E, bool)) Iterator[E]

Tap calls the provided fn on each result from iter.

func Transduce

func Transduce[F, T any](iter Iterator[F], fn func(F) T) Iterator[T]

Transduce maps values of type F to values of T using provided function fn. If input iter is drained, then output iterator will return false.

func TransduceFilter

func TransduceFilter[F, T any](iter Iterator[F], fn func(F) (T, bool)) Iterator[T]

TransduceFilter maps values of type F to values of T using provided function fn. If fn returns false, then corresponding result is skipped. If input iter is drained, then output iterator will return false.

type IteratorCloser

type IteratorCloser[E any] interface {
	Iterator[E]
	io.Closer
}

IteratorCloser describes an iterator, which can be closed. Multiple close method calls are a valid usage and must not panic. After first method close call the instance of iterator must return false from Next method.

func Closer

func Closer[E any](iter Iterator[E]) IteratorCloser[E]

Closer makes provided iter closable. If provided iter is a closer already, then it returned as is. If it's not, then returned iterator will always return false after method close is called.

type IteratorErr

type IteratorErr[E any] interface {
	Iterator[E]
	Err() error
}

IteratorErr describes an iterator, which can enter an erroneous state. If there is an error condition, then the Err method must return a non-nil error.

func TransduceErr

func TransduceErr[F, T any](iter Iterator[F], fn func(F) (T, error)) IteratorErr[T]

type Number

type Number interface {
	constraints.Signed | constraints.Unsigned | constraints.Float
}

Number describes a generic integer or float number.

type Pair

type Pair[A, B any] struct {
	A A
	B B
}

Pair describes two connected values.

func (*Pair[A, B]) Unpack

func (pair *Pair[A, B]) Unpack() (A, B)

Unpack returns both values from pair. It's useful then you need a (T, error) function.

type Pairs

type Pairs[A, B any] Iterator[Pair[A, B]]

Pair describes a sequence of pairs.

func Enumerate

func Enumerate[E any](iter Iterator[E]) Pairs[int, E]

Enumerate assignes a sequential increasing number starting from 0 to values from provided iterator.

func TransduceArg

func TransduceArg[F, T any](iter Iterator[F], fn func(F) T) Pairs[F, T]

TransduceArg maps values of type F to values of T using provided function fn. If input iter is drained, then output iterator will return false. Results of fn are attached to corresponding arguments of fn.

func TransduceErrWrap

func TransduceErrWrap[F, T any](iter Iterator[F], fn func(F) (T, error)) Pairs[T, error]

func Zip

func Zip[A, B any](aa Iterator[A], bb Iterator[B]) Pairs[A, B]

Zip combines two sequences into sequence of pairs. If any of iterators is drained, then resulting iterator will return false.

type PairsSized

type PairsSized[A, B any] Sized[Pair[A, B]]

Pair describes a sequence of pairs with known size.

func Map

func Map[K comparable, V any, M ~map[K]V](m M) PairsSized[K, V]

Map returns a sequence of key-value pairs from provided map. Resulting iterator follows the same iteration semantics as a range statement

type Sized

type Sized[E any] interface {
	Iterator[E]
	Len() int
}

Sized describe an iterator with known size. If Len()==0, then Next() must return false. If Next() returns false, then Len() must be 0.

func Slice

func Slice[E any, S ~[]E](slice S) Sized[E]

Slice creates an iterator from provided slice. Resulting iterator will emit all values in order index=0...len. Length of iterator reports the number of uncunsomed value.