Исполняемые доки Go: Enum и iota

Q: Есть ли в Go перечисления (enum)?

Как возможности языка нет. Ключевого слова enum не существует. Идиоматичная замена: именованный тип плюс блок типизированных констант, обычно пронумерованных через iota: Тип даёт читаемые сигнатуры и место для методов вроде String(). Он не мешает написать Color(42), поэтому значения, пришедшие извне, нужно проверять.

Q: Что такое iota в Go?

iota это предопределённый идентификатор, равный номеру текущей строки (спецификации константы) внутри блока const, начиная с 0. В каждом новом блоке const он сбрасывается в 0. Если в строке нет выражения, Go повторяет предыдущее выражение со следующим значением iota, поэтому Red = iota; Green; Blue даёт 0, 1, 2.

Q: Как сделать, чтобы iota начинался с 1?

Напишите в первой строке First Kind = iota + 1 или пропустите ноль через пустой идентификатор: _ = iota, затем First. Многие Go-разработчики вместо этого оставляют 0 и называют его Unknown или Invalid, чтобы неинициализированная переменная (нулевое значение которой 0) явно не была настоящим вариантом.

Q: Как вывести enum строкой в Go?

Дайте типу метод String() string. fmt вызывает его для %v, %s и Println, поэтому fmt.Println(Green) печатает Green, а не 1. Метод можно написать вручную через switch или массив либо сгенерировать командой go run golang.org/x/tools/cmd/stringer@latest -type=Color.

Q: Как преобразовать строку в enum в Go?

Напишите функцию разбора, которая ищет строку, обычно в map[string]Color или через switch, и возвращает ошибку для неизвестного ввода: func ParseColor(s string) (Color, error). Если реализовать UnmarshalText с той же логикой, JSON, флаги и загрузчики конфигурации будут использовать её автоматически.

Ключевого слова enum в Go нет. Перечисление собирается из двух частей: именованного типа и блока const со значениями этого типа, пронумерованными через 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 равен 0, а каждая следующая строка на единицу больше. Именно именованный тип Weekday делает это перечислением, а не списком чисел: isWeekend в своей сигнатуре сообщает, что ожидает, а к типу можно добавить методы. Вывод печатает 1 5 6, потому что пока ничто не говорит Go, как показывать Weekday текстом. Об этом ниже.

Как работает iota

iota это счётчик, который компилятор предоставляет внутри блока const. Два правила объясняют все приёмы на его основе:

iota равен номеру текущей строки в блоке, начиная с 0, и сбрасывается в 0 в каждом новом блоке const.
Строка без = выражение повторяет выражение и тип предыдущей строки, вычисленные с новым iota.

Поэтому Monday выше это сокращение для Monday Weekday = iota, где iota уже равен 1. Раз выражение повторяется, оно может быть любым константным выражением, а не только 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 считает строки, а не имена: две константы в одной строке делят одно значение iota, как показывают X и Y.

Начать с 1, и почему этого можно не делать

Переменная типа-перечисления, которой никто не присвоил значение, хранит 0, своё нулевое значение. Если 0 это настоящее значение вроде Sunday, нельзя отличить «пользователь выбрал воскресенье» от «поле так и не заполнили». Три распространённых решения:

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

Вариант 1 самый частый в продакшен-коде, и перечисления Go, сгенерированные из protobuf, следуют ему (..._UNSPECIFIED = 0). Нулевое значение тогда означает что-то честное.

Пропуск значений

Пустой идентификатор _ расходует значение iota, не создавая имени. С его помощью оставляют пропуски, например чтобы совпасть с числами из протокола или убрать значение, не перенумеровывая остальные:

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
)

Когда числа зафиксированы внешней спецификацией, как у этих опкодов WebSocket, явная запись (OpClose Opcode = 8) часто понятнее, чем подсчёт пропусков. iota нужен для значений, конкретные номера которых вам безразличны.

Никогда не переставляйте и не вставляйте строки в список iota, если его числа сохраняются в базе данных, файле или отправляются по сети. Добавленная в середину строка сдвигает все значения после неё. Новые значения добавляйте в конец или задавайте числа явно.

Добавляем метод String

Дайте типу метод String() string, и fmt будет использовать его для %v, %s и 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)
}

В этом методе важны две детали:

Проверка границ. Без неё Weekday(9).String() запаникует с выходом индекса за границы, и рано или поздно это случится, потому что ничто не мешает вызывающему коду создать Weekday(9).
int(d) внутри Sprintf. Форматировать сам d через %d можно, но форматирование через %v снова вызовет String(), и рекурсия продолжится до переполнения стека.

%d по-прежнему печатает число, так что доступны обе формы: Wednesday is day 3.

Генерация String через stringer

Для длинных списков метод за вас напишет утилита stringer:

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

go generate ./...

Она создаёт weekday_string.go с компактной реализацией String(), а также проверку на этапе компиляции, которая ломает сборку, если константы изменились, а код не перегенерировали. Флаг -linecomment берёт имя из комментария в конце строки, что удобно для имён с пробелами.

Проверка значений

Перечисление в Go не замкнуто. Любое значение базового типа преобразуется в него, а нетипизированные константы преобразуются неявно:

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

Поэтому проверяйте значения, пришедшие извне вашего кода (JSON, базы данных, флаги, другие пакеты):

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

Неэкспортированный маркер colorCount в конце блока сохраняет корректность IsValid при добавлении новых цветов, потому что он всегда стоит на единицу дальше последнего настоящего значения.

switch по перечислению

Перечисления обычно обрабатываются через switch. Go не проверяет, что switch покрывает все значения, поэтому добавьте default, который сообщает о неожиданности:

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

Сторонний линтер exhaustive (входит в golangci-lint) сообщает о switch по типам-перечислениям, где пропущен вариант, и это даёт большую часть того, что в других языках дают проверки полноты перечислений.

Перечисления битовых флагов

Когда значения комбинируются, как права доступа, используйте по одному биту на значение через 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)
}

| объединяет флаги, & проверяет их, а &^ (оператор AND NOT в Go) сбрасывает. Здесь правильно выбрать беззнаковый базовый тип: uint8 вмещает 8 флагов, uint64 вмещает 64.

Строковые перечисления

Когда значение всё равно хранится или передаётся текстом, тип на основе строки избавляет от слоя преобразований:

type Env string

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

Значения печатаются и сериализуются читаемо без метода String(), а столбец базы данных хранит "prod", а не число, зависящее от порядка объявления. Компромиссы: сравнения становятся сравнениями строк, битовые флаги невозможны, а проверка всё равно на вас, ведь Env("banana") тоже компилируется.

Перечисления и JSON

Целочисленное перечисление по умолчанию сериализуется как число. Чтобы читать и писать имена, реализуйте encoding.TextMarshaler и encoding.TextUnmarshaler. encoding/json использует их для значений и для ключей мап:

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 получатель-значение, поэтому он работает и для Level, и для *Level; UnmarshalText нужен получатель-указатель, потому что он меняет значение. Эти же два метода позволяют типу работать с TextVar из пакета flag и с большинством библиотек конфигурации.

Подводные камни

Неявное преобразование литералов. Функция, принимающая Weekday, примет и нетипизированную константу 42. Отвергаются только типизированные значения другого типа.
Тип не указан в первой строке. В const ( Red = iota; Green; Blue ) все три это нетипизированные целочисленные константы, а не значения Color, так что методы Color к ним не относятся. Пишите Red Color = iota, чтобы повторяемое выражение несло тип.
Перестановка сохраняемых перечислений. Вставка значения в середину блока iota молча меняет числа, которые уже где-то сохранены.
Рекурсия в String. Внутри String() никогда не форматируйте получатель через %v или %s. Сначала преобразуйте его в базовый тип.

Часто задаваемые вопросы

Есть ли в Go перечисления (enum)?

Как возможности языка нет. Ключевого слова enum не существует. Идиоматичная замена: именованный тип плюс блок типизированных констант, обычно пронумерованных через iota:

type Color int

const (
	Red Color = iota
	Green
	Blue
)

Тип даёт читаемые сигнатуры и место для методов вроде String(). Он не мешает написать Color(42), поэтому значения, пришедшие извне, нужно проверять.

Что такое iota в Go?

iota это предопределённый идентификатор, равный номеру текущей строки (спецификации константы) внутри блока const, начиная с 0. В каждом новом блоке const он сбрасывается в 0. Если в строке нет выражения, Go повторяет предыдущее выражение со следующим значением iota, поэтому Red = iota; Green; Blue даёт 0, 1, 2.

Как сделать, чтобы iota начинался с 1?

Напишите в первой строке First Kind = iota + 1 или пропустите ноль через пустой идентификатор: _ = iota, затем First. Многие Go-разработчики вместо этого оставляют 0 и называют его Unknown или Invalid, чтобы неинициализированная переменная (нулевое значение которой 0) явно не была настоящим вариантом.

Как вывести enum строкой в Go?

Дайте типу метод String() string. fmt вызывает его для %v, %s и Println, поэтому fmt.Println(Green) печатает Green, а не 1. Метод можно написать вручную через switch или массив либо сгенерировать командой go run golang.org/x/tools/cmd/stringer@latest -type=Color.

Как преобразовать строку в enum в Go?

Напишите функцию разбора, которая ищет строку, обычно в map[string]Color или через switch, и возвращает ошибку для неизвестного ввода: func ParseColor(s string) (Color, error). Если реализовать UnmarshalText с той же логикой, JSON, флаги и загрузчики конфигурации будут использовать её автоматически.

Связанные концепции