C# Reference ยท Types and Literals
Enums in depth
Reference for C# enums: underlying types, [Flags] bit sets, casts, Enum.Parse and TryParse, IsDefined, ToString formats and common pitfalls.
An enum is a value type that gives names to a set of integral constants. Underneath, every enum has an integral underlying type (int unless you choose another), and every enum value is just that number with a label. This makes enums cheap to store and compare, but it also means the compiler does not stop you from creating values that have no name.
Two patterns cover most uses: a plain enum for a set of mutually exclusive choices, and a [Flags] enum whose members are powers of two so that several can be combined in one value.
enum Level : byte { Low = 1, Medium = 5, High = 10 } [Flags] enum Access { None = 0, Read = 1, Write = 2, Execute = 4 }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
[attributes] [modifiers] enum Name [: underlyingType] { Member [= constantValue], ... }
| Part | Description |
|---|---|
| Underlying type | One of byte, sbyte, short, ushort, int (default), uint, long, ulong. |
| Member values | Without = value, a member is one more than the previous one; the first is 0. Values may refer to earlier members (`ReadWrite = Read |
[Flags] |
Documents a bit set and changes ToString and Parse so they read and write combinations such as Read, Write. It does not change arithmetic. |
Useful members of System.Enum: Enum.Parse<T>, Enum.TryParse<T>, Enum.IsDefined, Enum.GetValues<T>, Enum.GetNames<T>, Enum.GetName, GetUnderlyingType, and the instance methods HasFlag and ToString(format). The format strings are G (name, the default), D (decimal number), X (hex) and F (flags-style name list).
Errors. Enum.Parse throws ArgumentException for text that is not a member name or number, and OverflowException when a number does not fit the underlying type. TryParse returns false instead.
Usage notes
- A cast never validates.
(Level)7compiles and runs. Validate external input withEnum.IsDefined(for plain enums) or by checking against the mask of all flags;TryParsealso accepts numeric strings that are not defined, so it does not validate by itself. - Always define a zero member. The default value of an enum is
0, whether or not a member has that value. Name it (None,Unknown) so that fresh fields and arrays are meaningful. - Flags need powers of two (
1, 2, 4, 8, or1 << 0,1 << 1). UseNone = 0for the empty set, and combined members such asReadWrite = Read | Writefor convenience. - Test flags with
&.(value & flag) == flagis the classic test;HasFlagdoes the same and is optimized by the JIT in current .NET, but it still reads easily for single flags. For a test of "any of these", use(value & mask) != 0. - Switch expressions on enums are not exhaustive for the compiler's purposes because undefined numbers exist; add a discard arm that throws.
- Enums cannot have methods, but extension methods on the enum type work, and
statichelper classes can hold behavior. - Generic constraint.
where T : struct, Enumlets you write generic code over any enum. - Serialization.
System.Text.Jsonwrites enums as numbers by default; useJsonStringEnumConverterfor names. Numbers break when you reorder members, so give members explicit values once they are stored anywhere. - Boxing. Converting an enum to
objectboxes it like any struct.
Related
enum, Structs in depth, Type conversions, Default values- Lessons: Enums, Type conversion