C# Enum - SyntBlaze

An enumeration (enum) is a distinct value type defined by a set of named integral constants. At runtime, an enum is resolved to its underlying numeric type, meaning it carries the same memory footprint and performance characteristics as a standard primitive integer. All enums implicitly inherit from the abstract class System.Enum, which in turn inherits from System.ValueType.

Syntax and Initialization

By default, the underlying type of an enum is int. The first enumerator has the value 0, and the value of each successive enumerator is incremented by 1.

enum ConnectionState
{
    Disconnected, // 0
    Connecting,   // 1
    Connected     // 2
}

You can override the default indexing by explicitly assigning values. Unassigned enumerators will automatically increment from the last explicitly assigned value.

enum StatusCode
{
    Success = 0,
    Redirect = 300,
    NotFound = 404,
    InternalError     // Automatically assigned 405
}

Underlying Types

An enum can be declared with any integral numeric type except char. Supported types are byte, sbyte, short, ushort, int, uint, long, and ulong. The C# specification requires enum underlying types to have a deterministic size for memory layout and interop, which is why architecture-dependent types like nint and nuint are not permitted. Specifying a smaller underlying type reduces the memory footprint of the struct or class containing the enum.

enum ProcessLevel : byte
{
    Low = 0,
    Normal = 1,
    High = 2,
    Critical = 255 // Maximum value for a byte
}

Type Conversion

Because enums are strongly typed, implicit conversions between an enum and its underlying integral type are generally not allowed, requiring explicit casting. The sole exception is the decimal integer literal 0, which the C# specification permits to be implicitly converted to any enum type.

// Implicit conversion of the decimal literal 0 is allowed
StatusCode defaultCode = 0; // Valid without a cast

// Enum to Integer
int numericValue = (int)StatusCode.NotFound; // 404

// Integer to Enum (requires explicit cast for non-zero values)
StatusCode code = (StatusCode)300; // StatusCode.Redirect

// Note: Casting an undefined integer does not throw an exception
StatusCode undefinedCode = (StatusCode)999; 

Bitwise Enumerations (`[Flags]`)

The [Flags] attribute indicates that an enumeration can be treated as a bit field. This allows a single enum variable to store multiple values simultaneously using bitwise operations. When defining a flags enum, values must be powers of two (using bit shift operators is standard practice).

[Flags]
enum FilePermissions : short
{
    None    = 0,
    Read    = 1 << 0, // 1
    Write   = 1 << 1, // 2
    Execute = 1 << 2, // 4
    All     = Read | Write | Execute // 7
}

Bitwise operators (|, &, ~, ^) and the HasFlag method are used to manipulate and evaluate flag combinations.

FilePermissions access = FilePermissions.Read | FilePermissions.Write; // 3

// Check if a flag is set using HasFlag
bool canWrite = access.HasFlag(FilePermissions.Write); // True

// Check if a flag is set using bitwise AND (more performant in older .NET versions)
bool canExecute = (access & FilePermissions.Execute) == FilePermissions.Execute; // False

// Toggle a flag using bitwise XOR
access ^= FilePermissions.Write; // Removes Write flag

Core `System.Enum` Methods

The System.Enum base class provides static methods for reflection, parsing, and manipulation of enum types. Parsing Strings to Enums:

// Throws ArgumentException if parsing fails
ConnectionState state1 = (ConnectionState)Enum.Parse(typeof(ConnectionState), "Connected");

// Safe parsing (returns boolean)
if (Enum.TryParse("Connecting", true, out ConnectionState state2)) // true ignores case
{
    // state2 is ConnectionState.Connecting
}

Retrieving Metadata:

using System.Linq;

// Get all numeric values in the enum. 
// Enum.GetValues returns an array of the enum type (StatusCode[]). 
// Because unboxing in C# requires the exact type, elements must be cast to the enum type 
// first before projecting to the underlying integer.
int[] values = Enum.GetValues(typeof(StatusCode))
                   .Cast<StatusCode>()
                   .Select(e => (int)e)
                   .ToArray();

// Alternatively, cast directly to the enum array type:
StatusCode[] enumValues = (StatusCode[])Enum.GetValues(typeof(StatusCode));

// In .NET 5 and later, a generic overload simplifies this:
// StatusCode[] modernEnumValues = Enum.GetValues<StatusCode>();

// Get all string names in the enum
string[] names = Enum.GetNames(typeof(StatusCode));

// Check if a specific integer exists in the enum definition
bool isDefined = Enum.IsDefined(typeof(StatusCode), 404); // True