C# Cookbook

Chapter 4. Enumerations

Enumerations implicitly inherit from System.Enum, which, in turn, inherits from System.ValueType. Enumerations have a single use: to describe items of a specific group. For example, the colors red, blue, and yellow could be defined by the enumeration ValidShapeColor; likewise square, circle, and triangle could be defined by the enumeration ValidShape. These enumerations would look like the following:

enum ValidShapeColor
{
    Red, Blue, Yellow
}

enum ValidShape
{
    square = 2, circle = 4, triangle = 6
}

Each item in the enumeration receives a numeric value regardless of whether you assign one. Since the compiler automatically adds the numbers starting with zero and increments by one for each item in the enumeration, the ValidShapeColor enumeration previously defined would be exactly the same if it were defined in the following manner:

enum ValidShapeColor
{
    Red = 0, Blue = 1, Yellow = 2
}

Enumerations are good code-documenting tools. For example, it is more intuitive to write the following:

ValidShapeColor currentColor = ValidShapeColor.Red;

than it is to write:

int currentColor = 0;

Either mechanism can work, but the first method is easy to read and understand, especially for a new developer taking over someone else’s code.

4.1. Displaying an Enumeration Value as a String

Problem

You need to display the textual or numeric value of an enumeration member.

Solution

Use the ToString method that each enumeration member inherits from System.Enum.

Using the following ValidShape enumeration type as an example, we can obtain the textual and numeric values so that we may display them:

enum ValidShape
{
    Square = 0, Circle, Cylinder, Octagon
}

Using the ToString method of the ValidShape enumeration type, we can derive the value of a specific ValidShape enumeration value directly:

Console.WriteLine(ValidShape.Circle.ToString( ));
Console.WriteLine(ValidShape.Circle.ToString("G"));
Console.WriteLine(ValidShape.Circle.ToString("D"));
Console.WriteLine(ValidShape.Circle.ToString("F"));
Console.WriteLine(ValidShape.Circle.ToString("X"));

This generates the following output:

Circle
Circle
1
Circle
00000001

If we are working with a variable of type ValidShape, the enumeration values can be derived in the same manner:

ValidShape shapeStyle = ValidShape.Cylinder;

Console.WriteLine(shapeStyle.ToString( ));  
Console.WriteLine(shapeStyle.ToString("G"));  
Console.WriteLine(shapeStyle.ToString("D"));  
Console.WriteLine(shapeStyle.ToString("F"));  
Console.WriteLine(shapeStyle.ToString("X"));

The following is displayed:

Cylinder
Cylinder
2
Cylinder
00000002

Discussion

Deriving the textual or numeric representation of an enumeration value is a simple matter, using the ToString instance method on the Enum type. This method can accept a character indicating the type of formatting to place on the enumeration value. The character can be one of the following: G, g, F, f, D, d, X, or x. See Table 4-1 for a description of these formatting types.

Table 4-1. Formatting types

Formatting type	Description
G or g	(General) Displays the string representation of the enumeration value.
F or f	(Flag) Displays the string representation of the enumeration value. The enumeration is treated as if it were a bit field.
D or d	(Decimal) Displays decimal equivalent of the enumeration.
X or x	(Hexadecimal) Displays hexadecimal equivalent of the enumeration.

When printing out the values of an enumeration with the Flags attribute, the information displayed takes into account that more than one of the enumeration values may have been ORed together. The output will be all of the enumerations printed out as strings separated by commas or as the ORed numeric value, depending on the formatting chosen. For example, consider if the Flags attribute were added to the ValidShape enumeration as follows:

[Flags]
enum ValidShape
{
    Square = 0, Circle = 1, Cylinder = 2, Octagon = 4
}

and if we changed the code for this recipe as follows:

ValidShape shapeStyle = ValidShape.Circle | ValidShape.Cylinder;

Console.WriteLine(shapeStyle.ToString( ));  
Console.WriteLine(shapeStyle.ToString("G"));  
Console.WriteLine(shapeStyle.ToString("D"));  
Console.WriteLine(shapeStyle.ToString("F"));  
Console.WriteLine(shapeStyle.ToString("X"));

we would see the following output:

Circle, Cylinder
Circle, Cylinder
3
Circle, Cylinder
00000003

This technique provides a flexible way of extracting the flags that we are currently using on an enumeration type.

See Also

See the “Enum.ToString” method and “Enumeration Format Strings” topic in the MSDN documentation.