maps

maps.Clone as a shallow copy, Copy and Equal, DeleteFunc, and iterators whose order is not specified.

モジュールページの本文は現在英語です。

The maps package provides generic helpers for maps of any type. It has shipped in the standard library since Go 1.21. Keys, Values, All, Insert, and Collect return or consume iterators and require Go 1.23 or later. Import the package as "maps".

Clone is a shallow copy: keys and values are assigned into the new map, so a slice or pointer value is shared. The iteration order of a Go map, and of maps.Keys, maps.Values, and maps.All, is not specified and is not guaranteed to be the same from one call to the next. These pages never assert an unsorted range order. The package has no special handling for non-reflexive keys such as NaN.

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
maps.Clone, maps.CopyClone a map by assigning its keys and values, or copy pairs into an existing map. Clone is shallow.
maps.Equal, maps.DeleteFunc, maps.KeysCompare two maps with == on values, delete pairs that match a function, or iterate keys in an unspecified order.

Clone, Copy, and Equal

Clone returns a copy of m. Values are set with ordinary assignment, so mutating a shared slice value is visible in both maps, while adding or deleting a key in the clone is not. Copy copies every pair from src into dst and overwrites existing keys; keys that exist only in dst are left in place. Equal reports whether two maps contain the same key/value pairs using == on values. A nil map and an empty map contain the same pairs.

maps.Clone, maps.Copy

func Clone[M ~map[K]V, K comparable, V any](m M) M
func Copy[M1 ~map[K]V, M2 ~map[K]V, K comparable, V any](dst M1, src M2)

Clone a map by assigning its keys and values, or copy pairs into an existing map. Clone is shallow.

ParameterDescription
mThe map to clone. Clone of a nil map is nil.
dst, srcCopy adds every key/value pair from src to dst. A key already present in dst is overwritten.

Returns: Clone returns the new map. Copy has no return value.

  • After Clone, changing cloned["a"][0] also changes orig["a"][0] when the value is a slice. Assigning cloned["b"] = ... does not add "b" to orig.
  • Copy does not delete keys that are present in dst but absent from src.
go
package main

import (
	"fmt"
	"maps"
)

func main() {
	orig := map[string][]int{"a": {1}}
	cloned := maps.Clone(orig)
	cloned["a"][0] = 9
	cloned["b"] = []int{2}
	fmt.Println(orig["a"], cloned["a"], orig["b"] == nil, cloned["b"])

	dst := map[string]int{"a": 1, "keep": 2}
	maps.Copy(dst, map[string]int{"a": 9, "c": 3})
	for _, k := range []string{"a", "c", "keep"} {
		fmt.Printf("%s=%d\n", k, dst[k])
	}
	fmt.Println(maps.Clone(map[string]int(nil)) == nil)
}

Expected output

[9] [9] true [2]
a=9
c=3
keep=2
true

Official documentation →

maps.Equal, maps.DeleteFunc, maps.Keys

func Equal[M1, M2 ~map[K]V, K, V comparable](m1 M1, m2 M2) bool
func DeleteFunc[M ~map[K]V, K comparable, V any](m M, del func(K, V) bool)
func Keys[Map ~map[K]V, K comparable, V any](m Map) iter.Seq[K]

Compare two maps with == on values, delete pairs that match a function, or iterate keys in an unspecified order.

ParameterDescription
m1, m2, mThe maps to compare, edit, or iterate. Equal treats a nil map and an empty map as equal.
delDeleteFunc removes every pair for which del returns true.

Returns: Equal returns whether the maps contain the same pairs. DeleteFunc has no return value. Keys returns an iterator over keys; the order is not specified.

  • EqualFunc is like Equal but compares values with a function; keys are still compared with ==.
  • Do not assert the raw order of maps.Keys, maps.Values, or range over a map. Collect the keys and sort them when a test or log needs a stable sequence. Keys requires Go 1.23.
go
package main

import (
	"fmt"
	"maps"
	"slices"
)

func main() {
	fmt.Println(maps.Equal(map[string]int{"a": 1}, map[string]int{"a": 1}))
	fmt.Println(maps.Equal(map[string]int{}, map[string]int(nil)))
	fmt.Println(maps.Equal(map[string]int{"a": 1}, map[string]int{"a": 2}))

	m := map[string]int{"a": 1, "b": 2, "c": 3}
	maps.DeleteFunc(m, func(k string, v int) bool { return v%2 == 0 })
	keys := slices.Collect(maps.Keys(m))
	slices.Sort(keys)
	fmt.Println(keys, m["a"], m["c"], m["b"])
}

Expected output

true
true
false
[a c] 1 3 0

Official documentation →