[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]

You are allowed to mix them. We just don't think it will be common to do so.

[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.

[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.