# Union Types - More Details

## Syntax

Syntactically, unions follow the same rules as intersections, but have a lower precedence, see Intersection Types - More Details.

### Interaction with pattern matching syntax

`|`

is also used in pattern matching to separate pattern alternatives and has
lower precedence than `:`

as used in typed patterns, this means that:

```
case _: A | B => ...
```

is still equivalent to:

```
case (_: A) | B => ...
```

and not to:

```
case _: (A | B) => ...
```

## Subtyping Rules

`A`

is always a subtype of`A | B`

for all`A`

,`B`

.- If
`A <: C`

and`B <: C`

then`A | B <: C`

- Like
`&`

,`|`

is commutative and associative:`A | B =:= B | A A | (B | C) =:= (A | B) | C`

`&`

is distributive over`|`

:`A & (B | C) =:= A & B | A & C`

From these rules it follows that the *least upper bound* (lub) of a set of types
is the union of these types. This replaces the
definition of least upper bound in the Scala 2 specification.

## Motivation

The primary reason for introducing union types in Scala is that they allow us to guarantee that for every set of types, we can always form a finite lub. This is both useful in practice (infinite lubs in Scala 2 were approximated in an ad-hoc way, resulting in imprecise and sometimes incredibly long types) and in theory (the type system of Scala 3 is based on the DOT calculus, which has union types).

Additionally, union types are a useful construct when trying to give types to existing dynamically typed APIs, this is why they're an integral part of TypeScript and have even been partially implemented in Scala.js.

## Join of a union type

In some situation described below, a union type might need to be widened to
a non-union type, for this purpose we define the *join* of a union type `T1 | ... | Tn`

as the smallest intersection type of base class instances of
`T1`

,...,`Tn`

. Note that union types might still appear as type arguments in the
resulting type, this guarantees that the join is always finite.

### Example

Given

```
trait C[+T]
trait D
trait E
class A extends C[A] with D
class B extends C[B] with D with E
```

The join of `A | B`

is `C[A | B] with D`

## Type inference

When inferring the result type of a definition (`val`

, `var`

, or `def`

), if the
type we are about to infer is a union type, we replace it by its join.
Similarly, when instantiating a type argument, if the corresponding type
parameter is not upper-bounded by a union type and the type we are about to
instantiate is a union type, we replace it by its join. This mirrors the
treatment of singleton types which are also widened to their underlying type
unless explicitly specified. and the motivation is the same: inferring types
which are "too precise" can lead to unintuitive typechecking issues later on.

Note: Since this behavior limits the usability of union types, it might be changed in the future. For example by not widening unions that have been explicitly written down by the user and not inferred, or by not widening a type argument when the corresponding type parameter is covariant. See #2330 and #4867 for further discussions.

### Example

```
import scala.collection.mutable.ListBuffer
val x = ListBuffer(Right("foo"), Left(0))
val y: ListBuffer[Either[Int, String]] = x
```

This code typechecks because the inferred type argument to `ListBuffer`

in the
right-hand side of `x`

was `Left[Int, Nothing] | Right[Nothing, String]`

which
was widened to `Either[Int, String]`

. If the compiler hadn't done this widening,
the last line wouldn't typecheck because `ListBuffer`

is invariant in its
argument.

## Members

The members of a union type are the members of its join.

### Example

The following code does not typecheck, because `hello`

is not a member of
`AnyRef`

which is the join of `A | B`

.

```
trait A { def hello: String }
trait B { def hello: String }
def test(x: A | B) = x.hello // error: value `hello` is not a member of A | B
```

## Exhaustivity checking

If the selector of a pattern match is a union type, the match is considered exhaustive if all parts of the union are covered.

## Erasure

The erased type for `A | B`

is the *erased least upper bound* of the erased
types of `A`

and `B`

. Quoting from the documentation of `TypeErasure#erasedLub`

,
the erased lub is computed as follows:

- if both argument are arrays of objects, an array of the erased lub of the element types
- if both arguments are arrays of same primitives, an array of this primitive
- if one argument is array of primitives and the other is array of objects, Object
- if one argument is an array, Object
- otherwise a common superclass or trait S of the argument classes, with the
following two properties:
- S is minimal: no other common superclass or trait derives from S
- S is last : in the linearization of the first argument type
`|A|`

there are no minimal common superclasses or traits that come after S. The reason to pick last is that we prefer classes over traits that way, which leads to more predictable bytecode and (?) faster dynamic dispatch.