System.Enum Class

Provides the base class for enumerations.

See Also: Enum Members

Syntax

[System.Runtime.InteropServices.ComVisible(true)]
public abstract class Enum : IComparable, IConvertible, IFormattable

Remarks

An enumeration is a set of named constants whose underlying type is any integral type. If no underlying type is explicitly declared, int is used. Enum is the base class for all enumerations in the .NET Framework.

Enum provides methods for comparing instances of this class, converting the value of an instance to its string representation, converting the string representation of a number to an instance of this class, and creating an instance of a specified enumeration and value.

You can also treat an enumeration as a bit field. For more information, see the Non-Exclusive Members and the Flags Attribute section and the FlagsAttribute topic.

Creating an Enumeration Type

Programming languages typically provide syntax to declare an enumeration that consists of a set of named constants and their values. The following example illustrates the syntax used by C# and Visual Basic to define an enumeration. It creates an enumeration named ArrivalStatus that has three members: ArrivalStatus.Early, ArrivalStatus.OnTime, and ArrivalStatus.Late. Note that in both cases, the enumeration does not explicitly inherit from Enum; the inheritance relationship is handled implicitly by the compiler.

code reference: System.Enum.Class#1

Note:

You should never create an enumeration type whose underlying type is non-integral or char. Although you can create such an enumeration type by using reflection, method calls that use the resulting type are unreliable and may also throw additional exceptions.

Instantiating an Enumeration Type

You can instantiate an enumeration type just as you instantiate any other value type: by declaring a variable and assigning one of the enumeration's constants to it. The following example instantiates an ArrivalStatus whose value is ArrivalStatus.OnTime.

code reference: System.Enum.Class#2

You can also instantiate an enumeration value in the following ways:

Enumeration Best Practices

We recommend that you use the following best practices when you define enumeration types:

  • If you have not defined an enumeration member whose value is 0, consider creating a None enumerated constant. By default, the memory used for the enumeration is initialized to zero by the common language runtime. Consequently, if you do not define a constant whose value is zero, the enumeration will contain an illegal value when it is created.

  • If there is an obvious default case that your application has to represent, consider using an enumerated constant whose value is zero to represent it. If there is no default case, consider using an enumerated constant whose value is zero to specify the case that is not represented by any of the other enumerated constants.

  • Do not specify enumerated constants that are reserved for future use.

  • When you define a method or property that takes an enumerated constant as a value, consider validating the value. The reason is that you can cast a numeric value to the enumeration type even if that numeric value is not defined in the enumeration.

Additional best practices for enumeration types whose constants are bit fields are listed in the Non-Exclusive Members and the Flags Attribute section.

Performing Operations with Enumerations

You cannot define new methods when you are creating an enumeration. However, an enumeration type inherits a complete set of static and instance methods from the Enum class. The following sections survey most of these methods, in addition to several other methods that are commonly used when working with enumeration values.

Performing Conversions

You can convert between an enumeration member and its underlying type by using a casting (in C#) or conversion (in Visual Basic) operator. The following example uses casting or conversion operators to perform conversions both from an integer to an enumeration value and from an enumeration value to an integer.

code reference: System.Enum.Class#5

The Enum class also includes a Enum.ToObject(Type, byte) method that converts a value of any integral type to an enumeration value. The following example uses the Enum.ToObject(Type, int) method to convert an int to an ArrivalStatus value. Note that, because the Enum.ToObject(Type, byte) returns a value of type object, the use of a casting or conversion operator may still be necessary to cast the object to the enumeration type.

code reference: System.Enum.Class#6

When converting an integer to an enumeration value, it is possible to assign a value that is not actually a member of the enumeration. To prevent this, you can pass the integer to the Enum.IsDefined(Type, object) method before performing the conversion. The following example uses this method to determine whether the elements in an array of integer values can be converted to ArrivalStatus values.

code reference: System.Enum.Class#7

Although the Enum class provides explicit interface implementations of the IConvertible interface for converting from an enumeration value to an integral type, you should use the methods of the Convert class, such as Convert.ToInt32(object), to perform these conversions. The following example illustrates how you can use the Enum.GetUnderlyingType(Type) method along with the Convert.ChangeType(object, Type) method to convert an enumeration value to its underlying type. Note that this example does not require the underlying type of the enumeration to be known at compile time.

code reference: System.Enum.Class#8

Parsing Enumeration Values

The Enum.Parse(Type, string) and Enum.TryParse``1(string, ``0@) methods allow you to convert the string representation of an enumeration value to that value. The string representation can be either the name or the underlying value of an enumeration constant. Note that the parsing methods will successfully convert string representations of numbers that are not members of a particular enumeration if the strings can be converted to a value of the enumeration's underlying type. To prevent this, the Enum.IsDefined(Type, object) method can be called to ensure that the result of the parsing method is a valid enumeration value. The example illustrates this approach and demonstrates calls to both the Enum.Parse(Type, string) and Enum.TryParse``1(string, ``0@) methods. Note that the non-generic parsing method returns an object that you may have to cast (in C#) or convert (in Visual Basic) to the appropriate enumeration type.

code reference: System.Enum.Class#9

Formatting Enumeration Values

You can convert enumeration values to their string representations by calling the static Enum.Format(Type, object, string) method, as well as the overloads of the instance Enum.ToString method. You can use a format string to control the precise way in which an enumeration value is represented as a string. For more information, see Enumeration Format Strings. The following example uses each of the supported enumeration format strings to convert a member of the ArrivalStatus enumeration to its string representations.

code reference: System.Enum.Class#10

Iterating Enumeration Members

The Enum type does not implement the IEnumerable or IEnumerable`1 interface, which would enable you to iterate members of a collection by using a foreach (in C#) or For Each (in Visual Basic) construct. However, you can enumerate members in either of two ways.

Non-Exclusive Members and the Flags Attribute

One common use of an enumeration is to represent a set of mutually exclusive values. For example, an ArrivalStatus instance can have a value of Early, OnTime, or Late. It makes no sense for the value of an ArrivalStatus instance to reflect more than one enumeration constant.

In other cases, however, the value of an enumeration object can include multiple enumeration members, and each member represents a bit field in the enumeration value. The FlagsAttribute attribute can be used to indicate that the enumeration consists of bit fields. For example, an enumeration named Pets might be used to indicate the kinds of pets in a household. It can be defined as follows.

code reference: System.Enum.Class#13

The Pets enumeration can then be used as shown in the following example.

code reference: System.Enum.Class#14

The following best practices should be used when defining a bitwise enumeration and applying the FlagsAttribute attribute.

Requirements

Namespace: System
Assembly: mscorlib (in mscorlib.dll)
Assembly Versions: 1.0.5000.0, 2.0.0.0, 4.0.0.0