Docs Go exécutables : Enums et iota

Q: Go a-t-il des enums ?

Pas en tant que fonctionnalité du langage. Il n'y a pas de mot-clé enum. Le remplacement idiomatique est un type nommé plus un bloc de constantes typées, généralement numérotées avec iota : Le type vous donne des signatures lisibles et un endroit où accrocher des méthodes comme String(). Il n'empêche pas quelqu'un d'écrire Color(42), donc validez les valeurs qui viennent de l'extérieur.

Q: Qu'est-ce que iota en Go ?

iota est un identifiant prédéclaré qui vaut l'indice de la ligne courante (spécification de constante) dans un bloc const, à partir de 0. Il repart à 0 dans chaque nouveau bloc const. Quand une ligne omet son expression, Go répète l'expression précédente avec le iota suivant, ce qui fait que Red = iota; Green; Blue produit 0, 1, 2.

Q: Comment faire commencer iota à 1 ?

Écrivez First Kind = iota + 1 sur la première ligne, ou sautez zéro avec l'identifiant blanc : _ = iota puis First. Beaucoup de développeurs Go gardent plutôt 0 et le nomment Unknown ou Invalid, pour qu'une variable non initialisée (dont la valeur zéro est 0) ne soit manifestement pas un vrai choix.

Q: Comment afficher un enum sous forme de chaîne en Go ?

Donnez au type une méthode String() string. fmt l'appelle pour %v, %s et Println, donc fmt.Println(Green) affiche Green au lieu de 1. Vous pouvez écrire la méthode à la main avec un switch ou un tableau, ou la générer avec go run golang.org/x/tools/cmd/stringer@latest -type=Color.

Q: Comment convertir une chaîne en enum en Go ?

Écrivez une fonction de parsing qui recherche la chaîne, généralement dans une map[string]Color ou un switch, et renvoie une erreur pour une entrée inconnue : func ParseColor(s string) (Color, error). Implémenter UnmarshalText avec la même logique permet au JSON, aux flags et aux chargeurs de configuration de l'utiliser automatiquement.

Go n'a pas de mot-clé enum. Vous construisez un enum à partir de deux éléments : un type nommé, et un bloc const de valeurs de ce type, numérotées avec iota.

package main

import "fmt"

type Weekday int

const (
	Sunday    Weekday = iota // 0
	Monday                   // 1
	Tuesday                  // 2
	Wednesday                // 3
	Thursday                 // 4
	Friday                   // 5
	Saturday                 // 6
)

func isWeekend(d Weekday) bool {
	return d == Saturday || d == Sunday
}

func main() {
	fmt.Println(Monday, Friday, Saturday)
	fmt.Println("Saturday is weekend:", isWeekend(Saturday))
	fmt.Println("Tuesday is weekend:", isWeekend(Tuesday))
}

Sunday vaut 0, et chaque ligne suivante vaut un de plus. C'est le type nommé Weekday qui en fait un enum plutôt qu'une liste de nombres : isWeekend dit dans sa signature ce qu'elle attend, et on peut ajouter des méthodes au type. La sortie affiche 1 5 6 parce que rien n'indique encore à Go comment afficher un Weekday sous forme de texte. Cela vient plus bas.

Comment fonctionne iota

iota est un compteur que le compilateur fournit dans un bloc const. Deux règles expliquent toutes les astuces construites dessus :

iota vaut l'indice de la ligne courante dans le bloc, à partir de 0, et repart à 0 dans chaque nouveau bloc const.
Une ligne sans = expression répète l'expression et le type de la ligne précédente, évalués avec le nouveau iota.

Donc Monday ci-dessus est un raccourci pour Monday Weekday = iota, avec iota qui vaut maintenant 1. Comme l'expression est répétée, elle peut être n'importe quelle expression constante, pas seulement iota :

package main

import "fmt"

type Size int64

const (
	_  Size = iota             // 0, discarded
	KB Size = 1 << (10 * iota) // 1 << 10
	MB                         // 1 << 20
	GB                         // 1 << 30
	TB                         // 1 << 40
)

const (
	A = iota * 10 // 0
	B             // 10
	C             // 20
)

const (
	X, Y = iota, iota + 100 // both on line 0: 0, 100
	Z, W                    // line 1: 1, 101
)

func main() {
	fmt.Println(KB, MB, GB, TB)
	fmt.Println(A, B, C)
	fmt.Println(X, Y, Z, W)
}

iota compte les lignes, pas les noms : deux constantes sur la même ligne partagent une seule valeur de iota, comme le montrent X et Y.

Commencer à 1, et pourquoi ne pas le faire

Une variable d'un type enum que personne n'a définie contient 0, sa valeur zéro. Si 0 est une vraie valeur comme Sunday, vous ne pouvez pas distinguer « l'utilisateur a choisi dimanche » de « le champ n'a jamais été rempli ». Trois corrections courantes :

package main

import "fmt"

type Status int

// Option 1: reserve 0 for an explicit "unknown" value.
const (
	StatusUnknown Status = iota
	StatusActive
	StatusSuspended
	StatusDeleted
)

type Level int

// Option 2: start at 1 with iota + 1.
const (
	Low Level = iota + 1
	Medium
	High
)

type Priority int

// Option 3: skip 0 with the blank identifier.
const (
	_ Priority = iota
	P1
	P2
	P3
)

type Account struct {
	Name   string
	Status Status
}

func main() {
	var a Account // Status was never set
	fmt.Println(a.Status == StatusUnknown)
	fmt.Println(Low, Medium, High)
	fmt.Println(P1, P2, P3)
}

L'option 1 est la plus courante dans le code de production, et les enums Go générés par protobuf la suivent (..._UNSPECIFIED = 0). La valeur zéro signifie alors quelque chose d'honnête.

Sauter des valeurs

L'identifiant blanc _ consomme une valeur de iota sans créer de nom. Servez-vous-en pour laisser des trous, par exemple pour correspondre à des numéros définis par un protocole ou pour retirer une valeur sans renuméroter le reste :

type Opcode byte

const (
	OpContinue Opcode = iota // 0
	OpText                   // 1
	OpBinary                 // 2
	_                        // 3, reserved
	_                        // 4, reserved
	_                        // 5, reserved
	_                        // 6, reserved
	_                        // 7, reserved
	OpClose                  // 8
	OpPing                   // 9
	OpPong                   // 10
)

Quand les numéros sont fixés par une spécification externe, comme ces opcodes WebSocket, les écrire explicitement (OpClose Opcode = 8) est souvent plus clair que de compter des blancs. iota est fait pour des valeurs dont les numéros exacts vous importent peu.

Ne réordonnez jamais une liste iota et n'y insérez rien si ses numéros sont stockés dans une base de données, un fichier, ou envoyés sur le réseau. Ajouter une ligne au milieu décale toutes les valeurs suivantes. Ajoutez les nouvelles valeurs à la fin, ou attribuez les numéros explicitement.

Ajouter une méthode String

Donnez au type une méthode String() string et fmt l'utilise pour %v, %s et Println :

package main

import "fmt"

type Weekday int

const (
	Sunday Weekday = iota
	Monday
	Tuesday
	Wednesday
	Thursday
	Friday
	Saturday
)

var weekdayNames = [...]string{
	"Sunday", "Monday", "Tuesday", "Wednesday",
	"Thursday", "Friday", "Saturday",
}

func (d Weekday) String() string {
	if d < 0 || int(d) >= len(weekdayNames) {
		return fmt.Sprintf("Weekday(%d)", int(d))
	}
	return weekdayNames[d]
}

func main() {
	fmt.Println(Monday, Friday)
	fmt.Printf("%v is day %d\n", Wednesday, Wednesday)
	fmt.Println(Weekday(9)) // out of range, still prints something useful

	today := Saturday
	fmt.Println("today:", today)
}

Deux détails de cette méthode comptent :

La vérification des bornes. Sans elle, Weekday(9).String() provoque un panic d'indice hors limites, et cela finira par arriver, car rien n'empêche un appelant de créer Weekday(9).
Le int(d) dans Sprintf. Formater d lui-même avec %d ne pose pas de problème, mais le formater avec %v appellerait de nouveau String() et récurserait jusqu'au débordement de pile.

%d affiche toujours le nombre, donc vous avez les deux formes : Wednesday is day 3.

Générer String avec stringer

Pour les longues listes, l'outil stringer écrit la méthode à votre place :

//go:generate go run golang.org/x/tools/cmd/stringer@latest -type=Weekday

go generate ./...

Il crée weekday_string.go avec une implémentation compacte de String(), plus une vérification à la compilation qui casse le build si les constantes changent sans régénération. Le flag -linecomment utilise un commentaire de fin de ligne comme nom, pratique pour des noms avec des espaces.

Valider les valeurs

Un enum Go n'est pas fermé. Toute valeur du type sous-jacent s'y convertit, et les constantes non typées s'y convertissent implicitement :

var d Weekday = 42     // compiles
d = Weekday(userInput) // compiles

Vérifiez donc les valeurs qui viennent de l'extérieur de votre code (JSON, bases de données, flags, autres packages) :

package main

import (
	"fmt"
	"strings"
)

type Color int

const (
	ColorUnknown Color = iota
	Red
	Green
	Blue
	colorCount // unexported sentinel: always last
)

var colorNames = map[Color]string{
	Red:   "red",
	Green: "green",
	Blue:  "blue",
}

func (c Color) String() string {
	if name, ok := colorNames[c]; ok {
		return name
	}
	return fmt.Sprintf("Color(%d)", int(c))
}

func (c Color) IsValid() bool {
	return c > ColorUnknown && c < colorCount
}

func ParseColor(s string) (Color, error) {
	for c, name := range colorNames {
		if strings.EqualFold(name, s) {
			return c, nil
		}
	}
	return ColorUnknown, fmt.Errorf("unknown color %q", s)
}

func main() {
	fmt.Println(Green.IsValid(), Color(7).IsValid(), ColorUnknown.IsValid())

	for _, in := range []string{"BLUE", "purple"} {
		c, err := ParseColor(in)
		if err != nil {
			fmt.Println("error:", err)
			continue
		}
		fmt.Println("parsed:", c)
	}
}

La sentinelle non exportée colorCount à la fin du bloc garde IsValid correct quand vous ajoutez de nouvelles couleurs, puisqu'elle se trouve toujours juste après la dernière vraie valeur.

Un switch sur un enum

Les enums sont généralement consommés par un switch. Go ne vérifie pas qu'un switch couvre toutes les valeurs, donc ajoutez un default qui signale la surprise :

func (c Color) Hex() string {
	switch c {
	case Red:
		return "#ff0000"
	case Green:
		return "#00ff00"
	case Blue:
		return "#0000ff"
	default:
		return "#000000"
	}
}

Le linter tiers exhaustive (inclus dans golangci-lint) signale les switchs sur des types enum qui oublient un cas, ce qui vous donne l'essentiel de ce qu'apporte la vérification d'exhaustivité des enums dans d'autres langages.

Enums en flags binaires

Quand les valeurs se combinent, comme des permissions, utilisez un bit par valeur avec 1 << iota :

package main

import (
	"fmt"
	"strings"
)

type Permission uint8

const (
	Read    Permission = 1 << iota // 1
	Write                          // 2
	Execute                        // 4
)

func (p Permission) Has(flag Permission) bool {
	return p&flag != 0
}

func (p Permission) String() string {
	if p == 0 {
		return "none"
	}
	var parts []string
	for _, f := range []struct {
		flag Permission
		name string
	}{{Read, "read"}, {Write, "write"}, {Execute, "execute"}} {
		if p.Has(f.flag) {
			parts = append(parts, f.name)
		}
	}
	return strings.Join(parts, "|")
}

func main() {
	p := Read | Write
	fmt.Println(p, int(p))
	fmt.Println("can write:", p.Has(Write))
	fmt.Println("can execute:", p.Has(Execute))

	p |= Execute // add a flag
	p &^= Write  // remove a flag (AND NOT)
	fmt.Println(p)

	var none Permission
	fmt.Println(none)
}

| combine des flags, & les teste, et &^ (l'opérateur ET NON de Go) les efface. Un type sous-jacent non signé est le bon choix ici : uint8 contient 8 flags, uint64 en contient 64.

Enums de chaînes

Quand la valeur est de toute façon stockée ou envoyée sous forme de texte, un type basé sur string évite la couche de conversion :

type Env string

const (
	EnvDev     Env = "dev"
	EnvStaging Env = "staging"
	EnvProd    Env = "prod"
)

Les valeurs s'affichent et se sérialisent lisiblement sans méthode String(), et une colonne de base de données contient "prod" au lieu d'un nombre qui dépend de l'ordre de déclaration. Les compromis : les comparaisons sont des comparaisons de chaînes, les flags binaires sont impossibles, et la validation reste à votre charge, puisque Env("banana") compile aussi.

Enums et JSON

Un enum entier se sérialise par défaut comme un nombre. Pour lire et écrire des noms à la place, implémentez encoding.TextMarshaler et encoding.TextUnmarshaler. encoding/json les utilise pour les valeurs et pour les clés de map :

package main

import (
	"encoding/json"
	"fmt"
)

type Level int

const (
	LevelUnknown Level = iota
	LevelLow
	LevelHigh
)

var levelNames = []string{"unknown", "low", "high"}

func (l Level) String() string {
	if l < 0 || int(l) >= len(levelNames) {
		return fmt.Sprintf("Level(%d)", int(l))
	}
	return levelNames[l]
}

func (l Level) MarshalText() ([]byte, error) {
	return []byte(l.String()), nil
}

func (l *Level) UnmarshalText(b []byte) error {
	for i, name := range levelNames {
		if name == string(b) {
			*l = Level(i)
			return nil
		}
	}
	return fmt.Errorf("invalid level %q", b)
}

type Alert struct {
	Message string `json:"message"`
	Level   Level  `json:"level"`
}

func main() {
	out, err := json.Marshal(Alert{Message: "disk full", Level: LevelHigh})
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println(string(out))

	var a Alert
	err = json.Unmarshal([]byte(`{"message":"cpu","level":"low"}`), &a)
	fmt.Println(a.Level, err)

	err = json.Unmarshal([]byte(`{"message":"cpu","level":"extreme"}`), &a)
	fmt.Println(err)
}

MarshalText a un receveur valeur pour fonctionner à la fois sur Level et *Level ; UnmarshalText a besoin d'un receveur pointeur parce qu'il modifie la valeur. Ces deux mêmes méthodes font fonctionner le type avec TextVar du package flag et avec la plupart des bibliothèques de configuration.

Pièges

Conversion implicite des littéraux. Une fonction qui prend un Weekday accepte aussi la constante non typée 42. Seules les valeurs typées d'un autre type sont rejetées.
Oublier le type sur la première ligne. Dans const ( Red = iota; Green; Blue ), les trois sont des constantes entières non typées, pas des valeurs Color, donc les méthodes de Color ne s'appliquent pas à elles. Écrivez Red Color = iota pour que l'expression répétée porte le type.
Réordonner des enums stockés. Insérer une valeur au milieu d'un bloc iota change silencieusement les numéros déjà enregistrés ailleurs.
Récursion dans String. Dans String(), ne formatez jamais le receveur avec %v ou %s. Convertissez d'abord vers le type sous-jacent.

Questions fréquentes

Go a-t-il des enums ?

Pas en tant que fonctionnalité du langage. Il n'y a pas de mot-clé enum. Le remplacement idiomatique est un type nommé plus un bloc de constantes typées, généralement numérotées avec iota :

type Color int

const (
	Red Color = iota
	Green
	Blue
)

Le type vous donne des signatures lisibles et un endroit où accrocher des méthodes comme String(). Il n'empêche pas quelqu'un d'écrire Color(42), donc validez les valeurs qui viennent de l'extérieur.

Qu'est-ce que iota en Go ?

iota est un identifiant prédéclaré qui vaut l'indice de la ligne courante (spécification de constante) dans un bloc const, à partir de 0. Il repart à 0 dans chaque nouveau bloc const. Quand une ligne omet son expression, Go répète l'expression précédente avec le iota suivant, ce qui fait que Red = iota; Green; Blue produit 0, 1, 2.

Comment faire commencer iota à 1 ?

Écrivez First Kind = iota + 1 sur la première ligne, ou sautez zéro avec l'identifiant blanc : _ = iota puis First. Beaucoup de développeurs Go gardent plutôt 0 et le nomment Unknown ou Invalid, pour qu'une variable non initialisée (dont la valeur zéro est 0) ne soit manifestement pas un vrai choix.

Comment afficher un enum sous forme de chaîne en Go ?

Donnez au type une méthode String() string. fmt l'appelle pour %v, %s et Println, donc fmt.Println(Green) affiche Green au lieu de 1. Vous pouvez écrire la méthode à la main avec un switch ou un tableau, ou la générer avec go run golang.org/x/tools/cmd/stringer@latest -type=Color.

Comment convertir une chaîne en enum en Go ?

Écrivez une fonction de parsing qui recherche la chaîne, généralement dans une map[string]Color ou un switch, et renvoie une erreur pour une entrée inconnue : func ParseColor(s string) (Color, error). Implémenter UnmarshalText avec la même logique permet au JSON, aux flags et aux chargeurs de configuration de l'utiliser automatiquement.

Concepts liés