Docs Go exécutables : Maps

Q: Comment vérifier si une clé existe dans une map Go ?

Utilisez la forme à deux valeurs de la recherche : v, ok := m[key]. ok vaut true quand la clé est présente et false sinon, auquel cas v est la valeur zéro. Lire m[key] seul ne permet pas de distinguer une clé absente d'une clé stockée avec la valeur zéro.

Q: Comment récupérer toutes les clés d'une map en Go ?

Depuis Go 1.23, maps.Keys(m) renvoie un itérateur ; transformez-le en slice avec slices.Collect(maps.Keys(m)), ou en slice triée avec slices.Sorted(maps.Keys(m)). Avant 1.23, bouclez avec for k := range m et ajoutez chaque clé à une slice.

Q: Pourquoi écrire dans une map provoque-t-il le panic « assignment to entry in nil map » ?

La variable map a été déclarée mais jamais créée : var m map[string]int vaut nil. Lire une map nil renvoie des valeurs zéro, mais y écrire provoque un panic. Créez-la d'abord avec m = make(map[string]int) ou un littéral m := map[string]int{}. Un champ map dans une struct demande la même initialisation.

Créer et utiliser une map

Un type map s'écrit map[KeyType]ValueType. Créez-en une avec un littéral ou avec make, puis lisez, écrivez et supprimez par clé.

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

Sortie :

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

Deux commodités apparaissent ici. Lire une clé absente renvoie la valeur zéro du type des valeurs (counts['z'] vaut 0), ce qui fait fonctionner le comptage avec m[k]++ sans préparation. Et fmt affiche les maps avec les clés triées, ce qui est pratique pour déboguer mais ne dit rien de l'ordre d'itération.

make(map[K]V, n) accepte une indication de taille facultative. Elle préalloue de la place pour environ n entrées ; contrairement aux slices, une map n'a pas de capacité que l'on peut relire.

Tester l'existence d'une clé : comma-ok

Comme une clé absente se lit comme la valeur zéro, m[k] == 0 ne permet pas de distinguer « absente » de « stockée à 0 ». Utilisez la forme à deux valeurs :

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
}

La forme if v, ok := m[k]; ok { ... } limite la portée de v et ok au if. C'est l'une des lignes les plus courantes du code Go.

Supprimer des entrées

delete(m, key) retire l'entrée. Supprimer une clé absente ne fait rien, de même que supprimer dans une map nil. Pour vider toute une map, Go 1.21 a ajouté clear(m), qui garde la map allouée pour qu'elle puisse être réutilisée.

Supprimer des entrées pendant un range sur la même map est permis et sûr. Une entrée supprimée avant que la boucle ne l'atteigne ne sera pas produite.

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

Parcourir : l'ordre est aléatoire

for k, v := range m visite chaque entrée une fois, dans un ordre non spécifié. Le runtime rend le point de départ aléatoire exprès, donc deux boucles sur la même map dans le même programme ne sont souvent pas d'accord. Lancez ceci plusieurs fois :

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

Tout code dont la sortie dépend de l'ordre d'une map est un bug qui attend une autre exécution. Les tests qui comparent l'affichage d'une itération de map en sont l'exemple classique.

Clés triées

Pour parcourir une map dans l'ordre des clés, récupérez les clés, triez-les, et indexez la map. Go 1.23 en a fait une seule ligne grâce aux itérateurs des packages maps et 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)
}

Avec Go 1.22 et avant, maps.Keys n'existait pas dans la bibliothèque standard. L'équivalent est une boucle :

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

Autres fonctions de maps : maps.Values, maps.Clone (une copie superficielle), maps.Equal, maps.Copy(dst, src) et maps.DeleteFunc.

Types de clés valides

Les clés doivent être comparables avec == : nombres, chaînes, booléens, pointeurs, channels, tableaux de types comparables, structs dont tous les champs sont comparables, et valeurs interface. Les slices, maps et fonctions ne peuvent pas être des clés.

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

Une clé struct est la façon idiomatique d'indexer par plusieurs valeurs à la fois, au lieu de concaténer des chaînes.

Les clés interface compilent même quand le type dynamique n'est pas comparable, puis provoquent un panic à l'exécution : stocker un []int dans une map[any]int échoue avec runtime error: hash of unhashable type []int.

Les clés à virgule flottante fonctionnent, mais NaN n'est pas égal à lui-même, donc une clé NaN peut être insérée plusieurs fois sans jamais pouvoir être relue. Évitez les clés flottantes.

Map de structs

Une map peut contenir des structs, mais vous ne pouvez pas affecter un champ d'une struct stockée dans une map, parce que les valeurs d'une map ne sont pas adressables.

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

Choisissez des valeurs quand les entrées sont petites et remplacées en entier. Choisissez des pointeurs quand vous modifiez souvent des champs ou partagez le même enregistrement depuis plusieurs endroits. Avec des pointeurs, une clé absente renvoie nil, donc ptrs["nope"].Score provoque un panic.

Les maps de slices fonctionnent de la même façon pour les ajouts : groups[k] = append(groups[k], v) ne demande aucune initialisation, parce qu'une clé absente donne une slice nil et que append gère nil.

Les maps se comportent comme des références

Une valeur map fait référence à des données partagées. Affecter une map ou la passer à une fonction ne copie pas les entrées : les deux variables voient la même 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"])
}

C'est pourquoi une fonction peut remplir une map sans la renvoyer, contrairement à une slice à laquelle elle ajoute des éléments.

Le panic de la map nil

La valeur zéro d'une map est nil. Une map nil se lit comme une map vide, mais y écrire provoque un panic.

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

Sortie :

0 0
recovered: assignment to entry in nil map

Le cas de la struct est celui qui piège en pratique. Initialisez les champs map dans un constructeur (func NewCache() *Cache { return &Cache{data: map[string]string{}} }) ou paresseusement avant la première écriture.

Accès concurrent

Les maps ne sont pas sûres en accès concurrent. Si une goroutine écrit pendant qu'une autre lit ou écrit, le runtime peut arrêter le programme avec fatal error: concurrent map writes (ou concurrent map read and map write). C'est une erreur fatale, pas un panic, donc recover ne peut pas l'attraper.

Protégez la map avec un 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"])
}

Ce code affiche toujours 50 50. Utilisez sync.RWMutex quand les lectures sont bien plus nombreuses que les écritures. sync.Map existe pour deux cas précis (des clés écrites une fois et lues de nombreuses fois, ou des goroutines qui travaillent sur des clés disjointes) ; pour tout le reste, un mutex et une map ordinaire sont plus simples et généralement plus rapides. Plus de détails dans mutex.

Référence rapide

Opération	Code
Créer	`m := map[string]int{}` ou `make(map[string]int)`
Insérer ou mettre à jour	`m[k] = v`
Lire (zéro si absente)	`v := m[k]`
Tester la présence	`v, ok := m[k]`
Supprimer	`delete(m, k)`
Tout retirer	`clear(m)` (Go 1.21)
Taille	`len(m)`
Clés triées	`slices.Sorted(maps.Keys(m))` (Go 1.23)
Copier	`maps.Clone(m)`
Comparer	`maps.Equal(a, b)`

Une map avec des valeurs struct{} est aussi le type ensemble de Go ; voir les ensembles.

Erreurs courantes

Écrire dans une map nil. Faites toujours make, y compris pour les champs map des structs.
Compter sur l'ordre d'itération. Triez les clés.
Utiliser m[k] != 0 comme test de présence. Utilisez comma-ok.
Modifier un champ de struct via m[k].Field. Copiez, modifiez et réécrivez, ou stockez des pointeurs.
Partager une map entre goroutines sans verrou. Le plantage ne peut pas être récupéré.

Questions fréquentes

Comment vérifier si une clé existe dans une map Go ?

Utilisez la forme à deux valeurs de la recherche : v, ok := m[key]. ok vaut true quand la clé est présente et false sinon, auquel cas v est la valeur zéro. Lire m[key] seul ne permet pas de distinguer une clé absente d'une clé stockée avec la valeur zéro.

Pourquoi l'ordre d'itération des maps Go est-il aléatoire ?

Le langage ne définit pas d'ordre, et le runtime fait délibérément démarrer chaque range à une position aléatoire pour que les programmes ne puissent pas en dépendre. Pour parcourir dans l'ordre des clés, collectez et triez les clés : for _, k := range slices.Sorted(maps.Keys(m)) (Go 1.23).

Comment récupérer toutes les clés d'une map en Go ?

Depuis Go 1.23, maps.Keys(m) renvoie un itérateur ; transformez-le en slice avec slices.Collect(maps.Keys(m)), ou en slice triée avec slices.Sorted(maps.Keys(m)). Avant 1.23, bouclez avec for k := range m et ajoutez chaque clé à une slice.

Pourquoi écrire dans une map provoque-t-il le panic « assignment to entry in nil map » ?

La variable map a été déclarée mais jamais créée : var m map[string]int vaut nil. Lire une map nil renvoie des valeurs zéro, mais y écrire provoque un panic. Créez-la d'abord avec m = make(map[string]int) ou un littéral m := map[string]int{}. Un champ map dans une struct demande la même initialisation.

Les maps Go sont-elles sûres en accès concurrent ?

Non. Des écritures concurrentes, ou une écriture concurrente à des lectures, peuvent faire planter le programme avec fatal error: concurrent map writes, que recover ne peut pas attraper. Protégez la map avec un sync.Mutex ou un sync.RWMutex, ou utilisez sync.Map dans les cas précis pour lesquels elle est conçue.

Concepts liés