> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# C# Flags Attribute
The `[Flags]` attribute in C# is a metadata marker applied to an `enum` declaration to indicate that its values represent a bit field. It instructs the .NET runtime to treat the enumeration as a collection of composable bitwise flags rather than mutually exclusive scalar values.
Applying this attribute fundamentally alters how the `System.Enum.ToString()` method formats the enumeration. Without `[Flags]`, calling `ToString()` on a bitwise-combined enum value that does not have an exact named constant match returns its raw numeric integer. With `[Flags]`, the runtime evaluates the active bits and returns a comma-separated string of the corresponding enum names.
*Note: The `[Flags]` attribute only affects string formatting. Methods like `Enum.Parse` and `Enum.TryParse` natively support parsing comma-separated strings into bitwise-combined integers regardless of whether the attribute is present.*
## Value Assignment Mechanics
For a bit field enumeration to function correctly, the underlying numeric values must be defined as powers of two (1, 2, 4, 8, 16, etc.). This ensures that each value occupies exactly one distinct bit in the underlying binary representation.
The bitwise left-shift operator (`<<`) is the standard convention for defining these values, as it visually maps to the bit position.
```csharp theme={"dark"}
[Flags]
public enum SystemPermissions : byte
{
None = 0, // 00000000
Read = 1 << 0, // 00000001 (1)
Write = 1 << 1, // 00000010 (2)
Execute = 1 << 2, // 00000100 (4)
Modify = 1 << 3 // 00001000 (8)
}
```
## Runtime Behavior Changes
**String Formatting (`ToString`)**
When multiple flags are combined, `ToString()` behavior diverges based on the presence of the `[Flags]` attribute. To demonstrate this, we must compare two distinct enumerations: one with the attribute and one without.
```csharp theme={"dark"}
[Flags]
public enum FlagsPerms { None = 0, Read = 1, Write = 2 }
public enum BasicPerms { None = 0, Read = 1, Write = 2 }
// With [Flags] attribute:
FlagsPerms activeFlags = FlagsPerms.Read | FlagsPerms.Write;
Console.WriteLine(activeFlags.ToString());
// Output: "Read, Write"
// Without [Flags] attribute:
BasicPerms activeBasic = BasicPerms.Read | BasicPerms.Write;
Console.WriteLine(activeBasic.ToString());
// Output: "3"
```
*Crucial distinction: If the enumeration explicitly defines a composite value (e.g., `ReadWrite = Read | Write`, which equals `3`), `ToString()` will always output the exact named constant `"ReadWrite"` instead of `"Read, Write"` or `"3"`, regardless of the `[Flags]` attribute.*
## Bitwise Manipulation Syntax
Because `[Flags]` enums represent bit fields, they are manipulated using standard bitwise operators rather than arithmetic operators.
```csharp theme={"dark"}
SystemPermissions perms = SystemPermissions.None;
// Set a flag (Bitwise OR)
perms |= SystemPermissions.Read;
// Check for a flag (Bitwise AND or Enum.HasFlag)
bool canRead = (perms & SystemPermissions.Read) == SystemPermissions.Read;
bool canReadModern = perms.HasFlag(SystemPermissions.Read);
// Remove a flag (Bitwise AND with Bitwise NOT)
perms &= ~SystemPermissions.Read;
// Toggle a flag (Bitwise XOR)
perms ^= SystemPermissions.Write;
```
**Critical Caveat: Checking for `None` (0)**
Because the `None` value is mathematically `0`, bitwise evaluation against it behaves uniquely. The expression `value & 0 == 0` is a mathematical tautology. Consequently, calling `perms.HasFlag(SystemPermissions.None)` or evaluating `(perms & SystemPermissions.None) == SystemPermissions.None` will **always return `true`**, regardless of the current state of `perms`.
To correctly check if an enumeration is completely empty (set to `None`), you must use direct equality:
```csharp theme={"dark"}
// INCORRECT: Always evaluates to true
bool isEmpty = perms.HasFlag(SystemPermissions.None);
// CORRECT: Checks if the value is exactly 0
bool isEmptyCorrect = perms == SystemPermissions.None;
```
## Structural Rules
1. **The `None` Value:** Always define a value of `0` named `None` (or similar). Bitwise operations rely on `0` to represent an empty state (all bits cleared).
2. **Underlying Type Capacity:** By default, enums are backed by `int` (32-bit), allowing up to 32 distinct flags. If more flags are required, the underlying type must be explicitly declared as `long` or `ulong` (64-bit).
3. **Signed Types and the Sign Bit:** Avoid using signed underlying types (`sbyte`, `short`, `int`, `long`) if you intend to utilize the highest bit (the sign bit). Setting the sign bit results in a negative numeric value, which complicates bitwise operations and comparisons. Prefer unsigned types (`byte`, `ushort`, `uint`, `ulong`) when all bits of the underlying type are needed for flags.
Tired of Poor C# Skills? Fix That With Deep Grasping!
Learn More
