Documentation ¶
Overview ¶
Package xiter provides iterator-related functionality compatible with, but not requiring, Go 1.22 and GOEXPERIMENT=rangefunc.
Index ¶
- func All[T any](seq Seq[T], f func(T) bool) bool
- func Any[T any](seq Seq[T], f func(T) bool) bool
- func AppendSplitTo[T1, T2 any](seq SplitSeq[T1, T2], s1 []T1, s2 []T2) ([]T1, []T2)
- func AppendTo[T any, S ~[]T](seq Seq[T], s S) S
- func Collect[T any](seq Seq[T]) []T
- func CollectSize[T any](seq Seq[T], len int) []T
- func CollectSplit[T1, T2 any](seq SplitSeq[T1, T2]) (y1 []T1, y2 []T2)
- func Contains[T comparable](seq Seq[T], v T) bool
- func Drain[T any](seq Seq[T])
- func Equal[T cmp.Ordered](seq1, seq2 Seq[T]) bool
- func EqualFunc[T1, T2 any](seq1 Seq[T1], seq2 Seq[T2], equal func(T1, T2) bool) bool
- func Find[T any](seq Seq[T], f func(T) bool) (r T, ok bool)
- func Fold[T any](seq Seq[T], reducer func(T, T) T) T
- func GoPull[T any](seq Seq[T]) (iter func() (T, bool), stop func())
- func IsSorted[T cmp.Ordered](seq Seq[T]) bool
- func IsSortedFunc[T any](seq Seq[T], compare func(T, T) int) bool
- func Max[T cmp.Ordered](seq Seq[T]) T
- func Min[T cmp.Ordered](seq Seq[T]) T
- func Partition[T any](seq Seq[T], f func(T) bool) (true, false []T)
- func PartitionInto[T any](seq Seq[T], f func(T) bool, true, false []T) ([]T, []T)
- func Product[T Multiplyable](seq Seq[T]) T
- func Pull[T any](seq Seq[T]) (iter func() (T, bool), stop func())
- func Reduce[T, R any](seq Seq[T], initial R, reducer func(R, T) R) R
- func SendContext[T any](seq Seq[T], ctx context.Context, c chan<- T)
- func Sum[T Addable](seq Seq[T]) T
- type Addable
- type Multiplyable
- type Pair
- type Seq
- func Bytes(s string) Seq[byte]
- func Cache[T any](seq Seq[T]) Seq[T]
- func Chunks[T any](seq Seq[T], n int) Seq[[]T]
- func Concat[T any](seqs ...Seq[T]) Seq[T]
- func Filter[T any](seq Seq[T], f func(T) bool) Seq[T]
- func Flatten[T any](seq Seq[Seq[T]]) Seq[T]
- func Generate[T Addable](start, step T) Seq[T]
- func Handle[T any](seq Seq2[T, error], f func(error) bool) Seq[T]
- func Limit[T any](seq Seq[T], n int) Seq[T]
- func Map[T1, T2 any](seq Seq[T1], f func(T1) T2) Seq[T2]
- func MapKeys[K comparable, V any, M ~map[K]V](m M) Seq[K]
- func MapValues[K comparable, V any, M ~map[K]V](m M) Seq[V]
- func Merge[T cmp.Ordered](seq1, seq2 Seq[T]) Seq[T]
- func MergeFunc[T any](seq1, seq2 Seq[T], compare func(T, T) int) Seq[T]
- func Of[T any](vals ...T) Seq[T]
- func OfChan[T any](c <-chan T) Seq[T]
- func OfSlice[T any, S ~[]T](s S) Seq[T]
- func Or[T any](seqs ...Seq[T]) Seq[T]
- func RecvContext[T any](ctx context.Context, c <-chan T) Seq[T]
- func Runes[T ~[]byte | ~string](s T) Seq[rune]
- func Skip[T any](seq Seq[T], n int) Seq[T]
- func StringSplit(s, sep string) Seq[string]
- func ToPair[T1, T2 any](seq Seq2[T1, T2]) Seq[Pair[T1, T2]]
- func V1[T1, T2 any](seq Seq2[T1, T2]) Seq[T1]
- func V2[T1, T2 any](seq Seq2[T1, T2]) Seq[T2]
- func Windows[T any](seq Seq[T], n int) Seq[[]T]
- func Zip[T1, T2 any](seq1 Seq[T1], seq2 Seq[T2]) Seq[Zipped[T1, T2]]
- type Seq2
- type SplitSeq
- type Zipped
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppendSplitTo ¶
AppendSplitTo collects the elements of seq by appending them to existing slices.
func CollectSize ¶
CollectSize pre-allocates the slice being collected into to the given size. It is provided purely for convenience.
func CollectSplit ¶
CollectSplit is like Collect, but for a SplitSeq.
func Contains ¶
func Contains[T comparable](seq Seq[T], v T) bool
Contains returns true if v is an element of seq.
func Equal ¶
Equal returns true if seq1 and seq2 are the same length and each element of each is equal to the element at the same point in the sequence of the other.
func EqualFunc ¶
EqualFunc is like Equal but uses a custom comparison function to determine the equivalence of the elements of each sequence.
func Fold ¶
Fold performs a Reduce but uses the first value yielded by seq instead of a provided initial value. If seq doesn't yield any values, the zero value of T is returned.
func GoPull ¶
GoPull simulates a pull-iterator using Go's built-in concurrency primitives in lieu of coroutines. It handles all synchronization internally, so, despite running the iterator in a new thread, there shouldn't be any data races, but there is some performance overhead.
The returned stop function must be called when the iterator is no longer in use.
func IsSorted ¶
IsSorted returns true if each element of seq is greater than or equal to the previous one.
func IsSortedFunc ¶
IsSortedFunc is like IsSorted but uses a custom comparison function.
func Max ¶
Max returns maximum element yielded by seq or the zero value if seq doesn't yield anything.
func Min ¶
Min returns the minimum element yielded by seq or the zero value if seq doesn't yield anything.
func Partition ¶
Partition returns two slices, one containing all of the elements of seq for which f(element) is true and one containing all of those for which it is false.
func PartitionInto ¶
PartitionInto performs a Partition by appending to two existing slices.
func Product ¶
func Product[T Multiplyable](seq Seq[T]) T
Product returns the values of seq multiplied together. It returns 1 if no values are yielded.
func Reduce ¶
Reduce calls reducer on each value of seq, passing it initial as its first argument on the first call and then the result of the previous call for each call after that. It returns the final value returned by reducer.
Reduce can be somewhat complicated to get the hang of, but very powerful. For example, a simple summation of values can be done as
sum := Reduce(seq, 0, func(total, v int) int { return total + v })
func SendContext ¶
SendContext sends values from seq to c repeatedly until either the sequence ends or ctx is canceled. It blocks until one of those two things happens.
Types ¶
type Addable ¶
type Addable interface { int | int8 | int16 | int32 | int64 | uint | uint8 | uint16 | uint32 | uint64 | uintptr | float32 | float64 | complex64 | complex128 | string }
Addable is a type that should probably exist in the standard library somewhere because it's quite command and kind of a pain to write every time I need it.
type Multiplyable ¶
type Pair ¶
type Pair[T1, T2 any] struct { V1 T1 V2 T2 }
Pair contains two values of arbitrary types.
type Seq ¶
Seq represents an iterator over a sequence of values. When called, the passed yield function is called for each successive value. Returning false from yield causes the iterator to stop, equivalent to a break statement.
func Cache ¶
Cache returns a Seq that can be iterated more than once. On the first iteration, it yields the values from seq and caches them. On subsequent iterations, it yields the cached values from the first iteration.
func Chunks ¶
Chunks works just like Windows except that the yielded slices of elements do not overlap. In other words,
Chunks(Generate(0, 1), 3)
will yield
[0, 1, 2] [3, 4, 5] [6, 7, 8]
Like with Windows, the slice is reused between iterations.
func Filter ¶
Filter returns a Seq that yields only the values of seq for which f(value) returns true.
func Generate ¶
Generate returns a Seq that first yields start and then yields successive values by adding step to the previous continuously. The returned Seq does not end. To limit it to a specific number of returned elements, use Limit.
func Handle ¶
Handle splits seq by calling f for any non-nil errors yielded by seq. If f returns false, iteration stops. If an iteration's error is nil or f returns true, the other value is yielded by the returned Seq.
TODO: This is significantly less useful than it could be. For example, there's no way to tell it to skip the yield but continue iteration anyways.
func MapKeys ¶
func MapKeys[K comparable, V any, M ~map[K]V](m M) Seq[K]
MapKeys returns a Seq over the keys of m.
func MapValues ¶
func MapValues[K comparable, V any, M ~map[K]V](m M) Seq[V]
MapValues returns a Seq over the values of m.
func Merge ¶
Merge returns a sequence that yields values from the ordered sequences seq1 and seq2 one at a time to produce a new ordered sequence made up of all of the elements of both seq1 and seq2.
func MergeFunc ¶
MergeFunc is like Merge, but uses a custom comparison function for determining the order of values.
func OfChan ¶
OfChan returns a Seq which yields values received from c. The sequence ends when c is closed. It is equivalent to range c.
func OfSlice ¶
OfSlice returns a Seq over the elements of s. It is equivalent to range s with the index ignored.
func Or ¶
Or yields all of the values from the first Seq which yields at least one value and then stops.
func RecvContext ¶
RecvContext returns a Seq that receives from c continuously until either c is closed or the given context is canceled.
func Skip ¶
Skip returns a Seq that skips over the first n elements of seq and then yields the rest normally.
func StringSplit ¶
StringSplit returns an iterator over the substrings of s that are separated by sep. It behaves very similarly to strings.Split.
func Windows ¶
Windows returns a slice over successive overlapping portions of size n of the values yielded by seq. In other words,
Windows(Generate(0, 1), 3)
will yield
[0, 1, 2] [1, 2, 3] [2, 3, 4]
and so on. The slice yielded is reused from one iteration to the next, so it should not be held onto after each iteration has ended. Map and slices.Clone may come in handy for dealing with situations where this is necessary.
type Seq2 ¶
Seq2 represents a two-value iterator.
func Enumerate ¶
Enumerate returns a Seq2 that counts the number of iterations of seq as it yields elements from it, starting at 0.
func OfMap ¶
func OfMap[K comparable, V any, M ~map[K]V](m M) Seq2[K, V]
OfMap returns a Seq over the key-value pairs of m.
func OfSliceIndex ¶
OfSliceIndex returns a Seq over the elements of s. It is equivalent to range s.
type SplitSeq ¶
A SplitSeq is like a Seq but can yield via either of two functions. It might not be useful, but is included anyways because it might be.