Dokumentacja Go z przykładami: Mapy

Q: Jak sprawdzić, czy klucz istnieje w mapie w Go?

Użyj dwuwartościowej formy odczytu: v, ok := m[key]. ok ma wartość true, gdy klucz jest obecny, i false, gdy go nie ma, a wtedy v ma wartość zerową. Samo odczytanie m[key] nie odróżni brakującego klucza od klucza zapisanego z wartością zerową.

Q: Jak pobrać wszystkie klucze mapy w Go?

Od Go 1.23 maps.Keys(m) zwraca iterator; zamień go na slice przez slices.Collect(maps.Keys(m)) albo na posortowany slice przez slices.Sorted(maps.Keys(m)). Przed 1.23 przejdź pętlą for k := range m i dołączaj każdy klucz do slice'a.

Tworzenie i używanie mapy

Typ mapy zapisuje się jako map[KeyType]ValueType. Utwórz mapę literałem albo przez make, a potem odczytuj, zapisuj i usuwaj wpisy po kluczu.

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'])
}

Wynik:

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

Widać tu dwa udogodnienia. Odczyt brakującego klucza zwraca wartość zerową typu wartości (counts['z'] to 0), dzięki czemu liczenie przez m[k]++ działa bez przygotowań. A fmt wypisuje mapy z posortowanymi kluczami, co pomaga przy debugowaniu, ale nic nie mówi o kolejności iteracji.

make(map[K]V, n) przyjmuje opcjonalną wskazówkę rozmiaru. Rezerwuje miejsce na około n wpisów; w odróżnieniu od slice'ów mapa nie ma pojemności, którą można odczytać.

Sprawdzanie, czy klucz istnieje: comma-ok

Ponieważ brakujący klucz odczytuje się jako wartość zerową, m[k] == 0 nie odróżni „brak” od „zapisane jako 0”. Użyj formy dwuwartościowej:

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
}

Kształt if v, ok := m[k]; ok { ... } ogranicza zasięg v i ok do tego if. To jedna z najczęstszych linii w kodzie Go.

Usuwanie wpisów

delete(m, key) usuwa wpis. Usunięcie klucza, którego nie ma, nic nie robi, podobnie jak usuwanie z mapy nil. Aby opróżnić całą mapę, Go 1.21 dodało clear(m), które zachowuje zaalokowaną mapę do ponownego użycia.

Usuwanie wpisów w trakcie range po tej samej mapie jest dozwolone i bezpieczne. Wpis usunięty, zanim pętla do niego dotrze, nie zostanie zwrócony.

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))
}

Iteracja: kolejność jest losowa

for k, v := range m odwiedza każdy wpis raz, w nieokreślonej kolejności. Runtime celowo losuje punkt startowy, więc dwie pętle po tej samej mapie w tym samym programie często dają różne wyniki. Uruchom to kilka razy:

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()
	}
}

Każdy kod, którego wynik zależy od kolejności w mapie, to błąd czekający na inne uruchomienie. Klasyczny przykład to testy porównujące wypisaną iterację po mapie.

Posortowane klucze

Aby odwiedzić mapę w kolejności kluczy, pobierz klucze, posortuj je i odczytuj mapę po indeksie. Go 1.23 skróciło to do jednej linii dzięki iteratorom z pakietów maps i slices:

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)
}

W Go 1.22 i starszych maps.Keys nie istniało w bibliotece standardowej. Odpowiednikiem jest pętla:

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

Inne funkcje pomocnicze w maps: maps.Values, maps.Clone (płytka kopia), maps.Equal, maps.Copy(dst, src) i maps.DeleteFunc.

Dozwolone typy kluczy

Klucze muszą być porównywalne przez ==: liczby, stringi, wartości logiczne, wskaźniki, kanały, tablice typów porównywalnych, struktury, których wszystkie pola są porównywalne, i wartości interfejsów. Slice'y, mapy i funkcje nie mogą być kluczami.

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

Klucz w postaci struktury to idiomatyczny sposób na indeksowanie kilkoma wartościami naraz, zamiast sklejania stringów.

Klucze interfejsowe kompilują się nawet wtedy, gdy typ dynamiczny nie jest porównywalny, a potem wywołują panikę w czasie działania: zapisanie []int w map[any]int kończy się błędem runtime error: hash of unhashable type []int.

Klucze zmiennoprzecinkowe działają, ale NaN nie jest równe samemu sobie, więc klucz NaN można wstawiać wielokrotnie i nigdy go nie odczytać. Unikaj kluczy typu float.

Mapa struktur

Mapa może przechowywać struktury, ale nie można przypisać wartości do pola struktury zapisanej w mapie, bo wartości w mapie nie są adresowalne.

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"])
}

Wybierz wartości, gdy wpisy są małe i podmieniane w całości. Wybierz wskaźniki, gdy często aktualizujesz pola albo współdzielisz ten sam rekord z kilku miejsc. Przy wskaźnikach brakujący klucz zwraca nil, więc ptrs["nope"].Score wywołuje panikę.

Mapy slice'ów działają tak samo przy dołączaniu: groups[k] = append(groups[k], v) nie wymaga inicjalizacji, bo brakujący klucz daje slice nil, a append radzi sobie z nil.

Mapy zachowują się jak referencje

Wartość mapy odwołuje się do współdzielonych danych. Przypisanie mapy albo przekazanie jej do funkcji nie kopiuje wpisów: obie zmienne widzą tę samą 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"])
}

Dlatego funkcja może wypełnić mapę bez jej zwracania, inaczej niż slice, do którego dołącza elementy.

Panika przy mapie nil

Wartość zerowa mapy to nil. Mapa nil przy odczycie zachowuje się jak pusta mapa, ale zapis do niej wywołuje panikę.

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")
}

Wynik:

0 0
recovered: assignment to entry in nil map

W praktyce najczęściej gryzie przypadek ze strukturą. Inicjalizuj pola typu mapa w konstruktorze (func NewCache() *Cache { return &Cache{data: map[string]string{}} }) albo leniwie przed pierwszym zapisem.

Dostęp współbieżny

Mapy nie są bezpieczne przy współbieżnym użyciu. Jeśli jedna gorutyna zapisuje, a inna czyta lub zapisuje, runtime może zatrzymać program z fatal error: concurrent map writes (albo concurrent map read and map write). To błąd krytyczny, a nie panika, więc recover go nie złapie.

Chroń mapę mutexem:

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"])
}

To zawsze wypisuje 50 50. Użyj sync.RWMutex, gdy odczytów jest znacznie więcej niż zapisów. sync.Map istnieje dla dwóch wąskich przypadków (klucze zapisywane raz i czytane wiele razy albo gorutyny pracujące na rozłącznych kluczach); we wszystkich innych mutex i zwykła mapa są prostsze i zwykle szybsze. Więcej na ten temat w artykule o mutexie.

Ściągawka

Operacja	Kod
Utworzenie	`m := map[string]int{}` albo `make(map[string]int)`
Wstawienie lub aktualizacja	`m[k] = v`
Odczyt (zero, jeśli brak)	`v := m[k]`
Sprawdzenie obecności	`v, ok := m[k]`
Usunięcie	`delete(m, k)`
Usunięcie wszystkiego	`clear(m)` (Go 1.21)
Rozmiar	`len(m)`
Posortowane klucze	`slices.Sorted(maps.Keys(m))` (Go 1.23)
Kopia	`maps.Clone(m)`
Porównanie	`maps.Equal(a, b)`

Mapa z wartościami struct{} to w Go także typ zbioru; zobacz zbiory.

Częste błędy

Zapis do mapy nil. Zawsze twórz ją przez make, także pola typu mapa w strukturach.
Poleganie na kolejności iteracji. Posortuj klucze.
Używanie m[k] != 0 jako testu obecności. Użyj comma-ok.
Modyfikowanie pola struktury przez m[k].Field. Skopiuj wartość, zmień i zapisz z powrotem albo przechowuj wskaźniki.
Współdzielenie mapy między gorutynami bez blokady. Tej awarii nie da się przechwycić.

Najczęściej zadawane pytania

Jak sprawdzić, czy klucz istnieje w mapie w Go?

Użyj dwuwartościowej formy odczytu: v, ok := m[key]. ok ma wartość true, gdy klucz jest obecny, i false, gdy go nie ma, a wtedy v ma wartość zerową. Samo odczytanie m[key] nie odróżni brakującego klucza od klucza zapisanego z wartością zerową.

Dlaczego kolejność iteracji po mapie w Go jest losowa?

Język nie definiuje kolejności, a runtime celowo zaczyna każde range w losowym miejscu, żeby programy nie mogły od niej zależeć. Aby iterować w kolejności kluczy, zbierz je i posortuj: for _, k := range slices.Sorted(maps.Keys(m)) (Go 1.23).

Jak pobrać wszystkie klucze mapy w Go?

Od Go 1.23 maps.Keys(m) zwraca iterator; zamień go na slice przez slices.Collect(maps.Keys(m)) albo na posortowany slice przez slices.Sorted(maps.Keys(m)). Przed 1.23 przejdź pętlą for k := range m i dołączaj każdy klucz do slice'a.

Dlaczego zapis do mapy kończy się paniką "assignment to entry in nil map"?

Zmienna mapy została zadeklarowana, ale mapa nigdy nie została utworzona: var m map[string]int to nil. Odczyt z mapy nil zwraca wartości zerowe, ale zapis wywołuje panikę. Najpierw utwórz mapę przez m = make(map[string]int) albo literał m := map[string]int{}. Pole typu mapa w strukturze wymaga takiej samej inicjalizacji.

Czy mapy w Go są bezpieczne przy współbieżnym użyciu?

Nie. Współbieżne zapisy albo zapis równoległy z odczytami mogą wywrócić program z fatal error: concurrent map writes, czego recover nie złapie. Chroń mapę przez sync.Mutex albo sync.RWMutex lub użyj sync.Map w konkretnych przypadkach, do których została zaprojektowana.

Powiązane zagadnienia