[Draft Issue]: Add defined pattern for enums

[YairHalberstadt]

This is a Draft Issue. Please comment, and depending on feedback I will hopefully move to an issue soon.

Enum defined pattern

• Proposed
• Prototype: Not Started
• Implementation: Not Started
• Specification: Not Started

Summary

See #4577 for original idea. We add a new pattern defined that is only valid for enums. It matches if and only if the enum is exactly the same as any of the members defined on the enum.

E.g. Given the enum enum Directions { North, East, South, West }, then directions is defined is equivalent to directions is Directions.North or Directions.East or Directions.South or Directions.West.

Motivation

#2671 is a highly upvoted issue discussing how the current switch expression exhaustibility check for enums leaves a lot to be desired. Even if you handle all cases for valid enum members, you still get a warning because somebody could cast an arbitrary int to an enum. This forces you to add a catch all handler, which means you now don't get a warning if a new enum member is added which you don't explicitly handle.

With the defined pattern you could do:

direction switch {
    Directions.North => GoNorth(),
    Directions.East=> GoEast(),
    Directions.South=> GoSouth(),
    Directions.West=> GoWest(),
    not defined => throw new InvalidEnumArgumentException(...)
};

This will warn only if you haven't handled all members defined on Directions. For example if you left out Directions.East by mistake you would get a switch exhaustibility warning.

It's also useful for easy validation. You could now easily validate enums are in the correct range at the entrance to public API's without having to do a large switch / or pattern:

M(myEnum MyEnum)
{
   if (myEnum is not defined)
       throw new InvalidEnumArgumentException(...);
}

Detailed design

pattern
    : defined_pattern
    ...
    ;

defined_pattern
    : 'defined'
    ;

defined could either be a contextual keyword only if there's no type or constant named defined in scope, or we could take the breaking change and make it a contextual keyword in a pattern unconditionally. Given that both types and constants are usually Uppercase in csharp, the breaking change doesn't seem particularly worrisome.

The defined pattern is only valid on an enum target. It is not valid on object or a type parameter with a System.Enum constraint, or a type implicitly convertible to an enum.

Given that the target enum type has n members M1 to Mn, the defined pattern is equivalent to the pattern M1 or M2 or ... or Mn. Only members known at compile time are relevant here.

The compiler doesn't currently lower a series of or patterns into a jump table where possible, but this is a fairly straightforward optimization to make (it already does this for an or pattern in a switch expression), and should be done anyway. In the worst case though this will have O(n) performance.

Using the 'defined' pattern on a Flags enum should result in a warning.

Drawbacks

Addition of a new contextual keyword, and added complexity.
Potentially O(n) pattern added, although in practice the compiler should usually be able to generate very efficient code for this, especially when the enum members are left with their default values.

Alternatives

Use an analyzer to warn when a switch doesn't handle all cases of an enum explicitly

Unresolved questions

Best keyword to use. defined is only a placeholder.

Whether to take the breaking change, or have the meaning of a defined pattern depend on whether there are types/constants named defined in scope.

Design meetings

[alrz]

For proper exhaustive enums see #3179

Use an analyzer to warn when a switch doesn't handle all cases of an enum explicitly

What is the downside of this solution for existing enums compared to this proposal?

[YairHalberstadt]

I think the downside is there's no way to differentiate between a case where you intentionally didn't handle all enums and want some to be handled by the catch all, and where you actually made a mistake.

Attributes wouldn't work well as you can't apply attributes to expressions, and comment based approaches are not very pleasant.

[HaloFour]

You can get this same behavior by suppressing warning CS8524. The compiler will emit that warning if the switch exhaustively check the values of the enum but don't cover the default case, whereas the compiler will emit CS8509 if you don't exhaustively check the values of the enum.

[HaloFour]

Although that wouldn't help if you wanted to have a default case but still wanted to ensure that you were exhaustively checking the enum.

[333fred]

While that is possible, I don't consider it super likely. I tend to think this (HaloFour's answer) is mostly the correct solution.

[jnm2]

I still want this just for the is defined argument checking, with no switch.

[jnm2]

What if the enum type that gets loaded at runtime has extra members that weren't there at compile time? Is the difference in behavior between this and Enum.IsDefined desirable? If so, I don't think defined is the right keyword because this would lead to a false statement if at runtime the member is actually defined:

if (value is not defined) throw new IEAE("The specified value is not a defined enum member.", ...);

[YairHalberstadt]

This is explicitly meant to be compile time only. In most cases it doesn't help if the enum is defined at runtime if you didn't know about it when you wrote the code.

I do get the issue with the naming being potentially confusing, but I think the naming is reasonable. One is checking if the enum is defined at runtime, the other if it's defined at compile time. I'm happy to hear alternative names though.

[jnm2]

It's almost more appropriate to say "not supported" after is not defined then, in cases where the enum is defined outside the compilation. I'm not sure what a good name would be.