Documentation ¶
Overview ¶
Package iter provides generic, lazy iterators, functions for producing them from primitive types, as well as functions and methods for transforming and consuming them.
When reading the documentation of the functions contained in this package, you should assume that any function which accepts an iterator, but does not return one, consumes it unless otherwise stated, meaning that the values contained within cannot be used again.
Methods with names suffixed by Endo indicate that the method transforms iterators of generic type T to some type in terms of T, such as T or Iter[T]. Transformation between types is possible, but only through the corresponding function whose name is identical to the method, without the Endo prefix. Functions are required for these operations because Go does not support the definition of type parameters on methods. The nomenclature comes from the term endomorphism, though it is a bit of a misuse of the term in that some *Endo methods take extra parameters or return types derived from T other than Iter[T].
Index ¶
- func FindMap[T, U any](i Iter[T], f func(T) (U, error)) (U, bool)
- func Fold[T, U any](i Iter[T], init U, f func(curr U, next T) U) U
- func Max[T constraints.Ordered](oi Iter[T]) (T, bool)
- func MaxByKey[T any, U constraints.Ordered](oi Iter[T], key func(T) U) (T, bool)
- func Min[T constraints.Ordered](oi Iter[T]) (T, bool)
- func MinByKey[T any, U constraints.Ordered](oi Iter[T], key func(T) U) (T, bool)
- func Position[T any](i Iter[T], f func(T) bool) int
- func Sum[T constraints.Ordered](oi Iter[T]) T
- func TryFold[T, U any](i Iter[T], init U, f func(curr U, next T) (U, error)) (U, error)
- func Unzip[T, U any](i Iter[tuple.T2[T, U]]) (Iter[T], Iter[U])
- type Iter
- func Elems[T any](s []T) Iter[T]
- func Enumerate[T any](i Iter[T]) Iter[tuple.T2[int, T]]
- func FilterMap[T, U any](i Iter[T], f func(T) (U, error)) Iter[U]
- func FlatMap[T, U any](i Iter[T], f func(T) Iter[U]) Iter[U]
- func GenWhile[T any](f func() (T, error)) Iter[T]
- func Ints[T constraints.Integer]() Iter[T]
- func IntsBy[T constraints.Integer](by T) Iter[T]
- func IntsFrom[T constraints.Integer](start T) Iter[T]
- func IntsFromBy[T constraints.Integer](start T, by T) Iter[T]
- func KVZip[T comparable, U any](m map[T]U) Iter[tuple.T2[T, U]]
- func KVZipChannelled[T comparable, U any](m map[T]U) Iter[tuple.T2[T, U]]
- func Map[T, U any](i Iter[T], f func(T) U) Iter[U]
- func MapWhile[T, U any](i Iter[T], f func(T) (U, error)) Iter[U]
- func Receive[T any](ch *chan T) Iter[T]
- func Runes(s string) Iter[rune]
- func SplitByRune(s string, r rune) Iter[string]
- func SplitByString(s string, sep string) Iter[string]
- func Windows[T any](i Iter[T], n int) Iter[[]T]
- func Zip[T, U any](a Iter[T], b Iter[U]) Iter[tuple.T2[T, U]]
- func (i Iter[T]) All(f func(T) bool) bool
- func (i Iter[T]) Any(f func(T) bool) bool
- func (i Iter[T]) Chain(o Iter[T]) Iter[T]
- func (i Iter[T]) Collect() []T
- func (i Iter[T]) CollectInto(buf []T) int
- func (i Iter[T]) Consume()
- func (i Iter[T]) Count() int
- func (i Iter[T]) Cycle() (Iter[T], bool)
- func (i Iter[T]) Filter(f func(T) bool) Iter[T]
- func (i Iter[T]) FilterMapEndo(f func(T) (T, error)) Iter[T]
- func (i Iter[T]) Find(f func(T) bool) (T, bool)
- func (i Iter[T]) FindMapEndo(f func(T) (T, error)) (T, bool)
- func (i Iter[T]) FlatMapEndo(f func(T) Iter[T]) Iter[T]
- func (i Iter[T]) FoldEndo(init T, f func(curr T, next T) T) T
- func (i Iter[T]) ForEach(f func(T))
- func (i Iter[T]) ForEachParallel(f func(T))
- func (i Iter[T]) Inspect(f func(T)) Iter[T]
- func (i Iter[T]) Last() (T, bool)
- func (i Iter[T]) MapEndo(f func(T) T) Iter[T]
- func (i Iter[T]) MapWhileEndo(f func(T) (T, error)) Iter[T]
- func (i Iter[T]) Nth(n int) (T, bool)
- func (i Iter[T]) Partition(f func(T) bool) (Iter[T], Iter[T])
- func (i Iter[T]) Reduce(f func(curr T, next T) T) (T, bool)
- func (i Iter[T]) Rev() Iter[T]
- func (i Iter[T]) Send(ch *chan T)
- func (i Iter[T]) StepBy(step int) Iter[T]
- func (i Iter[T]) Take(n int) Iter[T]
- func (i Iter[T]) TakeWhile(f func(T) bool) Iter[T]
- func (i Iter[T]) TryFoldEndo(init T, f func(curr T, next T) (T, error)) (T, error)
- func (i Iter[T]) TryForEach(f func(T) error) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FindMap ¶
FindMap returns the first transformed value in the iterator for which the provided function does not return an error. As with Find, it consumes all values up to the first passing one.
func Fold ¶
Fold repeatedly applies the provided function to the current value (starting with `init`) and the next value of the iterator, until the whole iterator is consumed.
func Max ¶
func Max[T constraints.Ordered](oi Iter[T]) (T, bool)
Max returns the maximum value in the provided iterator.
func MaxByKey ¶
func MaxByKey[T any, U constraints.Ordered](oi Iter[T], key func(T) U) (T, bool)
MaxByKey returns the value with the maximum result after the application of the provided function.
func Min ¶
func Min[T constraints.Ordered](oi Iter[T]) (T, bool)
Min returns the minimum value in the provided iterator.
func MinByKey ¶
func MinByKey[T any, U constraints.Ordered](oi Iter[T], key func(T) U) (T, bool)
MinByKey returns the value with the minimum result after the application of the provided function.
func Position ¶
Position returns the index of the first element satisfying the provided function, or -1 if one is not found. It consumes every element up to and including the element that satisfies the function, or the whole iterator if no no satisfactory element is found.
func Sum ¶
func Sum[T constraints.Ordered](oi Iter[T]) T
Sum returns the sum of all the values in the provided iterator.
func TryFold ¶
TryFold applies the provided fallible function to the current value (starting with `init`) and the next value of the iterator, until the whole iterator is consumed. If at any point an error is returned, the operation stops and that error is returned.
func Unzip ¶
Unzip returns two iterators, one yielding the left values of the tuples yielded by the input iterator, the other yielding the right values of the tuples. Note that, while the input iterator is evaluated lazily, exceptionally inequal consumption of the left vs the right iterator can lead to high memory consumption by values cached for the other iterator.
Types ¶
type Iter ¶
Iter is a generic iterator function, the basis of this whole package. Note that the typical `iter.Next()` method is replaced with `iter()`, since Iter is simply defined as `func() (T, bool)`.
func Enumerate ¶
Enumerate returns an iterator of tuples indices and values from the input iterator.
func FilterMap ¶
FilterMap returns a new iterator that yields the mapped values which are produced without errors from the provided function.
func FlatMap ¶
FlatMap returns a new iterator that yields the values produced by iterators returned by the provided function when it is applied to values from the input iterator.
func GenWhile ¶
GenWhile returns an iterator that yields return values from the provided function while it does not produce errors. After the first error, no more values are yielded.
func Ints ¶
func Ints[T constraints.Integer]() Iter[T]
Ints returns an iterator that produces constraints.Integer values of the specified generic type, starting from 0 and increasing by 1.
func IntsBy ¶
func IntsBy[T constraints.Integer](by T) Iter[T]
IntsBy returns an iterator that produces constraints.Integer values of the specified generic type, starting from 0 and increasing by the provided value.
func IntsFrom ¶
func IntsFrom[T constraints.Integer](start T) Iter[T]
IntsFrom returns an iterator that produces constraints.Integer values of the specified generic type, starting from the provided value and increasing by 1.
func IntsFromBy ¶
func IntsFromBy[T constraints.Integer](start T, by T) Iter[T]
IntsFromBy returns an iterator that produces constraints.Integer values of the specified generic type, starting from, and increasing by the provided values.
func KVZip ¶
func KVZip[T comparable, U any](m map[T]U) Iter[tuple.T2[T, U]]
KVZip returns an iterator that yields tuples of the input map's keys and values. While the value lookup occurs lazily, the keys must be accumulated immediately when the iterator is created, so this operation can be expensive, both in terms of time as well as memory, especially if your keys are large. If this is a problem, see KVZip.
func KVZipChannelled ¶
func KVZipChannelled[T comparable, U any](m map[T]U) Iter[tuple.T2[T, U]]
KVZipChannelled returns an iterator that yields tuples of the input map's keys and values. This function uses a channel and a goroutine to channel the key values, so you must consume the whole iterator, otherwise garbage goroutines will be left sitting around. Unless you're tight on memory, you should use KVZip.
func Map ¶
Map returns a new iterator that yields the results of applying the provided function to the input iterator.
func MapWhile ¶
MapWhile returns a new iterator that yields the values produced by applying the provided function to the values of the input iterator, until the first error occurs. At that point, no further values are returned.
func Receive ¶
Receive returns an iterator that reads values from the provided channel, and is exhausted when the channel is closed. Note that since this iterator reads from a channel, every time the next value is requested the program may end up deadlocking if values have not been written: the same rules apply as those for reading from a channel in the usual manner.
func SplitByRune ¶
SplitByRune returns an iterator over the substrings of the input string between occurences of the provided rune.
func SplitByString ¶
SplitByString returns an iterator over the substrings of the input string between occurences of the provided separator string.
func Windows ¶
Windows returns an iterator over slices of the provided length, containing, first items 0 through n-1 of the input iterator, then items 1 through n, etc.
func (Iter[T]) All ¶
All returns whether all values of the iterator satisfy the provided predicate function.
func (Iter[T]) Any ¶
Any returns whether any of the values of the iterator satisfy the provided predicate function.
func (Iter[T]) Chain ¶
Chain returns a new iterator that first consumes the first iterator, then the second.
func (Iter[T]) Collect ¶
func (i Iter[T]) Collect() []T
Collect fetches the next value of the iterator until no more values are found, places these values in a slice, and returns it. Note that since Collect does not know how many values it will find, it must resize the slice multiple times during the collection process. This can result in poor performance, so CollectInto should be used when possible.
func (Iter[T]) CollectInto ¶
CollectInto inserts values yielded by the input iterator into the provided slice, and returns the number of values it was able to add before the iterator was exhausted or the slice was full.
func (Iter[T]) Consume ¶
func (i Iter[T]) Consume()
Consume fetches the next value of the iterator until no more values are found. Note that it doesn't do anything with the values that are produced, but it can be useful in certain cases, such as benchmarking.
func (Iter[T]) Cycle ¶
Cycle returns an iterator that first consumes the provided input iterator, then repeatedly returns the previous values. It also returns a boolean that indicates whether the creation of this iterator was successful: it will fail if the provided iterator is already empty.
func (Iter[T]) Filter ¶
Filter returns a new iterator that only yields the values in the input iterator that satisfy the provided function.
func (Iter[T]) FilterMapEndo ¶
FilterMapEndo returns a new iterator that yields the mapped values which are produced without errors from the provided function.
func (Iter[T]) Find ¶
Find returns the first value in the iterator that satisfies the provided predicate function, as well as a boolean indicating whether any value was found. It consumes all values up to the first satisfactory value, or the whole iterator if no values satisfy the predicate.
func (Iter[T]) FindMapEndo ¶
FindMapEndo returns the first transformed value in the iterator for which the provided function does not return an error. As with Find, it consumes all values up to the first passing one.
func (Iter[T]) FlatMapEndo ¶
FlatMapEndo returns a new iterator that yields the values produced by iterators returned by the provided function when it is applied to values from the input iterator.
func (Iter[T]) FoldEndo ¶
func (i Iter[T]) FoldEndo(init T, f func(curr T, next T) T) T
FoldEndo repeatedly applies the provided function to the current value (starting with `init`) and the next value of the iterator, until the whole iterator is consumed.
func (Iter[T]) ForEach ¶
func (i Iter[T]) ForEach(f func(T))
ForEach applies the provided function to all remaining values in the current iterator.
func (Iter[T]) ForEachParallel ¶
func (i Iter[T]) ForEachParallel(f func(T))
ForEachParallel applies the provided function to all remaining values in the current iterator. It differs from ForEach in that, where ForEach runs on a single thread and waits for each execution of the function to complete before fetching the next value and calling the function again, ForEachParallel performs executions of the function on different threads and only waits for all executions at the end. When the function to be executed is expensive and the order in which values of the iterator are operated upon does not matter, this method can result in better performance than ForEach.
func (Iter[T]) Inspect ¶
Inspect produces an iterator with identical values as the input iterator, but it applies the provided function to values of the iterator as they are requested. This methodh differs from ForEach in that it is lazy, whereas ForEach is not.
func (Iter[T]) Last ¶
Last returns the final value of the iterator, along with a boolean indicating whether the operation was successful, in other words, whether the iterator was already empty.
func (Iter[T]) MapEndo ¶
MapEndo returns a new iterator that yields the results of applying the provided function to the input iterator.
func (Iter[T]) MapWhileEndo ¶
MapWhileEndo returns a new iterator that yields the values produced by applying the provided function to the values of the input iterator, until the first error occurs. At that point, no further values are returned.
func (Iter[T]) Nth ¶
Nth returns the nth value in the iterator, and a boolean indicating whether the iterator was too short. The provided value of `n` should be non-negative.
func (Iter[T]) Partition ¶
Partition returns two iterators, one containing the values of the original iterator that satisfy the provided function, the other containing the values that do not.
func (Iter[T]) Reduce ¶
Reduce repeatedly applies the provided function to the current value (starting with iterator's first value) and the next value of the iterator, until the whole iterator is consumed. The boolean indicates whether the iterator was already empty, meaning that it could not be reduced.
func (Iter[T]) Rev ¶
Rev produces a new iterator whose values are reversed from those of the input iterator. Note that this method is not lazy, it must consume the whole input iterator immediately to produce the reversed result.
func (Iter[T]) Send ¶
func (i Iter[T]) Send(ch *chan T)
Send consumes the input iterator, sending all yielded values into the provided channel. As with receive, this can result in deadlocks if used improperly: if nobody is reading from the channel. Also note that this method does not close the value after the values have been written, if you want that to happen, you should do so yourself.
func (Iter[T]) StepBy ¶
StepBy returns a new iterator that returns every nth value of the input iterator. The provided step value must be positive, otherwise the method will panic.
func (Iter[T]) Take ¶
Take returns an iterator that limits that yields up to (but no more than) n values from the input iterator.
func (Iter[T]) TakeWhile ¶
TakeWhile produces a new iterator that yields values from the input iterator while those values satisfy the provided function. Once the first failure occurs, no more values are yielded. If this occurs, the previously yielded values, as well as the first failing value, are consumed from the input iterator.
func (Iter[T]) TryFoldEndo ¶
TryFoldEndo applies the provided fallible function to the current value (starting with `init`) and the next value of the iterator, until the whole iterator is consumed. If at any point an error is returned, the operation stops and that error is returned.
func (Iter[T]) TryForEach ¶
TryForEach applies the provided fallible function to all remaining values in the current iterator, but stops if an error is returned at any point.