irt

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 4, 2026 License: Apache-2.0 Imports: 17 Imported by: 25

Documentation

Overview

Package irt (for IteratoRTools), provides a collection of stateless iterator handling functions, with zero dependencies on other fun packages.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Any added in v0.14.3 

func Any[T any](seq iter.Seq[T]) iter.Seq[any]

Any converts an arbitrary sequence to a sequence of `any` values.

func Any2 added in v0.14.3 

func Any2[A, B any](seq iter.Seq2[A, B]) iter.Seq2[A, any]

Any2 converts the second value of a sequence of pairs to be `any` typed, leaving the first value unchanged.

func Append 

func Append[T any](seq iter.Seq[T], with ...T) iter.Seq[T]

Append returns a sequence containing all elements from the input sequence followed by additional values provided.

func Apply 

func Apply[T any, OP ~func(T)](seq iter.Seq[T], op OP) (count int)

Apply consumes the sequence and calls op for each element. Returns the number of elements processed.

func Apply2 

func Apply2[A, B any, OP ~func(A, B)](seq iter.Seq2[A, B], op OP) (count int)

Apply2 consumes the iterator and calls op for each pair. Returns the number of pairs processed.

func ApplyAll 

func ApplyAll[T any, OP ~func(T) error](seq iter.Seq[T], op OP) error

ApplyAll consumes the sequence and calls op for each element. It collects all errors returned by op and returns them joined.

func ApplyAll2 

func ApplyAll2[A, B any, OP ~func(A, B) error](seq iter.Seq2[A, B], op OP) error

ApplyAll2 consumes the iterator and calls op for each pair. It collects all errors returned by op and returns them joined.

func ApplyUnless 

func ApplyUnless[T any, OP ~func(T) bool](seq iter.Seq[T], op OP) int

ApplyUnless consumes the sequence and calls op for each element. Iteration stops if op returns true. Returns the number of elements processed.

func ApplyUnless2 

func ApplyUnless2[A, B any, OP ~func(A, B) bool](seq iter.Seq2[A, B], op OP) int

ApplyUnless2 consumes the iterator and calls op for each pair. Iteration stops if op returns true. Returns the number of pairs processed.

func ApplyUntil 

func ApplyUntil[T any, OP ~func(T) error](seq iter.Seq[T], op OP) error

ApplyUntil consumes the sequence and calls op for each element. Iteration stops if op returns an error. Returns the error from op, or nil if the sequence was fully consumed.

func ApplyUntil2 

func ApplyUntil2[A, B any, OP ~func(A, B) error](seq iter.Seq2[A, B], op OP) error

ApplyUntil2 consumes the iterator and calls op for each pair. Iteration stops if op returns an error. Returns the error from op, or nil if the sequence was fully consumed.

func ApplyWhile 

func ApplyWhile[T any, OP ~func(T) bool](seq iter.Seq[T], op OP) (count int)

ApplyWhile consumes the sequence and calls op for each element. Iteration stops if op returns false. Returns the number of elements processed.

func ApplyWhile2 

func ApplyWhile2[A, B any, OP ~func(A, B) bool](seq iter.Seq2[A, B], op OP) (count int)

ApplyWhile2 consumes the iterator and calls op for each pair. Iteration stops if op returns false. Returns the number of pairs processed.

func Args 

func Args[T any](items ...T) iter.Seq[T]

Args returns a sequence containing all provided arguments.

func AsChannel added in v0.15.0 

func AsChannel[T any](ctx context.Context, seq iter.Seq[T]) (<-chan T, func() error)

AsChannel returns an unbuffered channel that receives all elements from the input sequence, and a stop function. The channel is closed when the sequence is exhausted, when ctx is canceled, or when stop is called, whichever happens first.

The producer goroutine starts immediately. Calling stop (which is safe to call any number of times, from any goroutine, including after the channel has closed) cancels the producer, waits for it to exit, and returns its final result. It blocks if seq itself is blocked without observing ctx. Callers that do not read the channel to completion should call stop, typically with defer.

A panic in seq is recovered in the producer goroutine: the channel is closed and stop (every call, since stop waits) returns an error describing it (errors.Is/As see the panic value), or nil if seq did not panic.

func AsGenerator 

func AsGenerator[T any](seq iter.Seq[T]) func(context.Context) (T, bool)

AsGenerator provides in inverse of the GenerateOk operation: the function will yield values. When the boolean "ok" value is false the sequence has been exhausted.

The sequence is consumed by a background goroutine, started on the first (non-cancelled) call with a context derived from that call's ctx; a nil ctx is treated as context.Background. AsGenerator cannot detect that the caller has stopped calling the function, so callers that abandon the generator before exhaustion must cancel the ctx they passed to the first call to release the goroutine. Cancelling the ctx of a later call only aborts that call; the stream continues.

A panic in seq is recovered in the background goroutine and re-raised (with the original value) in the caller that observes the end of the stream, once; later calls return false.

func Cast added in v0.14.8 

func Cast[T, U any](seq iter.Seq[T]) iter.Seq[U]

Cast returns a sequence of U by performing a type assertion on each element of seq. Because all elements of a sequence share the same type, a failed assertion means no element can satisfy the cast, so iteration stops immediately on the first failure.

func Cast2 added in v0.14.8 

func Cast2[A, B, C, D any](seq iter.Seq2[A, B]) iter.Seq2[C, D]

Cast2 returns an iterator of (C, D) pairs by performing type assertions on the keys and values of seq independently. A failed key assertion stops iteration immediately; a failed value assertion likewise stops iteration immediately. Because all keys share one type and all values share another, a single failure predicts all subsequent failures for that position.

func Chain 

func Chain[T any](seq iter.Seq[iter.Seq[T]]) iter.Seq[T]

Chain flattens a sequence of sequences into a single sequence.

func Chain2 

func Chain2[A, B any](seq iter.Seq[iter.Seq2[A, B]]) iter.Seq2[A, B]

Chain2 flattens a sequence of pair sequences into a single pair sequence. Like Chain, nil inner sequences are skipped.

func ChainMaps 

func ChainMaps[A comparable, B any, M ~map[A]B](seq iter.Seq[M]) iter.Seq2[A, B]

ChainMaps flattens a sequence of maps into a single sequence.

func ChainSlices 

func ChainSlices[T any, S ~[]T](seq iter.Seq[S]) iter.Seq[T]

ChainSlices flattens a sequence of slices into a single sequence.

func Channel 

func Channel[T any](ctx context.Context, ch <-chan T) iter.Seq[T]

Channel returns a sequence that yields elements from the provided channel until the channel is closed or the context is canceled.

func Chunk 

func Chunk[T any](seq iter.Seq[T], num int) iter.Seq[iter.Seq[T]]

Chunk returns a sequence of sequences, where each inner sequence contains at most num elements from the input sequence. If num <= 0, the sequence is empty.

Chunk pulls from seq lazily and each inner sequence shares that pull and its countdown with the outer loop: inner sequences must be fully consumed (or abandoned) before the outer loop advances, and on the same goroutine. Consuming an inner sequence from another goroutine after the outer loop has moved on races on the countdown and pulls concurrently.

func Collect 

func Collect[T any](seq iter.Seq[T], args ...int) (s []T)

Collect consumes the sequence and returns a slice of all elements. This combines the operations slices.Collect and make([]T).

Unlike you can only set the capacity, not the initial length. For compatibility, you can specify more than one integer arguments, though ONLY one can be non-zero. If you specify a capacity argument that is less than zero, it becomes zero.

func Collect2 

func Collect2[K comparable, V any](seq iter.Seq2[K, V], args ...int) map[K]V

Collect2 consumes the sequence and returns a map with all elements. This combines the operations maps.Collect and make(map[K]V).

Like make(map[K]V), the optional args are args[0] sets initial length.

func CollectFirstN 

func CollectFirstN[T any](seq iter.Seq[T], n int) []T

CollectFirstN consumes up to n elements from the sequence and returns them as a slice. If n <= 0, returns an empty slice.

func Contains 

func Contains[T comparable](seq iter.Seq[T], cmp T) (ok bool)

Contains returns true if the sequence contains an element equal to cmp. Iteration stops as soon as a match is found.

func Convert 

func Convert[A, B any, OP ~func(A) B](seq iter.Seq[A], op OP) iter.Seq[B]

Convert returns a sequence where each element is the result of applying op to the elements of the input sequence.

func Convert2 

func Convert2[A, B, C, D any, OP ~func(A, B) (C, D)](seq iter.Seq2[A, B], op OP) iter.Seq2[C, D]

Convert2 returns a iterator where each pair is the result of applying op to the pairs of the input iterator.

func Count 

func Count[T any](seq iter.Seq[T]) (size int)

Count consumes the sequence and returns the total number of elements.

func Count2 

func Count2[A, B any](seq iter.Seq2[A, B]) (size int)

Count2 consumes the iterator and returns the total number of pairs.

func Deref 

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

Deref returns a sequence of values dereferenced from the input sequence of pointers. Nil pointers in the input sequence are skipped.

func DerefWithZeros 

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

DerefWithZeros returns a sequence of values dereferenced from the input sequence of pointers. Nil pointers in the input sequence result in the zero value for the type.

func Equal 

func Equal[T comparable](rh iter.Seq[T], lh iter.Seq[T]) bool

Equal returns true if the two sequences contain the same elements in the same order.

func Final added in v0.14.5 

func Final[T any](seq iter.Seq[T]) (out T, ok bool)

Final returns the last value from the sequence and true. If the sequence is empty, it returns the zero value and false.

func Final2 added in v0.14.5 

func Final2[A, B any](seq iter.Seq2[A, B]) (aout A, bout B, ok bool)

Final2 returns the last pair of values from the iterator and true. If the sequence is empty, it returns zero values and false.

func First 

func First[A, B any](seq iter.Seq2[A, B]) iter.Seq[A]

First returns a sequence containing only the first element (key) of each pair in the input iterator.

func Flatten added in v0.14.9 

func Flatten[K, V any, S iter.Seq[V]](seq iter.Seq2[K, S]) iter.Seq2[K, V]

Flatten a sequence/mapping of key/value pairs where the value is a sequence, into a sequence of pairs to single values.

func FlattenSlice added in v0.14.9 

func FlattenSlice[K, V any, S ~[]V](seq iter.Seq2[K, S]) iter.Seq2[K, V]

FlattenSlice a sequence/mapping of key/value pairs where the value is a slice of values, into a sequence of pairs to single values.

func Flip 

func Flip[A, B any](seq iter.Seq2[A, B]) iter.Seq2[B, A]

Flip returns a iterator where the keys and values of the input sequence are swapped.

func Flush added in v0.14.8 

func Flush[T any](seq iter.Seq[T], yield func(T) bool) bool

Flush iterates seq, passing each value to yield. It returns false if yield signals early termination, and true if the sequence is exhausted normally. Flush is the core building block for composing iterators: use it inside an iter.Seq body to forward elements from one sequence into another yield function.

func Flush2 added in v0.14.8 

func Flush2[A, B any](seq iter.Seq2[A, B], yield func(A, B) bool) bool

Flush2 iterates seq, passing each key-value pair to yield. It returns false if yield signals early termination, and true if the sequence is exhausted normally. Flush2 is the iter.Seq2 counterpart to Flush: use it inside an iter.Seq2 body to forward pairs from one sequence into another yield function.

func ForEach 

func ForEach[T any, OP ~func(T)](seq iter.Seq[T], op OP) iter.Seq[T]

ForEach returns a sequence that calls op for each element of the input sequence during iteration.

func ForEach2 

func ForEach2[A, B any, OP ~func(A, B)](seq iter.Seq2[A, B], op OP) iter.Seq2[A, B]

ForEach2 returns a iterator that calls op for each pair of the input iterator during iteration.

func ForEachWhile 

func ForEachWhile[T any, OP ~func(T) bool](seq iter.Seq[T], op OP) iter.Seq[T]

ForEachWhile returns a sequence that calls op for each element of the input sequence. Iteration stops if op returns false.

func ForEachWhile2 

func ForEachWhile2[A, B any, OP ~func(A, B) bool](seq iter.Seq2[A, B], op OP) iter.Seq2[A, B]

ForEachWhile2 returns a iterator that calls op for each pair of the input iterator. Iteration stops if op returns false.

func Generate 

func Generate[T any, OP ~func() T](op OP) iter.Seq[T]

Generate returns an infinite sequence where each element is produced by calling op.

func Generate2 

func Generate2[A, B any, OP ~func() (A, B)](op OP) iter.Seq2[A, B]

Generate2 returns an infinite iterator where each pair is produced by calling op.

func GenerateN 

func GenerateN[T any, OP ~func() T](num int, op OP) iter.Seq[T]

GenerateN returns a sequence that yields exactly num elements produced by calling op. If num <= 0, the sequence is empty.

func GenerateOk 

func GenerateOk[T any, OP ~func() (T, bool)](gen OP) iter.Seq[T]

GenerateOk returns a sequence that yields values produced by gen as long as gen returns true.

func GenerateOk2 

func GenerateOk2[A, B any, OP ~func() (A, B, bool)](gen OP) iter.Seq2[A, B]

GenerateOk2 returns a iterator that yields pairs produced by gen as long as gen returns true.

func GenerateWhile 

func GenerateWhile[T any, OP ~func() T, CHECK ~func(T) bool](op OP, while CHECK) iter.Seq[T]

GenerateWhile returns a sequence that yields values produced by op as long as they satisfy the while predicate.

func GenerateWhile2 

func GenerateWhile2[A, B any, OP ~func() (A, B), WHILE ~func(A, B) bool](op OP, while WHILE) iter.Seq2[A, B]

GenerateWhile2 returns a iterator that yields pairs produced by op as long as they satisfy the while predicate.

func Group 

func Group[K comparable, V any](seq iter.Seq2[K, V]) iter.Seq2[K, []V]

Group consumes the iterator and groups values by their keys into a iterator of keys and slices of values.

func GroupBy 

func GroupBy[K comparable, V any, OP ~func(V) K](seq iter.Seq[V], groupBy OP) iter.Seq2[K, []V]

GroupBy consumes the sequence and groups elements into a iterator of keys and slices of values, using the groupBy function to determine the key for each element.

func HasValues added in v0.14.8 

func HasValues[T any](seq iter.Seq[T]) bool

HasValues returns true if any items are found in the iterator. Use this, potentially in combination with 'Keep()' and 'Remove' to implement arbitrary "contains"-type expressions.

func HasValues2 added in v0.14.8 

func HasValues2[A, B any](seq iter.Seq2[A, B]) bool

HasValues2 returns true if any items are found in the iterator. Use this, potentially in combination with 'Keep()' and 'Remove' to implement arbitrary "contains"-type expressions.

func Index 

func Index[T any](seq iter.Seq[T]) iter.Seq2[int, T]

Index returns a iterator where each element from the input sequence is paired with its 0-based index. Each iteration restarts at 0.

func Index2 added in v0.14.5 

func Index2[A, B any](seq iter.Seq2[A, B]) iter.Seq2[int, KV[A, B]]

Index2 returns a pair iterator where each element from the input sequence is paired with its 0-based index.

func Initial added in v0.14.5 

func Initial[T any](seq iter.Seq[T]) (zero T, ok bool)

Initial returns the first value from the sequence and true. If the sequence is empty, it returns the zero value and false.

func Initial2 added in v0.14.5 

func Initial2[A, B any](seq iter.Seq2[A, B]) (azero A, bzero B, ok bool)

Initial2 returns the first pair of values from the iterator and true. If the sequence is empty, it returns zero values and false.

func Join 

func Join[T any](seqs ...iter.Seq[T]) iter.Seq[T]

Join concatenates multiple sequences into a single sequence, yielding all elements from each sequence in order.

func Join2 

func Join2[A, B any](seqs ...iter.Seq2[A, B]) iter.Seq2[A, B]

Join2 concatenates multiple pair sequences into a single pair sequence, yielding all key-value pairs from each sequence in order.

func JoinErrors 

func JoinErrors(seq iter.Seq[error]) error

JoinErrors consumes a sequence of errors and returns a single error produced by errors.Join. Returns nil if the sequence is empty.

func JoinStrings added in v0.14.3 

func JoinStrings[S ~string](seq iter.Seq[S]) S

JoinStrings takes a sequence of strings and concatenates them. Uses a strings.Buffer to minimize allocation overhead.

func JoinStringsWith added in v0.14.3 

func JoinStringsWith[S, T ~string](seq iter.Seq[S], with T) S

JoinStringsWith concatenates a sequence of strings and returns one string, inserting `with` between elements. If an element in the iterator is the empty string, then an extra separator is not inserted.

func KVapply 

func KVapply[A, B any, OP ~func(A, B)](seq iter.Seq[KV[A, B]], op OP)

KVapply applies a function to each Elem in a sequence.

func KVargs 

func KVargs[A, B any](elems ...KV[A, B]) iter.Seq2[A, B]

KVargs takes a variadic sequence of KV args and returns a pair iterator.

func KVcmp 

func KVcmp[A, B cmp.Ordered](lh, rh KV[A, B]) int

KVcmp compares two Elem values by comparing both their First and Second fields.

func KVcmpFirst 

func KVcmpFirst[A cmp.Ordered, B any](lh, rh KV[A, B]) int

KVcmpFirst compares two Elem values by comparing only their First fields.

func KVcmpSecond 

func KVcmpSecond[A any, B cmp.Ordered](l, r KV[A, B]) int

KVcmpSecond compares two Elem values by comparing only their Second fields.

func KVjoin 

func KVjoin[A, B any](seq iter.Seq2[A, B]) iter.Seq[KV[A, B]]

KVjoin converts an iter.Seq2 into an iter.Seq of Elem pairs.

func KVmap added in v0.14.1 

func KVmap[A comparable, B any, M ~map[A]B](in M) iter.Seq[KV[A, B]]

KVmap converts a map into a sequence of KV pairs, and returns them as an iterator.

func KVsplit 

func KVsplit[A, B any](seq iter.Seq[KV[A, B]]) iter.Seq2[A, B]

KVsplit converts an iter.Seq of Elem pairs into an iter.Seq2.

func Keep 

func Keep[T any, OP ~func(T) bool](seq iter.Seq[T], prd OP) iter.Seq[T]

Keep returns a sequence containing only the elements from the input sequence that satisfy the predicate prd.

func Keep2 

func Keep2[A, B any, OP ~func(A, B) bool](seq iter.Seq2[A, B], prd OP) iter.Seq2[A, B]

Keep2 returns a iterator containing only the pairs from the input iterator that satisfy the predicate prd.

func KeepErrors 

func KeepErrors(seq iter.Seq[error]) iter.Seq[error]

KeepErrors returns a sequence containing only the non-nil errors from the input sequence.

func KeepOk 

func KeepOk[T any](seq iter.Seq2[T, bool]) iter.Seq[T]

KeepOk returns a sequence containing only the values from pairs where the boolean is true.

func Limit 

func Limit[T any](seq iter.Seq[T], n int) iter.Seq[T]

Limit returns a sequence that yields at most n elements from the input sequence. If n <= 0, the sequence is empty.

func Limit2 

func Limit2[A, B any](seq iter.Seq2[A, B], n int) iter.Seq2[A, B]

Limit2 returns a iterator that yields at most n pairs from the input iterator. If n <= 0, the sequence is empty.

func Map 

func Map[K comparable, V any, M ~map[K]V](mp M) iter.Seq2[K, V]

Map returns a iterator containing all key-value pairs from the map.

func MapKV added in v0.14.1 

func MapKV[A comparable, B any, M ~map[A]B](mp M) iter.Seq[KV[A, B]]

MapKV transforms a map into an iterator of KV pairs.

func MarshalBinary added in v0.14.3 

func MarshalBinary[T any](seq iter.Seq[T]) ([]byte, error)

MarshalBinary marshals a sequence to bytes by trying BinaryMarshaler, Marshal, MarshalBSON, or []byte conversions. Returns an error for unsupported types.

Per-element payloads are joined with a single newline ("\n") separator between elements; there is no leading or trailing separator, and a single-element sequence is emitted unchanged. The empty sequence produces a non-nil, empty byte slice. This format is NOT self-delimiting: if an element's marshaled payload itself contains a 0x0A (newline) byte, the output cannot be unambiguously split back into the original elements.

func MarshalJSON added in v0.14.3 

func MarshalJSON[T any](seq iter.Seq[T]) ([]byte, error)

MarshalJSON consumes a sequence and returns its JSON encoding as an array. Returns an error if any element fails to marshal.

func MarshalJSON2 added in v0.14.3 

func MarshalJSON2[A any, B any](seq iter.Seq2[A, B]) ([]byte, error)

MarshalJSON2 consumes a pair sequence with string keys and returns its JSON encoding as an object. Keys are encoded by the Go 1.25 encoding/json key rules on every toolchain (see encodeJSONKey), so output does not change with the Go version. Returns an error if any element fails to marshal.

func MarshalJSONL added in v0.14.10 

func MarshalJSONL[T any](seq iter.Seq[T]) ([]byte, error)

MarshalJSONL encodes a sequence in JSON Lines format: one JSON value per line, with each line terminated by a newline character. Returns an error if any element fails to marshal.

func MarshalText added in v0.14.3 

func MarshalText[T any](seq iter.Seq[T]) ([]byte, error)

MarshalText marshals a sequence to bytes by trying TextMarshaler, JSONMarshaler, MarshalYAML, Marshal, string/[]byte conversions, or falling back to JSON encoding.

Per-element payloads are joined with a single newline ("\n") separator between elements; there is no leading or trailing separator, and a single-element sequence is emitted unchanged. The empty sequence produces a non-nil, empty byte slice.

func MarshalToJSON added in v0.14.10 

func MarshalToJSON[T any](seq iter.Seq[T], w io.Writer) error

MarshalToJSON encodes a sequence as a JSON array, writing directly to w. Returns an error if any element fails to marshal or if the writer fails. Callers that need buffered output should wrap w in a bufio.Writer.

func MarshalToJSON2 added in v0.14.10 

func MarshalToJSON2[K any, V any](seq iter.Seq2[K, V], w io.Writer) error

MarshalToJSON2 encodes a pair sequence as a JSON object, writing directly to w. Returns an error if any key or value fails to marshal or if the writer fails. Callers that need buffered output should wrap w in a bufio.Writer.

func MarshalToJSONL added in v0.14.10 

func MarshalToJSONL[T any](seq iter.Seq[T], w io.Writer) error

MarshalToJSONL encodes a sequence in JSON Lines format, writing directly to w. Each element is written as a JSON value followed by a newline. Returns an error if any element fails to marshal or if the writer fails. Callers that need buffered output should wrap w in a bufio.Writer.

func Merge 

func Merge[A, B, C any, OP ~func(A, B) C](seq iter.Seq2[A, B], op OP) iter.Seq[C]

Merge returns a sequence where each element is the result of applying op to the pairs of the input iterator.

func Modify 

func Modify[T any, OP ~func(T) T](seq iter.Seq[T], op OP) iter.Seq[T]

Modify applies a transformation function to each element in the sequence. If the operation is nil, the sequence is returned unchanged.

func Modify2 

func Modify2[A, B any, OP ~func(A, B) (A, B)](seq iter.Seq2[A, B], op OP) iter.Seq2[A, B]

Modify2 applies a transformation function to each pair in the sequence. If the operation is nil, the sequence is returned unchanged.

func ModifyAll 

func ModifyAll[T any, OP ~func(T) T](seq iter.Seq[T], ops ...OP) iter.Seq[T]

ModifyAll applies a sequence of transformation functions to each element in the sequence. Nil modification functions are skipped. Each transformation is applied in order, with the result of one transformation passed to the next.

func ModifyAll2 

func ModifyAll2[A, B any](seq iter.Seq2[A, B], ops ...func(A, B) (A, B)) iter.Seq2[A, B]

ModifyAll2 applies a sequence of transformation functions to each pair in the sequence. Nil functions are filtered out and skipped. Each transformation is applied in order, with the result of one transformation passed to the next.

func Monotonic 

func Monotonic() iter.Seq[int]

Monotonic returns an infinite sequence of integers starting from 1.

The sequence is re-iterable: each iteration starts again from 1.

func MonotonicFrom 

func MonotonicFrom[T ~int](start T) iter.Seq[T]

MonotonicFrom returns an infinite sequence of integers starting from start. Each iteration starts again from start.

func Mutable added in v0.14.5 

func Mutable[T any, S ~[]T](sl S) iter.Seq[*T]

Mutable takes a slice, and returns an iterator over pointers to the elements in the slice. Mutations to elements during iteration impact the underlying slice, and may be observable outside of the scope of this iterator.

func One 

func One[T any](v T) iter.Seq[T]

One returns a sequence containing exactly one element.

func OrEmpty added in v0.14.6 

func OrEmpty[T any](seq iter.Seq[T]) iter.Seq[T]

OrEmpty returns a noop (empty) sequence if the input sequence is nil, and returns the sequence otherwise.

func OrEmpty2 added in v0.14.6 

func OrEmpty2[A, B any](seq iter.Seq2[A, B]) iter.Seq2[A, B]

OrEmpty2 returns a noop (empty) sequence if the input sequence is nil, and returns the sequence otherwise.

func Pipe deprecated 

func Pipe[T any](ctx context.Context, seq iter.Seq[T]) <-chan T

Pipe returns a channel that receives all elements from the input sequence. The channel is closed when the sequence is exhausted or the context is canceled.

The producer goroutine starts immediately and, because Pipe returns a plain channel, cannot observe a consumer that stops reading: if you stop receiving before the channel is closed you must cancel ctx, or the producer goroutine blocks forever.

Deprecated: Pipe offers no way to release the producer other than cancelling ctx. Use AsChannel, which returns a stop function, or WithBuffer, which releases its producer when the consumer stops iterating.

func Pool added in v0.14.13 

func Pool[A, B any, OP ~func(A) B](ctx context.Context, num int, seq iter.Seq[A], op OP) iter.Seq[B]

Pool iterates seq and applies op to each element using a pool of num goroutines, merging the results into a single output sequence. op runs outside the input lock, so it executes in parallel across workers; only pulling the raw element from seq is serialized. Output order is not preserved.

Workers run on their own goroutines, but a panic in op, in the loop body consuming the output, or in seq is recovered and re-raised on the goroutine that is iterating the result, after the workers stop. The loop body is invoked by workers (serialized), not necessarily on the iterating goroutine.

ctx is checked before every pull, so a canceled context stops the pool without consuming further input; cancellation is silent. ctx cannot interrupt a pull that is already blocked: seq must itself honor ctx (for example by being built from a channel with Channel and the same ctx) if it can block. num is clamped to at least 1.

func Pool2 added in v0.14.15 

func Pool2[A, B, C, D any, OP ~func(A, B) (C, D)](ctx context.Context, num int, seq iter.Seq2[A, B], op OP) iter.Seq2[C, D]

Pool2 is the iter.Seq2 counterpart to Pool: it iterates seq and applies op to each pair using a pool of num goroutines, merging the results into a single output pair sequence.

func Pool3 added in v0.14.15 

func Pool3[A, B, C any, OP ~func(A) (B, C)](ctx context.Context, num int, seq iter.Seq[A], op OP) iter.Seq2[B, C]

Pool3 is the pooled counterpart to With2: it iterates seq and applies op to each element using a pool of num goroutines, merging the resulting pairs into a single output pair sequence. op runs outside the input lock, so it executes in parallel across workers; only pulling the raw element from seq is serialized. num is clamped to at least 1. Panic propagation and context handling are the same as for Pool: seq must honor ctx if it can block.

func Ptrs 

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

Ptrs returns a sequence where each element is a pointer to the value in the input sequence.

func PtrsWithNils 

func PtrsWithNils[T comparable](seq iter.Seq[T]) iter.Seq[*T]

PtrsWithNils returns a sequence of pointers to the values in the input sequence. If a value is the zero value for its type, a nil pointer is produced instead.

func Range 

func Range[T ~int](start T, end T) iter.Seq[T]

Range returns a sequence of integers from start to end (inclusive). The sequence is re-iterable, and end may be the maximum int value.

func ReadLines 

func ReadLines(reader io.Reader) iter.Seq[string]

ReadLines returns a sequence of strings from the reader, with one item for every line, stopping when the reader is exhausted at the first error.

func ReadLinesErr 

func ReadLinesErr(reader io.Reader) iter.Seq2[string, error]

ReadLinesErr returns a iterator of strings and errors from the reader. It yields each line with a nil error, and finally yields an empty string and the scanner's error.

func ReadWords added in v0.14.5 

func ReadWords(reader io.Reader) iter.Seq[string]

ReadWords returns a sequence of strings from the reader, with one item for every word, stopping at the first error.

func ReadWordsErr added in v0.14.5 

func ReadWordsErr(reader io.Reader) iter.Seq2[string, error]

ReadWordsErr returns a iterator of strings and errors from the reader. It yields each line with a nil error, and finally yields an empty string and the scanner's error.

func Reduce 

func Reduce[A, B any, OP ~func(B, A) B](seq iter.Seq[A], rfn OP) (out B)

Reduce consumes the sequence and reduces it to a single value by repeatedly applying rfn.

func Reduce2 added in v0.14.1 

func Reduce2[A, B, C any, OP ~func(C, A, B) C](seq iter.Seq2[A, B], rfn OP) (out C)

Reduce2 consumes a sequence o pairs and reduces it to a single value by repeatedly applying rfn.

func Remove 

func Remove[T any, OP ~func(T) bool](seq iter.Seq[T], prd OP) iter.Seq[T]

Remove returns a sequence containing only the elements from the input sequence that do NOT satisfy the predicate prd.

func Remove2 

func Remove2[A, B any, OP ~func(A, B) bool](seq iter.Seq2[A, B], prd OP) iter.Seq2[A, B]

Remove2 returns a iterator containing only the pairs from the input iterator that do NOT satisfy the predicate prd.

func RemoveErrors 

func RemoveErrors[T any](seq iter.Seq2[T, error]) iter.Seq[T]

RemoveErrors returns a sequence containing only the values from pairs where the error is nil.

func RemoveNils 

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

RemoveNils returns a sequence containing all non-nil pointers from the input sequence.

func RemoveValue added in v0.14.7 

func RemoveValue[T comparable](seq iter.Seq[T], to T) iter.Seq[T]

RemoveValue returns a sequence with all values equal to the provided values removed.

func RemoveZeros 

func RemoveZeros[T comparable](seq iter.Seq[T]) iter.Seq[T]

RemoveZeros returns a sequence containing all non-zero values from the input sequence.

func Resolve added in v0.14.2 

func Resolve[T any, F ~func() T](seq iter.Seq[F]) iter.Seq[T]

Resolve returns a sequence that lazily executes each function in the input sequence and yields the results. Functions are only called during iteration.

func Resolve2 added in v0.14.2 

func Resolve2[A, B any, F ~func() (A, B)](seq iter.Seq[F]) iter.Seq2[A, B]

Resolve2 returns a pair sequence that lazily executes each function in the input sequence and yields the result pairs. Functions are only called during iteration.

func ResolveWrap added in v0.14.2 

func ResolveWrap[A, B any, F ~func(A) B](seq iter.Seq[F], wrapping A) iter.Seq[B]

ResolveWrap returns a sequence that lazily executes each function in the input sequence with the provided argument and yields the results. Functions are only called during iteration.

func ResolveWrap2 added in v0.14.2 

func ResolveWrap2[A, B, C any, F ~func(A) (B, C)](seq iter.Seq[F], wrapping A) iter.Seq2[B, C]

ResolveWrap2 returns a pair sequence that lazily executes each function in the input sequence with the provided argument and yields the result pairs. Functions are only called during iteration.

func Reverse added in v0.14.5 

func Reverse[T any](seq iter.Seq[T]) iter.Seq[T]

Reverse collects the elements from an iterator and returns an iterator in reverse order. The contents of the iterator must be materialized first.

func ReverseMapping added in v0.14.9 

func ReverseMapping[A, B any](seq iter.Seq2[A, []B]) iter.Seq2[B, A]

ReverseMapping expands a mapping of keys to slices of values to a mapping of values to keys. Values may appear more than once in the output sequence.

func RunAll 

func RunAll[OP ~func()](seq iter.Seq[OP]) (count int)

RunAll takes a sequences of nilary functions and runs them all, returning a count. If any functions are Nil. For other function types, and for nil/panic safety, use the operations in the wpa package.

func Second 

func Second[A, B any](seq iter.Seq2[A, B]) iter.Seq[B]

Second returns a sequence containing only the second element (value) of each pair in the input iterator.

func Shard 

func Shard[T any](ctx context.Context, num int, seq iter.Seq[T]) iter.Seq[iter.Seq[T]]

Shard splits the input sequence into num separate sequences. All num "shards" alias the same mutex-guarded shared iterator, so elements are distributed dynamically across whichever shard is consumed fastest, not as a static partition. A shard that stops early does not affect the others: the shared iterator is released when the input is exhausted, when every shard has finished, or when ctx is canceled, even if some shards never started or never finish, and when the outer loop stops early. num is clamped to at least 1. Once ctx is canceled, every shard stops yielding new elements, the same way Pool's workers do.

func Shard2 added in v0.14.15 

func Shard2[A, B any](ctx context.Context, num int, seq iter.Seq2[A, B]) iter.Seq[iter.Seq2[A, B]]

Shard2 is the iter.Seq2 counterpart to Shard: it splits the input pair sequence into num separate pair sequences. Pairs are distributed.

func Sink added in v0.14.15 

func Sink[T any](yield func(T) bool) func(T) bool

Sink wraps yield so that concurrent workers can share it safely: calls are serialized by an internal mutex, and once yield returns false, every subsequent call - from any worker, forever after - short- circuits to false instead of invoking yield again, satisfying the range-over-func rule that yield must never be called after it has returned false. Pair with WithMutex (or another input-side lock) to merge multiple producers back into a single consumer, as Pool and Pool3 do.

func Sink2 added in v0.14.15 

func Sink2[A, B any](yield func(A, B) bool) func(A, B) bool

Sink2 is the iter.Seq2 counterpart to Sink: it wraps a pair yield function so that concurrent workers can share it safely.

func Slice 

func Slice[T any, S ~[]T](sl S) iter.Seq[T]

Slice returns a sequence containing all elements from the slice.

func Sort added in v0.14.4 

func Sort[T cmp.Ordered](seq iter.Seq[T]) iter.Seq[T]

Sort collects the elements in an iterator, sorts them, and then returns an iterator in ascending order.

func Sort1 added in v0.14.4 

func Sort1[A cmp.Ordered, B any](seq iter.Seq2[A, B]) iter.Seq2[A, B]

Sort1 collects the KV pairs from the iterator, sorts them by comparing only the first value, and returns an iterator in ascending order.

func Sort2 added in v0.14.4 

func Sort2[A, B cmp.Ordered](seq iter.Seq2[A, B]) iter.Seq2[A, B]

Sort2 collects the KV pairs from the iterator, sorts them by comparing the first value then the second value as a tiebreaker, and returns an iterator in ascending order.

func SortBy 

func SortBy[K cmp.Ordered, T any, OP ~func(T) K](seq iter.Seq[T], cf OP) iter.Seq[T]

SortBy consumes the sequence, sorts it based on the keys produced by the comparison function, cf, and returns a new sequence of the sorted elements.

func SortBy2 

func SortBy2[K cmp.Ordered, A, B any, OP ~func(A, B) K](seq iter.Seq2[A, B], cf OP) iter.Seq2[A, B]

SortBy2 consumes the iterator, sorts it based on the keys produced by cf, and returns a new iterator of the sorted pairs.

func SortFunc added in v0.14.8 

func SortFunc[T any, OP ~func(T, T) int](seq iter.Seq[T], cf OP) iter.Seq[T]

SortFunc consumes the sequence, sorts it using the provided cmp.Compare-style comparison function, and returns a new sorted sequence.

func SortFunc2 added in v0.14.8 

func SortFunc2[A, B any, OP ~func(A, B, A, B) int](seq iter.Seq2[A, B], cf OP) iter.Seq2[A, B]

SortFunc2 consumes the iterator, sorts its pairs using the provided cmp.Compare-style comparison function, and returns a new sorted iterator.

func Two 

func Two[A, B any](a A, b B) iter.Seq2[A, B]

Two returns a iterator containing exactly one pair of elements.

func Unique 

func Unique[T comparable](seq iter.Seq[T]) iter.Seq[T]

Unique returns a sequence containing only the first occurrence of each unique element from the input sequence.

func UniqueBy 

func UniqueBy[K comparable, V any, OP ~func(V) K](seq iter.Seq[V], kfn OP) iter.Seq[V]

UniqueBy returns a sequence containing only the first occurrence of each element from the input sequence that produces a unique key when passed to kfn.

func UnmarshalJSON added in v0.14.3 

func UnmarshalJSON[T any](data io.Reader) iter.Seq2[T, error]

UnmarshalJSON decodes a JSON stream from a reader and yields each element with a potential error. The reader is wrapped with bufio for efficient reading.

func UnmarshalJSON2 added in v0.14.3 

func UnmarshalJSON2[A any, B any](data io.Reader) iter.Seq2[KV[A, B], error]

UnmarshalJSON2 decodes a JSON object from the reader and yields each key-value pair as KV with a potential error. The reader is wrapped with bufio for efficient reading.

func Until 

func Until[T any, OP ~func(T) bool](seq iter.Seq[T], prd OP) iter.Seq[T]

Until returns a sequence that yields elements from the input sequence until the predicate prd returns true.

func Until2 

func Until2[A, B any, OP ~func(A, B) bool](seq iter.Seq2[A, B], is OP) iter.Seq2[A, B]

Until2 returns a iterator that yields pairs from the input iterator until the predicate is returns true.

func UntilError 

func UntilError[T any](seq iter.Seq2[T, error]) iter.Seq[T]

UntilError returns a sequence of values from pairs, stopping when a non-nil error is encountered.

func UntilNil 

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

UntilNil returns a sequence of dereferenced values from the input sequence of pointers, stopping when a nil pointer is encountered.

func While 

func While[T any, OP ~func(T) bool](seq iter.Seq[T], prd OP) iter.Seq[T]

While returns a sequence that yields elements from the input sequence as long as the predicate prd returns true.

func While2 

func While2[A, B any, OP ~func(A, B) bool](seq iter.Seq2[A, B], prd OP) iter.Seq2[A, B]

While2 returns a iterator that yields pairs from the input iterator as long as the predicate prd returns true.

func WhileOk 

func WhileOk[T any](seq iter.Seq2[T, bool]) iter.Seq[T]

WhileOk returns a sequence that yields values from pairs as long as the boolean is true.

func WhileSuccess 

func WhileSuccess[T any](seq iter.Seq2[T, error]) iter.Seq[T]

WhileSuccess returns a sequence that yields values from pairs as long as the error is nil.

func With 

func With[A, B any, OP ~func(A) B](seq iter.Seq[A], op OP) iter.Seq2[A, B]

With returns a iterator where each element from the input sequence is paired with the result of applying op to it.

func With2 

func With2[A, B, C any, OP ~func(A) (B, C)](seq iter.Seq[A], op OP) iter.Seq2[B, C]

With2 returns a iterator where each pair is produced by applying op to each element of the input sequence.

func With3 

func With3[A, B, C any, OP ~func(A) (B, C)](seq iter.Seq[A], op OP) iter.Seq2[KV[A, B], C]

With3 returns a iterator where each pair is produced by applying op to each element of the input sequence.

func WithBuffer 

func WithBuffer[T any](ctx context.Context, seq iter.Seq[T], size int) iter.Seq[T]

WithBuffer maintains a buffer of items read from the source iterator, waiting for downstream consumers of the output iterator, to consume them. The producer goroutine is released when the consumer stops iterating, as well as when ctx is canceled. A panic in the source is re-raised on the consuming goroutine once the buffered items have been consumed.

func WithEach 

func WithEach[A, B any, OP ~func() B](seq iter.Seq[A], op OP) iter.Seq2[A, B]

WithEach returns a iterator where each element from the input sequence is paired with a value produced by calling op.

func WithHooks 

func WithHooks[T any](seq iter.Seq[T], before func(), after func()) iter.Seq[T]

WithHooks returns a sequence that calls before() when iteration starts and after() when iteration ends. after() is called even if iteration stops early. Nil hooks are ignored.

func WithMutex 

func WithMutex[T any](seq iter.Seq[T], mtx *sync.Mutex) iter.Seq[T]

WithMutex returns a sequence that synchronizes all calls to the underlying iterator using the provided mutex.

All the WithMutex, WithRMutex and WithWMutex variants (and their pair forms) are single-use: the underlying iter.Pull is created eagerly and is stopped when the first iteration of the result ends, so any later iteration yields nothing. Concurrent iterations share the one underlying iterator.

func WithMutex2 

func WithMutex2[A, B any](seq iter.Seq2[A, B], mtx *sync.Mutex) iter.Seq2[A, B]

WithMutex2 returns a pair sequence that synchronizes all calls to the underlying iterator using the provided mutex.

func WithRMutex added in v0.14.7 

func WithRMutex[T any](seq iter.Seq[T], mtx *sync.RWMutex) iter.Seq[T]

WithRMutex returns a sequence that synchronizes all calls to the underlying iterator using the provided readers/writer mutex. Locks the mutex for reading (shared) while advancing the iterator.

func WithRMutex2 added in v0.14.7 

func WithRMutex2[A, B any](seq iter.Seq2[A, B], mtx *sync.RWMutex) iter.Seq2[A, B]

WithRMutex2 returns a pair sequence that synchronizes all calls to the underlying iterator using the provided readers/writer mutex. Locks the mutex for reading (shared) while advancing the iterator.

func WithSetup 

func WithSetup[T any](seq iter.Seq[T], setup func()) iter.Seq[T]

WithSetup returns a sequence that calls setup() exactly once when iteration starts for the first time.

func WithWMutex added in v0.14.7 

func WithWMutex[T any](seq iter.Seq[T], mtx *sync.RWMutex) iter.Seq[T]

WithWMutex returns a sequence that synchronizes all calls to the underlying iterator using the provided readers/writer mutex. Locks the mutex for writing (exclusive) while advancing the iterator.

func WithWMutex2 added in v0.14.7 

func WithWMutex2[A, B any](seq iter.Seq2[A, B], mtx *sync.RWMutex) iter.Seq2[A, B]

WithWMutex2 returns a pair sequence that synchronizes all calls to the underlying iterator using the provided readers/writer mutex. Locks the mutex for writing (exclusive) while advancing the iterator.

func Zero added in v0.14.6 

func Zero[T any]() iter.Seq[T]

Zero returns a sequence that never yeilds any elements.

func Zero2 added in v0.14.6 

func Zero2[A, B any]() iter.Seq2[A, B]

Zero2 returns a two element sequence that never yields any elements.

func Zip 

func Zip[A, B any](rh iter.Seq[A], lh iter.Seq[B]) iter.Seq2[A, B]

Zip returns a iterator that pairs elements from rh and lh. Iteration stops when either sequence is exhausted.

Types

type KV 

type KV[A, B any] struct {
	Key   A
	Value B
}

KV is a generic pair type that holds two values of potentially different types.

func MakeKV 

func MakeKV[A, B any](a A, b B) KV[A, B]

MakeKV creates a KV from two values.

func WithKV 

func WithKV[A, B any, OP ~func(A) B](a A, with OP) KV[A, B]

WithKV creates a KV by applying a function to the first value to derive the second value.

func (KV[A, B]) Apply 

func (e KV[A, B]) Apply(op func(A, B))

Apply calls the provided function with the First and Second values of the Elem.

func (KV[A, B]) Compare 

func (e KV[A, B]) Compare(aop func(A, A) int, bop func(B, B) int) interface{ With(KV[A, B]) int }

Compare returns a comparator that compares both First and Second fields using the provided comparison functions.

func (KV[A, B]) CompareFirst 

func (e KV[A, B]) CompareFirst(aop func(A, A) int) interface{ With(KV[A, B]) int }

CompareFirst returns a comparator that compares only the First field using the provided comparison function.

func (KV[A, B]) CompareSecond 

func (e KV[A, B]) CompareSecond(bop func(B, B) int) interface{ With(KV[A, B]) int }

CompareSecond returns a comparator that compares only the Second field using the provided comparison function.

func (KV[A, B]) Split 

func (e KV[A, B]) Split() (A, B)

Split returns the First and Second values of an Elem as separate return values.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.