System.Enum Class

Assembly: Mscorlib.dll
Namespace: System
Summary
Provides the base class for enumerations.
C# Syntax:
[Serializable]
public abstract class Enum : IComparable, IFormattable, IConvertible
Thread Safety
This type is safe for multithreaded operations.
Remarks
An Enum is a named constant whose underlying type is any integral type except Char. If no underlying type is explicitly declared, Int32 is used.Enum derives from ValueType, but is not a value type. Programming languages typically provide syntax to declare an enumeration that consists of a set of named constants and their values.

Enum provides methods to compare instances of this class, convert the value of an instance to its string representation, convert the string representation of a number to an instance of this class, and create an instance of a specified enumeration and value.

You can also treat an Enum as a bit field. For more information, see FlagsAttribute.

This class inherits from ValueType, and implements the IComparable, IFormattable, and IConvertible interfaces. Use the Convert class for conversions instead of this class' explicit interface member implementation of IConvertible.

See also:
System Namespace | ValueType | FlagsAttribute | Char | Int32

System.Enum Member List:

Public Methods
CompareTo Compares this instance to a specified object and returns an indication of their relative values.
Equals Overridden:
Returns a value indicating whether this instance is equal to a specified object.
Format Converts the specified value of a specified enumerated type to its equivalent string representation according to the specified format.
GetHashCode Overridden:
Returns the hash code for this instance.
GetName Retrieves the name of the constant in the specified enumeration that has the specified value.
GetNames Retrieves an array of the names of the constants in a specified enumeration.
GetType
(inherited from System.Object)		 See base class member description: System.Object.GetType

Derived from System.Object, the primary base class for all objects.
GetTypeCode Returns the underlying TypeCode for this instance.
GetUnderlyingType Returns the underlying type of the specified enumeration.
GetValues Retrieves an array of the values of the constants in a specified enumeration.
IsDefined Returns an indication whether a constant with a specified value exists in a specified enumeration.
Parse Overloaded:
Parse(Type enumType, string value)

 Converts the string representation of the name or numeric value of one or more enumerated constants to an equivalent enumerated object.
Parse Overloaded:
Parse(Type enumType, string value, bool ignoreCase)

 Converts the string representation of the name or numeric value of one or more enumerated constants to an equivalent enumerated object. A parameter specifies whether the operation is case-sensitive.
ToObject Overloaded:
ToObject(Type enumType, byte value)

 Returns an instance of the specified enumeration type set to the specified 8-bit unsigned integer value.
ToObject Overloaded:
ToObject(Type enumType, short value)

 Returns an instance of the specified enumeration type set to the specified 16-bit signed integer value.
ToObject Overloaded:
ToObject(Type enumType, int value)

 Returns an instance of the specified enumeration type set to the specified 32-bit signed integer value.
ToObject Overloaded:
ToObject(Type enumType, long value)

 Returns an instance of the specified enumeration type set to the specified 64-bit signed integer value.
ToObject Overloaded:
ToObject(Type enumType, object value)

 Returns an instance of the specified enumeration set to the specified value.
ToObject Overloaded:
ToObject(Type enumType, sbyte value)

 Returns an instance of the specified enumeration type set to the specified 8-bit signed integer value.
ToObject Overloaded:
ToObject(Type enumType, ushort value)

 Returns an instance of the specified enumeration type set to the specified 16-bit unsigned integer value.
ToObject Overloaded:
ToObject(Type enumType, uint value)

 Returns an instance of the specified enumeration type set to the specified 32-bit unsigned integer value.
ToObject Overloaded:
ToObject(Type enumType, ulong value)

 Returns an instance of the specified enumeration type set to the specified 64-bit unsigned integer value.
ToString Overloaded:
ToString()

Overridden:
Converts the value of this instance to its equivalent string representation.
ToString Overloaded:
ToString(IFormatProvider provider)

 Converts the value of this instance to its equivalent string representation using the specified format information.
ToString Overloaded:
ToString(string format)

 Converts the value of this instance to its equivalent string representation using the specified format.
ToString Overloaded:
ToString(string format, IFormatProvider provider)

 Converts the value of this instance to its equivalent string representation using the specified format and format information.
Protected Constructors
ctor #1 Default constructor. This constructor is called by derived class constructors to initialize state in this type.
Protected Methods
Finalize
(inherited from System.Object)		 See base class member description: System.Object.Finalize

Derived from System.Object, the primary base class for all objects.
MemberwiseClone
(inherited from System.Object)		 See base class member description: System.Object.MemberwiseClone

Derived from System.Object, the primary base class for all objects.

Hierarchy:

System.Enum Member Details

ctor #1
Summary:
Default constructor. This constructor is called by derived class constructors to initialize state in this type.
C# Syntax:
protected Enum();

Return to top

Method: CompareTo(
   object target
)
Summary
Compares this instance to a specified object and returns an indication of their relative values.
C# Syntax:
public int CompareTo(
   object target
);
Parameters:

target

An object to compare, or null.

Return Value:
A signed number indicating the relative values of this instance and target.

Return Value Description
Less than zero The value of this instance is less than the value of .
Zero The value of this instance is equal to the value of .
Greater than zero The value of this instance is greater than the value of target. -or- target is null.
Exceptions
Exception Type Condition
ArgumentException target and this instance are not the same type.
InvalidOperationException This instance is not type SByte, Int16, Int32, Int64, Byte, UInt16, UInt32, or UInt64.
See also:
Enum.Equals

Return to top

Overridden Method: Equals(
   object obj
)
Summary
Returns a value indicating whether this instance is equal to a specified object.
C# Syntax:
public override bool Equals(
   object obj
);
Parameters:

obj

An object to compare with this instance, or null.

Return Value:
true if obj is an Enum with the same underlying type and value as this instance; otherwise, false.
See also:
Enum.CompareTo

Return to top

Method: Finalize()
Inherited
See base class member description: System.Object.Finalize
C# Syntax:
~Enum();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: Format(
   Type enumType,
   object value,
   string format
)
Summary
Converts the specified value of a specified enumerated type to its equivalent string representation according to the specified format.
C# Syntax:
public static string Format(
   Type enumType,
   object value,
   string format
);
Parameters:

enumType

The enumeration type of the value to convert.

value

The value to convert.

format

The output format to use.

Return Value:
A string representation of value.
Exceptions
Exception Type Condition
ArgumentNullException The enumType, value, or format parameter is null.
ArgumentException The enumType parameter is not an Enum type.

-or-

The value is from an enumeration that differs in type from enumType.

-or-

The type of value is not an underlying type of enumType.
FormatException The format parameter contains an invalid value.
Remarks
The valid format values are:

Format Description
"G" or "g" If value is equal to a named enumerated constant, the name of that constant is returned; otherwise, the decimal equivalent of value is returned. For example, suppose the only enumerated constant is named, Red, and its value is 1. If value is specified as 1, then this format returns "Red". However, if value is specified as 2, this format returns "2". -or- If the FlagsAttribute custom attribute is applied to the enumeration, then value is treated as a bit field that contains one or more flags that consist of one or more bits. If value is equal to a combination of named enumerated constants, a delimiter-separated list of the names of those constants is returned.value is searched for flags, going from the flag with the largest value to the smallest value. For each flag that corresponds to a bit field in value, the name of the constant is concatenated to the delimiter-separated list. Then the value of that flag is excluded from further consideration, and the search continues for the next flag. If value is not equal to a combination of named enumerated constants, the decimal equivalent of value is returned.
"X" or "x" Represents in hexadecimal without a leading "0x".
"D" or "d" Represents in decimal form.
"F" or "f" Treats value as a bit field. If value is equal to a combination of named enumerated constants, a delimiter-separated list of the names of those constants is returned. Parameter value is searched for flags, going from the flag with the largest value to the smallest value. For each flag that corresponds to a bit field in value, the name of the constant is concatenated to the delimiter-separated list. Then the value of that flag is excluded from further consideration, and the search continues for the next flag. If value is not equal to a combination of named enumerated constants, the decimal equivalent of value is returned.
See also:
Enum.ToString

Return to top

Overridden Method: GetHashCode()
Summary
Returns the hash code for this instance.
C# Syntax:
public override int GetHashCode();
Return Value:
A 32-bit signed integer hash code.

Return to top

Method: GetName(
   Type enumType,
   object value
)
Summary
Retrieves the name of the constant in the specified enumeration that has the specified value.
C# Syntax:
public static string GetName(
   Type enumType,
   object value
);
Parameters:

enumType

An enumeration.

value

The value of a particular enumerated constant in terms of its underlying type.

Return Value:
A string containing the name of the enumerated constant in enumType whose value is value, or null if no such constant is found.
Exceptions
Exception Type Condition
ArgumentNullException enumType or value is null.
ArgumentException enumType is not an Enum.

-or-

value is neither of type enumType nor does it have the same underlying type as enumType.

Return to top

Method: GetNames(
   Type enumType
)
Summary
Retrieves an array of the names of the constants in a specified enumeration.
C# Syntax:
public static string[] GetNames(
   Type enumType
);
Parameters:

enumType

An enumeration.

Return Value:
A string array of the names of the constants in enumType. The elements of the array are sorted by the values of the enumerated constants.
Exceptions
Exception Type Condition
ArgumentNullException enumType or value is null.
ArgumentException enumType parameter is not an Enum.

Return to top

Method: GetType()
Inherited
See base class member description: System.Object.GetType
C# Syntax:
public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: GetTypeCode()
Summary
Returns the underlying TypeCode for this instance.
C# Syntax:
public TypeCode GetTypeCode();
Return Value:
The TypeCode for this instance.
See also:
Enum.GetUnderlyingType

Return to top

Method: GetUnderlyingType(
   Type enumType
)
Summary
Returns the underlying type of the specified enumeration.
C# Syntax:
public static Type GetUnderlyingType(
   Type enumType
);
Parameters:

enumType

An enumeration type.

Return Value:
The underlying Type of enumType.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.
See also:
Enum.GetTypeCode

Return to top

Method: GetValues(
   Type enumType
)
Summary
Retrieves an array of the values of the constants in a specified enumeration.
C# Syntax:
public static Array GetValues(
   Type enumType
);
Parameters:

enumType

An enumeration type.

Return Value:
An Array of the values of the constants in enumType. The elements of the array are sorted by the values of the enumeration constants.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.

Return to top

Method: IsDefined(
   Type enumType,
   object value
)
Summary
Returns an indication whether a constant with a specified value exists in a specified enumeration.
C# Syntax:
public static bool IsDefined(
   Type enumType,
   object value
);
Parameters:

enumType

An enumeration type.

value

The value or name of a constant in enumType.

Return Value:
true if a constant in enumType has a value equal to value; otherwise, false.
Exceptions
Exception Type Condition
ArgumentNullException enumType or value is null.
ArgumentException enumType is not an Enum.

-or-

The type of value is not an enumType.

-or-

The type of value is not an underlying type of enumType.
ExecutionEngineException value is not type SByte, Int16, Int32, Int64, Byte, UInt16, UInt32, or UInt64.

Return to top

Method: MemberwiseClone()
Inherited
See base class member description: System.Object.MemberwiseClone
C# Syntax:
protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Overloaded Method: Parse(
   Type enumType,
   string value
)
Summary
Converts the string representation of the name or numeric value of one or more enumerated constants to an equivalent enumerated object.
C# Syntax:
public static object Parse(
   Type enumType,
   string value
);
Parameters:

enumType

The Type of the enumeration.

value

A string containingthe name or value to convert.

Return Value:
An object of type enumType whose value is represented by value.
Exceptions
Exception Type Condition
ArgumentNullException enumType or value is null.
ArgumentException enumType is not an Enum.

-or-

value is either an empty string or only contains white space.

-or-

value is a name, but not one of the named constants defined for the enumeration.
Remarks
The value parameter contains a value, a named constant, or a list of named constants delimited by commas (,). One or more blanks spaces can precede or follow each value, name, or comma in value. If value is a list, the return value is the value of the specified names combined with a bitwise OR operation.

This operation is case-sensitive.

Return to top

Overloaded Method: Parse(
   Type enumType,
   string value,
   bool ignoreCase
)
Summary
Converts the string representation of the name or numeric value of one or more enumerated constants to an equivalent enumerated object. A parameter specifies whether the operation is case-sensitive.
C# Syntax:
public static object Parse(
   Type enumType,
   string value,
   bool ignoreCase
);
Parameters:

enumType

The Type of the enumeration.

value

A string containing the name or value to convert.

ignoreCase

If true, ignore case; otherwise, regard case.

Return Value:
An object of type enumType whose value is represented by value.
Exceptions
Exception Type Condition
ArgumentNullException enumType or value is null.
ArgumentException enumType is not an Enum.

-or-

value is either an empty string ("") or only contains white space.

-or-

value is a name, but not one of the named constants defined for the enumeration.
Remarks
The value parameter contains a value, a named constant, or a list of named constants delimited by commas (,). One or more blanks spaces can precede or follow each value, name, or comma in value. If value is a list, the return value is the value of the specified names combined with a bitwise OR operation.

The ignoreCase parameter specifies whether this operation is case-sensitive.

Return to top

Overloaded Method: ToObject(
   Type enumType,
   byte value
)
Summary
Returns an instance of the specified enumeration type set to the specified 8-bit unsigned integer value.
C# Syntax:
public static object ToObject(
   Type enumType,
   byte value
);
Parameters:

enumType

The enumeration for which to create a value.

value

The value to set.

Return Value:
An instance of the enumeration set to value.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.

Return to top

Overloaded Method: ToObject(
   Type enumType,
   short value
)
Summary
Returns an instance of the specified enumeration type set to the specified 16-bit signed integer value.
C# Syntax:
public static object ToObject(
   Type enumType,
   short value
);
Parameters:

enumType

The enumeration for which to create a value.

value

The value to set.

Return Value:
An instance of the enumeration set to value.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.

Return to top

Overloaded Method: ToObject(
   Type enumType,
   int value
)
Summary
Returns an instance of the specified enumeration type set to the specified 32-bit signed integer value.
C# Syntax:
public static object ToObject(
   Type enumType,
   int value
);
Parameters:

enumType

The enumeration for which to create a value.

value

The value to set.

Return Value:
An instance of the enumeration set to value.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.

Return to top

Overloaded Method: ToObject(
   Type enumType,
   long value
)
Summary
Returns an instance of the specified enumeration type set to the specified 64-bit signed integer value.
C# Syntax:
public static object ToObject(
   Type enumType,
   long value
);
Parameters:

enumType

The enumeration for which to create a value.

value

The value to set.

Return Value:
An instance of the enumeration set to value.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.

Return to top

Overloaded Method: ToObject(
   Type enumType,
   object value
)
Summary
Returns an instance of the specified enumeration set to the specified value.
C# Syntax:
public static object ToObject(
   Type enumType,
   object value
);
Parameters:

enumType

An enumeration.

value

The value.

Return Value:
An enumeration object whose value is value.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.

-or-

value is not type SByte, Int16, Int32, Int64, Byte, UInt16, UInt32, or UInt64.
Remarks
The value parameter is specified in terms of the underlying type of the enumeration.

Return to top

Overloaded Method: ToObject(
   Type enumType,
   sbyte value
)
Summary
Returns an instance of the specified enumeration type set to the specified 8-bit signed integer value.
This member is not CLS Compliant

C# Syntax:
[CLSCompliant(false)]
public static object ToObject(
   Type enumType,
   sbyte value
);
Parameters:

enumType

The enumeration for which to create a value.

value

The value to set.

Return Value:
An instance of the enumeration set to value.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.

Return to top

Overloaded Method: ToObject(
   Type enumType,
   ushort value
)
Summary
Returns an instance of the specified enumeration type set to the specified 16-bit unsigned integer value.
This member is not CLS Compliant

C# Syntax:
[CLSCompliant(false)]
public static object ToObject(
   Type enumType,
   ushort value
);
Parameters:

enumType

The enumeration for which to create a value.

value

The value to set.

Return Value:
An instance of the enumeration set to value.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.

Return to top

Overloaded Method: ToObject(
   Type enumType,
   uint value
)
Summary
Returns an instance of the specified enumeration type set to the specified 32-bit unsigned integer value.
This member is not CLS Compliant

C# Syntax:
[CLSCompliant(false)]
public static object ToObject(
   Type enumType,
   uint value
);
Parameters:

enumType

The enumeration for which to create a value.

value

The value to set.

Return Value:
An instance of the enumeration set to value.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.

Return to top

Overloaded Method: ToObject(
   Type enumType,
   ulong value
)
Summary
Returns an instance of the specified enumeration type set to the specified 64-bit unsigned integer value.
This member is not CLS Compliant

C# Syntax:
[CLSCompliant(false)]
public static object ToObject(
   Type enumType,
   ulong value
);
Parameters:

enumType

The enumeration for which to create a value.

value

The value to set.

Return Value:
An instance of the enumeration set to value.
Exceptions
Exception Type Condition
ArgumentNullException enumType is null.
ArgumentException enumType is not an Enum.

Return to top

Overloaded Method: ToString()
Summary
Converts the value of this instance to its equivalent string representation.
C# Syntax:
public override string ToString();
Return Value:
The string representation of the value of this instance.
Remarks
This method works as if the general format character, "G", were specified. That is, if the FlagsAttribute is not applied to this enumerated type and there is a named constant equal to the value of this instance, then the return value is a string containing the name of the constant. If the FlagsAttribute is applied and there is a combination of one or more named constants equal to the value of this instance, then the return value is a string containing a delimiter-separated list of the names of the constants. Otherwise, the return value is the string representation of the numeric value of this instance.

For more information about format characters, see the Remarks section of the Enum.Format method. For more information about formatting in general, see the conceptual topic at MSDN: formattingoverview.

Example
The following code example demonstrates converting an enumerated value to a string.
using System;

public class EnumSample {
    enum Colors {Red = 1, Blue = 2};
    
    public static void Main() {
        Enum myColors = Colors.Red;
        Console.WriteLine("The value of this instance is '{0}'",
           myColors.ToString());
    }
}
/*
Output.
The value of this instance is 'Red'.
*/
See also:
Enum.Format | Enum.Parse

Return to top

Overloaded Method: ToString(
   IFormatProvider provider
)
Summary
Converts the value of this instance to its equivalent string representation using the specified format information.
C# Syntax:
public string ToString(
   IFormatProvider provider
);
Parameters:

provider

(Reserved) An IFormatProvider that supplies format information about this instance.

Return Value:
The string representation of the name of the value of this instance as specified by provider.
Remarks
The provider parameter is reserved; it does not participate in this operation and can be specified as null. Therefore, this method is equivalent to the Enum.ToString method that takes no parameters.
See also:
Enum.Format | Enum.Parse

Return to top

Overloaded Method: ToString(
   string format
)
Summary
Converts the value of this instance to its equivalent string representation using the specified format.
C# Syntax:
public string ToString(
   string format
);
Parameters:

format

A format string.

Return Value:
The string representation of the value of this instance as specified by format.
Exceptions
Exception Type Condition
FormatException format contains an invalid specification.
Remarks
The format parameter can contain format characters "G" or "g", "D" or "d", "X" or "x", and "F" or "f". If format is null or an empty string (""), the general format specifier ("G") is used. For more information about these format characters, see the Remarks section of the Enum.Format method. For more information about formatting in general, see the conceptual topic at MSDN: formattingoverview.
See also:
Enum.Format | Enum.Parse

Return to top

Overloaded Method: ToString(
   string format,
   IFormatProvider provider
)
Summary
Converts the value of this instance to its equivalent string representation using the specified format and format information.
C# Syntax:
public string ToString(
   string format,
   IFormatProvider provider
);
Parameters:

format

A format specification.

provider

(Reserved) An IFormatProvider that supplies format information about this instance.

Return Value:
The string representation of the value of this instance as specified by format and provider.
Exceptions
Exception Type Condition
FormatException format does not contain a valid format specification.
Remarks
The format parameter can contain format characters "G" or "g", "D" or "d", "X" or "x", and "F" or "f". If format is null or an empty string (""), the general format specifier ("G") is used. For more information about these format characters, see the Remarks section of the Enum.Format method. For more information about formatting in general, see the conceptual topic at MSDN: formattingoverview.

The provider parameter is reserved; it does not participate in this operation and can be specified as null.

See also:
Enum.Format | Enum.Parse

Return to top

Top of page

Copyright (c) 2002 Microsoft Corporation. All rights reserved.