GeezerVison

ALGOL 68 has tagged unions, and uses a case clause to distinguish and extract the constituent type at runtime. A union containing another union is treated as the set of all its constituent possibilities, and if the context requires it a union is automatically coerced into the wider union. A union can explicitly contain no value, which can be distinguished at runtime. An example is:

 mode node = union (real, int, string, void);
 
 node n := "abc";
 
 case n in
   (real r):   print(("real:", r)),
   (int i):    print(("int:", i)),
   (string s): print(("string:", s)),
   (void):     print(("void:", "EMPTY")),
   out         print(("?:", n))
 esac

The syntax of the C/C++ union type and the notion of casts was derived from ALGOL 68, though in an untagged form.^[1]

In C and C++, untagged unions are expressed nearly exactly like structures (structs), except that each data member is located at the same memory address. The data members, as in structures, need not be primitive values, and in fact may be structures or even other unions. C++ (since C++11) also allows for a data member to be any type that has a full-fledged constructor/destructor and/or copy constructor, or a non-trivial copy assignment operator (for example, a std::string as a member of a union).

The primary use of a union is allowing access to a common location by different data types, for example hardware input/output access, and bitfield and word sharing. Unions can also provide low-level polymorphism. However, there is no checking of types, so it is up to the programmer to be sure that the proper fields are accessed in different contexts. The relevant field of a union variable is typically determined by the state of other variables, possibly in an enclosing struct.

One common C programming idiom uses unions to perform type punning, by assigning to one field of a union and reading from another, as is done in code which depends on the raw representation of the values. In C++, the equivalent feature is similar to a reinterpret_cast, but this cannot be used in most cases due to strict aliasing; instead, std::bit_cast<T>() is used (which reinterprets the raw bit pattern of a parameter of type U, as T). A practical example is the method of computing square roots using the IEEE representation. This is not, however, a safe use of unions in general.

Structure and union specifiers have the same form. [ . . . ] The size of a union is sufficient to contain the largest of its members. The value of at most one of the members can be stored in a union object at any time. A pointer to a union object, suitably converted, points to each of its members (or if a member is a bit-field, then to the unit in which it resides), and vice versa.

union {
    float f;
    uint32_t d; // Assumes float is 32 bits wide
};

f = 3.14f;
printf("Hexadecimal representation of 3.14f: %x\n", d);

In COBOL, union data items are defined in two ways. The first uses the RENAMES (66 level) keyword, which effectively maps a second alphanumeric data item on top of the same memory location as a preceding data item. In the example code below, data item PERSON-REC is defined as a group containing another group and a numeric data item. PERSON-DATA is defined as an alphanumeric data item that renames PERSON-REC, treating the data bytes continued within it as character data.

  01  PERSON-REC.
      05  PERSON-NAME.
          10  PERSON-NAME-LAST    PIC X(12).
          10  PERSON-NAME-FIRST   PIC X(16).
          10  PERSON-NAME-MID     PIC X.
      05  PERSON-ID               PIC 9(9) PACKED-DECIMAL.
  
  01  PERSON-DATA                 RENAMES PERSON-REC.

The second way to define a union type is by using the REDEFINES keyword. In the example code below, data item VERS-NUM is defined as a 2-byte binary integer containing a version number. A second data item VERS-BYTES is defined as a two-character alphanumeric variable. Since the second item is redefined over the first item, the two items share the same address in memory, and therefore share the same underlying data bytes. The first item interprets the two data bytes as a binary value, while the second item interprets the bytes as character values.

  01  VERS-INFO.
      05  VERS-NUM        PIC S9(4) COMP.
      05  VERS-BYTES      PIC X(2)
                          REDEFINES VERS-NUM

In Pascal, there are two ways to create unions. One is the standard way through a variant record. The second is a nonstandard means of declaring a variable as absolute, meaning it is placed at the same memory location as another variable or at an absolute address. While all Pascal compilers support variant records, only some support absolute variables.

For the purposes of this example, the following are all integer types: a byte consists of 8 bits, a word is 16 bits, and an integer is 32 bits.

The following example shows the non-standard absolute form:

var
    A: Integer;
    B: array[1..4] of Byte absolute A;
    C: Integer absolute 0;

In the first example, each of the elements of the array B maps to one of the specific bytes of the variable A. In the second example, the variable C is assigned to the exact machine address 0.

In the following example, a record has variants, some of which share the same location as others:

type
     Shape = (Circle, Square, Triangle);
     Dimensions = record
        case Figure: Shape of 
           Circle: (Diameter: real);
           Square: (Width: real);
           Triangle: (Side: real; Angle1, Angle2: 0..360)
        end;

In PL/I the original term for a union was cell,^[5] which is still accepted as a synonym for union by several compilers. The union declaration is similar to the structure definition, where elements at the same level within the union declaration occupy the same storage. Elements of the union can be any data type, including structures and array.^{[6]: pp192–193} Here vers_num and vers_bytes occupy the same storage locations.

  1  vers_info         union,
     5 vers_num        fixed binary,
     5 vers_bytes      pic '(2)A';

An alternative to a union declaration is the DEFINED attribute, which allows alternative declarations of storage, however the data types of the base and defined variables must match.^{[6]: pp.289–293}

Rust implements both tagged and untagged unions. In Rust, tagged unions are implemented using the enum keyword. Unlike enumerated types in most other languages, enum variants in Rust can contain additional data in the form of a tuple or struct, making them tagged unions rather than simple enumerated types.^[7]

Rust also supports untagged unions using the union keyword. The memory layout of unions in Rust is undefined by default,^[8] but a union with the #[repr(C)] attribute will be laid out in memory exactly like the equivalent union in C.^[9] Reading the fields of a union can only be done within an unsafe function or block, as the compiler cannot guarantee that the data in the union will be valid for the type of the field; if this is not the case, it will result in undefined behavior.^[10]

In C, a union is most commonly used to save memory by storing different data types in the same memory location.

union FloatBits {
    float f;
    uint32_t u;
};

A struct can also be a member of a union. In the following example, a struct with bit fields specified is a member of a union. For example, the following example represents a type that may be used as a single raw byte, or individual configuration flags.

union ControlRegister {
    uint8_t full_register;
    struct {  
        uint8_t enable : 1;
        uint8_t mode : 3;
        uint8_t status : 4;
    } bits;
};

union ControlRegister config = {
    .bits = {
        .enable = 1,
        .mode = 2,
    }
};

Additionally, unions are most widely used for type punning, i.e. interpreting the raw binary representation of one data type as another.

#include <stdio.h>

union Ipv4Addr {
    uint32_t address;
    uint8_t octets[4];
};

// Write individual octets
Ipv4Addr ip = {
    .octets = {192, 168, 1, 1}
}
// Read the octets as an integer: 0x0101A8C0
printf("0x%08X\n", ip.address);

// Write as a 32-bit integer
ip.address = 0x0A000001;
// Read the integer as octets: 1.0.0.10
printf("%u.%u.%u.%u\n", ip.octets[0], ip.octets[1], ip.octets[2], ip.octets[3]);

C++ supports C's unions, but these are un-idiomatic due to poor type safety. C++17 introduced a tagged union type in the standard library, called std::variant<Ts...>. The standard library provides free functions for reading and accessing from it std::holds_alternative<T>() is used to check the active type, and std::get<T>() retrieves the type (or throws if T is not the active type).^[11][12]

import std;

struct Circle {
    double radius;
};

struct Rectangle {
    double width;
    double height;
};

using Shape = std::variant<Circle, Rectangle>;

int main() {
    Shape s = Circle { .radius = 5.0 };

    // check if s holds a Circle
    if (std::holds_alternative<Circle>(s)) {
        // interpret s as a circle if so
        const Circle& circle = std::get<Circle>(s);
        std::println("s is a Circle with radius {}", circle.radius);
    }
    // s can be reassigned to another alternative
    s = Rectangle { .width = 2.0, .height = 3.0 };
}

Until C# 15, there were no union types in C#. The closest way to emulate them was through records and pattern matching.

namespace Wikipedia.Examples;

using System;

abstract record Shape;
record Circle(double Radius) : Shape;
record Rectangle(double Width, double Height) : Shape;

public class Example
{
    public static double Area(Shape s) => s switch
    {
        Circle c => Math.PI * c.Radius * c.Radius,
        Rectangle r => r.Width * r.Height,
        _ => throw new NotSupportedException()
    };
}

They could also be closely simulated using low-level layout. The following demonstrates such a union, where the fields occupy the same memory, but is not type-safe. This can be used for interoperability, serialization, and unsafe manipulation.

using System.Runtime.InteropServices;

// closest to C union FloatBits { float f; uint32_t u; };
[StructLayout(LayoutKind.Explicit)]
struct FloatBits
{
    [FieldOffset(0)]
    public float f;

    [FieldOffset(0)]
    public uint u;
}

In C# 15, the union keyword was introduced to the language. This declares a tagged union.^[13]

public record class Car(string Model);
public record class Bicycle(string Model);
public record class Bus(string Model);

public union Vehicle(Car, Bicycle, Bus);

Vehicle car = new Car("Tesla Model 3");
Console.WriteLine(car.Value); // Car { Model = Tesla Model 3 }

Vehicle bike = new Bicycle("Giant Escape 3");
Console.WriteLine(bike.Value); // Bicycle { Model = Giant Escape 3 }

Vehicle bus = new Bus("Volvo 9700");
Console.WriteLine(bus.Value); // Bus { Model = Volvo 9700 }

Vehicle v = /* some vehicle here */;
string model = v switch
{
    Car c => c.Model,
    Bicycle bk => b.Model,
    Bus bs => bs.Model,
};

The default value of a union is null, but if all types in the union are non-nullable, then a switch expression need not check for null.

Union types do not exist in Java, although they can be somewhat emulated using sealed interfaces.

// "Shape" can be thought of as a union of "Circle", "Rectangle",
// and other types that implement "Shape"
// we can explicitly restrict what is in the union using a sealed interface
sealed interface Shape permits Circle, Rectangle {}

record Circle(double radius) implements Shape {}

record Rectangle(double width, double height) implements Shape {}

class Example {
    double area(Shape s) {
        return switch (s) {
            case Circle(double r) -> Math.PI * r * r;
            case Rectangle(double w, double h) -> w * h;
        };
    }
}

A catch clause can declare a union of multiple exception types. This syntax resembles union type syntax in other languages, but does not actually introduce a new type. The effective type of the exception parameter is the most specific common supertype of the alternatives. The catch clause only catches exceptions of the declared types, no other subclasses of the common supertype.^[14]

class FooException extends RuntimeException {
    String name() {
        return "Foo";
    }
}

class BarException extends RuntimeException {
    String name() {
        return "Bar";
    }
}

void main() {
    try {
        throw Math.random() < 0.5 ? new FooException() : new BarException();
    } catch (FooException | BarException e) {
        // e has type RuntimeException, the common supertype of FooException and BarException
        System.out.println(e);
        e.printStackTrace();
        // System.out.println(e.name());
        // Because there is no name() method in RuntimeException, this fails to compile
    }
}

Union types were introduced to PHP in PHP 8.0.^[15] The values are implicitly "tagged" with a type by the language, and may be retrieved by gettype().

class Example
{
    private int|float $foo;

    public function squareAndAdd(float|int $bar): int|float
    {
        return $bar ** 2 + $this->foo;
    }
}

Support for type hints was introduced to Python in Python 3.5.^[16] The new syntax for union types were introduced in Python 3.10.^[17]

from typing import Union

class Example:
    foo: int = 0

    # old style:
    def square_and_add(self, bar: Union[int, float]) -> Union[int, float]:
        return bar ** 2 + self.foo

    # new style:
    def square_and_add(self, bar: int | float) -> int | float:
        return bar ** 2 + self.foo

Union types are supported in TypeScript.^[18] When TypeScript code is transpiled to JavaScript, all type-related information is lost.^[19] This means that there is no one way to identify the type of a value at runtime as it appears in TypeScript. However, all JavaScript values are implicitly "tagged" with a type by the language, which may be retrieved using the typeof operator for primitive values and the instanceof operator for classes. Because JavaScript uses a dynamic type system, how operations such as addition or indexing will behave is determined at runtime based on the type of the value. This means if all members of a union type support a given operation, no additional work has to be done to perform said operation.

function length(v: string | any[]): number {
    // Because both strings and arrays have a "length" property,
    // we can use it without having to figure out the actual type of v.
    return v.length;
}

function containsTheLetterA(v: string | string[] | number): boolean {
    // sometimes, it is important to know the exact type of a value.
    if (typeof v === "string") {
        return v.includes("a");
    } else if (v instanceof Array) {
        // Because v is an Array, we want to check if any element includes the letter A.
        return v.some((element) => element.includes("a"));
    } else {
        // Because we know it isn't an array or string, it must be a number.
        // Numbers don't ever contain the letter a.
        return false;
    }
}

Tagged unions in Rust use the enum keyword, and can contain tuple and struct variants:

enum Shape {
	Circle { radius: f64 },
	Rectangle { width: f64, height: f64 },
}

fn main() {
    let mut s = Shape::Circle { radius: 5.0 };
    if let Shape::Circle { radius } = s {
        println!("s is a Circle with radius {radius}");
    }
    s = Shape::Rectangle { width: 2.0, height: 3.0 };
}

Untagged unions in Rust use the union keyword:

union Foo {
	bar: i32,
	baz: bool,
}

Reading from the fields of an untagged union results in undefined behavior if the data in the union is not valid as the type of the field, and thus requires an unsafe block:

let x = Foo { bar: 10 };
let y = unsafe { x.bar }; // This will set y to 10, and does not result in undefined behavior.
let z = unsafe { x.baz }; // This results in undefined behavior, as the value stored in x is not a valid bool.