Ausführbare Go-Docs: Maps

Q: Wie prüft man, ob ein Schlüssel in einer Go-Map existiert?

Mit der Form des Lookups mit zwei Werten: v, ok := m[key]. ok ist true, wenn der Schlüssel vorhanden ist, und false, wenn nicht; dann ist v der Nullwert. Ein einfaches m[key] kann einen fehlenden Schlüssel nicht von einem Schlüssel unterscheiden, der mit dem Nullwert gespeichert ist.

Q: Wie bekomme ich in Go alle Schlüssel einer Map?

Seit Go 1.23 gibt maps.Keys(m) einen Iterator zurück; mach daraus mit slices.Collect(maps.Keys(m)) einen Slice oder mit slices.Sorted(maps.Keys(m)) einen sortierten Slice. Vor 1.23 schreibst du eine Schleife for k := range m und hängst jeden Schlüssel an einen Slice an.

Q: Warum löst das Schreiben in eine Map die Panic „assignment to entry in nil map“ aus?

Die Map-Variable wurde deklariert, aber nie erzeugt: var m map[string]int ist nil. Aus einer nil-Map zu lesen liefert Nullwerte, aber Schreiben löst eine Panic aus. Erzeuge sie vorher mit m = make(map[string]int) oder einem Literal m := map[string]int{}. Ein Map-Feld in einem Struct braucht dieselbe Initialisierung.

Eine Map erzeugen und nutzen

Ein Map-Typ wird map[KeyType]ValueType geschrieben. Du erzeugst eine mit einem Literal oder mit make und liest, schreibst und löschst dann per Schlüssel.

package main

import "fmt"

func main() {
	ages := map[string]int{
		"ana": 31,
		"bob": 25,
	}

	ages["cy"] = 40          // insert
	ages["bob"] = 26         // update
	fmt.Println(ages["ana"]) // read
	fmt.Println(len(ages))   // number of entries

	delete(ages, "ana")
	fmt.Println(ages) // fmt prints maps with keys sorted

	counts := make(map[rune]int)
	for _, r := range "hello" {
		counts[r]++ // missing keys start at zero
	}
	fmt.Println(counts['l'], counts['z'])
}

Ausgabe:

31
3
map[bob:26 cy:40]
2 0

Zwei Erleichterungen zeigen sich hier. Das Lesen eines fehlenden Schlüssels liefert den Nullwert des Werttyps (counts['z'] ist 0), also funktioniert Zählen mit m[k]++ ohne jede Vorbereitung. Und fmt gibt Maps mit sortierten Schlüsseln aus. Das ist praktisch beim Debuggen, sagt aber nichts über die Iterationsreihenfolge.

make(map[K]V, n) nimmt einen optionalen Größenhinweis. Es reserviert Platz für etwa n Einträge; anders als bei Slices hat eine Map keine Kapazität, die du auslesen kannst.

Prüfen, ob ein Schlüssel existiert: Comma-ok

Weil ein fehlender Schlüssel als Nullwert gelesen wird, kann m[k] == 0 „fehlt“ nicht von „als 0 gespeichert“ unterscheiden. Nimm die Form mit zwei Werten:

package main

import "fmt"

func main() {
	stock := map[string]int{"apple": 0, "pear": 12}

	if n, ok := stock["apple"]; ok {
		fmt.Println("apple is listed, quantity", n)
	}

	if _, ok := stock["kiwi"]; !ok {
		fmt.Println("kiwi is not listed")
	}

	fmt.Println(stock["apple"] == stock["kiwi"]) // both 0: indistinguishable without ok
}

Die Form if v, ok := m[k]; ok { ... } hält v und ok im Scope des if. Sie ist eine der häufigsten Zeilen in Go-Code.

Einträge löschen

delete(m, key) entfernt den Eintrag. Einen Schlüssel zu löschen, der nicht vorhanden ist, bewirkt nichts, ebenso das Löschen aus einer nil-Map. Um eine ganze Map zu leeren, hat Go 1.21 clear(m) eingeführt, das die angelegte Map zur Wiederverwendung behält.

Einträge während eines range über dieselbe Map zu löschen ist erlaubt und sicher. Ein Eintrag, der gelöscht wird, bevor die Schleife ihn erreicht, wird nicht geliefert.

package main

import "fmt"

func main() {
	sessions := map[string]int{"a": 5, "b": 120, "c": 90, "d": 3}
	for id, idle := range sessions {
		if idle > 60 {
			delete(sessions, id) // safe during range
		}
	}
	fmt.Println(sessions)

	clear(sessions)
	fmt.Println(len(sessions))
}

Durchlaufen: Die Reihenfolge ist zufällig

for k, v := range m besucht jeden Eintrag einmal, in einer nicht festgelegten Reihenfolge. Die Runtime randomisiert den Startpunkt absichtlich, also sind sich zwei Schleifen über dieselbe Map im selben Programm oft uneinig. Führ das ein paarmal aus:

package main

import "fmt"

func main() {
	m := map[string]int{"a": 1, "b": 2, "c": 3, "d": 4, "e": 5}
	for range 3 {
		for k := range m {
			fmt.Print(k, " ")
		}
		fmt.Println()
	}
}

Jeder Code, dessen Ausgabe von der Reihenfolge einer Map abhängt, ist ein Bug, der auf einen anderen Lauf wartet. Tests, die eine ausgegebene Map-Iteration vergleichen, sind das klassische Beispiel.

Sortierte Schlüssel

Um eine Map in Schlüsselreihenfolge zu besuchen, holst du die Schlüssel, sortierst sie und indizierst die Map. Go 1.23 hat das mit Iteratoren aus den Paketen maps und slices zu einer Zeile gemacht:

package main

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

func main() {
	prices := map[string]float64{"tea": 2.5, "coffee": 3.2, "juice": 4.0, "water": 1.0}

	for _, k := range slices.Sorted(maps.Keys(prices)) {
		fmt.Printf("%-7s %.2f\n", k, prices[k])
	}

	keys := slices.Collect(maps.Keys(prices)) // unsorted slice of keys
	fmt.Println(len(keys))

	// Sort by value instead: sort the keys with a custom comparison.
	byPrice := slices.Collect(maps.Keys(prices))
	slices.SortFunc(byPrice, func(a, b string) int {
		return cmp.Compare(prices[a], prices[b])
	})
	fmt.Println(byPrice)
}

Unter Go 1.22 und älter gab es maps.Keys in der Standardbibliothek nicht. Das Gegenstück ist eine Schleife:

keys := make([]string, 0, len(m))
for k := range m {
	keys = append(keys, k)
}
sort.Strings(keys)

Weitere Helfer in maps: maps.Values, maps.Clone (eine flache Kopie), maps.Equal, maps.Copy(dst, src) und maps.DeleteFunc.

Gültige Schlüsseltypen

Schlüssel müssen mit == vergleichbar sein: Zahlen, Strings, Booleans, Pointer, Channels, Arrays aus vergleichbaren Typen, Structs, deren Felder alle vergleichbar sind, und Interface-Werte. Slices, Maps und Funktionen können keine Schlüssel sein.

map[[]int]bool{}       // compile error: invalid map key type []int
map[[2]int]bool{}      // fine: arrays are comparable
map[struct{ X, Y int }]string{} // fine: a struct key for a grid position

Ein Struct als Schlüssel ist der idiomatische Weg, nach mehreren Werten gleichzeitig zu indizieren, statt Strings zu verketten.

Interface-Schlüssel kompilieren auch dann, wenn der dynamische Typ nicht vergleichbar ist, und lösen dann zur Laufzeit eine Panic aus: Einen []int unter einer map[any]int zu speichern scheitert mit runtime error: hash of unhashable type []int.

Gleitkomma-Schlüssel funktionieren, aber NaN ist nicht gleich sich selbst, also lässt sich ein NaN-Schlüssel wiederholt einfügen und nie wieder lesen. Vermeide Float-Schlüssel.

Map von Structs

Eine Map kann Structs enthalten, aber du kannst keinem Feld eines Structs zuweisen, das in einer Map gespeichert ist, weil Map-Werte nicht adressierbar sind.

package main

import "fmt"

type User struct {
	Name  string
	Score int
}

func main() {
	users := map[string]User{"u1": {Name: "Ana"}}
	// users["u1"].Score = 10 // compile error: cannot assign to struct field users["u1"].Score in map

	u := users["u1"] // copy out
	u.Score = 10
	users["u1"] = u // write back
	fmt.Println(users["u1"])

	// Or store pointers, and modify in place.
	ptrs := map[string]*User{"u2": {Name: "Bob"}}
	ptrs["u2"].Score += 5
	fmt.Println(*ptrs["u2"])
}

Nimm Werte, wenn die Einträge klein sind und als Ganzes ersetzt werden. Nimm Pointer, wenn du Felder oft aktualisierst oder denselben Datensatz von mehreren Stellen aus teilst. Mit Pointern liefert ein fehlender Schlüssel nil, also löst ptrs["nope"].Score eine Panic aus.

Maps von Slices funktionieren beim Anhängen genauso: groups[k] = append(groups[k], v) braucht keine Initialisierung, weil ein fehlender Schlüssel einen nil-Slice liefert und append mit nil umgehen kann.

Maps verhalten sich wie Referenzen

Ein Map-Wert verweist auf geteilte Daten. Eine Map zuzuweisen oder an eine Funktion zu übergeben kopiert die Einträge nicht: Beide Variablen sehen dieselbe Map.

package main

import (
	"fmt"
	"maps"
)

func addDefault(m map[string]int) {
	m["default"] = 1 // visible to the caller
}

func main() {
	a := map[string]int{"x": 1}
	b := a
	b["y"] = 2
	addDefault(a)
	fmt.Println(a)

	c := maps.Clone(a) // independent shallow copy
	c["x"] = 100
	fmt.Println(a["x"], c["x"])
}

Deshalb kann eine Funktion eine Map füllen, ohne sie zurückzugeben, anders als bei einem Slice, an den sie anhängt.

Die Panic bei der nil-Map

Der Nullwert einer Map ist nil. Eine nil-Map liest sich wie eine leere Map, aber das Schreiben darauf löst eine Panic aus.

package main

import "fmt"

type Cache struct {
	data map[string]string
}

func main() {
	var m map[string]int
	fmt.Println(m["x"], len(m)) // reading nil is fine

	defer func() {
		fmt.Println("recovered:", recover())
	}()

	var c Cache       // data is nil
	c.data["k"] = "v" // panics
	fmt.Println("not reached")
}

Ausgabe:

0 0
recovered: assignment to entry in nil map

Der Fall mit dem Struct ist der, der in der Praxis zubeißt. Initialisier Map-Felder in einem Konstruktor (func NewCache() *Cache { return &Cache{data: map[string]string{}} }) oder verzögert vor dem ersten Schreiben.

Nebenläufiger Zugriff

Maps sind nicht sicher für nebenläufige Nutzung. Schreibt eine Goroutine, während eine andere liest oder schreibt, kann die Runtime das Programm mit fatal error: concurrent map writes (oder concurrent map read and map write) stoppen. Das ist ein fataler Fehler, keine Panic, also kann recover ihn nicht abfangen.

Schütze die Map mit einem Mutex:

package main

import (
	"fmt"
	"sync"
)

type Counter struct {
	mu sync.Mutex
	m  map[string]int
}

func (c *Counter) Inc(key string) {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.m[key]++
}

func main() {
	c := Counter{m: make(map[string]int)}
	var wg sync.WaitGroup
	for i := range 100 {
		wg.Add(1)
		go func() {
			defer wg.Done()
			c.Inc([]string{"red", "green"}[i%2])
		}()
	}
	wg.Wait()
	fmt.Println(c.m["red"], c.m["green"])
}

Das gibt immer 50 50 aus. Nimm sync.RWMutex, wenn Lesezugriffe die Schreibzugriffe weit überwiegen. sync.Map gibt es für zwei enge Fälle (Schlüssel, die einmal geschrieben und oft gelesen werden, oder Goroutinen, die mit getrennten Schlüsseln arbeiten); für alles andere ist ein Mutex mit einer normalen Map einfacher und meist schneller. Mehr dazu unter Mutex.

Kurzreferenz

Operation	Code
Erzeugen	`m := map[string]int{}` oder `make(map[string]int)`
Einfügen oder aktualisieren	`m[k] = v`
Lesen (null, wenn fehlend)	`v := m[k]`
Vorhandensein prüfen	`v, ok := m[k]`
Löschen	`delete(m, k)`
Alles entfernen	`clear(m)` (Go 1.21)
Größe	`len(m)`
Sortierte Schlüssel	`slices.Sorted(maps.Keys(m))` (Go 1.23)
Kopieren	`maps.Clone(m)`
Vergleichen	`maps.Equal(a, b)`

Eine Map mit struct{}-Werten ist außerdem der Set-Typ von Go; siehe Sets.

Häufige Fehler

In eine nil-Map schreiben. Immer mit make anlegen, auch Map-Felder in Structs.
Sich auf die Iterationsreihenfolge verlassen. Sortier die Schlüssel.
m[k] != 0 als Test auf Vorhandensein nutzen. Nimm Comma-ok.
Ein Struct-Feld über m[k].Field ändern. Herauskopieren und zurückschreiben oder Pointer speichern.
Eine Map ohne Lock zwischen Goroutinen teilen. Der Absturz lässt sich nicht abfangen.

Häufig gestellte Fragen

Wie prüft man, ob ein Schlüssel in einer Go-Map existiert?

Mit der Form des Lookups mit zwei Werten: v, ok := m[key]. ok ist true, wenn der Schlüssel vorhanden ist, und false, wenn nicht; dann ist v der Nullwert. Ein einfaches m[key] kann einen fehlenden Schlüssel nicht von einem Schlüssel unterscheiden, der mit dem Nullwert gespeichert ist.

Warum ist die Iterationsreihenfolge einer Go-Map zufällig?

Die Sprache legt keine Reihenfolge fest, und die Runtime startet jedes range absichtlich an einer zufälligen Position, damit Programme nicht von einer Reihenfolge abhängig werden. Um in Schlüsselreihenfolge zu iterieren, sammle und sortiere die Schlüssel: for _, k := range slices.Sorted(maps.Keys(m)) (Go 1.23).

Wie bekomme ich in Go alle Schlüssel einer Map?

Seit Go 1.23 gibt maps.Keys(m) einen Iterator zurück; mach daraus mit slices.Collect(maps.Keys(m)) einen Slice oder mit slices.Sorted(maps.Keys(m)) einen sortierten Slice. Vor 1.23 schreibst du eine Schleife for k := range m und hängst jeden Schlüssel an einen Slice an.

Warum löst das Schreiben in eine Map die Panic „assignment to entry in nil map“ aus?

Die Map-Variable wurde deklariert, aber nie erzeugt: var m map[string]int ist nil. Aus einer nil-Map zu lesen liefert Nullwerte, aber Schreiben löst eine Panic aus. Erzeuge sie vorher mit m = make(map[string]int) oder einem Literal m := map[string]int{}. Ein Map-Feld in einem Struct braucht dieselbe Initialisierung.

Sind Go-Maps sicher für nebenläufige Nutzung?

Nein. Nebenläufiges Schreiben, oder Schreiben parallel zum Lesen, kann das Programm mit fatal error: concurrent map writes abstürzen lassen, und recover kann das nicht abfangen. Schütze die Map mit einem sync.Mutex oder sync.RWMutex oder nimm sync.Map für die speziellen Fälle, für die es gedacht ist.

Verwandte Konzepte