Ошибки и их решения

Атрибут [Flags] в перечислениях C#: примеры и правила

4 мин чтения

Атрибут [Flags] превращает обычный enum в набор битовых флагов, которые можно комбинировать в одной переменной. Так в C# удобно хранить права доступа, настройки и состояния. Ниже разобрано, как задавать значения, проверять и снимать флаги и какие ошибки встречаются чаще всего.

Атрибут [Flags] в перечислениях C#: примеры и правила
Содержание
  1. Чем перечисление с [Flags] отличается от обычного
  2. Как объявить перечисление с флагами
  3. Как задавать значения флагов
  4. Комбинирование и проверка флагов
  5. Как убрать и переключить флаг
  6. Вывод и разбор флагов из строки
  7. Преимущества флагов и типичные ошибки
  8. Частые вопросы

Чем перечисление с [Flags] отличается от обычного

Обычное перечисление хранит одно значение из набора именованных целочисленных констант. Например, для дней недели не нужно, чтобы переменная одновременно была и понедельником, и вторником.

Атрибут [Flags] сообщает, что значения перечисления нужно воспринимать как отдельные биты. Тогда несколько констант объединяются побитовыми операциями: ИЛИ (|), И (&), исключающее ИЛИ (^) и отрицание (~). Сам атрибут не меняет значения констант, он влияет на строковое представление и служит подсказкой для других разработчиков и инструментов.

Как объявить перечисление с флагами

Над объявлением enum ставят [Flags], а значения задают степенями двойки: 1, 2, 4, 8 и так далее. Каждое такое число занимает свой бит, поэтому комбинации не пересекаются. Имя FileAccess уже занято в пространстве имён System.IO, поэтому в примере используется другое название.

[Flags]
public enum AccessRights
{
    Read = 1,    // 0001
    Write = 2,   // 0010
    Execute = 4, // 0100
    ReadWrite = Read | Write // 0011
}

Константа ReadWrite здесь собрана из двух других. Такие готовые комбинации удобны, когда одни и те же наборы флагов используются часто.

Как задавать значения флагов

Каждое значение должно быть степенью двойки, иначе биты начнут пересекаться и проверка даст ложные срабатывания. Если писать числа вручную, легко ошибиться, поэтому чаще применяют сдвиг влево 1 << n. Также принято добавлять нулевое значение None, чтобы было с чем сравнивать пустой набор.

[Flags]
public enum FilePermissions
{
    None = 0,                    // 0000
    Read = 1 << 0,               // 0001
    Write = 1 << 1,              // 0010
    Execute = 1 << 2,            // 0100
    All = Read | Write | Execute // 0111
}

Если флагов может быть больше 32, базовый тип меняют на long: enum FilePermissions : long. Тогда сдвиги пишут как 1L << n.

Комбинирование и проверка флагов

Чтобы объединить флаги, используют операцию ИЛИ. Переменная после этого содержит сразу несколько значений:

AccessRights myAccess = AccessRights.Read | AccessRights.Write;

Для проверки применяют операцию И: результат равен искомому флагу, если этот флаг установлен. В современных версиях .NET есть и метод HasFlag, он короче, но читается чуть хуже при сложных масках.

if ((myAccess & AccessRights.Read) == AccessRights.Read)
{
    Console.WriteLine("Read access is granted.");
}

// то же самое через HasFlag
if (myAccess.HasFlag(AccessRights.Read))
{
    Console.WriteLine("Read access is granted.");
}

Если флаг Read установлен, условие истинно и сообщение будет выведено. Проверку на отсутствие любых флагов делают сравнением с None.

Как убрать и переключить флаг

Чтобы гарантированно снять флаг, комбинируют И и отрицание: value &= ~flag. Такая запись безопасна, даже если флаг не был установлен. Исключающее ИЛИ (^) работает как переключатель: если флаг был, он исчезнет, а если не было, появится.

FilePermissions permissions = FilePermissions.Read | FilePermissions.Write;

permissions &= ~FilePermissions.Write; // убираем флаг Write
permissions ^= FilePermissions.Execute; // переключаем Execute: теперь он включён
permissions |= FilePermissions.Write;   // добавляем Write обратно

После первой строки переменная содержит только Read, после второй - Read и Execute, после третьей - все три флага.

Вывод и разбор флагов из строки

Главное видимое отличие [Flags] проявляется при выводе. Без атрибута комбинация 3 выводится числом, а с атрибутом превращается в читаемый список имён через запятую. Обратное преобразование тоже работает: строку со списком имён можно разобрать в значение.

Console.WriteLine(AccessRights.Read | AccessRights.Write); // ReadWrite
Console.WriteLine(FilePermissions.Read | FilePermissions.Execute); // Read, Execute

if (Enum.TryParse<FilePermissions>("Read, Write", out var parsed))
{
    Console.WriteLine(parsed); // Read, Write
}

Если для комбинации есть готовая константа, как ReadWrite, выводится именно её имя. Это стоит учитывать при сохранении значений в логи и конфигурации.

Преимущества флагов и типичные ошибки

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

Ошибки обычно одни и те же. Забывают поставить атрибут, и вывод показывает число вместо имён. Задают значения подряд (1, 2, 3, 4), и бит пересекается: 3 уже равно 1 | 2. Проверяют флаг через == без маски, тогда составное значение не совпадёт с одиночным флагом.

Частые вопросы

Нужно ли обязательно ставить атрибут [Flags]?

Побитовые операции работают и без него, потому что enum остаётся числом. Но без атрибута ToString не покажет комбинацию именами, а другие разработчики не поймут, что значения можно объединять. Поэтому атрибут стоит ставить всегда, когда константы задуманы как флаги.

Почему значения должны быть степенями двойки?

Степень двойки в двоичной записи содержит ровно одну единицу, то есть занимает свой бит. Тогда сложение флагов через ИЛИ однозначно показывает, какие из них включены. Значения вроде 3 или 5 заняли бы сразу несколько битов и пересеклись бы с другими флагами.

Чем HasFlag отличается от проверки через &?

По результату они равны для одиночного флага. HasFlag читается проще, а запись с маской даёт больше контроля, например для проверки нескольких флагов сразу. В актуальных версиях .NET HasFlag не создаёт лишних выделений памяти, поэтому на производительность он обычно не влияет.

Как проверить, что установлен хотя бы один из нескольких флагов?

Достаточно применить маску из этих флагов и сравнить результат с нулём: (rights & (AccessRights.Read | AccessRights.Write)) != 0. Для проверки того, что установлены все флаги сразу, результат сравнивают с самой маской.