Note: None of this capability is currently implemented.

Unions are useful when we want a value to be represented by one of several variant struct types. For example, consider this union type:

union Point:
	struct XyPoint:
		x f32
		y f32
	struct AngPoint:
		dist f32
		angle f32

This defines a new union type called Point which holds a single point value. At any given point in time, that value would either be an XyPoint or a AngPoint value.

There are two interesting properties important to know about unions:

To create variant types who sizes vary, or whose number of variants is open-ended, use a variant trait instead of a union.


As the above example shows, the simplest form of a union type declaration is as easy as packaging several struct definitions inside an overall named union declaration block. It is permissible for any of these structs to be empty of fields, as the presence of the tag field ensures that the overall struct is not empty.

Any number of fields may be specified prior to the first struct declaration. All these fields are considered in common and at the beginning across all the variant structs.

union Event:
	time datetime
	struct ButtonEvent:
		button u8
		pushed Bool
	struct KeyEvent:
		key Unicode
	struct QuitEvent

In this example, all three variant structs include the time field prior to any fields they have defined.

For alignment reasons, it may be desirable to place the implicit tag field in some other spot other than the first field. To do this, specify an anonymous field of _ enum wherever the tag field should be located. The size and type of the tag field can vary depending on the number of variants (e.g., u8 when variant count is 255 or less). The tag field cannot be explicitly accessed, referenced or mutated.


An union initial value is built using a constructor for one of the variant struct types:

mut event = QuitEvent[timestamp]
oddval = KeyEvent[timestamp, 's']

Notice that the constructor must specify a value for all common fields. It can never specify a value for the hidden tag field, as that is determined by the variant type selected.


A union value may be passed around, by copy, just like any other value. This is possible because all variant values of a specific enum type are the same size. The enum type's size is effectively the size of its largest variant type plus the size of its hidden tag field.

Value Access

To safely gain access to the differently-typed value enclosed with an enum value, we must use pattern matching to determine which variant type it holds. Once that has been narrowed, it can be used like any other struct value.


An enum value may only be compared for equivalence (and not order). The equivalence check compares the tag fields first. If they are equal, the appropriately-typed interior values are compared using the == method.