Enums

Since language version 2.0

Enum types are similar to struct types but support defining multiple variants of the data layout. Each variant has its distinct set of fields. In expressions, tools for testing, matching, and deconstructing enum variants are supported.

Declaration of Enum Types

An enum type declaration lists the number of different variants, as seen in the example below:

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

There can be zero or more fields for an enum variant. If no arguments are given, the braces can also be omitted, declaring simple values:

enum Color {
  Red, Blue, Green
}

Like struct types, enum types can have abilities. For example, the Color enum type would be appropriately declared as copyable, droppable, and storable, like primitive number types:

enum Color has copy, drop, store, key { Red, Blue, Green }

Enum types can also have the key ability and appear as roots of data in global storage. A common usage of enums in this context is versioning of data:

enum VersionedData has key {
  V1{name: String}
  V2{name: String, age: u64}
}

Similar to structs, enum types can be generic. For example, the type below represents a generic result type, where the variant constructors use positional instead of named arguments (see also positional structs).

enum Result<T> has copy, drop, store {
  Err(u64),
  Ok(T)
}

Constructing Enum Values

An enum value is constructed similarly to a struct value:

let s: String;
let data = VersionedData::V1{name: s};

If the enum variant has no fields, the braces can also be omitted:

let color = Color::Blue;

Name Resolution for Enum Variants

An enum variant names need to be qualified by the enum type name, as in VersionedData::V1.

Note:” Aliasing via the use clause is currently not supported for enum variants, and will be added in later language versions

In selected contexts, the Move compiler infers the enum type from the context, and the qualification by the type name can be omitted:

fun f(data: VersionedData) {
  match (data) { V1{..} => .., ..} // simple variant name OK
}

Matching Enum Values

The value of an enum value can be inspected using a match expression. For example:

fun area(self: &Rectangle): u64 {
    match (self) {
        Circle{radius}           => mul_with_pi(*radius * *radius),
        Rectangle{width, height) => *width * *height
    }
}

Notice that above the value matched is an immutable reference to an enum value. We can also consume values, or match over a mutable reference for interior updates:

fun scale_radius(self: &mut Rectanle, factor:  u64) {
    match (self) {
        Circle{radius} => *radius = *radius * factor,
        _              => {} // do nothing if not a Circle
  }
}

The patterns provided in the match expression are evaluated sequentially, in order of textual experience, until a match is found. It is a compile time error if not all known patterns are covered.

Patterns can be nested and contain conditions, as in the following example:

use Result::*;
let r : Result<Result<u64>> = Ok(Err(42));
let v = match (r)) {
  Ok(Err(c)) if c < 42  => 0,
  Ok(Err(c)) if c >= 42 => 1,
  Ok(_)                 => 2,
  _                     => 3 
assert!(v == 1);

Notice that in the above example, the last match clause covers both the patterns Ok(Err(_)) as Err(_). The earlier one is not covered since whether a conditional pattern matches is not decidable by the compiler; thus the first two clauses in the match expression above are not counting for match completeness.

Notice that while match completeness is enforced by the compiler, at runtime it may not be guaranteed if code is upgraded. See the discussion of upgrade compatibility of enums here.

Testing Enum Variants

With the is operator, one can examine whether a given enum value is of a given variant:

let data: VersionedData;
if (data is VersionedData::V1) { .. }

The operator allows to specify a list of variants. Also, variants can be inferred if the type of the expression being tested is known:

assert!(data is V1|V2);

Selecting From Enum Values

It is possible to directly select a field from an enum value. Recall the definition of versioned data:

enum VersionedData has key {
  V1{name: String}
  V2{name: String, age: u64}
}

One can write code as below to directly select the fields of variants:

let s: String;
let data1 = VersionedData::V1{name: s};
let data2 = VersionedData::V2{name: s, age: 20};
assert!(data1 is VersionData::V2);
assert!(data1.name == data2.name)
assert!(data2.age == 20); // data1.age will abort!

Notice that field selection aborts if the enum value has no variant with the given field. This is the case for data1.age.

Field selection is only possible if the field is uniquely named and typed throughout all variants. Thus, the following yields in a compile time error:

enum VersionedData has key {
  V1{name: String}
  V3{name: u64}
}
 
data.name
 // ^^^^^ compile time error that `name` field selection is ambigious

Using Enums Patterns in Lets

It is allowed to use an enum variant pattern in a let:

let data: VersionData;
let V1{name} = data;

Unpacking of the enum value will abort if the variant is not the expected one. If one wants to ensure that all variants of an enum are taken care of, a match expressions is recommended instead of a let. The match is checked at compile time whether all variants are covered. Otherwise, tools like the Move Prover can be used to verify that unexpected aborts cannot happen.

Enum Type Upgrade Compatibility

An enum type can be upgraded by another enum type if the new type only adds new variants at the end of the variant list. All variants already in the old enum type must be also, in the same order and starting from the beginning, in the new type. Consider the VersionedData type would have started as follows:

enum VersionedData has key {
  V1{name: String}
}

This type can be upgraded to the version we used so far in this text:

enum VersionedData has key {
  V1{name: String}
  V2{name: String, age: u64}
}

Notice that the following upgrade would not be allowed, since the order of variants must be preserved:

enum VersionedData has key {
  V2{name: String, age: u64}   // not a compatible upgrade
  V1{name: String}
}