The maps Package

maps is ten generic functions for the loops you would otherwise write by hand: copy a map, compare two, prune one, and walk one as a sequence of keys, values, or pairs.

Examples

Map order is random, so a stable listing goes through slices.Sorted.

func main() {
    stock := map[string]int{"washer": 0, "bolt": 12, "nut": 30}

    for _, name := range slices.Sorted(maps.Keys(stock)) {
        fmt.Printf("%-7s %d\n", name, stock[name])
    }

    total := 0
    for n := range maps.Values(stock) {
        total += n
    }
    fmt.Println("total:", total)
}

Output

bolt    12
nut     30
washer  0
total: 42

Clone the defaults, copy the overrides over them, prune what is left.

func main() {
    defaults := map[string]string{"host": "localhost", "port": "8080"}

    cfg := maps.Clone(defaults)
    maps.Copy(cfg, map[string]string{"port": "9000", "tls": "on"})

    fmt.Println(cfg["host"], cfg["port"], cfg["tls"])
    fmt.Println(maps.Equal(cfg, defaults))

    maps.DeleteFunc(cfg, func(k, v string) bool { return v == "on" })
    fmt.Println(len(cfg))
}

Output

localhost 9000 on
false
2

Collect turns a sequence of pairs into a map, Insert merges one in.

type Row struct {
    SKU   string
    Count int
}

func main() {
    rows := []Row{{"bolt", 12}, {"nut", 30}}

    // Build a map straight from a sequence of pairs.
    stock := maps.Collect(func(yield func(string, int) bool) {
        for _, r := range rows {
            if !yield(r.SKU, r.Count) {
                return
            }
        }
    })

    // Merge a second map in.
    maps.Insert(stock, maps.All(map[string]int{"washer": 5}))

    fmt.Println(slices.Sorted(maps.Keys(stock)))
    fmt.Println(stock["nut"])
}

Output

[bolt nut washer]
30

Maps and sequences

Function	Description
Keys[Map ~map[K]V, K comparable, V any](m Map) iter.Seq[K] `for k := range maps.Keys(m)`	A sequence of the map's keys.
Input `m`, any map type. Output An `iter.Seq[K]`. A sequence, not a slice. Behavior Order is whatever the map gives, which changes between runs. `slices.Sorted(maps.Keys(m))` is the fix, and it is the most common thing this function appears inside. Use when You want the keys and not the values. Ranging the map directly is fine too, and shorter, unless the sequence is going somewhere else.
Values[Map ~map[K]V, K comparable, V any](m Map) iter.Seq[V] `for v := range maps.Values(m)`	A sequence of the map's values.
Input `m`, any map type. Output An `iter.Seq[V]`. Behavior Duplicates are kept, since two keys can hold the same value. Order is random, as with `Keys`.
All[Map ~map[K]V, K comparable, V any](m Map) iter.Seq2[K, V] `maps.Insert(dst, maps.All(src))`	A sequence of the map's key-value pairs.
Input `m`, any map type. Output An `iter.Seq2[K, V]`, one pair per entry. Use when A pair sequence is what the other side wants, such as `maps.Insert` or a filter you wrote. Reading the map in a loop wants a plain `range` over it.
Collect[K comparable, V any](seq iter.Seq2[K, V]) map[K]V `m := maps.Collect(seq)`	Builds a new map from a sequence of pairs.
Input `seq`, a sequence of pairs. Output A new `map[K]V` holding them. Behavior A key that arrives twice keeps whichever pair came last. Use when The pairs come from somewhere that is not already a map. Copying a map is `Clone`.
Insert[Map ~map[K]V, K comparable, V any](m Map, seq iter.Seq2[K, V]) `maps.Insert(m, maps.All(other))`	Adds a sequence of pairs into an existing map.
Input `m`, the map to write into. `seq`, the pairs to add. Output `m`, changed in place. Behavior An existing key is overwritten. Equivalent to `maps.Copy(m, other)`, when the source is a map rather than a sequence.

Whole-map operations

Function	Description
Clone[M ~map[K]V, K comparable, V any](m M) M `cfg := maps.Clone(defaults)`	A new map with the same entries.
Input `m`, the map to copy. A `nil` map is allowed. Output A new map of the same type, or `nil` when `m` was nil. Behavior The copy is one level deep. A value that is itself a map, a slice, or a pointer is shared between the two, so writing through it changes both. Use when Handing a caller a map they can change without it reaching yours.
Copy[M1 ~map[K]V, M2 ~map[K]V, K comparable, V any](dst M1, src M2) `maps.Copy(cfg, overrides)`	Copies src's entries into dst.
Input `dst`, an existing map. `src`, the map to read. Output `dst`, changed in place. Behavior A key in both is taken from `src`. Keys only in `dst` are left alone, which is what makes this the layered-config move: clone the defaults, then copy the overrides over them.
Equal[M1, M2 ~map[K]V, K, V comparable](m1 M1, m2 M2) bool `maps.Equal(got, want)`	True when both hold the same keys and values.
Input Two maps whose values are comparable. Output A `bool`. Behavior Values are compared with `==`, so a map of slices or of structs containing one will not compile. Two nil maps are equal, and a nil map equals an empty one. Use when Comparing in a test. `reflect.DeepEqual` does the same job at a fraction of the speed.
EqualFunc[M1 ~map[K]V1, M2 ~map[K]V2, K comparable, V1, V2 any](m1 M1, m2 M2, eq func(V1, V2) bool) bool `maps.EqualFunc(a, b, strings.EqualFold)`	Equal, with your own comparison for the values.
Input Two maps sharing a key type, and `eq`, called once per key present in both. Output A `bool`. Behavior The key sets are checked first, so `eq` never sees a key that only one map has. Use when The values are not comparable, or equality means something looser than `==`. The two maps may even hold different value types.
DeleteFunc[M ~map[K]V, K comparable, V any](m M, del func(K, V) bool) `maps.DeleteFunc(m, func(k string, v int) bool { return v == 0 })`	Deletes every entry the function says yes to.
Input `m`, the map to prune. `del`, called once per entry. Output `m`, with the matching entries gone. Behavior Deleting during the walk is safe here, which is the thing a hand-written range loop over a map has to be careful about.

Maps The language feature: declaring one, the comma-ok read, and delete.iter Keys, Values, and All all return an iter.Seq.slices slices.Sorted and slices.Collect turn those sequences back into a slice.cmp Ordering the keys of a map whose key type is not a plain string or int.

Previous log Next Topic math

The maps Package

Examples

Maps and sequences

Whole-map operations

Related