[Proposal]: Discriminated unions

[CyrusNajmabadi]

Discriminated unions

• Specification: Discriminated unions
• Champion issue: [Proposal]: Discriminated unions #10399

An alternate approach builds discriminated unions on C# enums.

Summary

This proposal builds on the shipped union feature. A normal union is a type union: its alternatives can overlap, so union Content(string, object) cannot distinguish a string supplied as string from the same string supplied as object. Declared cases preserve that distinction, even when their payloads have the same or overlapping types.

Each case declares a nested record and adds it to the union. Building on the existing union model lets the design reuse union behavior and keeps type unions and discriminated unions closely aligned.

Sample walkthrough:

public union Option<T>
{
    case None;
    case Some(T Value);

    public T GetValueOrDefault(T fallback)
        => this switch
        {
            .Some(var value) => value,
            .None => fallback
        };
}

static Option<T> Parse<T>(string text) where T : IParsable<T>
    => T.TryParse(text, provider: null, out var value)
        ? .Some(value)
        : .None;

Option<int> result = Parse("42");

string message = result switch
{
    .Some(var value) => $"Parsed {value}",
    .None => "Not an integer"
};

Parse("42") uses target-typed generic type inference, which is not specific to unions. The .Some(...) and .None forms depend on the contextual case syntax extensions.

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.

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

[Richiban]

I think I much prefer this to the expanded enum design.

[forgotten-aquilon]

enum class and enum struct describe the actual kind of the enclosing type, consistent with record class and record struct. Authors can choose a reference type when APIs or generic constraints require one.

A union always declares a struct...

Why isn't it possible to introduce some default implementation for union class?

[forgotten-aquilon]

Okay. The last question: what about custom DUs then?

[CyrusNajmabadi]

Okay. The last question: what about custom DUs then?

I'm not sure what this means. Can you clarify?

Right now a custom DU is already possible. You can just use a normal union, and define your cases how you want (like with records), etc. And you can control layout how you want. etc. etc. The custom approach is already possible. The point of this feature is how users can get the streamlined approach so they can have DUs without all that custom work. If you want to go the custom route, feel free :)

[forgotten-aquilon]

Being able to match named cases like in your example:

string message = result switch
{
    .Some(var value) => $"Parsed {value}",
    .None => "Not an integer"
};

[CyrusNajmabadi]

Being able to match named cases like in your example:

That can already work if you make your own custom version :)

There's nothing specific to DU in that example.

[jnm2]

Well, that can already work once #9078 ships in some future language version.