Enumerations

They both print: As.

The “enum” keyword introduces the new Continent type, specified just after it. Such a type is called enumerative, because it lists a set of items, internally associating a unique number to each item. In the example, the allowed values for the type Continent are Europe, Asia, Africa, America, and Oceania, which respectively are represented internally by the values 0u8, 1u8, 2u8, 3u8, and 4u8. Such allowed values are named variants.

In the simplest cases, like the one just shown, this type is similar to the construct of the C language having the same name.

After having defined an enumerative type, it is possible to create objects of such type, named enumerations, or enums for short. In the example, the contin enum variable, of Continent type, has been defined.

The first line of the program is an attribute. We have seen attributes in the section “Rust Attributes” in Chapter 5. Its purpose is the following one.

The compiler includes a useful check: every variant must be constructed at least one time in an application, otherwise it is useless, and the compiler will emit a warning about it. In the preceding program only the Asia variant is constructed, so the compiler would emit four warnings about the unused variants. To avoid them, the attribute #[allow(dead_code)] has been added. Actually, the creation of an enum variant is some kind of code. The compiler reckons that this code will never be run, so it is dead code. We are warned of the existence of such dead code.

Notice that the use of a variant must be qualified by the name of its type, like in Continent::Asia.

generates a compilation error at the second line, and another one at the third line, both of the kind mismatched types. The first error is described as expected `i32`, found enum `T`, and the second error is described as expected enum `T`, found integer. Therefore, enums cannot implicitly be converted to numbers, and numbers cannot implicitly be converted to enums.

The match Construct

In the example introducing the enum construct, the just created enum is used by a new kind of statement, beginning with the “match” keyword .

The match statement is the basic Rust tool to use enumerations, similarly to the switch statement in C language, even if they differ about many aspects.

In the first place, notice that the expression following the match keyword doesn’t have to be enclosed in parentheses.

Then, the various cases, also called arms, are made of a pattern, followed by the symbol “=>” (named fat arrow), followed by an expression. Such arms are separated by commas.

Both in the declaration of the enumerative type, and in the match statement, after the last item, it is optional to put another comma. That is, you can write a comma after the last variant of an enum declaration, or you can omit it; and you can write a comma after the last arm of a match statement, or you can omit it. Usually, if you put each item in a different line, the comma is written, so that every line containing items ends with a comma. However, the comma is usually omitted just before a closed brace, like in enum CardinalPoint { North, South, West, East };.

The behavior of our match statement is as follows.

First, the statement following match is evaluated, thereby obtaining a value, which in our example is Continent::Asia. Then, that value is compared with each one of the (five) patterns, in the order that they appear written. As soon as a pattern matches, the right side of its arm is evaluated and the statement is ended.

Notice that the right side of every arm must be a single expression. So far, we always used print! as if it were a statement, but actually it is an expression.

Given that an invocation of the print! macro is a valid expression, when we added a “;” character after it, we transformed it into a statement.

we would have gotten the error message: expected expression, found keyword `fn`, because at the right of the fat arrow, there isn’t a valid expression.

This will print: 7.

Here contin has been declared as mutable, and then, in case its value was Europe , it would be changed to Asia and the letter E would be printed. But in case its value was Asia, another variable would be declared, initialized, printed, and then destroyed.

Such two arms have a block as their right side, and, because any block is an expression, this syntax is valid.

Relational Operators and Enums

For the last statement the compiler generates the message “binary operation `==` cannot be applied to type `CardinalPoint`”. Consequently, to check the value of an enum, you are required to use a match statement.

Enums are important, as they are used in many places in the standard library and also in other Rust libraries. And the match construct is important, because it is required to use enums, even if often it is encapsulated in other constructs.

Handling All the Cases

you will get the error: non-exhaustive patterns: `West` and `East` not covered. The compiler complains that among the allowed values for the expression direction, only two of them were considered, and the cases in which the expression’s value would be West or East weren’t considered. This happens because Rust requires that the match statement explicitly handles every possible case.

This program does not print anything, because the matching CardinalPoint::South case is never reached, but the compiler notices that the last case can never be reached, and it emits the warning: unreachable pattern.

The “_” pattern corresponds to the “default” case of the C language.

Using match with Numbers

This will print: other three point .

The first match statement has a string as its argument, so it expects strings as left sides of its arms. In particular, no arm matches exactly, so the default case is taken.

The second match statement has an integer number as its argument, so it expects integer numbers as left sides of its arms. In particular, the pattern of the first arm matches, so it is taken.

The third match statement has a character as its argument, so it expects single characters as left sides of its arms. In particular, the pattern of the second arm matches, so it is taken.

Also for match statements with arguments that aren’t enums, it is required that all possible cases are handled. However, except for enums and Booleans, it is not feasible to specify all single cases; therefore, it is required to use the underscore “catch-all” case.

Enumerations with Data

It will print: Error X.

Instead, if the commented out line that declares the outcome variable is reactivated, and the next line is commented out, the program will print: Result: 1.

In this code, in the definition of the Result enumerative type, the first variant specifies a data type enclosed in parentheses (u8); the second variant specifies two data types in parentheses (u16 and char); and the third variant does not specifies any data type (and does not use parentheses).

The effect of such a declaration is that every object having such a Result type, like the variable outcome in the example, can have the following values:Result::Success, and in addition it also contains a field of type u8;Result::Failure, in addition it also contains a field of type u16 and a field of type char;Result::Uncertainty, and it contains no further data.There is no other possibility.

Therefore, with respect to the C language, Rust enumerative types combine the enum feature with the union feature.

You can see that to assign a value to the outcome variable, the name of the variant (Result::Success or Result::Failure) is specified, and such name is followed by some comma-separated values, enclosed in parentheses, like in a function call ((1) in the first case and (20, 'X') in the second case).

When you assign a value to an enumeration of such a type, you must specify in parentheses the arguments having the same types specified in the fields of that variant. In the example, in the Success case, an integer is passed; in the Failure case, an integer and a character are passed; and in the Uncertainty case, no parameter is passed. If you pass arguments of other types or in different numbers, you’ll get a compilation error.

The match statement extends the concept of pattern matching to the variant fields. You can see that in the example code there are seven different patterns. The first three of them require a Result::Success variant; the next three require a Result::Failure variant; and the last one requires a Result::Uncertainty variant.

These patterns contain some literals in parentheses. For example, the first arm contains the “0” literal. In case the value to match is a Success variant containing the “0” value, the pattern matches, so this arm is taken and the string “Result: 0” is printed. In case the value is different, this arm is skipped.

The second arm matches only with the value Success(1). If the value to match is still different, even this arm is skipped. The third arm contains an underscore, which is a catch-all pattern, meaning that any Success pattern will match.

In case the value to match is a Failure variant, the fourth arm checks whether the values of the fields to match are 10 and 'X'. In case both fields match, the arm is taken.

Otherwise, the fifth arm is checked. It checks that the value of the first field is 10, and it allows any value for the second field. If the first field is not 10, this arm is skipped.

The sixth arm allows any value for the first field, but requires that the value of the second field is 'X'.

The seventh arm allows any value for both fields of the Failure variant.

The last arm is taken only for an Uncertainty variant .

So, in every pattern there must be as many arguments as the fields defined in their respective declaration. In addition, the types of the literals must be the same of the respective fields. Here too, doing it differently causes compilation errors.

In addition, a compilation error is emitted if a possible case is not considered by any pattern.

As you can see, it is much more verbose.

match Statements with Variables in Patterns

This will print: Error: n.20 X.

Activating the first declaration of the outcome variable, instead of the second one, it will print: Result: 13.

In the match statement, the patterns of the third, fifth, sixth, and seventh arms contain identifiers never declared. They are n, m, code, and module. Such identifiers are declared as new variables in this way.

Their type is inferred by the type of the corresponding field. So, the type of n is u8; the type of code is u16; and the type of m and of module is char.

Such variables always match with the corresponding field, and, in case the complete pattern matches, they are initialized by the matching value.

The scope of such variables is only the arm in which they are declared. So, if a variable with the same name exists before, it will be shadowed just for the body of the arm.

match Expressions

This will print: S.

We already saw that if the “if” keyword is used to create an if expression, it must also have an else block, and its returned type must be the same as the block before the else keyword.

The same applies for match expressions: all the arms of any match expressions must have the right sides of the same type. In the example, the three arms have the values 'N', 'S', and '*', so they are all of char type.

If the third arm were replaced by “_ => {},”, you would get the compilation error “match arms have incompatible types.” Indeed, as two arms are of char type, and one of empty tuple type, it is impossible to determine the type of the whole match expression.

Use of Guards in match Constructs

The for statement iterates the integer numbers from -2 included to 5 excluded.

For each processed number, that number is printed, followed by its classification. Such classification is performed by the match construct, which here is used as an expression having a string as its value. Indeed, each of its arms has a literal string as its value.

The third arm differs from the others, though. Its pattern is an underscore, so such an arm should always match, but the pattern is followed by a clause made by the “if” keyword followed by a Boolean condition. Such a clause causes this pattern to match only if that Boolean condition is true. It is named guard, as it protects the expression by an arbitrary Boolean condition, in addition to the pattern to match.

The last arm is the real catch-all pattern.

if-let and while-let Constructs

In this code, we need to check whether the value of v is a Case3 variant, and in such a case we need to use its two fields.

Here the construct let E::Case3(n, b) = v tries to match the value of the expression v with the pattern E::Case3(n, b). If the match is successful, the n and b variables get the value of the two fields of v, and they can be used inside the following block. Instead, if the match is unsuccessful, the condition of the if-expression is considered false, and the following expression is not evaluated; if there is an else clause, it is evaluated.

It will print: 0123456.

At any iteration, the value of v is matched against the pattern E::Case1(n). As long as the match is successful, the loop is repeated.