Типы перечислений (справочник по C#) Enumeration types (C# reference)

Тип перечисления (или тип enum) — это тип значения, определенный набором именованных констант применяемого целочисленного типа. An enumeration type (or enum type) is a value type defined by a set of named constants of the underlying integral numeric type. Чтобы определить тип перечисления, используйте ключевое слово enum и укажите имена элементов перечисления: To define an enumeration type, use the enum keyword and specify the names of enum members:

По умолчанию связанные значения констант элементов перечисления имеют тип int . Они начинаются с нуля и увеличиваются на единицу в соответствии с порядком текста определения. By default, the associated constant values of enum members are of type int ; they start with zero and increase by one following the definition text order. Вы можете явно указать любой другой целочисленный тип в качестве базового типа перечисления. You can explicitly specify any other integral numeric type as an underlying type of an enumeration type. Вы можете также явно указать соответствующие значения констант, как показано в следующем примере. You can also explicitly specify the associated constant values, as the following example shows:

Вы не можете определить метод внутри определения типа перечисления. You cannot define a method inside the definition of an enumeration type. Чтобы добавить функциональные возможности к типу перечисления, создайте метод расширения. To add functionality to an enumeration type, create an extension method.

Значением по умолчанию для типа перечисления E является значение, созданное выражением (E)0 , даже если ноль не имеет соответствующего элемента перечисления. The default value of an enumeration type E is the value produced by expression (E)0 , even if zero doesn’t have the corresponding enum member.

Тип перечисления используется для представления выбора из набора взаимоисключающих значений или комбинации вариантов выбора. You use an enumeration type to represent a choice from a set of mutually exclusive values or a combination of choices. Чтобы представить комбинацию вариантов выбора, определите тип перечисления как битовые флаги. To represent a combination of choices, define an enumeration type as bit flags.

Типы перечислений как битовые флаги Enumeration types as bit flags

Если вам необходимо, чтобы тип перечисления представлял комбинацию вариантов выбора, определите элементы перечисления для этих вариантов так, чтобы отдельный выбор был битовым полем. If you want an enumeration type to represent a combination of choices, define enum members for those choices such that an individual choice is a bit field. То есть связанные значения этих элементов перечисления должны быть степенями двух. That is, the associated values of those enum members should be the powers of two. Затем вы можете использовать побитовые логические операторы | или & , чтобы комбинировать варианты выбора или пересекать комбинации вариантов выбора соответственно. Then, you can use the bitwise logical operators | or & to combine choices or intersect combinations of choices, respectively. Чтобы указать, что тип перечисления объявляет битовые поля, примените к нему атрибут Flags. To indicate that an enumeration type declares bit fields, apply the Flags attribute to it. Как показано в следующем примере, вы можете включить некоторые типичные комбинации в определение типа перечисления. As the following example shows, you can also include some typical combinations in the definition of an enumeration type.

Дополнительные сведения и примеры см. на странице справочника по API System.FlagsAttribute и в разделе о неисключительных элементах и атрибутах Flags страницы справочника по API System.Enum. For more information and examples, see the System.FlagsAttribute API reference page and the Non-exclusive members and the Flags attribute section of the System.Enum API reference page.

Тип System.Enum и ограничение перечисления The System.Enum type and enum constraint

Тип System.Enum является абстрактным базовым классом всех типов перечисления. The System.Enum type is the abstract base class of all enumeration types. Он предоставляет различные методы, позволяющие получить информацию о типе перечисления и его значениях. It provides a number of methods to get information about an enumeration type and its values. Дополнительные сведения и примеры см. на странице справочника по API System.Enum. For more information and examples, see the System.Enum API reference page.

Начиная с C# версии 7.3, вы можете использовать тип System.Enum в ограничении базового класса (которое известно как ограничение перечисления), чтобы указать, что параметр типа является типом перечисления. Beginning with C# 7.3, you can use System.Enum in a base class constraint (that is known as the enum constraint) to specify that a type parameter is an enumeration type. Любой тип перечисления также удовлетворяет ограничению struct , которое используется для указания того, что параметр типа является типом значения, не допускающим значения NULL. Any enumeration type also satisfies the struct constraint, which is used to specify that a type parameter is a non-nullable value type.

Преобразования Conversions

Для любого типа перечисления существуют явные преобразования между типом перечисления и его базовым целочисленным типом. For any enumeration type, there exist explicit conversions between the enumeration type and its underlying integral type. Если вы привели значение перечисления к его базовому типу, то результатом будет связанное целочисленное значение элемента перечисления. If you cast an enum value to its underlying type, the result is the associated integral value of an enum member.

Используйте метод Enum.IsDefined, чтобы определить, содержит ли тип перечисления элемент перечисления с определенным связанным значением. Use the Enum.IsDefined method to determine whether an enumeration type contains an enum member with the certain associated value.

Для любого типа перечисления существует упаковка — преобразование и распаковка — преобразование в тип System.Enum и из него соответственно. For any enumeration type, there exist boxing and unboxing conversions to and from the System.Enum type, respectively.

Спецификация языка C# C# language specification

Дополнительные сведения см. в следующих разделах статьи Спецификация языка C#: For more information, see the following sections of the C# language specification:

Перечисления в C#: как правильно использовать enum

В C# есть много крутых инструментов, которые позволяют улучшить любой код. Один из них — enum. Давайте разберёмся, что это и как с ним работать.

Списки перечисления (или enum) сокращают код и улучшают его читаемость. В этой статье мы создадим enum и научимся применять его эффективно.

Что такое enum в C#

Это список однотипных значений: цветов, состояний, способов выравнивания и так далее. Например, в C# существует встроенный список цветов:

То есть нам не нужно вручную вводить код цвета — вместо этого мы просто выбираем значение из заранее составленного списка.

В самом enum тоже не хранится код цвета. Цифра 9 на примере выше — это индекс элемента в списке. Логика изменения цвета в нашем случае примерно такая:

Пишет о программировании, в свободное время создает игры. Мечтает открыть свою студию и выпускать ламповые RPG.

Как создать enum в C#

Создайте отдельный файл и назовите его так, чтобы понять, какой это список. Например, Direction.cs:

После объявления нового enum он используется как тип данных:

Вы можете указать и какие-то собственные значения для элементов. Например, коды ответа веб-сервера:

По умолчанию тип значения — int, но он изменяется на любой другой целочисленный тип:

Как использовать enum в C#

Самый простой пример — конструкции if и switch.

Вот результат работы такой программы:

Также вы можете использовать enum вместе с полиморфизмом.

Таким образом вы получите код, который очень быстро читается. И теперь не нужно думать, какой метод использовать, — благодаря полиморфизму всё выглядит почти как человеческая речь: set item type — Food (указать тип предмета — Еда).

Другая хорошая практика — использовать enum в качестве возвращаемого типа для методов, в которых ошибка может произойти по разным причинам. Например, отправка данных на сервер.

Этот метод возвращает три сообщения в зависимости от ситуации:

1. Попытка отправить пустой запрос.
2. Успешная отправка запроса.
3. Неизвестная ошибка.

Конечно, допустимо куда больше вариантов: от ошибки базы данных до превышения времени ожидания.

Как enum помогает улучшить читаемость

Представим, что у нас есть класс Item со следующими полями:

• id — идентификатор;
• name — название;
• isWeapon — булево значение, которое говорит, является ли предмет оружием.

Все эти значения передаются объекту через конструктор, поэтому инициализация выглядит так:

Без enum со временем вы забудете, за что отвечает третий аргумент, и вам придётся каждый раз проверять реализацию класса, чтобы освежить память. Или вы добавите новые типы предметов, из-за чего таких аргументов ( isArmor, isPotion) станет ещё больше:

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

С первого взгляда понятно, что здесь имеется в виду.

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

Тип перечисления — это отдельный тип значения (типы значений), объявляющий набор именованных констант. An enum type is a distinct value type (Value types) that declares a set of named constants.

Пример The example

объявляет тип перечисления Color с именем с членами Red , Green и Blue . declares an enum type named Color with members Red , Green , and Blue .

Объявления перечислений Enum declarations

Объявление перечисления объявляет новый тип перечисления. An enum declaration declares a new enum type. Объявление перечисления начинается с ключевого слова enum и определяет имя, доступность, базовый тип и элементы перечисления. An enum declaration begins with the keyword enum , and defines the name, accessibility, underlying type, and members of the enum.

Каждый тип перечисления имеет соответствующий целочисленный тип, называемый базовым типом перечисляемого типа. Each enum type has a corresponding integral type called the underlying type of the enum type. Этот базовый тип должен иметь возможность представлять все значения перечислителя, определенные в перечислении. This underlying type must be able to represent all the enumerator values defined in the enumeration. Объявление перечисления может явно объявить базовый тип byte , sbyte . short , ushort int uint long или ulong . An enum declaration may explicitly declare an underlying type of byte , sbyte , short , ushort , int , uint , long or ulong . Обратите внимание, что char не может использоваться в качестве базового типа. Note that char cannot be used as an underlying type. Объявление перечисления, которое не объявляет явно базовый тип, имеет базовый тип int . An enum declaration that does not explicitly declare an underlying type has an underlying type of int .

Пример The example

объявляет перечисление с базовым типом long . declares an enum with an underlying type of long . Разработчик может использовать базовый тип long , как в примере, чтобы разрешить использование значений, которые находятся в диапазоне long , но не находятся в диапазоне int , или для сохранения этого параметра в будущем. A developer might choose to use an underlying type of long , as in the example, to enable the use of values that are in the range of long but not in the range of int , or to preserve this option for the future.

Модификаторы перечислений Enum modifiers

В enum_declaration при необходимости можно включить последовательность модификаторов enum: An enum_declaration may optionally include a sequence of enum modifiers:

Ошибка времени компиляции, когда один и тот же модификатор встречается несколько раз в объявлении перечисления. It is a compile-time error for the same modifier to appear multiple times in an enum declaration.

Модификаторы объявления перечисления имеют то же значение, что и объявления класса (модификаторы класса). The modifiers of an enum declaration have the same meaning as those of a class declaration (Class modifiers). Однако обратите внимание, что abstract sealed модификаторы и не допускаются в объявлении перечисления. Note, however, that the abstract and sealed modifiers are not permitted in an enum declaration. Перечисления не могут быть абстрактными и не допускают наследования. Enums cannot be abstract and do not permit derivation.

Элементы перечислений Enum members

Текст объявления типа перечисления определяет ноль или более членов перечисления, которые являются именованными константами типа Enum. The body of an enum type declaration defines zero or more enum members, which are the named constants of the enum type. Два члена перечисления не могут иметь одно и то же имя. No two enum members can have the same name.

Каждый элемент перечисления имеет связанное значение константы. Each enum member has an associated constant value. Тип этого значения является базовым типом для содержащего перечисления. The type of this value is the underlying type for the containing enum. Постоянное значение для каждого члена перечисления должно быть в диапазоне базового типа для перечисления. The constant value for each enum member must be in the range of the underlying type for the enum. Пример The example

приводит к ошибке во время компиляции, так как значения константы, -1 -2 и -3 не находятся в диапазоне базового целочисленного типа uint . results in a compile-time error because the constant values -1 , -2 , and -3 are not in the range of the underlying integral type uint .

Несколько членов перечисления могут иметь одно и то же связанное значение. Multiple enum members may share the same associated value. Пример The example

показывает перечисление, в котором два члена перечисления— Blue и Max —имеют одно и то же связанное значение. shows an enum in which two enum members — Blue and Max — have the same associated value.

Связанное значение члена перечисления присваивается либо неявно, либо явным образом. The associated value of an enum member is assigned either implicitly or explicitly. Если объявление члена перечисления имеет constant_expression инициализатор, значение этого константного выражения, неявно преобразованное в базовый тип перечисления, является связанным значением члена перечисления. If the declaration of the enum member has a constant_expression initializer, the value of that constant expression, implicitly converted to the underlying type of the enum, is the associated value of the enum member. Если объявление члена перечисления не имеет инициализатора, его связанное значение устанавливается неявно, как показано ниже. If the declaration of the enum member has no initializer, its associated value is set implicitly, as follows:

• Если элемент Enum является первым членом перечисления, объявленным в типе Enum, его связанное значение равно нулю. If the enum member is the first enum member declared in the enum type, its associated value is zero.
• В противном случае связанное значение члена перечисления получается путем увеличения связанного значения текста, предшествующего предыдущему элементу Enum, на единицу. Otherwise, the associated value of the enum member is obtained by increasing the associated value of the textually preceding enum member by one. Это увеличенное значение должно находиться в диапазоне значений, которые могут быть представлены базовым типом, в противном случае возникает ошибка времени компиляции. This increased value must be within the range of values that can be represented by the underlying type, otherwise a compile-time error occurs.

Пример The example

выводит имена элементов перечисления и связанные с ними значения. prints out the enum member names and their associated values. Результат. The output is:

по следующим причинам: for the following reasons:

• члену перечисления Red автоматически присваивается нулевое значение (поскольку оно не имеет инициализатора и является первым членом перечисления); the enum member Red is automatically assigned the value zero (since it has no initializer and is the first enum member);
• члену перечисления Green явно присваивается значение 10 ; the enum member Green is explicitly given the value 10 ;
• и элементу Enum Blue автоматически присваивается значение, которое больше, чем элемент, который ему предшествует. and the enum member Blue is automatically assigned the value one greater than the member that textually precedes it.

Связанное значение члена перечисления не может напрямую или косвенно использовать значение его собственного связанного элемента перечисления. The associated value of an enum member may not, directly or indirectly, use the value of its own associated enum member. Помимо этого ограничения цикличности инициализаторы членов перечисления могут свободно ссылаться на другие инициализаторы членов перечисления, независимо от их текстового расположения. Other than this circularity restriction, enum member initializers may freely refer to other enum member initializers, regardless of their textual position. В инициализаторе членов перечисления значения других элементов Enum всегда обрабатываются как имеющие тип базового типа, поэтому при ссылке на другие элементы перечисления не требуется выполнять приведения. Within an enum member initializer, values of other enum members are always treated as having the type of their underlying type, so that casts are not necessary when referring to other enum members.

Пример The example

приводит к ошибке во время компиляции, так как объявления A и B являются циклическими. results in a compile-time error because the declarations of A and B are circular. A зависит от B явного и B зависит от A неявного. A depends on B explicitly, and B depends on A implicitly.

Членам перечисления присваиваются имена и области в точности аналогично полям в классах. Enum members are named and scoped in a manner exactly analogous to fields within classes. Областью видимости элемента перечисления является тело содержащего его типа Enum. The scope of an enum member is the body of its containing enum type. В пределах этой области члены перечисления могут ссылаться по их простому имени. Within that scope, enum members can be referred to by their simple name. Из любого другого кода имя члена перечисления должно быть дополнено именем типа перечисления. From all other code, the name of an enum member must be qualified with the name of its enum type. Члены перечисления не имеют объявленного уровня доступности — элемент перечисления доступен, если его вмещающий тип enum доступен. Enum members do not have any declared accessibility — an enum member is accessible if its containing enum type is accessible.

Тип System.Enum The System.Enum type

Тип System.Enum является абстрактным базовым классом для всех перечисляемых типов (он отличается от базового типа перечисляемого типа), а члены, наследуемые от System.Enum , доступны в любом типе перечисления. The type System.Enum is the abstract base class of all enum types (this is distinct and different from the underlying type of the enum type), and the members inherited from System.Enum are available in any enum type. Преобразование упаковки (упаковки-преобразования) из любого перечисляемого типа в, а преобразование распаковки (распаковка-преобразования System.Enum ) существует из любого System.Enum типа перечисления. A boxing conversion (Boxing conversions) exists from any enum type to System.Enum , and an unboxing conversion (Unboxing conversions) exists from System.Enum to any enum type.

Обратите внимание, что System.Enum сама по себе не является enum_type. Note that System.Enum is not itself an enum_type. Скорее, это class_type , из которого производятся все enum_type. Rather, it is a class_type from which all enum_type s are derived. Тип System.Enum наследуется от типа System.ValueType (тип System. ValueType), который, в свою очередь, наследует от типа object . The type System.Enum inherits from the type System.ValueType (The System.ValueType type), which, in turn, inherits from type object . Во время выполнения значение типа System.Enum может быть null или ссылкой на упакованное значение любого типа перечисления. At run-time, a value of type System.Enum can be null or a reference to a boxed value of any enum type.

Значения перечислений и операции с ними Enum values and operations

Каждый тип перечисления определяет отдельный тип; явное преобразование перечисления (явные преобразования перечислений) требуется для преобразования между типом перечисления и целочисленным типом или между двумя перечисляемыми типами. Each enum type defines a distinct type; an explicit enumeration conversion (Explicit enumeration conversions) is required to convert between an enum type and an integral type, or between two enum types. Набор значений, которые может принимать тип enum, не ограничивается его элементами перечисления. The set of values that an enum type can take on is not limited by its enum members. В частности, любое значение базового типа перечисления может быть приведено к типу enum, а — различное допустимое значение этого типа перечисления. In particular, any value of the underlying type of an enum can be cast to the enum type, and is a distinct valid value of that enum type.

Члены перечисления имеют тип содержащего перечисляемого типа (за исключением других инициализаторов членов перечисления: см. раздел enum Members). Enum members have the type of their containing enum type (except within other enum member initializers: see Enum members). Члену перечисления, объявленному в типе Enum E со связанным значением v , является (E)v . The value of an enum member declared in enum type E with associated value v is (E)v .