|
| 1 | +# Enums |
| 2 | + |
| 3 | +_Since language version 2.0_ |
| 4 | + |
| 5 | +Enum types are similar to struct types but support defining multiple *variants* of the data layout. Each variant has its distinct set of fields. Enum variants are supported in expressions, tools for testing, matching, and deconstructing. |
| 6 | + |
| 7 | + |
| 8 | +## Declaration of Enum Types |
| 9 | + |
| 10 | +An enum type declaration lists the number of different variants, as seen in the example below: |
| 11 | + |
| 12 | +```move |
| 13 | +enum Shape { |
| 14 | + Circle{radius: u64}, |
| 15 | + Rectangle{width: u64, height: u64} |
| 16 | +} |
| 17 | +``` |
| 18 | + |
| 19 | +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: |
| 20 | + |
| 21 | +```move |
| 22 | +enum Color { |
| 23 | + Red, Blue, Green |
| 24 | +} |
| 25 | +``` |
| 26 | + |
| 27 | +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: |
| 28 | + |
| 29 | +```move |
| 30 | +enum Color has copy, drop, store, key { Red, Blue, Green } |
| 31 | +``` |
| 32 | + |
| 33 | +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: |
| 34 | + |
| 35 | +```move |
| 36 | +enum VersionedData has key { |
| 37 | + V1{name: String} |
| 38 | + V2{name: String, age: u64} |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +Similar to structs, enum types can be generic and take positional arguments. For example, the type below represents a generic result type, where the variant constructors use positional instead of named arguments (see also [positional structs](structs-and-resources.mdx#positional-structs)). |
| 43 | + |
| 44 | +```move |
| 45 | +enum Result<T> has copy, drop, store { |
| 46 | + Err(u64), |
| 47 | + Ok(T) |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +## Constructing Enum Values |
| 52 | + |
| 53 | +An enum value is constructed similarly to a struct value: |
| 54 | + |
| 55 | +```move |
| 56 | +let s: String; |
| 57 | +let data = VersionedData::V1{name: s}; |
| 58 | +``` |
| 59 | + |
| 60 | +If the enum variant has no fields, the braces can also be omitted: |
| 61 | + |
| 62 | +```move |
| 63 | +let color = Color::Blue; |
| 64 | +``` |
| 65 | + |
| 66 | +## Name Resolution for Enum Variants |
| 67 | + |
| 68 | +The variant names for an enum need to be qualified by the enum type name, as in `VersionedData::V1`. |
| 69 | + |
| 70 | +> Note: Aliasing via the `use` clause is currently not supported for enum variants, but will be added in later language versions |
| 71 | +
|
| 72 | +In certain cases (such as match expressions, below), the Move compiler can infer the enum type from the context, and the qualification by the type name may be omitted: |
| 73 | + |
| 74 | +```move |
| 75 | +fun f(data: VersionedData) { |
| 76 | + match (data) { V1{..} => .., ..} // simple variant name OK |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +## Matching Enum Values |
| 81 | + |
| 82 | +The value of an enum value can be inspected using a match expression. For example: |
| 83 | + |
| 84 | +```move |
| 85 | +fun area(self: &Rectangle): u64 { |
| 86 | + match (self) { |
| 87 | + Circle{radius} => mul_with_pi(*radius * *radius), |
| 88 | + Rectangle{width, height) => *width * *height |
| 89 | + } |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +Notice above that the value matched is an immutable reference to an enum value. A match expression can also consume a value, or match over a mutable reference for interior updates: |
| 94 | + |
| 95 | +```move |
| 96 | +fun scale_radius(self: &mut Rectangle, factor: u64) { |
| 97 | + match (self) { |
| 98 | + Circle{radius: r} => *r = *r * factor, |
| 99 | + _ => {} // do nothing if not a Circle |
| 100 | + } |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +The patterns provided in the match expression are evaluated sequentially, in order of textual occurrence, until a match is found. It is a compile time error if not all known patterns are covered. |
| 105 | + |
| 106 | +Patterns can be nested and contain conditions, as in the following example: |
| 107 | + |
| 108 | +```move |
| 109 | +let r : Result<Result<u64>> = Ok(Err(42)); |
| 110 | +let v = match (r)) { |
| 111 | + Ok(Err(c)) if c < 42 => 0, |
| 112 | + Ok(Err(c)) if c >= 42 => 1, |
| 113 | + Ok(_) => 2, |
| 114 | + _ => 3 |
| 115 | +}; |
| 116 | +assert!(v == 1); |
| 117 | +``` |
| 118 | + |
| 119 | +Notice that in the above example, the last match clause (`_`) covers both patterns `Ok(Err(_))` and `Err(_)`. Although at execution time, the earlier clauses match `Ok(Err(c))` for all values of `c`, the compiler cannot be sure all cases are covered due to the conditionals: conditions in match expressions are not considered when tracking coverage. Thus the first two clauses in the match expression above are not sufficient for match completeness, and an additional clause is required to avoid a compiler error. |
| 120 | + |
| 121 | +## Testing Enum Variants |
| 122 | + |
| 123 | +With the `is` operator, one can examine whether a given enum value is of a given variant: |
| 124 | + |
| 125 | +```move |
| 126 | +let data: VersionedData; |
| 127 | +if (data is VersionedData::V1) { .. } |
| 128 | +``` |
| 129 | + |
| 130 | +The operator allows specifying a list of variants, separated by "`|`" characters. The variants need not be qualified by the enum name if the type of the expression being tested is known: |
| 131 | + |
| 132 | +```move |
| 133 | +assert!(data is V1|V2); |
| 134 | +``` |
| 135 | + |
| 136 | +## Selecting From Enum Values |
| 137 | + |
| 138 | +It is possible to directly select a field from an enum value. Recall the definition of versioned data: |
| 139 | + |
| 140 | +```move |
| 141 | +enum VersionedData has key { |
| 142 | + V1{name: String} |
| 143 | + V2{name: String, age: u64} |
| 144 | +} |
| 145 | +``` |
| 146 | + |
| 147 | +One can write code as below to directly select the fields of variants: |
| 148 | + |
| 149 | +```move |
| 150 | +let s: String; |
| 151 | +let data1 = VersionedData::V1{name: s}; |
| 152 | +let data2 = VersionedData::V2{name: s, age: 20}; |
| 153 | +assert!(data1.name == data2.name) |
| 154 | +assert!(data2.age == 20); |
| 155 | +``` |
| 156 | + |
| 157 | +Notice that field selection aborts if the enum value has no variant with the given field. This is the case for `data1.age`. |
| 158 | +The abort code used for this case is `0xCA26CBD9BE0B0001`. In terms of the `std::error` convention, this code has |
| 159 | +category `std::error::INTERNAL` and reason `1`. |
| 160 | + |
| 161 | +Field selection is only possible if the field is uniquely named and typed throughout all variants. Thus, the following yields a compile time error: |
| 162 | + |
| 163 | +```move |
| 164 | +enum VersionedData has key { |
| 165 | + V1{name: String} |
| 166 | + V2{name: u64} |
| 167 | +} |
| 168 | +
|
| 169 | +data.name |
| 170 | + // ^^^^^ compile time error that `name` field selection is ambigious |
| 171 | +``` |
| 172 | + |
| 173 | +## Using Enums Patterns in Lets |
| 174 | + |
| 175 | +An enum variant pattern may be used in a `let` statement: |
| 176 | + |
| 177 | +```move |
| 178 | +let data: VersionData; |
| 179 | +let V1{name} = data; |
| 180 | +``` |
| 181 | + |
| 182 | +Unpacking the enum value will abort if the variant is not the expected one. To ensure that all variants of an enum are handled, a `match` expression is recommended instead of a `let`. The `match` is checked at compile time, ensuring that all variants are covered. In some cases, tools like the Move Prover can be used to verify that unexpected aborts cannot happen with a `let`. |
| 183 | + |
| 184 | + |
| 185 | +## Enum Type Upgrade Compatibility |
| 186 | + |
| 187 | +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 present in the old enum type must also appear in the new type, in the same order and starting from the beginning. Consider the `VersionedData` type, which might have begun with a single version: |
| 188 | + |
| 189 | + |
| 190 | +```move |
| 191 | +enum VersionedData has key { |
| 192 | + V1{name: String} |
| 193 | +} |
| 194 | +``` |
| 195 | + |
| 196 | +This type could be upgraded to the version we used so far in this text: |
| 197 | + |
| 198 | +```move |
| 199 | +enum VersionedData has key { |
| 200 | + V1{name: String} |
| 201 | + V2{name: String, age: u64} |
| 202 | +} |
| 203 | +``` |
| 204 | + |
| 205 | +That following upgrade would not be allowed, since the order of variants must be preserved: |
| 206 | + |
| 207 | +```move |
| 208 | +enum VersionedData has key { |
| 209 | + V2{name: String, age: u64} // not a compatible upgrade |
| 210 | + V1{name: String} |
| 211 | +} |
| 212 | +``` |
0 commit comments