System.Enum Class

public abstract class Enum : ValueType, IComparable, IFormattable

Base Types

Object
  ValueType
    Enum

This type implements IComparable and IFormattable.

Assembly

mscorlib

Library

BCL

Summary

Provides support for all enumeration types. Serves as the base class for all enumeration types.

Description

A Enum is a distinct type with named constant members. Each enumeration type has a corresponding integral type called the underlying type of the enumeration type. This underlying type is required to be a system-supplied integer type that is large enough to represent all values defined in the enumeration; the field that holds the underlying type must be called value__ . A Enum declaration is allowed to explicitly declare any integral type other than Char as an underlying type. This includes Byte, SByte, Int16, Int32, Int64, UInt16, UInt32, and UInt64. A Enum declaration that does not explicitly declare an underlying type has an underlying type of Int32 .

Enum derives from ValueType but is not a value type. Programming languages typically provide syntax to declare sets of a specified enumeration type consisting of named constants and their values.

It is possible to treat instances of a Enum as bit fields containing multiple values. For more information, see FlagsAttribute .

[Note: Enum provides methods to compare instances of enumeration types, convert the value of an instance to its String representation, convert the String representation of a number to an instance of the enumeration type, and create an instance of a specified enumeration and value.]

See Also

System Namespace

Members

Enum Methods

Enum.CompareTo Method
Enum.Equals Method
Enum.Format Method
Enum.GetHashCode Method
Enum.GetName Method
Enum.GetNames Method
Enum.GetUnderlyingType Method
Enum.GetValues Method
Enum.IsDefined Method
Enum.Parse(System.Type, System.String) Method
Enum.Parse(System.Type, System.String, bool) Method
Enum.ToObject(System.Type, System.Object) Method
Enum.ToObject(System.Type, sbyte) Method
Enum.ToObject(System.Type, short) Method
Enum.ToObject(System.Type, ulong) Method
Enum.ToObject(System.Type, long) Method
Enum.ToObject(System.Type, uint) Method
Enum.ToObject(System.Type, ushort) Method
Enum.ToObject(System.Type, byte) Method
Enum.ToObject(System.Type, int) Method
Enum.ToString(System.String) Method
Enum.ToString() Method
Enum.ToString(System.String, System.IFormatProvider) Method
Enum.ToString(System.IFormatProvider) Method


Enum.CompareTo Method

public int CompareTo(object target);

Summary

Returns the sort order of the current instance compared to the specified Object.

Parameters

target
An object to compare the current instance to.

Return Value

The return value is a negative number, zero, or a positive number reflecting the sort order of the current instance as compared to target. For non-zero return values, the exact value returned by this method is unspecified. The following table defines the return value:

Return ValueDescription
A negative integerThe value of the current instance is less than the value of target.
ZeroThe value of the current instance is equal to the value of target.
Any positive integerThe value of the current instance is greater than the value of target, or target is null .

Exceptions

Exception TypeCondition
ArgumentExceptiontarget and the current instance are not of the same enumeration type.

Description

[Note: This method is implemented to support the IComparable interface.]

See Also

System.Enum Class, System Namespace

Enum.Equals Method

public override bool Equals(object obj);

Summary

Determines whether the current instance and the specified Object represent the same type and value.

Parameters

obj
An object to compare the current instance to.

Return Value

true if obj is of the same enumeration type and represents the same value as the current instance; otherwise, false .

Description

[Note: This method overrides System.Object.Equals(System.Object).]

See Also

System.Enum Class, System Namespace

Enum.Format Method

public static string Format(Type enumType, object value, string format);

Summary

Converts the specified element of the specified enumeration type to its String representation using the specified format.

Parameters

enumType
A Type that specifies the type of the enumeration of which value is a member.
value
The enumeration element to be converted.
format
A String that specifies the output format to use.

Return Value

The String representation of the value of the enumeration element.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType, value or format is a null reference.
ArgumentExceptionenumType is not a Enum.

-or-

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

FormatExceptionformat contains an invalid value.

Description

For cross-platform portability, the only valid values for format are:

Format Description
"G" or "g" If value is equal to a defined value of enumType , returns the element name defined for value. If the FlagsAttribute attribute is set on the Enum declaration and value is a built-in integer type and is equal to a summation of enumeration elements, the return value contains the element names in an unspecified order, separated by commas (e.g. "Red, Yellow"). Otherwise, value is returned in decimal format.

"X" or "x" Returns value in hexadecimal format, without a leading 0x. The value is padded with leading zeroes to ensure the returned value is at least eight digits in length.
"F" or "f"Behaves identically to "G", except the FlagsAttribute is not required to be present on the Enum declaration.
"D" or "d" Returns value in decimal format with no leading zeroes.

Example

The following example demonstrates formatting enumeration values.

using System;
public enum Signs {
  Stop = 1,
  Yield = 2,
  Merge = 4
};
[Flags]
public enum Lights {
  Red = 1,
  Yellow = 2,
  Green = 4
};
public class EnumCompTo {
  public static void Main() {
   Console.WriteLine(Signs.Format(typeof(Signs), Signs.Merge, "d"));
   Console.WriteLine(Signs.Format(typeof(Signs), 7, "g"));
   Console.WriteLine(Lights.Format(typeof(Lights), Lights.Yellow, "x"));
   Console.WriteLine(Lights.Format(typeof(Lights), 7, "g"));
  }
}
   
The output is

4

7

00000002

Red, Yellow, Green

See Also

System.Enum Class, System Namespace

Enum.GetHashCode Method

public override int GetHashCode();

Summary

Generates a hash code for the current instance.

Return Value

A Int32 containing a hash code for the current instance.

Description

The algorithm used to generate the hash code is unspecified.

[Note: This method overrides System.Object.GetHashCode.]

See Also

System.Enum Class, System Namespace

Enum.GetName Method

public static string GetName(Type enumType, object value);

Summary

Retrieves the name of the constant of the specified enumeration type that has the specified value.

Parameters

enumType
A Type that specifies the type of the enumeration.
value
A Object that contains the integral value or the name of an enumeration constant.

Return Value

A String containing the name of the enumerated constant in enumType whose value is value, or a null reference if no such constant is found. If multiple constants have the same value, as to which name is returned for that value, is unspecified.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType or value is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum .

-or-

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

Example

The following example demonstrates the System.Enum.GetName(System.Type,System.Object) method.

using System;
public enum Signs {
  Stop = 1,
  Yield = 2,
  Merge = 4
};
public class EnumCompTo {
  public static void Main() {
   Console.Write( "The name of the constant with the value 4 is: " );
   Console.WriteLine( "{0}.", Signs.GetName(typeof(Signs), 4));
   Console.Write( "The name of the constant with the value Stop is: " );
   Console.WriteLine( "{0}.", Signs.GetName(typeof(Signs), Signs.Stop ));
  }
}
The output is

The name of the constant with the value 4 is: Merge.

The name of the constant with the value Stop is: Stop.

See Also

System.Enum Class, System Namespace

Enum.GetNames Method

public static string[] GetNames(Type enumType);

Summary

Returns a zero-based, one-dimensional String array that contains the names of the constants of the specified enumeration type.

Parameters

enumType
A Type that specifies the type of an enumeration.

Return Value

A String vector of the names of the constants in enumType. The elements of the vector are sorted by the values of the enumerated constants. If multiple constants have the same value, the order in which their names appear in the vector, relative to each other, is unspecified.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentException enumType is not a Type that describes a Enum .

Example

The following example demonstrates the System.Enum.GetNames(System.Type) method.

using System;

public enum Colors {
   Red,
   White,
   Blue
};

public class enumGetNames {

   public static void Main() {
      int i = 0;
      String[] strAry = Colors.GetNames( typeof(Colors) );
      foreach (String str in strAry) { 
         Console.Write("The value indexed '{0}' ", i++ );
         Console.WriteLine("is {0}.", str);
      }
   }
}
The output is

The value indexed '0' is Red.

The value indexed '1' is White.

The value indexed '2' is Blue.

See Also

System.Enum Class, System Namespace

Enum.GetUnderlyingType Method

public static Type GetUnderlyingType(Type enumType);

Summary

Returns the underlying type of the specified enumeration type.

Parameters

enumType
The Type of an enumeration.

Return Value

A Type instance that describes the underlying type of enumType.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not an enumeration type.

Example

The following example demonstrates the System.Enum.GetUnderlyingType(System.Type) method.

using System;
public enum Colors {
  Red,
  White,
  Blue
}
public class EnumUnderlyingTypeTest {
  public static void Main() {
     Type t = Colors.GetUnderlyingType( typeof(Colors) );
     Console.WriteLine("The underlying type of Colors is {0}.", t.ToString());
  }
}
The output is

The underlying type of Colors is System.Int32.

See Also

System.Enum Class, System Namespace

Enum.GetValues Method

public static Array GetValues(Type enumType);

Summary

Returns a zero-based, one-dimensional array of the values of the constants of the specified enumeration type.

Parameters

enumType
The Type of an enumeration.

Return Value

A vector of the enumeration type specified by enumType containing the values of the constants in enumType. The elements of the array are sorted by the values of the enumeration constants. If multiple constants have the same value, the value of each is included in the array.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not an enumeration type.

Example

The following example demonstrates the System.Enum.GetValues(System.Type) method.

using System;
public enum Colors {
  Red = 1,
  White = 2,
  Blue = 4
}
public class enumGetValues {
   public static void Main() {
      Array valueAry = Enum.GetValues(typeof(Colors));
      foreach (int i in valueAry) {
        Console.WriteLine("The value of element {0} is {1}",
        Enum.Format(typeof(Colors), i, "g"),i);
      }
   }
}
The output is

The value of element Red is 1.

The value of element White is 2.

The value of element Blue is 4.

See Also

System.Enum Class, System Namespace

Enum.IsDefined Method

public static bool IsDefined(Type enumType, object value);

Summary

Returns a Boolean indicating whether a constant with the specified value exists in the specified enumeration type.

Parameters

enumType
A Type that describes an enumeration.
value
The constant or value being searched for in enumType.

Return Value

true if a constant in the enumeration described by enumType has a value equal to value; otherwise, false .

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType or value is a null reference.
ArgumentExceptionenumType is not an enumeration type.

-or-

The type of value is not an enumType or an underlying type of enumType.

Example

The following example demonstrates the System.Enum.IsDefined(System.Type,System.Object) method.

using System;
public enum Colors {
  Red = 1,
  White = 2,
  Blue = 4
}
public class enumIsDefined {
  public static void Main() {
     Console.Write("It is {0} ", Enum.IsDefined(typeof(Colors), 1));
     Console.WriteLine("that '1' is defined in 'Colors'.");
     Console.Write("It is {0} ", Enum.IsDefined(typeof(Colors), 3)); 
     Console.WriteLine("that '3' is defined in 'Colors'.");
  }
}
The output is

It is True that '1' is defined in 'Colors'.

It is False that '3' is defined in 'Colors'.

See Also

System.Enum Class, System Namespace

Enum.Parse(System.Type, System.String) Method

public static object Parse(Type enumType, string value);

Summary

Converts the specified String representation of one or more enumerated constants of a specified enumeration type to an equivalent enumerated object.

Parameters

enumType
The Type of an enumeration.
value
A String containing one or more names or a single numeric value to convert. If the string contains more than one name, each name is required to be separated by a comma (','). The names are parsed in a case-sensitive manner. The names or number can be surrounded by any amount of white space.

Return Value

A Object of type enumType whose values are represented by value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType or value is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum.

-or-

value is either equal to System.String.Empty or contains only white space.

-or-

value represents one or more names, and at least one name represented by value is not of type enumType.

Description

This version of System.Enum.Parse(System.Type,System.String) is equivalent to System.Enum.Parse(System.Type,System.String) (enumType, value, false ).

Example

The following example demonstrates the System.Enum.Parse(System.Type,System.String) method.

using System;
public enum Colors {
  Red = 1,
  Blue = 2
}
public class enumTest {
  public static void Main() {
    object o = Enum.Parse( typeof (Colors), "Red, Blue");
    Type oType = o.GetType();
    Console.WriteLine("The type of the object returned is {0}",oType.ToString());
    Array values = Enum.GetValues(oType);
    foreach (Colors c in values) { 
      Console.WriteLine(Enum.Format(oType,c,"D"));
    }
  }
}
The output is

The type of the object returned is Colors

1

2

See Also

System.Enum Class, System Namespace

Enum.Parse(System.Type, System.String, bool) Method

public static object Parse(Type enumType, string value, bool ignoreCase);

Summary

Converts the specified String representation of one or more enumerated constants of a specified enumeration type to an equivalent enumerated object. This method behaves in a case-sensitive or insensitive manner according to the specified Boolean.

Parameters

enumType
The Type of an enumeration.
value
A String containing one or more names or a single numeric value to convert. If the string contains more than one name, each name is required to be separated by a comma (','). The names or number can be surrounded by any amount of white space.

ignoreCase
A Boolean value. Specify true to have names in value parsed in a case-insensitive manner. Specify false to have names parsed in a case-sensitive manner.

Return Value

A Object of type enumType whose values are represented by value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType or value is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum.

-or-

value is either equal to System.String.Empty or contains only white space.

-or-

value represents one or more names, and at least one name represented by value is not of type enumType.

Example

For an example that demonstrates parsing strings containing enumeration values, see System.Enum.Parse(System.Type,System.String)(Type, String).

See Also

System.Enum Class, System Namespace

Enum.ToObject(System.Type, System.Object) Method

public static object ToObject(Type enumType, object value);

Summary

Returns an instance of the specified enumeration type set to the specified value.

Parameters

enumType
The Type of the enumeration.
value
The value to set.

Return Value

An enumeration object of type enumType whose value is value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum .

See Also

System.Enum Class, System Namespace

Enum.ToObject(System.Type, sbyte) Method

public static object ToObject(Type enumType, sbyte value);

Summary

Returns an instance of the specified enumeration type set to the specified SByte value.

Parameters

enumType
The Type of an enumeration.
value
The SByte value to set.

Return Value

An enumeration object of type enumType whose value is value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum .

Description

This member is not CLS-compliant. For a CLS-compliant alternative, use System.Enum.ToObject(System.Type,System.Object)(Type, Int16).

Attributes

CLSCompliantAttribute(false)

See Also

System.Enum Class, System Namespace

Enum.ToObject(System.Type, short) Method

public static object ToObject(Type enumType, short value);

Summary

Returns an instance of the specified enumeration type set to the specified Int16 value.

Parameters

enumType
The Type of an enumeration.
value
The Int16 value to set.

Return Value

An enumeration object of type enumType whose value is value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum .

See Also

System.Enum Class, System Namespace

Enum.ToObject(System.Type, ulong) Method

public static object ToObject(Type enumType, ulong value);

Summary

Returns an instance of the specified enumeration type set to the specified UInt64 value.

Parameters

enumType
The Type of an enumeration.
value
The UInt64 value to set.

Return Value

An enumeration object of type enumType whose value is value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum .

Description

This member is not CLS-compliant. For a CLS-compliant alternative, use System.Enum.ToObject(System.Type,System.Object)(Type, Int64 ).

Attributes

CLSCompliantAttribute(false)

See Also

System.Enum Class, System Namespace

Enum.ToObject(System.Type, long) Method

public static object ToObject(Type enumType, long value);

Summary

Returns an instance of the specified enumeration type set to the specified Int64 value.

Parameters

enumType
The Type of an enumeration.
value
The Int64 value to set.

Return Value

An enumeration object of type enumType whose value is value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum .

See Also

System.Enum Class, System Namespace

Enum.ToObject(System.Type, uint) Method

public static object ToObject(Type enumType, uint value);

Summary

Returns an instance of the specified enumeration type set to the specified UInt32 value.

Parameters

enumType
The Type of an enumeration.
value
The UInt32 value to set.

Return Value

An enumeration object of type enumType whose value is value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum .

Description

This member is not CLS-compliant. For a CLS-compliant alternative, use System.Enum.ToObject(System.Type,System.Object)(Type, Int64).

Attributes

CLSCompliantAttribute(false)

See Also

System.Enum Class, System Namespace

Enum.ToObject(System.Type, ushort) Method

public static object ToObject(Type enumType, ushort value);

Summary

Returns an instance of the specified enumeration type set to the specified UInt16 value.

Parameters

enumType
The Type of an enumeration.
value
The UInt16 value to set.

Return Value

An enumeration object of type enumType whose value is value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum .

Description

This member is not CLS-compliant. For a CLS-compliant alternative, use System.Enum.ToObject(System.Type,System.Object)(Type, Int32).

Attributes

CLSCompliantAttribute(false)

See Also

System.Enum Class, System Namespace

Enum.ToObject(System.Type, byte) Method

public static object ToObject(Type enumType, byte value);

Summary

Returns an instance of the specified enumeration type set to the specified Byte value.

Parameters

enumType
The Type of an enumeration.
value
The Byte value to set.

Return Value

An enumeration object of type enumType whose value is value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum .

See Also

System.Enum Class, System Namespace

Enum.ToObject(System.Type, int) Method

public static object ToObject(Type enumType, int value);

Summary

Returns an instance of the specified enumeration type set to the specified Int32 value.

Parameters

enumType
The Type of an enumeration.
value
The Int32 value to set.

Return Value

An enumeration object of type enumType whose value is value.

Exceptions

Exception TypeCondition
ArgumentNullExceptionenumType is a null reference.
ArgumentExceptionenumType is not a Type that describes a Enum .

See Also

System.Enum Class, System Namespace

Enum.ToString(System.String) Method

public string ToString(string format);

Summary

Converts the value of the current instance to its equivalent String representation using the specified format.

Parameters

format
A String that specifies the format to use when converting the current instance to a String. Specify one of the following values in upper or lowercase: "G", "D", "X", or "F" .

Return Value

The String representation of the value of the current instance as specified by format.

Exceptions

Exception TypeCondition
FormatExceptionformat contains an invalid value.

Description

If format is a null reference or an empty string, the return value is formatted using the general format specifier ("G").

[Note: For details on the format specifiers used with an enumeration object, see System.Enum.Format(System.Type,System.Object,System.String) .]

See Also

System.Enum Class, System Namespace

Enum.ToString() Method

public override string ToString();

Summary

Converts the name of the value of the current instance to its equivalent String representation.

Return Value

The String representation of the named constant specified by the current instance.

Description

This version of System.Enum.ToString(System.String) is equivalent to System.Enum.ToString(System.String) ("G", null ).

This method returns the same value as System.Enum.Format(System.Type,System.Object,System.String) with the "g" or "G" format option.

An instance of an enumeration is set to a named constant value. This method returns the name of the constant an instance is set to, not the value itself.

See Also

System.Enum Class, System Namespace

Enum.ToString(System.String, System.IFormatProvider) Method

public string ToString(string format, IFormatProvider provider);

Summary

Converts the numeric value of the current instance to its equivalent String representation using the specified format.

Parameters

format
A String that specifies the format to use when converting the current instance to a String . Specify one of the following values in upper or lowercase: "G", "D", "X", or "F" .
provider
An object that implements the IFormatProvider interface or a null reference. The IFormatProvider is not used in the implementation of this method. [Note: There is no IFormatProvider that corresponds to a Enum object; therefore, provider is not utilized by this method, and any IFormatProvider can be passed as a parameter.]

Return Value

The String representation of the value of the current instance as specified by format.

Exceptions

Exception TypeCondition
FormatExceptionformat does not contain a valid format specifier.

Description

If format is a null reference or an empty string, the return value is formatted using the general format specifier ("G").

[Note: For details on the format specifiers used with an enumeration object, see System.Enum.Format(System.Type,System.Object,System.String) .

This method is implemented to support the IFormattable interface.

]

See Also

System.Enum Class, System Namespace

Enum.ToString(System.IFormatProvider) Method

public string ToString(IFormatProvider provider);

Summary

Converts the name of the value of the current instance to its equivalent String representation.

Parameters

provider
An object that implements the IFormatProvider interface or a null reference. The IFormatProvider is not used in the implementation of this method. [Note: There is no IFormatProvider that corresponds to a Enum object; therefore, provider is not utilized by this method, and any IFormatProvider can be passed as a parameter.]

Return Value

The String representation of the name of the value of the current instance.

Description

This method is equivalent to the version of System.Enum.ToString(System.String) that takes no arguments.

See Also

System.Enum Class, System Namespace