.NET 1.1+

Bit Field Enumerations

by Richard Carr, published at http://www.blackwasp.co.uk/FlagsAttribute.aspx

When you need to store multiple Boolean statuses for a single item, you may elect to place each on/off attribute into a bit field. If you use an enumeration marked with the FlagsAttribute class, the .NET framework will assist with some of the operations.

What is a Bit Field?

A bit field is a common programming construct. It is used to store a number of associated Boolean values within an integer value, using each bit in the integer to determine the value of a single status flag. The flags can be read and modified individually using bitwise logical operators.

As an example, a simple bit field could be used to determine the status of a device such as a printer. In the following table, four possible errors can occur. Each of these problems is completely independent so can be described using a single bit. The index of each bit and the associated integer value are shown in the table.

Using the above flags, the printer is able to identify sixteen different statuses. For example:

• 0. There are no problems.
• 2. The printer is out of paper.
• 12. A combination of statuses 4 and 8 indicating that the toner is exhausted and there is a paper jam.

Bit Field Enumerations

A standard enumeration provides a list of named integer values. These values can be accessed using either the name or the associated value. Using the name rather than the value from within your program makes the code much easier to read and maintain.

A bit field enumeration extends the standard variety by automatically combining the values of the available bits. In the printer status example, only the four error scenarios need to be defined; the compiler automatically understands that these error statuses are designed to be combined.

Syntax

The syntax for declaring a bit field enumeration is similar to that of a standard enumeration. The name of the enumerated type is prefixed with the enum keyword and followed by a code block containing the names of the flags. To indicate that each item is a flag, the definition is modified using the FlagsAttribute class. Additionally, each constant in the list is assigned a value that is a power of two. If a default value is required to indicate that no flags are set, this is declared with a value of zero.

The basic syntax is therefore:

[FlagsAttribute]
enum name
{
    default-value = 0,
    flag-1 = 1,
    flag-2 = 2,
    flag-3 = 4,
    .
    .
    flag-n = 2n-1
}

NB: Without the use of "FlagsAttribute", the constants declared are seen as mutually exclusive list items.

Printer Status Enumeration

To demonstrate the use of bit fields, we can create an enumeration to represent the printer statuses in the table above. The enumeration will contain each flag as well as a default status of "OK" when no flags are set. To create the enumeration, use the following code.

[FlagsAttribute]
enum PrinterStatus
{
    OK = 0,
    OffLine = 1,
    PaperTrayEmpty = 2,
    TonerExhausted = 4,
    PaperJam = 8
}

Outputting Values

When querying non-zero values from a bit field enumeration, the name of every set flag can be automatically combined into a string. We can see this by simply outputting each of the sixteen possible printer statuses to the console:

for (int status = 0; status <= 15; status++)
{
    Console.WriteLine((PrinterStatus)status);
}

/* OUTPUT

OK
OffLine
PaperTrayEmpty
OffLine, PaperTrayEmpty
TonerExhausted
OffLine, TonerExhausted
PaperTrayEmpty, TonerExhausted
OffLine, PaperTrayEmpty, TonerExhausted
PaperJam
OffLine, PaperJam
PaperTrayEmpty, PaperJam
OffLine, PaperTrayEmpty, PaperJam
TonerExhausted, PaperJam
OffLine, TonerExhausted, PaperJam
PaperTrayEmpty, TonerExhausted, PaperJam
OffLine, PaperTrayEmpty, TonerExhausted, PaperJam

*/