Documentation
¶
Overview ¶
Package stream provides an immutable, lazy sequence abstraction that makes it easy to build and compose pipelines over slices and iterators.
A Stream wraps Go's iter.Seq[T] protocol and provides a chainable API of intermediate operations such as Filter, Map, FlatMap, Limit, Skip, and Sort that return new Streams, and terminal operations such as Slice, All, Find, Reduce, and ReduceFrom that execute the pipeline and produce a result.
Streams are lazy: intermediate operations only describe how to transform the data and perform no work until a terminal operation consumes them. The pipeline is also short-circuiting, so operations like Limit and Find stop iterating the upstream sequence as soon as enough elements have been seen.
Create a Stream from a slice with Of, or from any iterator with New:
s := stream.Of([]int{1, 2, 3, 4, 5}).
Filter(func(i int) bool { return i > 2 }).
Map(func(i int) string { return fmt.Sprintf("item-%d", i) }).
Slice()
See the Stream type documentation for the full list of operations.
Index ¶
- type Stream
- func (s *Stream[T]) All() iter.Seq[T]
- func (s *Stream[T]) Filter(fn func(T) bool) *Stream[T]
- func (s *Stream[T]) Find(fn func(T) bool) (T, bool)
- func (s *Stream[T]) FlatMap[R any](fn func(T) []R) *Stream[R]
- func (s *Stream[T]) Limit(limit int) *Stream[T]
- func (s *Stream[T]) Map[R any](fn func(T) R) *Stream[R]
- func (s *Stream[T]) Reduce[R any](fn func(R, T) R) R
- func (s *Stream[T]) ReduceFrom[R any](accumulator R, fn func(R, T) R) R
- func (s *Stream[T]) Skip(skip int) *Stream[T]
- func (s *Stream[T]) Slice() []T
- func (s *Stream[T]) Sort(cmp func(a, b T) int) *Stream[T]
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Stream ¶
type Stream[T any] struct { // contains filtered or unexported fields }
Stream is a lazy sequence of elements of type T.
Streams wrap Go's iter.Seq[T] protocol and expose a chainable API. Use Of to create a Stream from a slice or New to create one from an arbitrary iterator. Intermediate operations (Filter, Map, FlatMap, Limit, Skip, Sort) return new Streams without doing any work, while terminal operations (Slice, All, Find, Reduce, ReduceFrom) execute the pipeline and produce a result.
Example ¶
s := Of([]int{1, 2, 3, 4, 5}).
Filter(func(i int) bool {
return i > 2
}).
Skip(1).
Map(func(i int) string {
return fmt.Sprintf("item-%d", i)
}).
Slice()
fmt.Println(s)
Output: [item-4 item-5]
func New ¶
New returns a Stream that yields the elements of seq.
Use New to turn any iter.Seq[T] iterator, such as a generator function, into a Stream. Prefer Of when building a Stream from a slice.
func Of ¶
Of returns a Stream that yields the elements of s.
The Stream holds a reference to s rather than a copy, so Slice on the resulting Stream returns the same underlying array and any mutations are shared with the caller's slice.
func (*Stream[T]) All ¶
All returns the underlying sequence as an iter.Seq[T] iterator.
All is a terminal operation; iterating the returned sequence runs the pipeline. It can be used with a for-range loop when a Stream is not needed.
func (*Stream[T]) Filter ¶
Filter returns a new Stream containing only the elements for which fn returns true.
Filter is an intermediate operation and is evaluated lazily as the returned Stream is iterated. It only consumes upstream elements until the consumer stops iterating.
func (*Stream[T]) Find ¶
Find returns the first element for which fn returns true and whether such an element was found.
Find is a terminal operation that executes the pipeline and stops as soon as the first matching element is seen. If no element matches, it returns the zero value of T and false.
func (*Stream[T]) FlatMap ¶
FlatMap returns a new Stream containing the elements of each slice produced by applying fn to every element of the original Stream.
FlatMap is an intermediate operation and is evaluated lazily. The results are concatenated in order, and a function call that returns an empty slice contributes no elements.
func (*Stream[T]) Limit ¶
Limit returns a new Stream containing at most the first limit elements of the original Stream.
Limit is an intermediate operation and is evaluated lazily. It stops consuming the upstream sequence as soon as limit elements have been yielded. A limit of zero yields nothing.
func (*Stream[T]) Map ¶
Map returns a new Stream containing the results of applying the function fn to each element in the original Stream.
The mapping function is evaluated lazily as the returned Stream is iterated. If the target sequence iteration is halted early by the consumer, mapping stops immediately.
func (*Stream[T]) Reduce ¶
Reduce combines the elements of the Stream into a single value of type R by applying fn to an accumulator and each element in order.
Reduce is a terminal operation that starts with the zero value of R as the initial accumulator, so it returns the zero value for an empty Stream. Use ReduceFrom to start from a different accumulator.
func (*Stream[T]) ReduceFrom ¶
ReduceFrom combines the elements of the Stream into a single value by applying fn to the accumulator and each element in order, starting from the given initial accumulator.
ReduceFrom is a terminal operation. For an empty Stream it returns the supplied accumulator unchanged.
func (*Stream[T]) Skip ¶
Skip returns a new Stream containing all elements of the original Stream except the first skip elements.
Skip is an intermediate operation and is evaluated lazily. Skipping zero elements yields everything, and skipping at least as many elements as the Stream contains yields nothing.
func (*Stream[T]) Slice ¶
func (s *Stream[T]) Slice() []T
Slice returns the elements of the Stream as a slice.
Slice executes the pipeline and collects its output. It is a terminal operation. If the Stream was created with Of and has not been transformed, the original slice is returned without copying.
func (*Stream[T]) Sort ¶
Sort returns a new Stream containing the elements of the original Stream sorted according to the three-way comparison function cmp. cmp should return a negative value when a is less than b, zero when they are equal, and a positive value when a is greater than b.
Unlike the other intermediate operations, Sort is eager: it consumes the original Stream and sorts the collected elements at the time it is called, rather than when the returned Stream is iterated.
Source Files