The Visual Basic .NET Programming Language

An enumeration is a user -defined type that gives names to numeric values. For example, the following defines a new enumeration, Colors , that has values that represent the seven basic colors of the spectrum.

Enum Colors Red Orange Yellow Green Blue Indigo Violet End Enum

The set of names in an enumeration can be used to refer to the numeric values. The names of the values are scoped to the enumeration itself, so enumeration values must always be qualified with the name of the type. For example:

Dim a As Colors a = Colors.Red If a = Colors.Blue Then Console.WriteLine("Blue") End If

The values of the enumeration are scoped only to the type itself because you are likely to want to use the same names in different enumerations.

Enum Colors Red Orange Yellow Green Blue Indigo Violet End Enum Enum StopLightColors Red Yellow Green End Enum

In the preceding example, if the values were not scoped to the enumerations, then Red , Yellow , and Green would be ambiguous.

Underlying Types

Because enumerations can only enumerate whole numbers , enumerations can only be based on the fundamental integer types ( Byte , Short , Integer , or Long ). The underlying type of an enumeration determines how many distinct values the enumeration can have. By default, the first value in an enumeration corresponds to the value 0, and each value after that represents one more than the one before it. In the Colors example earlier, the value of Red is 0, the value of Orange is 1, the value of Yellow is 2, and the value of Violet is 6.

The correspondence between an enumeration value and its underlying type can be explicitly set by assigning a value to the name in the enumeration declaration.

Enum Colors Red = 1 Orange = 2 Yellow = 4 Green = 8 Blue = 16 Indigo = 32 Violet = 64 End Enum

In this example, the Colors enumeration is defined such that each color value is a distinct binary value. This would allow combining the values of the Colors enumeration using the And , Or , and Xor bitwise operators.

An enumeration value can be assigned any constant expression, even one involving another enumeration value ”as long as the enumeration value's underlying value doesn't depend on itself.

Enum StopLightColors Red = Yellow ' Invalid: Yellow's value depends on Red's value Green Yellow End Enum

In this example, the enumeration value Red cannot have the same underlying value as the enumeration value Yellow , because Yellow 's underlying value depends on Red 's underlying value. Remember, if an enumeration member is not explicitly assigned a value, it will have the value of the previous enumeration member's underlying value plus one.

By default, an enumeration's underlying type is Integer . If another integral type size is needed, however, it can be specified in an As clause after the enumeration name.

Enum StopLightColors As Byte Red Green Yellow End Enum

Conversions

Because all the names in an enumeration have a corresponding value in the enumeration's underlying type, an enumeration can always be converted to its underlying type, and the conversion is widening. The underlying type of an enumeration can also be converted to the enumeration, but because not all values of the underlying type may be represented in the enumeration, the conversion is narrowing. Enumerations can be converted from one to another. The conversion is narrowing or widening based on the underlying types. (So a Long enumeration conversion to an Integer enumeration would be narrowing.)

An enumeration can also be converted to any type its underlying type can convert to. For example, an enumeration with a Long underlying type can be converted to Integer . The conversion is either widening or narrowing depending on whether the conversion from the underlying type is widening or narrowing. (So a Long enumeration conversion to Integer would be narrowing.)

An enumeration value converted to String will result in the underlying value being converted to String (i.e., "0"). Similarly, converting a String to an enumeration requires the string to be the underlying value (i.e., "0") instead of the value's name (i.e., "Red"). The method System.Enum.ToString , however, will convert the value into the enumerated name (i.e., "Red"). The method System.Enum.Parse can be used to convert from an enumerated value name (i.e., "Red") back to the enumeration. For example:

Sub Main() Dim c As StopLightColors = StopLightColors.Red Dim s As String s = CStr(c) Console.WriteLine(s) ' Prints out "0" ' Set c equal to StopLightColors.Green c = CType("1", StopLightColors) s = c.ToString() Console.WriteLine(s) ' Prints out "Green" ' Set c equal to StopLightColors.Yellow c = Enum.Parse(GetType(StopLightColors), "Yellow") End Sub

It's worth noting that the conversion from the underlying type of an enumeration to the enumeration exists even though the underlying type may be able to represent more values than the enumeration can. For example:

Enum StopLightColors Red Green Yellow End Enum Module Test Sub Main() Dim x As StopLightColors x = CType(42, StopLightColors) End Sub End Module

It is valid to assign values to an enumeration variable that is not defined by the enumeration as long as they fit into the underlying type. This is allowed because, as noted in the previous section, some enumerations are used as flags.

Enum Colors Red = 1 Orange = 2 Yellow = 4 Green = 8 Blue = 16 Indigo = 32 Violet = 64 End Enum Module Test Sub Main() Dim Green As Colors Green = Colors.Red And Colors.Yellow End Sub End Module

In this situation, the colors can be combined to produce values that were not part of the original enumeration but that may be valid nonetheless.