README
¶
Go iterator helper suite
Type safe Stream processing library inspired in the Gosequence library, which at the same time is heavily inspired in the Java Streams API.
Table of contents
Requirements
- Go 1.24 or higher
Usage examples
Example 1: basic creation, transformation and iteration
- Creates a literal iter.Seq containing all the integers from 1 to 11.
- From the sequence, selects all the integers that are prime
- Iterates the sequence. For each filtered int, prints a message.
import (
"fmt"
"github.com/mariomac/iters"
)
func main() {
numbers := iters.OfRange(1, 12)
for n := range iters.Filter(numbers, isPrime) {
fmt.Printf("%d is a prime number\n", n)
}
}
func isPrime(n int) bool {
for i := 2; i <= n/2; i++ {
if n%i == 0 {
return false
}
}
return true
}
Output:
1 is a prime number
2 is a prime number
3 is a prime number
5 is a prime number
7 is a prime number
11 is a prime number
Alternatively, you can use the ForEach method to iterate the sequence in a functional way:
iters.ForEach(prime, func(n int) {
fmt.Printf("%d is a prime number\n", n)
})
Example 2: generation, map, limit and slice conversion
- Creates an infinite sequence of random integers (no problem, the generated sequences are evaluated lazily!)
- Divides the random integer to get a number between 1 and 6
- Limits the infinite sequence to 5 elements.
- Collects the sequence items as a slice.
rnd := rand.New(rand.NewSource(time.Now().UnixMilli()))
fmt.Println("let me throw 5 times a dice for you")
results := iters.Map(
iters.Generate(rnd.Int),
func(n int) int {
return n%6 + 1
},
)
takeFive := iters.Limit(5, results)
fmt.Printf("results: %v\n",
slices.Collect(takeFive))
Output:
let me throw 5 times a dice for you
results: [3 5 2 1 3]
Example 3: Generation from an iterator, Map to a different type
- Generates an infinite sequence composed by
1,double(1),double(double(1)), etc... and cut it to 6 elements. - Maps the numbers' sequence to a strings' sequence.
- Converts the words sequence to a slice and prints it.
func main() {
numbers := iters.Iterate(1, double)
sixNums := iters.Limit(6, numbers)
words := iters.Map(sixNums, asWord)
fmt.Println(slices.Collect(words))
}
func double(n int) int {
return 2 * n
}
func asWord(n int) string {
if n < 10 {
return []string{"zero", "one", "two", "three", "four", "five",
"six", "seven", "eight", "nine"}[n]
} else {
return "many"
}
}
Output:
[one two four eight many many]
Example 4: deduplication of elements
Following example requires to compare the elements of the iter.Seq, so the iter.Seq needs to be
composed by comparable elements (this is, accepted by the the == and != operators):
- Instantiate an
iter.Seqofcomparableitems. - Pass it to the
Distinctmethod, that will return a copy of the originaliter.Seqwithout duplicates - Operating as any other sequence.
words := iters.Distinct(
iters.Of("hello", "hello", "!", "ho", "ho", "ho", "!"),
)
fmt.Printf("Deduplicated words: %v\n", slices.Collect(words))
Output:
Deduplicated words: [hello ! ho]
Example 5: Reduce
- Generate an incremental sequence from 1 to 8, both included.
- Reduce all the elements multiplying them
// create a sequence in range [1, 8]
seq := iters.OfRange(1, 9)
// multiply each item in the limited sequence
fac8, _ := iters.Reduce(seq8, func(a, b int) int {
return a * b
})
fmt.Println("The factorial of 8 is", fac8)
Output:
The factorial of 8 is 40320
Extra credits
This library is a port of the Gostream library from the same
author, adopted to work directly with the Go 1.23 iter.Seq and iter.Seq2 without
intermediate types.
The Gostream processing and aggregation functions, and thus most of the functions of this library, are heavily inspired in the Java Stream Specification.
Documentation
¶
Index ¶
- func AllMatch[T any](input iter.Seq[T], predicate func(T) bool) bool
- func AnyMatch[T any](input iter.Seq[T], predicate func(T) bool) bool
- func Concat[T any](a, b iter.Seq[T]) iter.Seq[T]
- func Count[T any](input iter.Seq[T]) int
- func Distinct[T comparable](input iter.Seq[T]) iter.Seq[T]
- func Empty[T any]() iter.Seq[T]
- func Filter[T any](input iter.Seq[T], predicate func(T) bool) iter.Seq[T]
- func FindFirst[T any](input iter.Seq[T]) (T, bool)
- func FlatMap[IN, OUT any](input iter.Seq[IN], mapper func(IN) iter.Seq[OUT]) iter.Seq[OUT]
- func ForEach[T any](input iter.Seq[T], consumer func(T))
- func ForEach2[T1, T2 any](input iter.Seq2[T1, T2], consumer func(T1, T2))
- func Generate[T any](supplier func() T) iter.Seq[T]
- func Iterate[T any](seed T, f func(T) T) iter.Seq[T]
- func Keys[K, V any](source iter.Seq2[K, V]) iter.Seq[K]
- func Limit[T any](maxSize int, input iter.Seq[T]) iter.Seq[T]
- func Limit2[K, V any](maxSize int, input iter.Seq2[K, V]) iter.Seq2[K, V]
- func Map[IT, OT any](input iter.Seq[IT], mapper func(IT) OT) iter.Seq[OT]
- func Max[T cmp.Ordered](input iter.Seq[T]) (T, bool)
- func MaxFunc[T any](input iter.Seq[T], cmp func(a, b T) int) (T, bool)
- func Min[T cmp.Ordered](input iter.Seq[T]) (T, bool)
- func MinFunc[T any](input iter.Seq[T], cmp func(a, b T) int) (T, bool)
- func NoneMatch[T any](input iter.Seq[T], predicate func(T) bool) bool
- func Of[T any](a ...T) iter.Seq[T]
- func OfChannel[T any](ch <-chan T) iter.Seq[T]
- func OfMap[K comparable, V any](m map[K]V) iter.Seq2[K, V]
- func OfMapKeys[T comparable, K any](m map[T]K) iter.Seq[T]
- func OfMapValues[T comparable, V any](m map[T]V) iter.Seq[V]
- func OfRange[T constraints.Integer](start, excludedEnd T) iter.Seq[T]
- func OfSlice[T any](sl []T) iter.Seq[T]
- func Peek[T any](input iter.Seq[T], consumer func(T)) iter.Seq[T]
- func Reduce[T any](input iter.Seq[T], accumulator func(a, b T) T) (T, bool)
- func Skip[T any](n int, input iter.Seq[T]) iter.Seq[T]
- func Skip2[K, V any](n int, input iter.Seq2[K, V]) iter.Seq2[K, V]
- func Values[K, V any](source iter.Seq2[K, V]) iter.Seq[V]
- func Zip[K, V any](keys iter.Seq[K], vals iter.Seq[V]) iter.Seq2[K, V]
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AllMatch ¶
AllMatch returns whether all elements of this iter.Seq match the provided predicate. If this operation finds an item where the predicate is false, it stops processing the rest of the iter.Seq.
func AnyMatch ¶
AnyMatch returns whether any elements of the iter.Seq match the provided predicate. If this operation finds an item where the predicate is true, it stops processing the rest of the iter.Seq.
func Concat ¶
Concat creates a lazily concatenated iter.Seq whose elements are all the elements of the first iter.Seq followed by all the elements of the second iter.Seq.
func Distinct ¶
func Distinct[T comparable](input iter.Seq[T]) iter.Seq[T]
Distinct returns an iter.Seq consisting of the distinct elements (according to equality operator) of the input iter.Seq. This function needs to internally store the previous distinct elements in memory, so it might not be suitable for large or infinite sequences with high variability in their items.
func Filter ¶
Filter returns a iter.Seq consisting of the items of this input iter.Seq that match the given predicate (this is, applying the predicate function over the item returns true).
func FindFirst ¶
FindFirst returns the first element of this iter.Seq along with true or, if the iter.Seq is empty, the zero value of the inner type along with false.
func FlatMap ¶
FlatMap returns an iter.Seq consisting of the results of replacing each element of the input iter.Seq with the contents of a mapped iter.Seq produced by applying the provided mapping function to each element. Each mapped iter.Seq is closed after its contents have been placed into this iter.Seq. (If a mapped iter.Seq is null an empty iter.Seq is used, instead.)
Due to the lazy nature of sequences, if any of the mapped sequences is infinite, some operations (Count, Reduce, Sorted, AllMatch...) will not end.
When both the input and output type are the same, the operation can be invoked as the method input.FlatMap(mapper).
func Generate ¶
Generate an infinite iter.Seq where each element is generated by the provided supplier function. Due to the potential statefulness of the supplier, multiple operations towards the same iter.Seq might provide different results.
This creates a lazy sequence. The supplier won't be called until it is requested for consumption by the transformation or aggregation functions.
Caution! Unless you limit the lenght of the iter.Seq (e.g. using the Limit function), the aggregation functions over this iter.Seq might not terminate.
func Iterate ¶
Iterate returns an infinite sequential ordered iter.Seq produced by iterative application of a function f to an initial element seed, producing a iter.Seq consisting of seed, f(seed), f(f(seed)), etc. The first element (position 0) in the iter.Seq will be the provided seed. For n > 0, the element at position n, will be the result of applying the function f to the element at position n - 1. Due to the stateful nature of the supplier, multiple operations towards the same iter.Seq might provide different results.
func Keys ¶
Keys returns an iter.Seq that iterates the keys (first/left items) of the source iter.Seq2
func Limit ¶
Limit returns an iter.Seq consisting of the elements of the input iter.Seq, truncated to be no longer than maxSize in length.
func Limit2 ¶ added in v0.2.0
Limit2 returns an iter.Seq2 consisting of the elements of the input iter.Seq2, truncated to be no longer than maxSize in length.
func Map ¶
Map returns a iter.Seq consisting of the results of individually applying the mapper function to each elements of the input iter.Seq.
func Max ¶
Max returns the maximum element of the iter.Seq. along with true if the iter.Seq is not empty. If the iter.Seq is empty, returns the zero value along with false.
func MaxFunc ¶
MaxFunc returns the maximum element of the iter.Seq according to the provided Comparator, along with true if the iter.Seq is not empty. If the iter.Seq is empty, returns the zero value along with false.
func Min ¶
Min returns the minimum element of the iter.Seq, along with true if the iter.Seq is not empty. If the iter.Seq is empty, returns the zero value along with false.
func MinFunc ¶
MinFunc returns the minimum element of the iter.Seq according to the provided Comparator, along with true if the iter.Seq is not empty. If the iter.Seq is empty, returns the zero value along with false.
func NoneMatch ¶
NoneMatch returns whether no elements of the iter.Seq match the provided predicate. If this operation finds an item where the predicate is true, it stops processing the rest of the iter.Seq.
func OfChannel ¶
OfChannel returns an iter.Seq that iterates over all values received from the provided channel. The iteration continues until the channel is closed. This means that aggregations over the returned iter.Seq might not terminate if the channel is inactive or never closed.
func OfMap ¶
func OfMap[K comparable, V any](m map[K]V) iter.Seq2[K, V]
OfMap returns an iter.Seq2 that iterates over all key-value pairs of the provided map. It is just an alias for maps.All.
func OfMapKeys ¶
func OfMapKeys[T comparable, K any](m map[T]K) iter.Seq[T]
OfMapKeys returns an iter.Seq that iterates over all keys of the provided map. It is just an alias for maps.Keys.
func OfMapValues ¶
func OfMapValues[T comparable, V any](m map[T]V) iter.Seq[V]
OfMapValues returns an iter.Seq that iterates over all values of the provided map. It is just an alias for maps.Values.
func OfRange ¶
func OfRange[T constraints.Integer](start, excludedEnd T) iter.Seq[T]
OfRange returns an iter.Seq that iterates the integer numbers from the first argument (inclusive) to the second argument (exclusive).
func OfSlice ¶
OfSlice returns an iter.Seq that iterates over all elements of the provided slice. It is just an alias for slices.Values.
func Peek ¶
Peek peturns an iter.Seq consisting of the elements of the input iter.Seq, additionally performing the provided action on each element as elements are consumed from the resulting iter.Seq.
func Reduce ¶
Reduce performs a reduction on the elements of the input Seq, using an associative accumulation function, and returns a value describing the reduced value, if any. If no reduced value (e.g. because the iter.Seq is empty), the second returned value is false.
func Skip ¶
Skip returns an iter.Seq consisting of the remaining elements of the input iter.Seq after discarding the first n elements of the sequence.
func Skip2 ¶ added in v0.2.0
Skip2 returns an iter.Seq consisting of the remaining elements of the input iter.Seq2 after discarding the first n elements of the sequence.
Types ¶
This section is empty.
Source Files
Directories