[Discussion]: Unions

[MadsTorgersen]

Several union proposals were consolidated into one. Here is a place to discuss the one.

Proposal document:
https://github.com/dotnet/csharplang/blob/main/proposals/unions.md

Issue for proposal:
#9662

[AndersKehlet]

// Union of exiting types

*existing, I assume

[mattwar]

Maybe exciting?

[nuiva]

Also, this is missing union keyword:

// Union with function member
public OneOrMore<T>(T, IEnumerable<T>)

[TahirAhmadov]

What is the purpose for having the null state of a union?

[HaloFour]

Any union over reference types will have to handle the possibility of a null value:

class Foo { }
class Bar { }
union FooOrBar(Foo, Bar);

var u = new FooOrBar((Foo) null);
// or
var u = default(FooOrBar);

if (u is Foo foo) { ... } // nope
if (u is Bar bar) { ... } // also nope

It would be interesting to see if/how NRTs and unions would interact with each other, beyond how the Value property is declared on that particular union.

[2xRon]

Does exhautiveness work for "partial" unions (a "sub-union")?

class Foo { }
class Bar { }
class Baz { }
union FooOrBar(Foo, Bar)
union BarOrBaz(Bar, Baz)
union FooOrBarOrBaz(Foo, Bar, Baz)

var u = FooOrBarOrBaz(new Baz())

var name = u switch
{
    Foo foo => ...,
    BarOrBaz fob => ...,
    // Warning?
};

A related question, can we return a sub-union?

private bool GetError(out UnionTypedResults<BadResult, Unauthorized> error) => ...;

public async Task<UnionTypedResults<BadRequest, Unauthorized, Ok<string>>> MyEndpoint()
{
    if (GetError(out var error))
        return error;
    UnionTypedResults.Ok("It worked!");
}

[mattwar]

1st part, no. The value of the union is not the other union type so it will fail.

2nd part, no. This is a union to union conversion and is not part of the proposal. We may end up with some helpers or extensions that do conversions.

[full-ing-arr]

for my opinion add static multi-inheritance for struct

other cases we can resolve with [Offsets]

[nuiva]

If by "static multi-inheritance" you mean compile-time subtyping, I believe it was considered in one of the early proposals, but the idea was dropped because lack of runtime support would cause too much friction. It would be a new kind of subtyping that doesn't play nicely across assemblies.

[full-ing-arr]

i'm about next

struct A { ... }
struct B { ... }
struct AB: A, B { ... }

var b = new B ...
var ab = new AB ...

arr[0] = b;
arr[1] = ab //copy only part B

for (int i = 0; i < 10; i++)
  if (arr[i] is A a)
    a.Smth() //just call without use data of B type, its track that arr[1] assign with C type, C has A part

or if we need runtime data

B[] arr = new union B[10]{ } //may be other way notation that array store link on data that located in stack
arr[0] = new A(); //can link but value be default when we try get its
arr[1] = new B(); //just store link on this
arr[2] = new AB(); //just store link on this

for (int i = 0; i < 10; i++)
  if (arr[i] is A a)
    a.Smth() //call with use data that contains in arr[i] and get part of B inside itselfs

Whole idea may be comparasing with multiarrays of structs in ZIG, but works inside and hide like for iterators, hided from developer

main part of idea is store different struct with different data and size in one array, and have instrument to operate them, may be its a same problem that not boxing when cast struct to interface, but a little cap deeply

B[] arr = new B[] ...

foreach(var el in arr) 
  el.Smth ...

may be like this

foreach(arr => 
  A => some code for A
  B => some code for B
)

but in actualy code its will be

A[] arrA = ...
B[] arrB = ...
AB[] arrC = ...
MultiArr<B> arr_ids = ...

foreach (var a = arraA)
  some code for A ...

foreach (var b = arraB)
  some code for B ...

[HaloFour]

Are you proposing that AB is a way to express a union of A or B? I'm not really sure I understand what you're proposing or how it relates to unions, which don't have anything to do with arrays.

[mattwar]

Multiple inheritance is about having a single type act as multiple types at the same time. Unions are about having a single type act as multiple types at different times (never at the same time). A multiple inheritance solution will not get you unions, unless you add a tag and restrict access to only the parts corresponding to the tag, which negates the benefit of having the multiple inheritance.

[jnm2]

What about this syntax, since C# has recently added the keyword allows? This would mean the same thing as Java's permits, and it would have the benefit of working on non-union closed hierarchies too:

union Pet allows Cat, Dog, Bird;
closed record Pet2 allows Cat, Dog, Bird;

I feel no conflict having commas once the parens are gone, interestingly.

[mattwar]

@jnm2 I tried to come up with a better keyword, but I cannot find one that both sort of works for unions and closed classes/records. There was a suggestion to use 'of':

union Pet of Cat, Dog;

However, for unions with type parameters it gets weird.

union U<T> of T, int;

Since the type parameter itself is associated with saying 'of'. Saying, "union U of T of T or int" is awkward. :-)

[jnm2]

I put up a proposal at #9676 for the allows syntax. Let's see where it goes!

[soc]

@mattwar I went with of in Core and have been very happy with it, compared to C#'s proposed Algol 68 syntax. (But I also don't associate "of" with type params.)

[jnm2]

That bridge was already crossed when C# 13 added the allows keyword.

[soc]

allows means the opposite in C# today; it is "everything normally and also ref structs". In this context, it would mean "only the types listed".

"We already used allows to not express what is allowed, so using allows to express what is allowed would be inconsistent." 🤦

[TahirAhmadov]

Isn't it possible to make a tagged union implementation behind the scenes when all of the cases are struct types, and maintain the same surface area? Basically, Value boxes, but strong-typed TryGetValue methods don't, and this way no boxing occurs at all when using a union of struct typed-cases in a strongly typed manner. (Perhaps even a strategy can be envisioned when some of the cases are struct typed and others are not; I'm not sure if this is allowed at all at this point.)

[mattwar]

Yes, this is what the TryGetValue methods are for.

[HaloFour]

I think the question is if you used the built-in union syntax would the compiler support emitting the union struct with a storage strategy that could avoid boxing, such as a tagged union.

[mattwar]

No currently, but its left open for the future.

[RikkiGibson]

It feels like the non-boxing pattern which is proposed here, is also requiring a "sequence of type tests", calling the TryGetValue methods one-by-one.

I wonder if in a future revision of the feature, it would be possible to have an O(1), non-boxing dispatch, by using a switch over System.Type (#356). Switching over System.Type was proposed some time ago but I don't think was ever implemented in the language or runtime.

struct MyUnion : IUnion, IUnion<int>, IUnion<bool> { ... }

var myUnion = new MyUnion(true);
switch (myUnion)
{
    case int i: ...;
    case bool b: ...;
}

// lowered to?
switch (myUnion.GetValueType())
{
    case typeof(int): int i = myUnion.IntValue; ...;
    case typeof(bool): bool b = myUnion.BoolValue; ...;
}

I am just not sure how myUnion.GetValueType() would actually be implemented by a custom non-boxing union in an efficient way, I'd have to think a little more about whether this concept would ultimately add any value. And again, it doesn't seem like something that needs solving in the first release of the feature.

[mattwar]

You could store the type as the tag to avoid the switch when accessing it.

[nuiva]

I wonder if in a future revision of the feature, it would be possible to have an O(1), non-boxing dispatch, by using a switch over System.Type

Pardon my ignorance about CLR/CIL, but doesn't O(1) switch require using a jump table, which in turn requires contiguous tag values to do efficiently? This seems difficult to do using globals like System.Type.

I imagine you'd want something like this if you want switches to be convertible to jump tables:

public struct MyUnion : IUnion
{
    enum Kind
    {
        Case1,
        // ...
        CaseN
    }

    Kind kind;
    Case1 value1;
    // ...
    CaseN valueN;

    // Constructors would need some new annotation so that compiler understands the mapping between Kind and union cases
    [UnionCase(Kind.Case1)] public MyUnion(Case1 value) => (kind, value1) = (Kind.Case1, value);
    [UnionCase(Kind.CaseN)] public MyUnion(CaseN value) => (kind, valueN) = (Kind.CaseN, value);

    public bool HasValue => kind != Kind.None;
    public Kind CaseKind => kind; // New getter to extract an enum of union cases
    public bool TryGetValue(out Case1 value) {/* ... */}
    // ...
    public bool TryGetValue(out CaseN value) {/* ... */}
}

MyUnion GetData() {/* ... */}
// Then this switch...
var _ = GetData() switch
{
    Case1 value => Branch1(value),
    // ...
    CaseN value => BranchN(value)
};
// ...could be lowered to this...
var _data = GetData();
var _ = _data.CaseKind switch
{
    MyUnion.Kind.Case1 => _data.TryGetValue(out Case1 value) ? Branch1(value) : throw new Exception(),
    // ...
    MyUnion.Kind.CaseN => _data.TryGetValue(out CaseN value) ? BranchN(value) : throw new Exception()
};
// ...which could be compiled to a jump table or CIL switch.

That said, I think this would be a really niche optimization, because:

• If any of a switch's patterns is not one of the cases (e.g. when matching an interface implemented by multiple cases), then the entire switch can't be lowered.
• AFAIK you need a lot of switch branches for jump tables to be worth it.
• It needs a lot of verbose boilerplate to declare. More so if you want different cases to overlap in memory, which is probably important if there are enough cases to use jump tables to begin with and you really want unboxed values.

[TahirAhmadov]

@RikkiGibson - What @nuiva wrote above, at best, Type would need to be a hashcode lookup dictionary style thing, O(log(N)).

[jnm2]

Wouldn't the switch miss derived value types?

[RikkiGibson]

Yes, you're right, switching on a type identity won't work if case types are not sealed. Given comments in this thread I find it pretty convincing that this approach is a dead end. Thanks!

[mattwar]

You could do exact type switch and then on failure fallback to slower type match.

[zigzag312]

Compatibility of proposed union syntax with potential future anonymous unions

Currently, anonymous unions are out of scope. Is there any possibility they might be added in the future? If not, please disregard this post.

Anonymous unions would be useful for method return types and method input parameters.

Current proposed union syntax is union Pet(Cat, Dog, Bird). If I try to convert this syntax to anonymous union used (for example purposes) as both input parameter and return type I get:

union(Cat, Dog, Bird) Feed(union(Cat, Dog, Bird) pet) { }

Omitting union keyword isn't possible with this syntax as that would make it a tuple.

And for other syntaxes discusses in LDM-2025-09-29, using short syntax without the union keyword where possible:

union[Cat, Dog, Bird] Feed(union[Cat, Dog, Bird] pet) { }

(Cat or Dog or Bird) Feed((Cat or Dog or Bird) pet) { }

(Cat | Dog | Bird) Feed((Cat | Dog | Bird) pet) { }

allows Cat, Dog, Bird Feed(allows Cat, Dog, Bird pet) { }

Syntaxes in which the type list is not surrounded by any kind of delimiter don’t seem to work well with anonymous unions, so I’ve added only one example.

To me, the easiest to read is (Cat | Dog | Bird), followed by (Cat or Dog or Bird). The union (Cat, Dog, Bird) can look like a tuple at first glance, if there's a space after the union keyword.

[mattwar]

There are standard unions, so you can use Union<Cat, Dog, Bird>.

[zigzag312]

I wasn't aware of standard unions. They seem like a reasonable alternative to anonymous unions.

[nuiva]

Note that the unions in this proposal and #9565 are distinct nominal† types, which means that Union<A,B> is not a supertype of A. If you're used to union types from TypeScript, you might find C# unions quite unwieldy in practice, since e.g. converting IEnumerable<A> to IEnumerable<Union<A,B>> (or A[] to (A|B)[] in TS terms) requires an actual conversion instead of a no-op upcast.

I think this unwieldiness will make people avoid writing the kind of code that would utilize anonymous unions (or standard unions) to begin with. For most intents and purposes, C# unions are sum types instead of union types (although they aren't quite true sum types either).

† Edit: Now that I think about it, nominal is not quite the right word here, since there are languages with nominal subtyping but proper union types. Anyways, point is that anonymous unions would be largely useless in C#, since the proposed C# type unions don't have union semantics.

[mattwar]

That is why they are called nominal type unions. They are not structural. There is no relationship between the case types and the union type. The union type has a name as with most types in the runtime and is distinct from other types that may seem similar but have different names. This is similar to delegate types. We have not yet defined any conversion rules between similar union types. If we do, they will be language level conversions and not involve the runtime, so will require work to convert types that have unions embedded in them like IEnumerable<Union<A,B>>.

You can use standard unions for unions you don't want to give a name too. This is similar to using Func and Action delegate types or using tuples instead of records.

[perennialmind]

The anonymous unions were what I was most looking forward to in an earlier proposal, though clearly the consensus is headed elsewhere. Still, I agree with @zigzag312 that | and or tokens better convey the intent. Commas have too strong a sequential connotation. I'm still holding out hope for the "good stuff". I'd like an ADT with the potential to be as workaday as named value tuples are today. For that to happen (int or string) has to be interchangeable with (string or int), and I have my doubts that Union<int,string> will ever be interchangeable with Union<string,int>.

[AustinGrey]

My team are interested in this feature - working in a Typescript frontends and C# backends company there's significant difficulty being proficient in both languages especially when they have features that look similar but are different. From reading the proposal and discussion, and watching the announcement video, I understand this will be one of those features. I've got a few concerns that I'm wondering how or if they will be addressed.

1. What are the ergonomics of using unions to track multiple return types?
   • In a Typescript world, nearly all well typed code has multiple return types on functions.
   • Recently interest in exception-less or exception-discouraged languages such as Go and Rust has risen, with the promise that the return type explains everything the function you are calling is expected to do.
   • Unions seems like the natural way to bring this into C#. A union Result(ValueType, ErrorType1, ErrorType2, ....) could efficiently pack that information into the return. Preventing unwanted unhandled exceptions.

Our team was interested in trying this approach, and used the OneOf library to get used to the idea of unions in C# for this purpose. There's real benefit (actually knowing, with type safety, all the possible response types in our minimal api definitions!) but the ergonomics are painful when you pass unions through layers of services.

If

• method A returns union AReturn(Foo, ErrW, ErrX)
• method B returns union BReturn(Bar, ErrY, ErrZ)
• method C is expected to return union CReturn(Baz, ErrW, ErrX, ErrY, ErrZ) and calls A and B like so:

var a = A();
var b = B(a);
return b;

You know this wouldn't compile since a might be one of the errors and also b as well. So you think to do something like an early return to clear out those options:

var a = A();
var b = a switch {
    ErrW w => // Unsure what to do here you can't "return" w from the function, that would just assign it to b, which we don't want
    ErrX x=> // Same issue as the ErrW case
    Foo happyPath => B(happyPath);
}

return b switch {
    ErrY y => // same unable to return issue
    ErrZ z=> // same unable to return issue
    Foo happyPath => happyPath; // Also an issue, since you can't implicitly case the union B returns to the union C returns
}

I may be misreading the proposal but using the pattern matching switch is the only way to deal with union possibilities, and with that, you cannot perform an early return. OneOf provides a Switch method - but it suffers the same inability to early return due to using lambdas. Your stuck with successively peeling off one value at a time - which explodes the amount of code needed and sets off all kinds of code quality alarms.

Is there any way in the given proposal to ergonomically change the control flow based on the value in a union? The most ideal would be something like:

var a = A();
return a switch {
    Foo happyPath => B(happyPath);
    var other => return other; // I know this is invalid code, but imagine this fully returns from the function
}

2. How ergonomic or type-safe could it possibly be made to cast a subset union to a superset union?
   • I have read the proposal, I know these aren't Typescript unions and that union A(B) is NOT a subset of union AA(B, C) and requires an explicit cast.
   • My examples in the first question show the Typescript background - not only are the error paths a problem, but the happy paths too since I'm returning "subset" unions as if they'll magically be valid to return as a "superset" union value - which they are not in the proposal.
   • But it feels like this is something that will happen all the time. Is there an ergonomic path?

The simplest approach I see is syntax like:

var a = A();
return a switch {
    Foo happyPath => (CReturn)B(happyPath);
    var other => ... // ignore the error case for now
}

or

var a = A();
return a switch {
    Foo happyPath => CReturn.From(B(happyPath));
    var other => ... // ignore the error case for now
}

But that implies that either

• A manual conversion from BReturn to CReturn was written somewhere, which would be a horrible amount of boilerplate
• OR that this conversion throws at runtime if B is expanded later to include a new error type - not typesafe.

I know that it's maybe out of scope, or maybe this is something best left up to code gen wizards as an aftermarket thing, but it would be great if there was something typesafe and ergonomic. I know that implicitly casting is off the table as per the spec but maybe explicit doesn't have to be so bad either. Maybe even just a naive "if the target union has an explicitly defined case for the cast union cases and the cast union cases are all explicitly defined, then the cast is valid, otherwise the compiler throws an error.

[HaloFour]

See: #7488

If C# were to support something like early returns it would certainly require an explicit syntax and some kind of rules around mapping. It really only applies to unions that represent results.

[RikkiGibson]

Is there any way in the given proposal to ergonomically change the control flow based on the value in a union?

You can handle the union cases in any constructs which work with patterns. Switch expressions, switch statements, and is-expressions would be the primary ways.

var a = A();
if (a is not Foo happyPath) {
    Console.Error.WriteLine($"Error: {a}");
    return;
}

// proceed with happy path...
happyPath.Use();

Or:

var a = A();
switch (a)
{
    case Foo happyPath:
        // do stuff...
        break;
    case ErrorType1 error1:
        // handle error1...
        return;
    case ErrorType2 error2:
        // handle error1...
        throw error2.Error; // or something
}

[CyrusNajmabadi]

I may be misreading the proposal but using the pattern matching switch is the only way to deal with union possibilities

Having some syntax for early returning is interesting. But something we have discussed and would be an orthogonal feature that could work with unions, but wouldn't be required to be part of the union proposal itself.

[mattwar]

We will be talking about these kinds of issues more in the coming months.

[HaloFour]

Aren't the F# folks also currently exploring type unions?

[miloush]

I haven't seen any mention of F# discriminated unions in any of the LDM notes or discussions. Would there be any compatibility or interoperability? How do the implementations compare?

[HaloFour]

I can understand the frustration and it would be nice if C# would just work with F# features out of the box, but given how much F# relies on custom metadata and attributes that directly reference FSharp.Core assemblies that's not really a practical solution. F# may consider how their language features might interact with other languages by emitting CLS-compatible members, but they don't really design the features to be directly consumed by those other languages.

[miloush]

I only wanted to point that there is already a .NET/CLI language that has designed a solution and implemented the feature and I wondered whether any of that work could be leveraged, built upon or learned from. For example, if they rely heavily on their own attributes, whether these attributes could be lifted to the common library and taken advantage of in other languages. I do not know much about the approach F# took, hence me asking. I understand that C# is going with interfaces rather than attributes; it would be interesting to know if F# considered that option and decided against it. I have no strong feelings either way.

[BreyerW]

@miloush F# is less interested in absolute performance than C# but more interested in programming ergonomics. For that reason attributes were perfectly fine tool for the task and bar for using attributes is much lower than going low-level solution which meant much faster delivery of feature too but C# tries to avoid costly abstractions whenever possible even if that means potentially much longer delivery

[soc]

Would certainly be amusing to see an OCaml-derivative adopt Algol unions. 🤣

[mattwar]

I think you would have to go back quite far to find references to F# in the LDM notes. For a variety of reasons/goals we are not attempting to make exactly the same type that F# is using, but we are well aware of the F# design. As for interface vs attributes, we want the interface to be available for easy boxed access to the inner value for tools like serializers, making an attribute unnecessary. Though there may be reasons to also recognize an attribute.

[Thaina]

I am not so sure but it seem I didn't see generic union in the proposal?

I think the most common usage of union would be anonymous union of 2-3 types, which I feel almost all people would not want to create explicit type. I bet people would use union in similar manner as delegate, most people just use Action and Func

It would be most beneficial if we can express union like tuple such as

public Union<Dog,Cat,Bird> GetPetOf(Person person)
{
}

or even

public (Dog | Cat | Bird) GetPetOf(Person person)
{
}

And it should be non boxing struct with layout fieldoffset 1 (0 for type switch)

[nuiva]

You're looking for proposal #9565.

[Euan-McVie]

Hi,

Interesting possible use case for enum extension via #9955
I suggested future combination of #9662 and #9011 might work as it looks good when defining.

public closed enum BasicColor
{
    Red,
    Green,
    Blue
}

public closed enum ExtendedColor
{
    White,
    Black
}

public union AllColor(BasicColor, ExtendedColor);

My follow up question would be would this work as expected and what would the switch look like?

var myColor = AllColor(BasicColor.Green);

var colorName = myColor switch
{
    BasicColor.Red => "red",
    BasicColor.Green => "green",
    ExtendedColor.White => "white"
    // Appropriate warnings if all combinations of all enum values are not provided unless _ used?
}

[HaloFour]

I expect it would as a boxed enum is aware of what the enum type is, so even if White and Red technically have the same underlying integral value they would not be the same type. You can see this same behavior with object instead of AllColor today.

[mattwar]

Ideally that should work. Fundamentally, there is a type test going on and a value match. The type test for an enum type that is a case type of the union should succeed and produce a value that is then matched with the switch cases. If it does not automatically fall out that way in implementation, we should make it a feature to work this way.

[baywet]

From reading the current version of the proposal, something isn't clear to me: does this require new runtime features?

The reason I'm asking this question is because the lack of unions as a first class concept has been lacking in the context of deserialization of discriminated unions. And to help plan code-generation support (in TypeSpec but also in other places), it be great to have a clear idea whether this new feature will require a runtime of net11+, or whether a net11 SDK will be able to "compile it down" to earlier versions of dotnet?

The motivation for that question being: if that requires a compatibility bar of net11+ for the runtime, it'll be difficult to adopt in generic libraries which want to have a broad compatibility story.

[baywet]

@DavidArno my expectation here would be that ToString() is a proxy to the union member ToString() and returns "foo" in that example.

If an enum has numeric values assigned, or a DiplayName attribute, you would expect MyEnum.Foo.ToString() to return "foo", not "MyEnum:foo". The expectation on the union is at least consistent with that.

[HaloFour]

Per this design the discriminator is intentionally an implementation detail. In the default case it would be the type itself, but a custom union could use a tag or something else entirely:

public struct Either<TL, TR> : IUnion {
    private enum Tag { Left, Right }
    private readonly Tag tag;
    private readonly TL left;
    private readonly TR right;

    public Either(TL left) {
        tag = Tag.Left;
        this.left = left;
    }

    public Either(TR right) {
        tag = Tag.Right;
        this.right = right;
    }

    object IUnion.Value { get => tag switch { Tag.Left => left, Tag.Right => right }; }

    public bool TryGet(TL value) {
        if (tag == Tag.Left) {
            value = left;
            return true;
        }
        value = default;
        return false;
    }

    public bool TryGet(TR value) {
        if (tag == Tag.Right) {
            value = right;
            return true;
        }
        value = default;
        return false;
    }
}

[CyrusNajmabadi]

You guys are talking discriminated unions. The proposal here is more around type-unions. There are proposals for things like discriminated unions. But they're taking place more in specs like: https://github.com/dotnet/csharplang/blob/main/meetings/working-groups/discriminated-unions/extended-enums.md

[CyrusNajmabadi]

And, to follow up on what Halo was saying. The language is not dictating a particular implementation shape for unions. The intent is to allow you to use your existing union types (whether written by you, or through a 3rd party) while getting all the language smarts lighting up for them (like not needing to explicitly convert between types, or knowing if things like switches are exhaustive).

We'll have a particular emit strategy the C# compiler uses. But we're not at all requiring you use that.

[DavidArno]

@CyrusNajmabadi

That flexibility is a laudable aim. It will be great if you can get it to work in practice. Definitely a "one to watch" topic.

[TheFo2sh]

Hi, I built a small experimental source-generator prototype for union-like types in C# and thought some of the lessons might be relevant here:
https://github.com/TheFo2sh/ExperimnetalTypeSystem/blob/main/README.md

A few takeaways from implementing it:

1. Implicit conversion into the union wrapper feels important for boilerplates reduction.
2. Accessing shared members across cases is useful, I have some concerns if it is cleaner but i encounter several cases where it would eliminate boilerplates.
3. A library/generator approach can approximate some behavior, but it becomes constrained by syntax shape and discoverability.
4. The experiment reinforced for me that first-class language support would be much cleaner than library-only emulation.
5. My prototype is intentionally limited, but it helped exploring the friction points in this direction.

[Thaina]

This is great

Is it possible to have this implemented as extension of Tuple<byte,T0,T1,T2,T3> or generally create enum from HashSet of type?

[TheFo2sh]

A tuple with a discriminator (e.g. (byte tag, T0, T1, ...)) could work as an internal storage representation. However, the goal of this experiment is less about how the value is encoded at runtime and more about modeling a closed, compile time case set with a generated, strongly typed API (Match, implicit conversions, shared members, etc.).

Similarly, using something like a HashSet would make the case set runtime data, whereas this prototype relies on the case set being fixed at compile time so the generator can produce a stable abstraction surface.

So I see those ideas as possible low-level representations, but not substitutes for the type level union abstraction being explored here.

[Thaina]

For hashset I don't mean runtime

I mean, the union should be unordered. So when we want to make unique ID of type we might use Set<Type> and generate hash ID out of that

So we might have

(T0 | T1) obj1;
(T1 | T0) obj2;

// become

public enum ByteTag_`base64hash` : byte
{
    _T0,
    _T1
}

Tuple<ByteTag_`base64hash`,T0,T1> obj1;
Tuple<ByteTag_`base64hash`,T0,T1> obj2;

[CyrusNajmabadi]

@Thaina you can have whatever internal representation you want. As long as abide by the union-pattern that the compiler/lang uses to identify unions.

[TheFo2sh]

Thanks for the discussion, especially around canonicalization and union pattern recognition.

I went ahead and implemented a Roslyn analyzer alongside the generator to explore this more concretely.

Current state of the experiment:

1. The union case set is declared via attribute.
2. The active value is projected through GetValue().
3. The analyzer enforces exhaustiveness on switch over that projection.
4. Missing cases are reported as errors.
5. default is allowed as an explicit fallback.

Case order is normalized for comparison.

An additional analyzer rule prevents duplicate union declarations that normalize to the same case set (even if declared in different orders).

Declarations remain nominal (no silent collapsing of distinct types), but semantic duplication is detected and reported explicitly.

The internal representation is flexible, the key piece is defining a stable observable “union pattern” (closed case set + single active value + analyzer-enforced exhaustiveness). That seems to be the minimal contract needed for union like behavior without language changes.

This experiment helped clarify where tooling can approximate first class support and where compiler level integration would still be cleaner.

Happy to share examples if useful.

[qwertie]

I came to register my very strong preference for ad-hoc union types over nominal discriminated unions... but after looking over the spec, I'm a little more ambivalent.

I really like the ad-hoc unions in languages such as TypeScript, and I find the closed unions in languages such as Haskell to be unnecessarily inconvenient. This proposal tries to chart a middle path, by requiring a nominal type to represent the union but also allowing (1) implicit conversion to a union and (2) implicit unwrapping (u is string s rather than requiring u.Value is string s). It seems suspiciously complicated, though. (e.g. why are there 3 definitional patterns: IUnionMembers, IUnion and no interface?)

The main thing I didn't see in the proposal was cross-union conversions. A common case is that one component can return A|B while another can return A|B|C, so if I have an A|B union I want there to be an implicit conversion to A|B|C. (If this cannot be done efficiently, it makes me more skeptical about the proposal). And if I have a union of type B|C|D, I would like a convenient way to get to a narrower union B|C or A|B|C, e.g.

static AorBorC? Example(BorCorD x) => x is D _ ? null : x;

[CyrusNajmabadi]

e.g. why are there 3 definitional patterns: IUnionMembers, IUnion

You only need the former if:

1. you're bringing an existing type (that you don't want to stop using) and
2. you want that type to behave like a normal C# union and
3. you don't want to expose the same surface area that the union pattern requires.

Imagine you have your own type in your codebase. And that types is already used everywhere and would be tough to move off of. At the same time, it has a surface area you like, that you don't want getting cluttered with a bunch of other members. For example, it may use factory methods instead of constructors, etc. etc. Now you can just implement IUnionMembers and get the benefits, without changing that surface area.

Note: this is a highly specialized situation. Consuming users don't need to care about this. They just see their usage of an existing union-like type get better (exhaustivity checks, etc). This is only for the rare case of a type-author who is in this situation and would like the benefits. S

[CyrusNajmabadi]

If this cannot be done efficiently, it makes me more skeptical about the proposal

It honestly depends on what you call 'efficient'. I would imagine that the compiler has broad leeway here (esp. in the future). At the end of the day, the union type that the language provides is just a wrapper around an object. So i don't see a reason blocking literally no-cost conversion (at least in the future). Whether that comes in the initial release would tbd.

[colejohnson66]

Ad-hoc unions in TypeScript work because JavaScript boxes everything and has type-erasure; C# is different. To have ad-hoc unions work in C# would either (a) require runtime involvement, or (b) have the compiler synthesize the nominal type, while at the same time, allow any possible conversions between them. The LDM's work here is to avoid (a) while making (b) possible as much as they can.

In theory, as Cyrus said, ad-hoc can be done later. Nothing requires "unions 1.0" to support every use case. Users have been waiting for unions for literal years, and I'm extremely excited to have them finally out, even if they don't cover every possible edge case.

[schmitch]

well actually I think for big adoption rates of unions ad-hoc is actually a requirement. if it can be done later: good! however if not that would probably be bad adoption wise since than only the closed-hierachies feature is the goat at the moment.

[HaloFour]

I believe the more the language tries to pretend that the nominal union type doesn't exist the more developers will incorrectly use the feature and introduce bugs. There is already enough confusion that a boxed union(string, int) will never match to a string or an int.

[dotlogix]

Hey there very interesting feature indeed.

However with the current implementation it is kind of unclear how this could ever be implemented for ref structs, they can't be boxed.

So I would assume ref structs are not and will never be supported for these types of unions?

[mattwar]

We would have to relax the Value property requirement to allow for ref structs. We can do that, but not included in current implementation to simplify the amount of compiler work.

[GiottoVerducci]

Is there an implicit conversion from union(A, B) to union(A, B, C)? From union(A,C) to union(A,B,C)?

[mattwar]

Not currently.

[WhoAmI-x86]

public interface IHasCommonProperty
{
    int CommonProperty { get; set; }
}

public class A : IHasCommonProperty
{
    public int CommonProperty { get; set; }
}

public class B : IHasCommonProperty
{
    public int CommonProperty { get; set; }
}

public union AorB(A, B);

AorB something = ...;
Console.WriteLine(something.CommonProperty); // Will access to `CommonProperty` work? or access to any other common member that is defined in common interface?

[333fred]

No, there is no plan for common property passthrough.

[HaloFour]

Source generators and extensions to the rescue! :D

[CrossBound]

The boxing problem feels like it's going to make the use case for this restricted. I'm not going to want to have to pay the price for boxing to use this with value types unless I can't find any other solution.

[CyrusNajmabadi]

I'm not going to want to have to pay the price for boxing to use this with value types

You don't hve to box. The point of the union pattern is that it can sit on any type, including those that choose a different implementation strategy. you can then decide if the tradeoffs of those other implementations are better for your needs.

[KevinCathcart]

It would be very possible to create a source generator that would make the following work:

[NonBoxingUnion(typeof(int), typeof(MyStruct), typeof(string), typeof(MyClass))]
public partial struct MyUnion;

The implementation could use an object? field for all reference types, an enum discriminator field to differentiate various value types, and some number of value type fields.

You could have one field per distinct value type. That is the always safe option, but is space inefficient. I suspect many people would want value types to packed better. One can also easilly and safely store the primitive numeric types all in a long (or whatever the longest unioned primitive numeric type is). Those have a fixed size and shape that can never change.

But can we go further? Attempting that is where things get hard.

You can sometimes use unsafe tricks to combine value types into the same field, but only if both have any reference type fields at the exact same offsets. You can potentially group all unmanaged struct (i.e. contains no reference type fields, recursively) union members into a single field of the largest size.

The problem with trying to do such packing is if any of the value types are defined in a different assembly, and are eventually changed to add a new reference type field, or similar, but the union defining assembly does not get recompiled (can happen easily if shipped as a nuget library). Use of that union type would destabilize the runtime.

Therefore if such a generator does try packing value types defined in external assemblies into a single field, it really should add a static constructor for the type that uses reflection to verify all its assumptions about those types (runtime size, relative positions of reference type fields, etc) and throw a TypeLoadException if any of the assumptions are violated.

It may also need to do that for any partial structs defined in the same assembly, since in theory some other source generator could be adding additional fields, and this one could not know about that.

[CyrusNajmabadi]

It would be very possible to create a source generator that would make the following work:

[NonBoxingUnion(typeof(int), typeof(MyStruct), typeof(string), typeof(MyClass))]
public partial struct MyUnion;

C# has partial instance constructors. So you can just do:

[NonBoxingUnion(whatever parameters control this)]
public partial struct MyUnion
{
    public partial MyUnion(int val);
    public partial MyUnion(MyStruct val);
    public partial MyUnion(string val);
    public partial MyUnion(MyClass val);
}

[la83lynx]

I wonder will it be supported in where clause in generics? Will where T : Pet create 3 versions of a method with concrete Pet type?

[CyrusNajmabadi]

Pet is a struct. So it could not be a constraint type

[martincostello]

Today while investigating adding support for custom union types to Polly's Outcome<T> type which conceptually represents either the result of an operation or an exception from that operation (App-vNext/Polly#3020), I came across two different behaviours of the feature as-designed that appeared to be counter-intuitive and created quite a time sink to work out why making an existing type a union broke the tests once I reacted to the compilation breaks.

Making an existing type a custom union type breaks existing pattern matching

Originally reported in dotnet/roslyn#83055.

Making an existing type a custom union breaks any existing pattern matching on the public members of the type that's been made a union.

You can see examples of the changes required to fix the code in the linked PR around the #if UNION_TYPES directives.

To fix the code, the pattern matching needs to be re-written to work against unions.

Custom union type does not work with "is" when used with Nullable

Originally reported in dotnet/roslyn#83050.

Existing code using is on a Nullable<T> no longer matches to the T if T is a union.

There were no compiler warnings for the change, the code just silently stopped working correctly. It was only the library's test suite that found the silent change in semantics.

To fix the code, pattern matching needs to be replaced with Nullable<T>.HasValue usage to get the intended behaviour.

Outcome<T>? maybeOutcome = Something();

if (maybeOutcome is Outcome<T> outcome)
{
    return outcome;
}

Fixing the code paths required changing the code to patterns like:

if (maybeOutcome.HasValue)
{
    return maybeOutcome.GetValueOrDefault();
}

[RikkiGibson]

Pasting my comment from one of the original issues:

This is part of a breaking change category that I worry about.

In the old code, is is effectively just checking Nullable<T>.HasValue. The new code is checking that as well as whether the type of Outcome<T>.Value is itself Outcome<T>.

It feels like we are silently changing the code from a reasonable/intended old meaning to a likely unwanted new meaning. Library authors who adopt [Union] will pass the unwanted new meaning on to their users on upgrade.

I think we should figure out whether there's anything we can do to at least not be silent in this scenario.

[perennialmind]

I expect more of this sort of thing to pop. I had hoped the pattern matching would use the established collection syntax, where I just need to wrap my expression in brackets. Conflating a wrapper type with the underlying object is bound to incur subtle problems like this. I'd go so far as to say the pretense increases the cognitive load.

I liked that the earlier proposal tried to suss out the different use cases and handled each individually. What makes sense for Typescript-style ad-hoc unions isn't obviously a good fit for high-performance or exotic/legacy code. Somebody probably wants to lift out a TLVs from a ASN.1 buffer. Oy. While I'm winging, I might as well ask for discriminated unions explicitly using the enum keyword. Not the direction they picked. 🤷

[CyrusNajmabadi]

I might as well ask for discriminated unions explicitly using the enum keyword. Not the direction they picked.

Something we're def looking at. Here's a rough initial spec i'm writing on that: https://github.com/dotnet/csharplang/blob/main/meetings/working-groups/discriminated-unions/extended-enums.md

[TahirAhmadov]

Here's a rough initial spec i'm writing on that: https://github.com/dotnet/csharplang/blob/main/meetings/working-groups/discriminated-unions/extended-enums.md

This is great! I hope it comes to fruition.

[JVimes]

Union "declarations" are implemented with boxing. Is it safe to switch to a non-boxing implementation in the future?

[CyrusNajmabadi]

It depends on what you define as "safe" in your domain. For example, you may be depending on the fact that the single object reads and writes atomically, and you can't experience any "torn" values.

But if you then change to a non boxing approach, now with several fields presumably, you might get race conditions in concurrent cases if you're not careful.

@JVimes

[SeSamSeg]

I like the proposal of allowing to switch over, and use custom pattern matching on, user defined types.
I tried it on my custom Result type and have some thoughts about the current approach:

1. Value property

I would not want to have a object Value property on my type's API as I think it is the purpose of this proposal to have well defined typing and deliberately not use any open matching or type-erased object casts.

The object backing field seems like an implementation detail of the default boiler plate code for the implementation of this union feature. Why not just keep it as a field and also generate the TryGetValue methods?

All the rules of the Well-formedness seem overcoplicated, when the TryGetValue methods are typesafe and easy to explain.

2. Nullability

There are in this proposal more than one ways to have a union in the null state:

1. The union is uninitalized
2. The union is initialized with any of the types that are nullable

uninitialized

For me it would make more sense that unions should always be initialized with the same type of compiler checks as non-nullable reference types. If the type is not initialized, it's either undefined behavior or some default state depending on the type, like is the case for any struct you create on a array without initializing it.

If the user wants to not initialize the, he can just wrap the union in a nullable and have all the same behavior (unwrapping, automatic casts, HasValue, patern matching), but without the type having to have a HasValue on the enum that most implementation would just point to true. It seems more idiomatic C#.

null value

The null value is a separate state of the union, not a value of any of the type cases on the union. For me that feels weird. If I put in a string?, i'd expect to get a string? back, not that the union is in a separate state with no clue of the string. That some types are allowed to be null, but there is no way to cast back to that type, seems more limiting than just not allowing any nullable types in the union and that you should wrap the union in a Nullable if you need null state.

If storing null by type is required, it still seems easy to save the type that was used for the null:

class NullValue<T>
{
  private NullValue() {}
  NullValue<T> Instance {get;} = new()
}

class Union
{
  object? value;
  Union(string? str)
  {
    value = str ?? NullValue<string>.Instance
  }
  bool TryGetValue(out string? str)
  {
    if (value is String storedString)
    {
      str = storedString;
      return true;
    }
    str = null;
    return value == NullValue<string>.Instance;
  }
}

This would break the Well-formedness of the Value property, another reason I don't think it's a good idea to expose the object.

It would certainly be unfortunate that if we wrap a Nullable in a union, that we have can only match in int ore null instead of Nullable. It just feels wrong.

Union member providers

That the compiler searches for an interface this way does not feel like idiomatic C#.
The requirement of static interface members also rule out the use of this feature in .net standard.
Can't we just pass a list of types to the attribute? I guess the Create methods are also used for the automatic casting to union, but I'd say that for custom types, the compiler should just use the regular conversion methods. I don't think that auto matching is the blocker for the current community implementations of union types. They all defined custom implicit conversions already.

union keyword and generator

I'm a bit disappointed with another keyword for a boilerplate generator. It's the same type of feature as the record, that it is: a code generator to produce boiler plate code. For the C# community it would have been a lot better if these features followed a pattern that could be used for regular code generators and that any missing features for doing it that way got implemented That way the community could also write better code generators for boiler plate code.

It also adds yet another keyword to C# instead of using already defined flows. I'd even say that requiring the class to be partial and auto generating it on the inclusion of a UnionAttribute would be more in-line with existing code generators and make it more discoverable that it is a generator and what is added on adding the attribute.

Newcomers to C# already are overwhelmed by the amount of different flows and keywords in a modern C# library.

[CyrusNajmabadi]

so it is coupled and those cases do matter in the scope of the API

I do not agree. But, as I mentioned. If this is relevant to you, you should wait until we do discriminated unions and use those for your apis, not type unions.

[CyrusNajmabadi]

But if attribute notation got extended to allow the generics, other generators could use that as well.

Or... We just use an interface. Since it works and doesn't need extensions to handle this case.

Also, if you want to use generators, nothing is stopping you. Define an attribute you care about, and have your generator spit out another partial part with the pieces you want to take care of (like emitting the entire IUnionMembers impl).

The point of it is to allow existing types to fit into unions, and allow other langs/compilers a clear way to map in as well. There's nothing stopping you from using that as the pattern the generator emits.

[SeSamSeg]

This is incorrect. That's not how her runtime works.
I get that Nullable get type erased when cast to an object,

My first point is that in if (nullableStruct is null), there is no null object involved. No runtime case to object, no null. These are compile type decisions, not runtime.

Second point is that the propose union will not be type erased when it holds a null value and cast to an object, but still is null will be true. It's the underlying value in the proposed implementation that is type erased. It's all compile type decisions what is null means and is mapped to.

The decisions of this proposal matter for any implementation of unions cause:

• what the cases in a switch map to
• what is null on a union means and is mapped to (its not checking if the union is null, it's a function call)
• if the unions can hold a "null" or not
• if casing to object with a "null" value casts to null

Those things cannot be changed ones decided on. Not for any user types and probably not even for discriminatory unions or tagged enum-structs.

[CyrusNajmabadi]

Second point is that the propose union will not be type erased

Then it's no longer a type union. At that point it is a discriminated union, which is a different feature set that we are interested in. But which we intend to do more on after we ship type-unions.

Those things cannot be changed ones decided on.

For type-unions no. But i see no issue with that, as this preserves teh meaning of how 'null' works with types/values anyways in the language.

not even for discriminatory unions or tagged enum-structs.

I don't see how that's the case. Those don't exist. So there's no concept of a 'change' when it comes to them.

[HaloFour]

As mentioned previously, it would be really nice if type unions could flatten themselves when boxed, so you end up with only the raw underlying value. Would make many type-checking situations better, including the null union check. But I understand the complexities involved make this impractical and it doesn't really help in the generic case anyway.

union IntOrString(int, string);

string? s = null;
IntOrString is = s;
object o = is;

Debug.Assert(o is null);

[AndrejStanisev]

For custom, non-boxing implementations, are there performance implications of the TryGet pattern?

I assume it will compile down to

if(union.TryGetValue(out A a)) { } else if(union.TryGetValue(B b)) { } else if...

As opposed to something like:

var type = union.Type; switch(type) { case 0: union.GetValue(out A a) }

[Thaina]

Not sure if possible but if C# support union we should have it be special case of is and switch case

if(union is A a)
{
}
else if(union is B b)
{
}

switch(union)
{
    case A a:break;
    case B b:break;
    case C c:break;
}

union switch {
    A a => a.X,
    B b => b.X,
    C c => c.X,
}

[ufcpp]

Is there a reason why the struct generated from union isn't readonly? It only has one get-only property, so it seems like it should always be readonly struct.

[CyrusNajmabadi]

Primarily, because we found this design clean:

A union declaration is lowered to a struct declaration with

the same attributes, modifiers, name, type parameters and constraints,

basically, if you want it to be readonly, you can mark it as such.

That said, having 'Value' be readonly likely makes sense

[ufcpp]

I see your point, but it’s cumbersome that I have to declare every union as a readonly union otherwise it always triggers the IDE0250 code fix. Anyway, it's fair enought.

That aside, isn't the IDE0250 code fix failing to work properly? Nothing happens when I run “make struct ‘readonly’” in Visual Studio.

[CyrusNajmabadi]

That aside, isn't the IDE0250 code fix failing to work properly?

No clue. It likely hasn't been updated since the compiler work isn't even done. We do IDE feature updates after compiler lands.

[SupinePandora43]

Does this proposal account for ref structs?

[CyrusNajmabadi]

Not supported currently. But identified as something we want to support.