[Proposal]: Data-carrying enums

[CyrusNajmabadi]

Data-carrying enums

• Specification: Data-carrying enums
• Champion issue: [Proposal]: Data-carrying enums #10378

An alternate approach builds discriminated unions on C#'s existing union feature.

Summary

Bring discriminated unions to C# through named cases that can carry data. The enum class and enum struct forms provide reference-type and value-type representations with record-like case behavior and enum-style construction without new.

public enum struct Option<T>
{
    None,
    Some(T value)
}

Option<int> option = Option<int>.Some(42);

int value = option switch
{
    Option<int>.Some(var item) => item,
    _ => 0
};

Supporting Documents

The directory overview maps the supporting documents:

• Design comparison examines the advantages and tradeoffs of the union and enum approaches.
• Common design covers contextual construction and inference, equality and hashing, nullability, metadata, and other shared behavior and open questions.
• Non-boxed storage explores a shared internal layout for unions and enum struct that avoids boxing during construction and extraction.
• Generated layouts explores selecting storage through attributes and source generators, including native layout and Swift interop.
• Ref-like types explores an optional extension for ref-like payloads and its open design questions. Neither main design depends on it.
• Switch dispatch discusses implementation strategies and possible compiler and JIT optimizations.
• Enum members proposes allowing user-declared members in ordinary enums and supports those members in the data-carrying enum design.

This is the community discussion for the proposal; LDM design work is tracked in the champion issue.

[GeeLaw]

In mixed-data example, the storage for ints are not aligned, which might degrade extraction efficiency due to unaligned reads. Is it on the table that data-carrying enum implementation can be user-supplied so that authors can choose the best strategy for their case?

On case numbering. A simple idea is to do case numbering if and only if the data-carrying enum is closed (and case types don't have their own type parameters, if that's a thing), and assign the indices sequentially by sorted case type name-and-signatures. Since changing the case type name-and-signature set is a breaking change for closed anyways, the simultaneous breakage of case numbering is acceptable.

[jnm2]

I'm sure that if consensus develops around something for DUs, it would be considered for type unions. It's a little different for type unions because it could require a discriminator internally to understand how to unpack the payload, but a type union has to emulate there being no discriminator in case multiple types in the union can overlap. That extra bit of emulation makes it not an exact drop-in, but maybe close enough.

[jnm2]

Imagine for example union Foo(IFormattable, int, long, decimal);

A well-behaved type union implementation needs to allow is IFormattable f to also succeed when internally it is storing an int, long, or decimal.

This behavior requirement is still true even for a type union which chooses the internal representation to be byte packedKind, InlineArray8<byte> packedPrimitives, IFormattable referenceSlot.

[mattwar]

I don't think the enum class/struct will end up being more of a DU that the type union is currently. It will likely just be a more concise way to declare a union or closed hierarchy than existing syntax.

[CyrusNajmabadi]

Right, sorry wasn't being picky, I just meant, if there's a good solution for enum struct then it could be adopted for the built in unions too I think?

@bencyoung-Fignum I've extracted that part out of the spec and placed it in https://github.com/dotnet/csharplang/blob/main/proposals/discriminated-unions/union-enum-non-boxed-layout.md. It discusses how it is a general concept that could be applied to enums/unions/etc. Thanks!

[jnm2]

A DU is a thing which is defined by having a discriminator which identifies a particular case. A type union (both in theory and as shipped) does not necessarily have such a discriminator. A type union can be incidentally evolved into a DU when the types in the union happen to be mutually exclusive, but not all type unions are DUs.

[sator-imaging]

it must be on the table. enum ref struct MyResult<T> where T : allows ref struct

[GeeLaw]

The proposal text includes ANTLR grammar that doesn't permit enum ref struct. Plus, there's always an easily generatable correct implementation of (the imaginary) enum ref struct, just lay out all the cases sequentially, so the desire to support enum ref struct by itself doesn't imply a custom implementation must be allowed.

[CyrusNajmabadi]

Explicitly added a sub-proposal on ref-structs here: https://github.com/dotnet/csharplang/blob/main/proposals/discriminated-unions/union-enum-ref-like-types.md

[MattParkerDev]

Thoughts on allowing omitting Option<int>. in cases where the type is known? Both of the example cases. It would be necessary eg with an implicit var variable.

[GabeSchaffer]

That doesn't seem to be part of this proposal, but almost what you get with the target-typed static member access proposal: https://github.com/dotnet/csharplang/blob/main/proposals/target-typed-static-member-access.md

It looks like with that you'd be able to omit the type name, but not the . because it makes name resolution harder. In other words, you could use .Some(var num). Both this proposal and the one I linked to have enum examples.

[CyrusNajmabadi]

Thoughts on allowing omitting Option. in cases where the type is known?

The specs show exactly that, and refer to the feature that would make that possible without anything special about unions/enums.

[huoyaoyuan]

We can consider to utilize the Union feature provided by runtime (dotnet/runtime#100896) when struct members are unmanaged, but can be calculated at compile time.

[CyrusNajmabadi]

This concept is covered in: https://github.com/dotnet/csharplang/blob/main/proposals/discriminated-unions/union-case-types-and-layout.md

[UniqeId6542]

Enum has been a named integer data type up until now, and I think it would be confusing to change it to be a data storage type.
C#'s 'apparent' type system has been getting more complicated and this increases the barrier to entry. I don't want it getting any more complicated than it already is.
Early on, there was class/struct/delegate/enum. Then a nullable wrapper around structs was made - which itself was a struct. Then records were made with slightly different rules. And then record-structs. Now, unions are being added.
I don't want to make things even more complicated by saying that enums are numbers, unless they are a different struct & one of those can hold data while the other is just a value.

[CyrusNajmabadi]

@UniqeId6542 Thanks for the feedback :)

[Richiban]

I'm slightly concerned by the fact that enum classes and structs support being open and closed.

That strongly suggests that, given

public enum class Foo
{ Bar, Baz } 

it's somehow possible to declare a case of the Foo enum outside its definition, which is... a choice.

I know that being open-by-default is a better fit with existing C#, but i get the feeling that 99.999% of these enums are going to be closed and the extra keyword is going to become quite the irritation.

[jnm2]

@TahirAhmadov Openness makes a lot of sense espectially for libraries and especially for 'input' enums like StringComparison or MidpointRounding or FileMode or Environment.SpecialFolder or LazyThreadSafetyMode or CompressionLevel or SearchOption.

But even for some of the enums that are likely to be switched on in user code, too, like ConsoleKey or HttpStatusCode. The claim that users are going to be throwing in the majority of the default cases might be assuming a lens that could be widened.

[TahirAhmadov]

I'm sorry, I'm even more confused now.
Currently integer enums are open; this means when compiling code as it is today (ignoring assembly hot swapping etc.), the enum can contain any integer and not at all guaranteed to be limited to defined options.
Data carrying enums, on the other hand, regardless of the presence of open or closed keyword, have a finite set of options and there is no (languaged-defined, safe) way to create an instance which is something else (except zero-value, but let's assume for simplicity that zero-value is a valid option).
On this basis alone, we cannot conflate these two situations. Yet, both Cyrus and Joseph made explicit references to current integer enums being closed or open.
In other words, previously I thought that there's a new semantic for open/closed modifier for DCEs, and that new semantic didn't make sense to me (because of intersection of inter-party agreements and programming language, etc.)
Now though, it looks like open/closed modifier for DCEs is meant to somehow mirror open/close modifier on current integer enums, which makes even less sense than before.

[CyrusNajmabadi]

Currently integer enums are open

@TahirAhmadov Correct. And 'closed' is how an author tells you that it is not opened.

The modifier tells you if you can expect to run into values beyond the set you were aware of when you compiled against the enum, and if your code needs to be written to be explicit that it can handle this situation. Or if it is fine to assume it will not happen, and you don't need to explicitly handle this.

Data carrying enums, on the other hand, regardless of the presence of open or closed keyword, have a finite set of options

The question is not about finite or not. Normal integral enums are finite as well. What is relevant is if you are aware of the entire set of options at the time when you compiled your code or not.

Now though, it looks like open/closed modifier for DCEs is meant to somehow mirror open/close modifier on current integer enums

Yes. That's the case. For both DCEs and for integral enums, closed/open does hte following:

1. allows the library author to state if the set of values is known to be fixed or not.
2. allows the library consumer to then know if htey have to have their consumption code handle future values that were not present when tehy compiled against the library.

[TahirAhmadov]

The modifier tells you if you can expect to run into values beyond the set you were aware of when you compiled against the enum

That's incorrect, though.

enum MyEnum { A = 0, B, C }

void Foo(MyEnum x)
{
  switch (x)
  {
    // ...
  }
}

Foo((MyEnum)45);

The above is perfectly legal (PS. And more importantly - safe) C#. Can you demonstrate the same for an "open" DCE?

[CyrusNajmabadi]

That's incorrect, though.

It isn't. The modifier states if you can expect to encounter values outside of this. Not that it's impossible. It's telling you a contract. It is not an enforcement mechanism.

closed states it is sufficient to handle the set of cases defined by the library author at the time you compiled against it. You can assume you won't encounter values outside of that. Code that does things in violation of the closed contract is considered not well-behaved.

That's why you don't need to handle those cases. Because any code sending it to you is already operating out of bounds of allowed behavior. So you don't need to deal with it. It's not your problem. In this case, teh system will just throw in a switch-expression.

(note: switch statements are not relevant. they have never had to be exhaustiv anyways).

Please see the docs here: https://github.com/dotnet/csharplang/blob/main/proposals/closed-enums.md @TahirAhmadov .

Note the relevant parts:

A consuming switch expression that covers all its specified members can therefore be concluded to "exhaust" the closed enum - it does not need to provide a default case to avoid warnings:

It can be a breaking change to add a closed modifier to an existing enum, or to add an additional member to an existing closed enum. Before publishing a closed enum type, the author needs to consider the long term contract it implies with its consumers.

The same applies to close on DCEs.

[forgotten-aquilon]

I love the idea of this feature, but don't like usage of enum keyword. Especially, because it covers all existing functionality of unions except when you don't want to have named states public union Shape(Circle, Square, Triangle);, but no, this is legally distinct unions! It's similar to Func/Action and delegates, but Func and Action are delegates. So, in my opinion enum doesn't require new additions after the closed keyword. It should stay as an old-school approach to having set of distinct labels. Maybe let it represent other types aside from numerical types, but this is the other question.

[colejohnson66]

Rust calls them enums.

[HaloFour]

So does Swift, "enums with associated values":

enum Barcode {
    case upc(Int, Int, Int, Int)
    case qrCode(String)
}

[forgotten-aquilon]

If unions were not already implemented, I would be ok with it. I just don't like that we can end with unions and "unions but better under the different name".

[eqpoqpe]

public readonly partial closed enum record struct Foo { }

Too liberal?

Please fix union non-boxing. that's all

[CyrusNajmabadi]

enum record

There is no concept of this (in this proposal or elsewhere) @eqpoqpe .