README
¶
combo
Combinatorial constructions: Cartesian products, permutations, combinations, and power sets.
Eager functions allocate the full result in memory as slice.Mapper — chain directly with .KeepIf, .Convert, etc. Seq variants (SeqPermutations, SeqPowerSet, etc.) return seq.Seq for lazy evaluation with early termination — use these when the full result is too large to materialize.
// Before: nested loop to generate all size/color combinations
var pairs []Option
for _, size := range sizes {
for _, color := range colors {
pairs = append(pairs, Option{size, color})
}
}
// After: one call — produces domain objects directly
pairs := combo.CartesianProductWith(sizes, colors, NewOption)
What It Looks Like
// All pairs from two slices
pairs := combo.CartesianProduct([]int{1, 2}, []string{"a", "b"})
// [{1 a} {1 b} {2 a} {2 b}]
// All orderings (n! results)
combo.Permutations([]int{1, 2, 3})
// [[1 2 3] [1 3 2] [2 1 3] [2 3 1] [3 1 2] [3 2 1]]
// k-element subsets — C(n,k) results
combo.Combinations([]string{"a", "b", "c", "d"}, 2)
// [[a b] [a c] [a d] [b c] [b d] [c d]]
// All subsets (2^n results)
combo.PowerSet([]int{1, 2})
// [[] [2] [1] [1 2]]
// Fluent chain — results are slice.Mapper, so chain directly
// Keep only 2-element combinations that sum to at least 5
combo.Combinations([]int{1, 2, 3, 4}, 2).KeepIf(sumsToAtLeast5)
// [[1 4] [2 3] [2 4] [3 4]]
Growth Rates
All results are fully materialized in memory. Compute the result size before calling:
| Function | Results | n=5 | n=10 | n=15 |
|---|---|---|---|---|
| Permutations | n! | 120 | 3.6M | 1.3T |
| PowerSet | 2^n | 32 | 1,024 | 32,768 |
| Combinations(n, k) | C(n, k) | C(5,2)=10 | C(10,5)=252 | C(15,7)=6,435 |
| CartesianProduct | a * b | depends on inputs |
Eager functions are impractical for large inputs — Permutations above ~10-12 elements, PowerSet above ~20. Use the Seq variants for lazy evaluation with early termination:
// Lazy: only generates elements as needed
for perm := range combo.SeqPermutations(largeSlice) {
if isInteresting(perm) {
break // stops generation
}
}
Empty and Invalid Input
| Function | Empty/nil input | Invalid args |
|---|---|---|
CartesianProduct |
nil if either input is empty/nil |
— |
CartesianProductWith |
nil if either input is empty/nil |
fn must not be nil |
Permutations |
[[]] (one empty permutation) |
— |
Combinations |
[[]] for k=0 |
nil if k < 0 or k > len(items) |
PowerSet |
[[]] (one empty subset) |
— |
Operations
Eager (return slice.Mapper)
CartesianProduct[A, B any]([]A, []B) slice.Mapper[pair.Pair[A, B]]— all pairsCartesianProductWith[A, B, R any]([]A, []B, func(A, B) R) slice.Mapper[R]— all pairs, transformed (avoids intermediatepair.Pairallocation)Permutations[T any]([]T) slice.Mapper[[]T]— all orderingsCombinations[T any]([]T, int) slice.Mapper[[]T]— k-element subsets, preserving orderPowerSet[T any]([]T) slice.Mapper[[]T]— all subsets
Lazy (return seq.Seq)
SeqCartesianProduct[A, B any]([]A, []B) seq.Seq[pair.Pair[A, B]]— lazy pairsSeqCartesianProductWith[A, B, R any]([]A, []B, func(A, B) R) seq.Seq[R]— lazy pairs, transformedSeqPermutations[T any]([]T) seq.Seq[[]T]— lazy orderingsSeqCombinations[T any]([]T, int) seq.Seq[[]T]— lazy k-element subsetsSeqPowerSet[T any]([]T) seq.Seq[[]T]— lazy subsets
See pkg.go.dev for complete API documentation and the main README for installation.
Documentation
¶
Overview ¶
Package combo generates combinatorial structures over slices: Cartesian products, permutations, combinations (k-subsets), and power sets.
Eager functions return slice.Mapper for fluent chaining. Seq variants (SeqPermutations, SeqPowerSet, etc.) return seq.Seq for lazy evaluation with early termination — use these for large inputs where materializing the full result is impractical.
Index ¶
- func CartesianProduct[A, B any](a []A, b []B) slice.Mapper[pair.Pair[A, B]]
- func CartesianProductWith[A, B, R any](a []A, b []B, fn func(A, B) R) slice.Mapper[R]
- func Combinations[T any](items []T, k int) slice.Mapper[[]T]
- func Permutations[T any](items []T) slice.Mapper[[]T]
- func PowerSet[T any](items []T) slice.Mapper[[]T]
- func SeqCartesianProduct[A, B any](a []A, b []B) seq.Seq[pair.Pair[A, B]]
- func SeqCartesianProductWith[A, B, R any](a []A, b []B, fn func(A, B) R) seq.Seq[R]
- func SeqCombinations[T any](items []T, k int) seq.Seq[[]T]
- func SeqPermutations[T any](items []T) seq.Seq[[]T]
- func SeqPowerSet[T any](items []T) seq.Seq[[]T]
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CartesianProduct ¶
CartesianProduct returns all pairs from a and b.
Example ¶
package main
import (
"fmt"
"github.com/binaryphile/fluentfp/combo"
)
func main() {
// All pairs from two lists.
results := combo.CartesianProduct([]string{"a", "b"}, []int{1, 2})
for _, p := range results {
fmt.Printf("(%s, %d)\n", p.First, p.Second)
}
}
Output: (a, 1) (a, 2) (b, 1) (b, 2)
func CartesianProductWith ¶
CartesianProductWith applies fn to every (a, b) pair. Avoids intermediate Pair allocation when the caller transforms immediately. Panics if fn is nil.
func Combinations ¶
Combinations returns all k-element subsets of items, preserving order. Returns C(n,k) results.
Example ¶
package main
import (
"fmt"
"github.com/binaryphile/fluentfp/combo"
)
func main() {
// Choose 2 items from 4.
results := combo.Combinations([]string{"a", "b", "c", "d"}, 2)
for _, c := range results {
fmt.Println(c)
}
}
Output: [a b] [a c] [a d] [b c] [b d] [c d]
func Permutations ¶
Permutations returns all orderings of items. Returns n! results — use only for small inputs.
Example ¶
package main
import (
"fmt"
"github.com/binaryphile/fluentfp/combo"
)
func main() {
// All orderings of 3 items.
results := combo.Permutations([]int{1, 2, 3})
fmt.Println(results.Len(), "permutations")
fmt.Println(results[0])
}
Output: 6 permutations [1 2 3]
func PowerSet ¶
PowerSet returns all subsets of items. Returns 2^n results — use only for small inputs.
Example ¶
package main
import (
"fmt"
"github.com/binaryphile/fluentfp/combo"
)
func main() {
// All subsets of a set.
results := combo.PowerSet([]string{"x", "y"})
for _, s := range results {
fmt.Println(s)
}
}
Output: [] [y] [x] [x y]
func SeqCartesianProduct ¶ added in v0.114.0
SeqCartesianProduct returns a lazy sequence of all pairs from a and b.
func SeqCartesianProductWith ¶ added in v0.114.0
SeqCartesianProductWith returns a lazy sequence applying fn to every (a, b) pair. Avoids intermediate Pair allocation when the caller transforms immediately. Panics if fn is nil.
func SeqCombinations ¶ added in v0.114.0
SeqCombinations returns a lazy sequence of all k-element subsets of items, preserving order. Returns C(n,k) results.
func SeqPermutations ¶ added in v0.114.0
SeqPermutations returns a lazy sequence of all orderings of items. Returns n! results — use seq.Seq.Take for large inputs.
func SeqPowerSet ¶ added in v0.114.0
SeqPowerSet returns a lazy sequence of all subsets of items. Returns 2^n results — use seq.Seq.Take for large inputs.
Types ¶
This section is empty.
Source Files