go-functional

The library is built around two main types of functions:

1. Iterators: Functions that yield new values and can be ranged over (compatible with Go's iter.Seq).
2. Consumers: Functions that iterate over an iterator, often draining it completely or partially to collect values into a data type.

Warning: Attempting to collect infinite iterators will cause an infinite loop and likely deadlock. Always bound infinite iterators (e.g., using Take) before calling a consumer like Collect.

Install the library using go get. This project requires Go 1.23+ and works with iter.Seq.

go get github.com/BooleanCat/go-functional/v2@latest

The Chain function glues multiple iterators together, yielding values from each in the sequence they are provided. If zero iterators are provided, it behaves like Exhausted.

// Using it package
numbers := it.Chain(slices.Values([]int{1, 2}), slices.Values([]int{3, 4}))

// Using itx package (chainable)
pairs := itx.FromSlice([]int{1, 2}).Chain(slices.Values([]int{3, 4}))

// Using maps
pairs := it.Chain2(maps.All(map[string]int{"a": 1}), maps.All(map[string]int{"b": 2}))

Use it.All and it.Any to evaluate boolean conditions across an iterator.

• it.All: Returns true if all values are true. Returns true for empty iterators. Terminates early if false is encountered.
• it.Any: Returns true if any value is true. Returns false for empty iterators. Terminates early if true is encountered.

Note: These are not available in the itx package due to Go type system limitations.

it.All(slices.Values([]bool{true, false, true}))  // false
it.Any(slices.Values([]bool{false, false, true}))  // true

Take

Limits the iterator to a specified number of values. If the iterator is shorter than the limit, it simply exhausts normally.

TakeWhile

Yields values as long as the predicate returns true. Once the predicate returns false, the iterator is exhausted.

// Take
// Returns [1, 2]
slices.Collect(it.Take(slices.Values([]int{1, 2, 3}), 2))

// TakeWhile
// Returns [1, 2]
slices.Collect(it.TakeWhile(slices.Values([]int{1, 2, 3, 4}), filter.LessThan(3)))

If you need to iterate over an iterator solely to trigger side effects (like printing or logging) but do not need the resulting values, use Drain or Drain2. This effectively consumes the iterator and discards the output.

// Drain a single sequence
it.Drain(it.Map(slices.Values([]int{1, 2, 3}), func(n int) int { 
    fmt.Println(n); return n 
}))

// Chainable Drain
itx.From(it.Map(slices.Values([]int{1, 2, 3}), printValue)).Drain()

Cycle

Yields all values from an iterator before returning to the beginning and yielding all values again indefinitely. It stores all values in memory, so memory usage grows until the first cycle is complete.

Repeat

Yields the same value indefinitely.

WARNING: Both are infinite. Always use Take to bound the consumption to avoid infinite loops.

// Bounding a Cycle
numbers := it.Take(it.Cycle(slices.Values([]int{1, 2})), 5)

// Chainable Cycle
numbers := itx.FromSlice([]int{1, 2}).Cycle().Take(5)

// Bounding a Repeat
slices.Collect(it.Take(it.Repeat(42), 5))

// Chainable Repeat
itx.Repeat(42).Take(5).Collect()

The Enumerate function transforms an iter.Seq into an iter.Seq2, yielding the index of each value alongside the value itself.

// it package
indexedValues := it.Enumerate(slices.Values([]int{1, 2, 3}))

// itx package (chainable)
indexedValues := itx.FromSlice([]int{1, 2, 3}).Enumerate()

Drop

Yields values from a delegate iterator after skipping a specified number of values from the beginning. If the drop count is larger than the iterator length, it behaves like Exhausted.

DropWhile

Drops values from the iterator as long as the provided predicate returns true. Once the predicate returns false, the iterator resumes normal yielding.

// Drop
numbers := it.Drop(slices.Values([]int{1, 2, 3, 4, 5}), 2)
// Chainable
numbers := itx.FromSlice([]int{1, 2, 3, 4, 5}).Drop(2)

// DropWhile
// Returns [3, 4, 5]
slices.Collect(it.DropWhile(slices.Values([]int{1, 2, 3, 4, 5}), filter.LessThan(3)))

// Chainable DropWhile
itx.FromSlice([]int{1, 2, 3, 4, 5}).DropWhile(filter.LessThan(3)).Collect()

The FromChannel function pulls values from a channel and yields them via an iterator.

Important:

• The iterator is exhausted when the channel is closed.
• It is the caller's responsibility to close the channel.
• To prevent deadlocks when using pull-style consumption (like iter.Pull), the channel must be closed before attempting to stop the iterator.

items := make(chan int)

go func() {
	defer close(items)
	items <- 1
	items <- 2
}()

for number := range it.FromChannel(items) {
	fmt.Println(number)
}

// Chainable version
for number := range itx.FromChannel(items).Exclude(filter.IsZero) {
	fmt.Println(number)
}