Recipe 4.3 Testing for a Valid Enumeration Value

Problem

When a numeric value is passed to a method that accepts an enumeration type, it is possible that the numeric value does not exist in the parameter that accepts the enumeration value. You want to perform a test before using this numeric value to determine whether it is indeed listed in this enumeration type.

Solution

Use the static Enum.IsDefined method on the Enum class.

Using the following Language enumeration:

enum Language
{
    Other = 0, CSharp = 1, VBNET = 2, VB6 = 3
}

If we have a method that accepts the Language enumeration such as the following method:

public void HandleEnum(Language language)
{
    // Use language here...
}

Discussion

The static Enum.IsDefined method determines whether an enumeration value actually exists within an enumeration of a particular type. Enum.IsDefined is a check used to determine whether the values exist in the enumeration before they are used in your code. This method returns a bool value, where a true indicates that the enumeration value is defined in this enumeration and false indicates that it is not.

The Enum.IsDefined method should be used to determine whether a valid enumeration value has been passed to any method that accepts an enumeration value as a parameter. In particular, this Enum.IsDefined should always be used whenever the method is visible to external objects. Any external object can invoke methods with public visibility; therefore, any enumerated value passed in to this method should be screened before it is actually used. Methods with internal, protected, and internal protected visibility have a much smaller scope than public methods but could still suffer from the same problems as the public methods. Methods with private visibility may not need this extra level of protection. Use your own judgment on whether to use Enum.IsDefined to evaluate enumeration values passed in to private methods. Note that calling this method adds a little overhead to your method. This slight performance hit can be magnified if this method is called many times throughout your application.

The HandleEnum method can be called in several different ways. Two of these ways are shown here:

HandleEnum(Language.CSharp)
HandleEnum((Language)1)

Any of these method calls are valid. In addition, the following method calls are also valid:

HandleEnum((Language)100)

someVar = 100;

These method calls will also compile without errors, but odd behavior will result if the code in HandleEnum tries to use the value passed in to it (in this case, the value 100). In many cases an exception will not even be thrown and the CLR will attempt to handle the value 100 as part of the Language enumeration.

To prevent this from happening, use the static Enum.IsDefined method to determine if these are valid Language enumeration values. The following code shows the modified body of the HandleEnum method:

public void HandleEnum(Language language)
{
    if (Enum.IsDefined(typeof(Language), language))
    {
        // Use language here...
    }
    else
    {
        // Deal with the invalid language value here...
    }
}

See Also

To test for a valid enumeration within an enumeration marked with the [Flags] attribute, see Recipe 4.4; see the "Enum.IsDefined" method in the MSDN documentation.