iterator

func AdvanceBy ¶

func AdvanceBy[T any](iter Iterator[T], n uint64) result.Result[struct{}, uint64]

Advances the iterator by n elements. This method will eagerly skip n elements by calling next up to n times until Nothing is encountered. Returns Ok[struct{}{}] if successful. Returns Err[k] if Nothing is encountered, where k is the number of elements advanced before hitting the end.

func All ¶

func All[T any](iter Iterator[T], pred func(T) bool) bool

Tests if every element of the iterator matches the predicate. Applies pred to each element of the iterator, until the iterator returns Nothing. Once the first element returns false, all() will short-circuit and exit. The empty iterator returns true.

func Any ¶

func Any[T any](iter Iterator[T], pred func(T) bool) bool

Tests if any element of the iterator matches the predicate. Applies pred to each element of the iterator, until the iterator returns Nothing. Once the first element returns true, any() will short-circuit and exit. The empty iterator returns false.

func Chain ¶

func Chain[T any](first Iterator[T], second Iterator[T]) *chainIterator[T]

Returns a new iterator that delivers all elements from first, then second once first is exhausted.

func Collect ¶

func Collect[T any](iter Iterator[T]) []T

Collect returns all the elements of the iterator into a slice.

func CollectInto ¶

func CollectInto[T any, C Collection[T]](iter Iterator[T], collection C) C

CollectInto collects the iterator into the given collection. The provided collection is modified to hold the elements in iter.

func Count ¶

func Count[T any](iter Iterator[T]) uint64

Consumes the iterator, counting the number of elements until it was exhausted. Next() will be called at least once even if the iterator has no elements.

func Enumerate ¶

func Enumerate[T any](iter Iterator[T]) *enumerateIterator[T]

Returns a new iterator that delivers Pairs of indexes and values from the wrapped iterator.

func Filter ¶

func Filter[T any](iter Iterator[T], pred func(T) bool) *filterIterator[T]

Returns an iterator that only returns elements from iter that pass pred.

func FilterMap ¶

func FilterMap[T any, U any](iter Iterator[T], pred func(T) option.Option[U]) *filterMapIterator[T, U]

Creates an iterator that both filters and maps. The returned iterator yields only the values for which the supplied closure returns Some(value).

func Find ¶

func Find[T any](iter Iterator[T], pred func(T) bool) option.Option[T]

Find searches for the first element of the iterator that satisfies the predicate. Returns Some[T] for the first element that returns true. Short-circuits upon finding the first true element. If no element satisfies the predicate, returns Nothing.

func Fold ¶

func Fold[T any, A any](iter Iterator[T], a A, f func(A, T) A) A

Folds every element into an accumulator by applying an operation, returning the final either. The entire iterator will be consumed by this.

func ForEach ¶

func ForEach[T any](iter Iterator[T], f func(T))

Runs the given closure on each element of the iterator.

func FromSeq ¶

func FromSeq[T any](seq iter.Seq[T]) *seqIterator[T]

FromSeq converts an iter.Seq[T] to a seqIterator[T]. The sequence will be pulled from lazily as Next() is called.

The returned iterator holds resources from iter.Pull. It is intended that Close be called via defer immediately after creating the iterator. This ensures resources are released even if the iterator is not fully consumed. Close is safe to call multiple times or after the iterator is exhausted.

Important: You should defer Close even if the iterator is chained into other adapters like Map, Filter, Take, etc. The adapters do not propagate Close to the underlying iterator, so the original CloseableIterator must be closed explicitly.

Example:

it := iterator.FromSeq(slices.Values(mySlice))
defer it.Close()
// Safe to chain into adapters after deferring Close
mapped := iterator.Map(it, func(x int) int { return x * 2 })
result := iterator.Collect(mapped)

func FromSeq2 ¶

func FromSeq2[K any, V any](seq iter.Seq2[K, V]) *seq2Iterator[K, V]

FromSeq2 converts an iter.Seq2[K, V] to a seq2Iterator[K, V]. The sequence will be pulled from lazily as Next() is called.

The returned iterator holds resources from iter.Pull2. It is intended that Close be called via defer immediately after creating the iterator. This ensures resources are released even if the iterator is not fully consumed. Close is safe to call multiple times or after the iterator is exhausted.

Important: You should defer Close even if the iterator is chained into other adapters like Map, Filter, Take, etc. The adapters do not propagate Close to the underlying iterator, so the original CloseableIterator must be closed explicitly.

Example:

it := iterator.FromSeq2(maps.All(myMap))
defer it.Close()
// Safe to chain into adapters after deferring Close
filtered := iterator.Filter(it, func(p pair.Pair[K, V]) bool { return p.First != "" })
result := iterator.Collect(filtered)

func Fuse ¶

func Fuse[T any](inner Iterator[T]) *fuseIterator[T]

Creates an iterator that will always return Nothing after the first Nothing.

func Inspect ¶

func Inspect[T any](inner Iterator[T], f func(T)) *inspectIterator[T]

Does something with each element of an iterator, passing the value on.

func Intersperse ¶

func Intersperse[T any](inner Iterator[T], item T) *intersperseIterator[T]

Creates a new iterator which places a copy of separator between adjacent items of the original iterator. A copy of item will be placed before the final Nothing. The item will only be shallow-copied. If you desire deep copying/bespoke behavior, use IntersperseWith.

func IntersperseWith ¶

func IntersperseWith[T any](inner Iterator[T], f func() T) *intersperseWithIterator[T]

Creates a new iterator which calls f and places a copy of its return value between items of the original iterator. Before the final Nothing, f will be called and its result will be returned.

func Last ¶

func Last[T any](iter Iterator[T]) option.Option[T]

Last returns the final element of the iterator, before it returns Nothing. Returns Nothing if the iterator is empty.

func Map ¶

func Map[T any, U any](iter Iterator[T], f func(T) U) *mapIterator[T, U]

Creates an iterator that maps elements from the original iterator. Converts an iterator from type T to U.

func MapWhile ¶

func MapWhile[T any, U any](inner Iterator[T], pred func(T) option.Option[U]) *mapWhileIterator[T, U]

Returns an iterator yielding elements from inner, mapped by pred. The iterator stops once pred returns Nothing. Yields elements while pred continues to return Some.

func Max ¶

func Max[T cmp.Ordered](iter Iterator[T]) option.Option[T]

Max returns the maximum element of the iterator. Returns the last element if multiple elements are equally maximal. Returns Nothing if the iterator is empty.

func MaxBy ¶

func MaxBy[T any](iter Iterator[T], less func(T, T) bool) option.Option[T]

MaxBy returns the maximum element of the iterator with respect to the specified less function. less(a, b) should return true if a is less than b, and false otherwise. Returns the last element if multiple elements are equally maximal. Returns Nothing if the iterator is empty.

func Min ¶

func Min[T cmp.Ordered](iter Iterator[T]) option.Option[T]

Min returns the minimum element of the iterator. Returns the first element if multiple elements are equally minimal. Returns Nothing if the iterator is empty.

func MinBy ¶

func MinBy[T any](iter Iterator[T], less func(T, T) bool) option.Option[T]

MinBy returns the minimum element of the iterator with respect to the specified less function. less(a, b) should return true if a is less than b, and false otherwise. Returns the first element if multiple elements are equally minimal. Returns Nothing if the iterator is empty.

func Nth ¶

func Nth[T any](iter Iterator[T], n uint64) option.Option[T]

Advances the iterator by n and returns the nth next item. Count starts from 0, so Nth(I, 0) returns the current element. The iterator is not rewinded, so preceding elements will be discarded. Subsequent calls (even to Nth(I, 0)) will return different values. Returns Nothing if n is greater or equal to the length of the iterator.

func Partition ¶

func Partition[T any](iter Iterator[T], f func(T) bool) ([]T, []T)

Consumes an iterator, producing two lists from it. The first contains all the elements the predicate returned true for, and the second, false.

func Position ¶

func Position[T any](iter Iterator[T], pred func(T) bool) option.Option[uint64]

Searches for an element in an iterator, returning its index. Returns Nothing if it was not found. Consumes the iterator up to the item that returned true.

func Range ¶

func Range[T numeric](start T, end T) *rangeIterator[T]

Returns an iterator ranging from start (inclusive) to end (exclusive), stepping by 1. If end is less than start, the iterator will be empty.

func RangeBy ¶

func RangeBy[T numeric](start T, end T, step T) *rangeIterator[T]

Returns an iterator ranging from start (inclusive) to end (exclusive), stepping by step. If end is less than start, the iterator will be empty. This can be used with a negative step. If so, if end is greater than start, the iterator will be empty. NOTE: A zero step will return start ad infinitum.

func RangeInclusive ¶

func RangeInclusive[T numeric](start T, end T) *rangeIterator[T]

Returns an iterator ranging from start (inclusive) to end (inclusive), stepping by 1. If end is less than start, the iterator will be empty.

func RangeInclusiveBy ¶

func RangeInclusiveBy[T numeric](start T, end T, step T) *rangeIterator[T]

Returns an iterator ranging from start (inclusive) to end (exclusive), stepping by step. If end is less than start, the iterator will be empty. This can be used with a negative step. If so, if end is greater than start, the iterator will be empty. NOTE: A zero step will return start ad infinitum.

func Scan ¶

func Scan[T any, S any, U any](inner Iterator[T], initial S, f func(*S, T) option.Option[U]) *scanIterator[T, S, U]

An iterator adapter similar to fold that holds internal state and produces a new iterator. Calls f with the current state and the current item, and yields a new item mapped by the closure. NOTE: The closure is responsible for updating the state; it is not automatically assigned the result of the closure.

func Skip ¶

func Skip[T any](inner Iterator[T], n uint64) *skipIterator[T]

Creates an iterator that skips the first n elements. If the iterator is too short, an empty iterator is returned.

func SkipWhile ¶

func SkipWhile[T any](inner Iterator[T], f func(T) bool) *skipWhileIterator[T]

Creates an iterator that skips the elements for which pred is true. As soon as pred returns false, the predicate is no longer evaluated. Even if further elements would pass the predicate, they will still be yielded.

func StepBy ¶

func StepBy[T any](inner Iterator[T], n uint64) *stepByIterator[T]

Creates an iterator starting with the same element, but stepping by n each time. Will always return the first element of the iterator, regardless of the step provided.

func Take ¶

func Take[T any](inner Iterator[T], n uint64) *takeIterator[T]

Creates an iterator yielding the first n elements, or fewer if the provided iterator ends first.

func TakeWhile ¶

func TakeWhile[T any](inner Iterator[T], f func(T) bool) *takeWhileIterator[T]

Creates an iterator that takes the elements for which pred is true. As soon as pred returns false, the predicate is no longer evaluated. The rest of the elements will be ignored. The element for which false is returned will be removed from the iterator in order to check it.

func ToSeq ¶

func ToSeq[T any](it Iterator[T]) iter.Seq[T]

ToSeq converts an Iterator[T] to an iter.Seq[T]. The returned sequence can be used in a for-range loop. The iterator will be consumed as the sequence is iterated.

func ToSeq2 ¶

func ToSeq2[K any, V any](it Iterator[pair.Pair[K, V]]) iter.Seq2[K, V]

ToSeq2 converts an Iterator[pair.Pair[K, V]] to an iter.Seq2[K, V]. This is useful for iterators that yield key-value pairs, such as those created by Zip or Enumerate.

func TryCollect ¶

func TryCollect[T any, E any](iter Iterator[result.Result[T, E]]) result.Result[[]T, E]

TryCollect attempts to collect an iterator of Result[T, E] into []T. It short-circuits upon reaching the first Err variant, instead returning Err[E].

func TryFold ¶

func TryFold[T any, A any, E any](
	iter Iterator[T], a A, f func(A, T) result.Result[A, E],
) result.Result[A, E]

Tries to fold every element into an accumulator by applying an operation, returning the final either. Short-circuits if the function returns Err, returning the Result.

func Unzip ¶

func Unzip[T any, U any](iter Iterator[pair.Pair[T, U]]) ([]T, []U)

Consumes an entire iterator of pairs, producing two collections, for the first and second elements respectively.

func Zip ¶

func Zip[T any, U any](first Iterator[T], second Iterator[U]) *zipIterator[T, U]

‘Zips up’ two iterators into a single iterator of pairs. zip() returns a new iterator that will iterate over two other iterators. The iterator returns a tuple where the first element comes from the first iterator, and the second element comes from the second iterator. If either iterator returns None, next from the zipped iterator will return None.