Enumerations

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.

Advanced

An enumeration whose values are distinct binary values is known as an enumeration of flags . Flag enumerations should have the attribute System.FlagsAttribute specified on them. This doesn't affect the language, but .NET Framework APIs such as System.Enum.IsDefined make use of it.

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.

Advanced

The shared method System.Enum.IsDefined can be used to determine at runtime whether a value is part of an enumeration or not. The IsDefined method takes the System.Flags attribute into consideration.