Map - Iterator helpers

This page lists all operations on maps, available in the it lo sub-package.

Help improve this documentation

This documentation is still new and evolving. If you spot any mistakes, unclear explanations, or missing details, please open an issue.

Your feedback helps us improve!

Creates a sequence of the map keys. Accepts multiple maps and concatenates their keys.

Examples:

m1 := map[string]int{
    "apple":  1,
    "banana": 2,
}
m2 := map[string]int{
    "cherry": 3,
    "date":   4,
}
keysSeq := it.Keys(m1, m2)
var result []string
for k := range keysSeq {
    result = append(result, k)
}
// result contains keys from both maps

Similar:

uniqkeys values core› keys

Prototype:

func Keys[K comparable, V any](in ...map[K]V) iter.Seq[K]

Creates a sequence of the map values. Accepts multiple maps and concatenates their values.

Examples:

m1 := map[string]int{
    "apple":  1,
    "banana": 2,
}
m2 := map[string]int{
    "cherry": 3,
    "date":   4,
}
valuesSeq := it.Values(m1, m2)
var result []int
for v := range valuesSeq {
    result = append(result, v)
}
// result contains values from both maps

Similar:

keys uniqvalues core› values

Prototype:

func Values[K comparable, V any](in ...map[K]V) iter.Seq[V]

Transforms a map into a sequence of key/value pairs. Accepts multiple maps and concatenates their entries.

Examples:

m := map[string]int{
    "apple":  1,
    "banana": 2,
    "cherry": 3,
}
entriesSeq := it.Entries(m)
var keys []string
var values []int
for k, v := range entriesSeq {
    keys = append(keys, k)
    values = append(values, v)
}
// keys contains map keys, values contains corresponding values

Similar:

fromentries topairs core› entries

Prototype:

func Entries[K comparable, V any](in ...map[K]V) iter.Seq2[K, V]

Transforms a sequence of key/value pairs into a map. Alias of FromEntries().

pairs := it.Seq2(func(yield func(string, int) bool) {
    yield("a", 1)
    yield("b", 2)
    yield("c", 3)
})

result := it.FromPairs(pairs)
// map[string]int{"a": 1, "b": 2, "c": 3}

Variant:

fromentries

Similar:

core› fromentries core› frompairs

Prototype:

func FromPairs[K comparable, V any](entries ...iter.Seq2[K, V]) map[K]V

Transforms a sequence of key/value pairs into a map. Accepts multiple sequences and merges them.

Examples:

entries := func(yield func(string, int) bool) {
    _ = yield("apple", 1)
    _ = yield("banana", 2)
    _ = yield("cherry", 3)
}
m := it.FromEntries(entries)
// m == map[string]int{"apple": 1, "banana": 2, "cherry": 3}

entries1 := func(yield func(string, int) bool) {
    _ = yield("a", 1)
    _ = yield("b", 2)
}
entries2 := func(yield func(string, int) bool) {
    _ = yield("c", 3)
    _ = yield("d", 4)
}
m := it.FromEntries(entries1, entries2)
// m contains all entries from both sequences

Variant:

frompairs

Similar:

entries core› fromentries

Prototype:

func FromEntries[K comparable, V any](entries ...iter.Seq2[K, V]) map[K]V

Creates a sequence composed of inverted keys and values from a sequence of key/value pairs.

Examples:

entries := func(yield func(string, int) bool) {
    _ = yield("apple", 1)
    _ = yield("banana", 2)
    _ = yield("cherry", 3)
}
inverted := it.Invert(entries)
var keys []int
var values []string
for k, v := range inverted {
    keys = append(keys, k)
    values = append(values, v)
}
// keys contains 1, 2, 3 and values contains "apple", "banana", "cherry"

Similar:

entries core› invert

Prototype:

func Invert[K, V comparable](in iter.Seq2[K, V]) iter.Seq2[V, K]

Merges multiple map sequences into a single map. Later maps overwrite values from earlier maps when keys conflict.

map1 := func(yield func(map[string]int) bool) {
    yield(map[string]int{"a": 1, "b": 2})
}
map2 := func(yield func(map[string]int) bool) {
    yield(map[string]int{"b": 3, "c": 4})
}
map3 := func(yield func(map[string]int) bool) {
    yield(map[string]int{"d": 5, "e": 6})
}
result := it.Assign(map1, map2, map3)
// map[string]int{"a": 1, "b": 3, "c": 4, "d": 5, "e": 6}
// Note: "b" is 3 (overwritten from map2)

singleMap := func(yield func(map[int]string) bool) {
    yield(map[int]string{1: "one", 2: "two"})
}
result = it.Assign(singleMap)
// map[int]string{1: "one", 2: "two"}

emptyMap1 := func(yield func(map[string]bool) bool) {
    yield(map[string]bool{})
}
emptyMap2 := func(yield func(map[string]bool) bool) {
    yield(map[string]bool{"active": true})
}
result = it.Assign(emptyMap1, emptyMap2)
// map[string]bool{"active": true}

Similar:

fromentries invert core› assign

Prototype:

func Assign[K comparable, V any, Map ~map[K]V](maps ...iter.Seq[Map]) Map

Transforms a map into a sequence by applying a transform function to each key-value pair. The transform function determines what values are yielded in the output sequence.

m := map[string]int{
    "apple":  3,
    "banana": 5,
    "cherry": 2,
}
result := it.MapToSeq(m, func(key string, value int) string {
    return fmt.Sprintf("%s:%d", key, value)
})
// iter.Seq[string] yielding "apple:3", "banana:5", "cherry:2"

numberMap := map[int]string{1: "one", 2: "two", 3: "three"}
result = it.MapToSeq(numberMap, func(key int, value string) int {
    return key * len(value)
})
// iter.Seq[int] yielding 3, 6, 15 (1*3, 2*3, 3*5)

personMap := map[string]int{"alice": 25, "bob": 30}
type Person struct {
    Name string
    Age  int
}
result = it.MapToSeq(personMap, func(name string, age int) Person {
    return Person{Name: name, Age: age}
})
// iter.Seq[Person] yielding {Name: "alice", Age: 25}, {Name: "bob", Age: 30}

Prototype:

func MapToSeq[K comparable, V, R any](in map[K]V, transform func(key K, value V) R) iter.Seq[R]

Transforms a map into a sequence by applying a transform function to each key-value pair, but only includes values where the transform function returns true as the second value.

m := map[string]int{
    "apple":  3,
    "banana": 0,
    "cherry": 2,
    "date":   0,
}
result := it.FilterMapToSeq(m, func(key string, value int) (string, bool) {
    if value > 0 {
        return fmt.Sprintf("%s:%d", key, value), true
    }
    return "", false
})
// iter.Seq[string] yielding "apple:3", "cherry:2" (only entries with value > 0)

personMap := map[string]int{"alice": 25, "bob": 30, "charlie": 15}
type Person struct {
    Name string
    Age  int
}
result = it.FilterMapToSeq(personMap, func(name string, age int) (Person, bool) {
    person := Person{Name: name, Age: age}
    return person, age >= 18
})
// iter.Seq[Person] yielding {Name: "alice", Age: 25}, {Name: "bob", Age: 30} (only adults)

dataMap := map[string]float64{"a": 1.5, "b": -2.0, "c": 3.14}
result = it.FilterMapToSeq(dataMap, func(key string, value float64) (int, bool) {
    if value > 0 {
        return int(value * 100), true
    }
    return 0, false
})
// iter.Seq[int] yielding 150, 314 (1.5*100, 3.14*100 rounded)

Prototype:

func FilterMapToSeq[K comparable, V, R any](in map[K]V, transform func(key K, value V) (R, bool)) iter.Seq[R]

Filters map keys based on a predicate function that takes both key and value. Returns a slice of keys that satisfy the predicate.

m := map[string]int{
    "apple":  3,
    "banana": 5,
    "cherry": 2,
    "date":   0,
}
result := it.FilterKeys(m, func(key string, value int) bool {
    return value > 2
})
// []string{"apple", "banana"} (keys with values > 2)

numberMap := map[int]string{1: "one", 2: "two", 3: "three", 4: "four"}
result = it.FilterKeys(numberMap, func(key int, value string) bool {
    return len(value) == 3
})
// []int{1, 2, 3} (keys where value length is 3)

personMap := map[string]int{"alice": 25, "bob": 30, "charlie": 17}
result = it.FilterKeys(personMap, func(key string, age int) bool {
    return strings.HasPrefix(key, "a") && age >= 20
})
// []string{"alice"} (keys starting with "a" and age >= 20)

emptyMap := map[string]int{}
result = it.FilterKeys(emptyMap, func(key string, value int) bool {
    return true
})
// []string{} (empty map)

Prototype:

func FilterKeys[K comparable, V any](in map[K]V, predicate func(key K, value V) bool) []K

Filters map values based on a predicate function that takes both key and value. Returns a slice of values that satisfy the predicate.

m := map[string]int{
    "apple":  3,
    "banana": 5,
    "cherry": 2,
    "date":   0,
}
result := it.FilterValues(m, func(key string, value int) bool {
    return value > 2
})
// []int{3, 5} (values > 2, corresponds to "apple" and "banana")

numberMap := map[int]string{1: "one", 2: "two", 3: "three", 4: "four"}
result = it.FilterValues(numberMap, func(key int, value string) bool {
    return len(value) == 3
})
// []string{"one", "two", "three"} (values with length 3)

personMap := map[string]int{"alice": 25, "bob": 30, "charlie": 17}
result = it.FilterValues(personMap, func(key string, age int) bool {
    return strings.HasPrefix(key, "a") && age >= 20
})
// []int{25} (value for "alice" only)

emptyMap := map[string]int{}
result = it.FilterValues(emptyMap, func(key string, value int) bool {
    return true
})
// []int{} (empty map)

dataMap := map[string]float64{"a": 1.5, "b": -2.0, "c": 0.0, "d": 3.14}
result = it.FilterValues(dataMap, func(key string, value float64) bool {
    return value > 0
})
// []float64{1.5, 3.14} (positive values only)

Prototype:

func FilterValues[K comparable, V any](in map[K]V, predicate func(key K, value V) bool) []V

Chunks a map into smaller maps of the specified size. Returns a sequence of maps, each containing up to the specified number of entries.

originalMap := map[string]int{
    "a": 1, "b": 2, "c": 3, "d": 4, "e": 5,
}
result := it.ChunkEntries(originalMap, 2)
// iter.Seq[map[string]int] yielding:
// map[string]int{"a": 1, "b": 2}
// map[string]int{"c": 3, "d": 4}
// map[string]int{"e": 5}

smallMap := map[int]string{1: "one", 2: "two"}
result = it.ChunkEntries(smallMap, 5)
// iter.Seq[map[int]string] yielding:
// map[int]string{1: "one", 2: "two"}

largeMap := make(map[int]bool)
for i := 0; i < 10; i++ {
    largeMap[i] = true
}
result = it.ChunkEntries(largeMap, 3)
// iter.Seq[map[int]bool] yielding 4 maps with 3, 3, 3, and 1 entries respectively

Similar:

chunk keys values core› chunkentries

Prototype:

func ChunkEntries[K comparable, V any](m map[K]V, size int) iter.Seq[map[K]V]

Associate returns a map containing key-value pairs provided by transform function applied to elements of the given sequence.
If any of two pairs have the same key the last one gets added to the map.

collection := func(yield func(string) bool) {
    yield("apple")
    yield("banana")
    yield("cherry")
}

result := it.Associate(collection, func(s string) (string, int) {
    return s, len(s)
})
// result contains {"apple": 5, "banana": 6, "cherry": 6}

AssociateI returns a map containing key-value pairs provided by transform function applied to elements of the given sequence, with index.

collection := func(yield func(string) bool) {
    yield("a")
    yield("b")
    yield("c")
}

result := it.AssociateI(collection, func(item string, index int) (int, string) {
    return index, item
})
// result contains {0: "a", 1: "b", 2: "c"}

SeqToMap returns a map containing key-value pairs provided by transform function applied to elements of the given sequence.
Alias of Associate().

collection := func(yield func(int) bool) {
    yield(1)
    yield(2)
    yield(3)
}

result := it.SeqToMap(collection, func(i int) (int, string) {
    return i, fmt.Sprintf("item-%d", i)
})
// result contains {1: "item-1", 2: "item-2", 3: "item-3"}

FilterSeqToMap returns a map containing key-value pairs provided by transform function applied to elements of the given sequence.
The third return value of the transform function is a boolean that indicates whether the key-value pair should be included in the map.

collection := func(yield func(int) bool) {
    yield(1)
    yield(2)
    yield(3)
    yield(4)
}

result := it.FilterSeqToMap(collection, func(i int) (int, string, bool) {
    return i, fmt.Sprintf("item-%d", i), i%2 == 0
})
// result contains {2: "item-2", 4: "item-4"}

Variant:

associate associatei filterseqtomap filterseqtomapi seqtomap seqtomapi

Similar:

keyby core› associate core› keyby

Prototypes:

func Associate[T any, K comparable, V any](collection iter.Seq[T], transform func(item T) (K, V)) map[K]V
func AssociateI[T any, K comparable, V any](collection iter.Seq[T], transform func(item T, index int) (K, V)) map[K]V
func SeqToMap[T any, K comparable, V any](collection iter.Seq[T], transform func(item T) (K, V)) map[K]V
func SeqToMapI[T any, K comparable, V any](collection iter.Seq[T], transform func(item T, index int) (K, V)) map[K]V
func FilterSeqToMap[T any, K comparable, V any](collection iter.Seq[T], transform func(item T) (K, V, bool)) map[K]V
func FilterSeqToMapI[T any, K comparable, V any](collection iter.Seq[T], transform func(item T, index int) (K, V, bool)) map[K]V

Creates a sequence of unique keys from multiple maps.

Will allocate a map large enough to hold all distinct input keys.
Long input sequences with heterogeneous keys can cause excessive memory usage.

Examples:

// Single map
m1 := map[string]int{
    "apple":  1,
    "banana": 2,
    "cherry": 3,
}
uniqueKeys := it.UniqKeys(m1)
// uniqueKeys: sequence with "apple", "banana", "cherry"

// Multiple maps with duplicate keys
m1 := map[string]int{
    "apple":  1,
    "banana": 2,
}
m2 := map[string]int{
    "banana": 3,
    "cherry": 4,
    "apple":  5,
}
uniqueKeys = it.UniqKeys(m1, m2)
// uniqueKeys: sequence with "apple", "banana", "cherry" (no duplicates)

// Maps with integer keys
scores1 := map[int]string{
    1: "Alice",
    2: "Bob",
    3: "Charlie",
}
scores2 := map[int]string{
    3: "David",
    4: "Eve",
    1: "Frank",
}
uniqueKeys = it.UniqKeys(scores1, scores2)
// uniqueKeys: sequence with 1, 2, 3, 4

// Maps with struct keys
type Person struct {
    Name string
    Age  int
}
people1 := map[Person]bool{
    {Name: "Alice", Age: 30}: true,
    {Name: "Bob", Age: 25}:   true,
}
people2 := map[Person]bool{
    {Name: "Bob", Age: 25}:     false,  // Same struct
    {Name: "Charlie", Age: 35}: true,
}
uniqueKeys = it.UniqKeys(people1, people2)
// uniqueKeys: sequence with {Alice 30}, {Bob 25}, {Charlie 35}

// Empty maps
empty1 := map[string]int{}
empty2 := map[string]int{}
uniqueKeys = it.UniqKeys(empty1, empty2)
// uniqueKeys: empty sequence

// Mix of empty and non-empty maps
m1 := map[string]int{"a": 1}
empty := map[string]int{}
m2 := map[string]int{"b": 2}
uniqueKeys = it.UniqKeys(m1, empty, m2)
// uniqueKeys: sequence with "a", "b"

// Maps with same keys but different values
m1 := map[string]int{
    "key1": 10,
    "key2": 20,
}
m2 := map[string]int{
    "key1": 100,  // Same key, different value
    "key3": 30,
}
uniqueKeys = it.UniqKeys(m1, m2)
// uniqueKeys: sequence with "key1", "key2", "key3" (key1 appears once)

// Large number of maps
maps := make([]map[int]string, 100)
for i := range maps {
    maps[i] = map[int]string{i: fmt.Sprintf("value%d", i)}
}
uniqueKeys = it.UniqKeys(maps...)
// uniqueKeys: sequence with keys 0, 1, 2, ..., 99

Similar:

core› uniqkeys

Prototype:

func UniqKeys[K comparable, V any](in ...map[K]V) iter.Seq[K]

Creates a sequence of unique values from multiple maps.

Will allocate a map large enough to hold all distinct input values.
Long input sequences with heterogeneous values can cause excessive memory usage.

Examples:

// Single map
m1 := map[string]int{
    "apple":  1,
    "banana": 2,
    "cherry": 3,
}
uniqueValues := it.UniqValues(m1)
// uniqueValues: sequence with 1, 2, 3

// Multiple maps with duplicate values
m1 := map[string]int{
    "apple":  1,
    "banana": 2,
}
m2 := map[string]int{
    "orange": 1,  // Same value as "apple"
    "grape":  3,
}
uniqueValues = it.UniqValues(m1, m2)
// uniqueValues: sequence with 1, 2, 3 (no duplicates)

// Maps with string values
scores1 := map[int]string{
    1: "Alice",
    2: "Bob",
    3: "Charlie",
}
scores2 := map[int]string{
    4: "Alice",   // Same value
    5: "David",
    6: "Bob",     // Same value
}
uniqueValues = it.UniqValues(scores1, scores2)
// uniqueValues: sequence with "Alice", "Bob", "Charlie", "David"

// Maps with boolean values
boolMaps := []map[string]bool{
    {"enabled": true, "debug": false},
    {"test": true, "prod": false},  // Same values
    {"dev": true, "staging": false}, // Same values
}
uniqueValues = it.UniqValues(boolMaps...)
// uniqueValues: sequence with true, false

// Maps with float values
prices1 := map[string]float64{
    "apple":  1.99,
    "banana": 2.99,
}
prices2 := map[string]float64{
    "orange": 1.99,  // Same price as apple
    "grape":  3.99,
}
uniqueValues = it.UniqValues(prices1, prices2)
// uniqueValues: sequence with 1.99, 2.99, 3.99

// Maps with struct values
type Product struct {
    Name  string
    Price float64
}
products1 := map[int]Product{
    1: {Name: "Book", Price: 19.99},
    2: {Name: "Pen", Price: 1.99},
}
products2 := map[int]Product{
    3: {Name: "Notebook", Price: 19.99},  // Same price as book
    4: {Name: "Book", Price: 19.99},      // Same struct as products1[1]
}
uniqueValues = it.UniqValues(products1, products2)
// uniqueValues: sequence with {Book 19.99}, {Pen 1.99}, {Notebook 19.99}

// Maps with pointer values
type Person struct {
    Name string
}
alice := &Person{Name: "Alice"}
bob := &Person{Name: "Bob"}
people1 := map[string]*Person{
    "user1": alice,
    "user2": bob,
}
people2 := map[string]*Person{
    "user3": alice,  // Same pointer
    "user4": &Person{Name: "Charlie"},
}
uniqueValues = it.UniqValues(people1, people2)
// uniqueValues: sequence with pointers to Alice, Bob, Charlie

// Empty maps
empty1 := map[string]int{}
empty2 := map[string]int{}
uniqueValues = it.UniqValues(empty1, empty2)
// uniqueValues: empty sequence

// Mix of empty and non-empty maps
m1 := map[string]int{"a": 10}
empty := map[string]int{}
m2 := map[string]int{"b": 20, "c": 10}  // 10 is duplicate
uniqueValues = it.UniqValues(m1, empty, m2)
// uniqueValues: sequence with 10, 20

// Maps with same values from different keys
m1 := map[string]int{
    "key1": 100,
    "key2": 200,
}
m2 := map[string]int{
    "key3": 100,  // Same value as key1
    "key4": 200,  // Same value as key2
    "key5": 300,
}
uniqueValues = it.UniqValues(m1, m2)
// uniqueValues: sequence with 100, 200, 300

// Large number of duplicate values
maps := make([]map[int]string, 10)
for i := range maps {
    maps[i] = map[int]string{
        i: "common",  // All maps have the same value
        i + 100: fmt.Sprintf("unique_%d", i),
    }
}
uniqueValues = it.UniqValues(maps...)
// uniqueValues: sequence with "common" and 10 unique values

Similar:

core› uniqvalues

Prototype:

func UniqValues[K, V comparable](in ...map[K]V) iter.Seq[V]

Keys​

Values​

Entries​

FromPairs​

FromEntries​

Invert​

Assign​

MapToSeq​

FilterMapToSeq​

FilterKeys​

FilterValues​

ChunkEntries​

Associate​

UniqKeys​

UniqValues​

Keys

Values

Entries

FromPairs

FromEntries

Invert

Assign

MapToSeq

FilterMapToSeq

FilterKeys

FilterValues

ChunkEntries

Associate

UniqKeys

UniqValues