Apr. 17, 2015 · Felix S. Klock II
+
+
+
One of the primary goals of the Rust project is to enable safe systems
+programming. Systems programming usually implies imperative
+programming, which in turns often implies side-effects, reasoning
+about shared state, et cetera.
+
At the same time, to provide safety, Rust programs and data types
+must be structured in a way that allows static checking to ensure
+soundness. Rust has features and restrictions that operate in tandem
+to ease writing programs that can pass these checks and thus ensure
+safety. For example, Rust incorporates the notion of ownership deeply
+into the language.
+
Rust's match expression is a construct that offers an interesting
+combination of such features and restrictions. A match expression
+takes an input value, classifies it, and then jumps to code written to
+handle the identified class of data.
+
In this post we explore how Rust processes such data via match.
+The crucial elements that match and its counterpart enum tie
+together are:
+
+-
+
Structural pattern matching: case analysis with ergonomics vastly
+improved over a C or Java style switch statement.
+
+-
+
Exhaustive case analysis: ensures that no case is omitted
+when processing an input.
+
+-
+
match embraces both imperative and functional styles of
+programming: you can continue using break statements, assignments,
+et cetera,
+rather than being forced to adopt an expression-oriented mindset.
+
+-
+
match "borrows" or "moves", as needed: Rust encourages the developer to
+think carefully about ownership and borrowing. To ensure that
+one is not forced to yield ownership of a value
+prematurely, match is designed with support for merely borrowing
+substructure (as opposed to always moving such substructure).
+
+
+
We cover each of the items above in detail below, but first we
+establish a foundation for the discussion: What does match look
+like, and how does it work?
+
The Basics of match
+
The match expression in Rust has this form:
+
match INPUT_EXPRESSION {
+ PATTERNS_1 => RESULT_EXPRESSION_1,
+ PATTERNS_2 => RESULT_EXPRESSION_2,
+ ...
+ PATTERNS_n => RESULT_EXPRESSION_n
+}
+
+
where each of the PATTERNS_i contains at least one pattern. A
+pattern describes a subset of the possible values to which
+INPUT_EXPRESSION could evaluate.
+The syntax PATTERNS => RESULT_EXPRESSION is called a "match arm",
+or simply "arm".
+
Patterns can match simple values like integers or characters; they
+can also match user-defined symbolic data, defined via enum.
+
The below code demonstrates generating the next guess (poorly) in a number
+guessing game, given the answer from a previous guess.
+
enum Answer {
+ Higher,
+ Lower,
+ Bingo,
+}
+
+fn suggest_guess(prior_guess: u32, answer: Answer) {
+ match answer {
+ Answer::Higher => println!("maybe try {} next", prior_guess + 10),
+ Answer::Lower => println!("maybe try {} next", prior_guess - 1),
+ Answer::Bingo => println!("we won with {}!", prior_guess),
+ }
+}
+
+#[test]
+fn demo_suggest_guess() {
+ suggest_guess(10, Answer::Higher);
+ suggest_guess(20, Answer::Lower);
+ suggest_guess(19, Answer::Bingo);
+}
+
+
(Incidentally, nearly all the code in this post is directly
+executable; you can cut-and-paste the code snippets into a file
+demo.rs, compile the file with --test, and run the resulting
+binary to see the tests run.)
+
Patterns can also match structured data (e.g. tuples, slices, user-defined
+data types) via corresponding patterns. In such patterns, one often
+binds parts of the input to local variables;
+those variables can then be used in the result expression.
+
The special _ pattern matches any single value, and is often used as
+a catch-all; the special .. pattern generalizes this by matching any
+series of values or name/value pairs.
+
Also, one can collapse multiple patterns into one arm by separating the
+patterns by vertical bars (|); thus that arm matches either this pattern,
+or that pattern, et cetera.
+
These features are illustrated in the following revision to the
+guessing-game answer generation strategy:
+
struct GuessState {
+ guess: u32,
+ answer: Answer,
+ low: u32,
+ high: u32,
+}
+
+fn suggest_guess_smarter(s: GuessState) {
+ match s {
+ // First arm only fires on Bingo; it binds `p` to last guess.
+ GuessState { answer: Answer::Bingo, guess: p, .. } => {
+ // ~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~ ~~
+ // | | | |
+ // | | | Ignore remaining fields
+ // | | |
+ // | | Copy value of field `guess` into local variable `p`
+ // | |
+ // | Test that `answer field is equal to `Bingo`
+ // |
+ // Match against an instance of the struct `GuessState`
+
+ println!("we won with {}!", p);
+ }
+
+ // Second arm fires if answer was too low or too high.
+ // We want to find a new guess in the range (l..h), where:
+ //
+ // - If it was too low, then we want something higher, so we
+ // bind the guess to `l` and use our last high guess as `h`.
+ // - If it was too high, then we want something lower; bind
+ // the guess to `h` and use our last low guess as `l`.
+ GuessState { answer: Answer::Higher, low: _, guess: l, high: h } |
+ GuessState { answer: Answer::Lower, low: l, guess: h, high: _ } => {
+ // ~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~ ~~~~~~ ~~~~~~~~ ~~~~~~~
+ // | | | | |
+ // | | | | Copy or ignore
+ // | | | | field `high`,
+ // | | | | as appropriate
+ // | | | |
+ // | | | Copy field `guess` into
+ // | | | local variable `l` or `h`,
+ // | | | as appropriate
+ // | | |
+ // | | Copy value of field `low` into local
+ // | | variable `l`, or ignore it, as appropriate
+ // | |
+ // | Test that `answer field is equal
+ // | to `Higher` or `Lower`, as appropriate
+ // |
+ // Match against an instance of the struct `GuessState`
+
+ let mid = l + ((h - l) / 2);
+ println!("lets try {} next", mid);
+ }
+ }
+}
+
+#[test]
+fn demo_guess_state() {
+ suggest_guess_smarter(GuessState {
+ guess: 20, answer: Answer::Lower, low: 10, high: 1000
+ });
+}
+
+
This ability to simultaneously perform case analysis and bind input
+substructure leads to powerful, clear, and concise code, focusing the
+reader's attention directly on the data relevant to the case at hand.
+
That is match in a nutshell.
+
So, what is the interplay between this construct and Rust's approach to
+ownership and safety in general?
+
Exhaustive case analysis
+
+...when you have eliminated all which is impossible,
+then whatever remains, however improbable, must be the truth.
+-- Sherlock Holmes (Arthur Conan Doyle, "The Blanched Soldier")
+
+
One useful way to tackle a complex problem is to break it down
+into individual cases and analyze each case individually.
+For this method of problem solving to work, the breakdown must be
+collectively exhaustive; all of the cases you identified must
+actually cover all possible scenarios.
+
Using enum and match in Rust can aid this process, because
+match enforces exhaustive case analysis:
+Every possible input value for a match must be covered by the pattern
+in a least one arm in the match.
+
This helps catch bugs in program logic and ensures that the value of a
+match expression is well-defined.
+
So, for example, the following code is rejected at compile-time.
+
fn suggest_guess_broken(prior_guess: u32, answer: Answer) {
+ let next_guess = match answer {
+ Answer::Higher => prior_guess + 10,
+ Answer::Lower => prior_guess - 1,
+ // ERROR: non-exhaustive patterns: `Bingo` not covered
+ };
+ println!("maybe try {} next", next_guess);
+}
+
+
Many other languages offer a pattern matching construct (ML and
+various macro-based match implementations in Scheme both come to
+mind), but not all of them have this restriction.
+
Rust has this restriction for these reasons:
+
+-
+
First, as noted above, dividing a problem into cases only yields a
+general solution if the cases are exhaustive. Exhaustiveness-checking
+exposes logical errors.
+
+-
+
Second, exhaustiveness-checking can act as a refactoring aid. During
+the development process, I often add new variants for a particular
+enum definition. The exhaustiveness-check helps points out all of
+the match expressions where I only wrote the cases from the prior
+version of the enum type.
+
+-
+
Third, since match is an expression form, exhaustiveness ensures
+that such expressions always either evaluate to a value of the correct type,
+or jump elsewhere in the program.
+
+
+
Jumping out of a match
+
The following code is a fixed version of the suggest_guess_broken
+function we saw above; it directly illustrates "jumping elsewhere":
+
fn suggest_guess_fixed(prior_guess: u32, answer: Answer) {
+ let next_guess = match answer {
+ Answer::Higher => prior_guess + 10,
+ Answer::Lower => prior_guess - 1,
+ Answer::Bingo => {
+ println!("we won with {}!", prior_guess);
+ return;
+ }
+ };
+ println!("maybe try {} next", next_guess);
+}
+
+#[test]
+fn demo_guess_fixed() {
+ suggest_guess_fixed(10, Answer::Higher);
+ suggest_guess_fixed(20, Answer::Lower);
+ suggest_guess_fixed(19, Answer::Bingo);
+}
+
+
The suggest_guess_fixed function illustrates that match can handle
+some cases early (and then immediately return from the function),
+while computing whatever values are needed from the remaining cases
+and letting them fall through to the remainder of the function
+body.
+
We can add such special case handling via match without fear
+of overlooking a case, because match will force the case
+analysis to be exhaustive.
+
Algebraic Data Types and Structural Invariants
+
Algebraic data types succinctly describe classes of data and allow one
+to encode rich structural invariants. Rust uses enum and struct
+definitions for this purpose.
+
An enum type allows one to define mutually-exclusive classes of
+values. The examples shown above used enum for simple symbolic tags,
+but in Rust, enums can define much richer classes of data.
+
For example, a binary tree is either a leaf, or an internal node with
+references to two child trees. Here is one way to encode a tree of
+integers in Rust:
+
enum BinaryTree {
+ Leaf(i32),
+ Node(Box<BinaryTree>, i32, Box<BinaryTree>)
+}
+
+
(The Box<V> type describes an owning reference to a heap-allocated
+instance of V; if you own a Box<V>, then you also own the V it
+contains, and can mutate it, lend out references to it, et cetera.
+When you finish with the box and let it fall out of scope, it will
+automatically clean up the resources associated with the
+heap-allocated V.)
+
The above enum definition ensures that if we are given a BinaryTree, it
+will always fall into one of the above two cases. One will never
+encounter a BinaryTree::Node that does not have a left-hand child.
+There is no need to check for null.
+
One does need to check whether a given BinaryTree is a Leaf or
+is a Node, but the compiler statically ensures such checks are done:
+you cannot accidentally interpret the data of a Leaf as if it were a
+Node, nor vice versa.
+
Here is a function that sums all of the integers in a tree
+using match.
+
fn tree_weight_v1(t: BinaryTree) -> i32 {
+ match t {
+ BinaryTree::Leaf(payload) => payload,
+ BinaryTree::Node(left, payload, right) => {
+ tree_weight_v1(*left) + payload + tree_weight_v1(*right)
+ }
+ }
+}
+
+/// Returns tree that Looks like:
+///
+/// +----(4)---+
+/// | |
+/// +-(2)-+ [5]
+/// | |
+/// [1] [3]
+///
+fn sample_tree() -> BinaryTree {
+ let l1 = Box::new(BinaryTree::Leaf(1));
+ let l3 = Box::new(BinaryTree::Leaf(3));
+ let n2 = Box::new(BinaryTree::Node(l1, 2, l3));
+ let l5 = Box::new(BinaryTree::Leaf(5));
+
+ BinaryTree::Node(n2, 4, l5)
+}
+
+#[test]
+fn tree_demo_1() {
+ let tree = sample_tree();
+ assert_eq!(tree_weight_v1(tree), (1 + 2 + 3) + 4 + 5);
+}
+
+
Algebraic data types establish structural invariants that are strictly
+enforced by the language. (Even richer representation invariants can
+be maintained via the use of modules and privacy; but let us not
+digress from the topic at hand.)
+
Both expression- and statement-oriented
+
Unlike many languages that offer pattern matching, Rust embraces
+both statement- and expression-oriented programming.
+
Many functional languages that offer pattern matching encourage one to
+write in an "expression-oriented style", where the focus is always on
+the values returned by evaluating combinations of expressions, and
+side-effects are discouraged. This style contrasts with imperative
+languages, which encourage a statement-oriented style that focuses on
+sequences of commands executed solely for their side-effects.
+
Rust excels in supporting both styles.
+
Consider writing a function which maps a non-negative integer to a
+string rendering it as an ordinal ("1st", "2nd", "3rd", ...).
+
The following code uses range patterns to simplify things, but also,
+it is written in a style similar to a switch in a statement-oriented
+language like C (or C++, Java, et cetera), where the arms of the
+match are executed for their side-effect alone:
+
fn num_to_ordinal(x: u32) -> String {
+ let suffix;
+ match (x % 10, x % 100) {
+ (1, 1) | (1, 21...91) => {
+ suffix = "st";
+ }
+ (2, 2) | (2, 22...92) => {
+ suffix = "nd";
+ }
+ (3, 3) | (3, 23...93) => {
+ suffix = "rd";
+ }
+ _ => {
+ suffix = "th";
+ }
+ }
+ return format!("{}{}", x, suffix);
+}
+
+#[test]
+fn test_num_to_ordinal() {
+ assert_eq!(num_to_ordinal( 0), "0th");
+ assert_eq!(num_to_ordinal( 1), "1st");
+ assert_eq!(num_to_ordinal( 12), "12th");
+ assert_eq!(num_to_ordinal( 22), "22nd");
+ assert_eq!(num_to_ordinal( 43), "43rd");
+ assert_eq!(num_to_ordinal( 67), "67th");
+ assert_eq!(num_to_ordinal(1901), "1901st");
+}
+
+
The Rust compiler accepts the above program. This is notable because
+its static analyses ensure both:
+
+-
+
suffix is always initialized before we run the format! at the end
+of the function, and
+
+-
+
suffix is assigned at most once during the function's execution (because if
+we could assign suffix multiple times, the compiler would force us
+to mark suffix as mutable).
+
+
+
To be clear, the above program certainly can be written in an
+expression-oriented style in Rust; for example, like so:
+
fn num_to_ordinal_expr(x: u32) -> String {
+ format!("{}{}", x, match (x % 10, x % 100) {
+ (1, 1) | (1, 21...91) => "st",
+ (2, 2) | (2, 22...92) => "nd",
+ (3, 3) | (3, 23...93) => "rd",
+ _ => "th"
+ })
+}
+
+
Sometimes expression-oriented style can yield very succinct code;
+other times the style requires contortions that can be
+avoided by writing in a statement-oriented style.
+(The ability to return from one match arm in the
+suggest_guess_fixed function earlier was an example of this.)
+
Each of the styles has its use cases. Crucially, switching to a
+statement-oriented style in Rust does not sacrifice every other
+feature that Rust provides, such as the guarantee that a non-mut
+binding is assigned at most once.
+
An important case where this arises is when one wants to
+initialize some state and then borrow from it, but only on
+some control-flow branches.
+
fn sometimes_initialize(input: i32) {
+ let string: String; // a dynamically-constructed string value
+ let borrowed: &str; // a reference to string data
+ match input {
+ 0...100 => {
+ // Construct a String on the fly...
+ string = format!("input prints as {}", input);
+ // ... and then borrow from inside it.
+ borrowed = &string[6..];
+ }
+ _ => {
+ // String literals are *already* borrowed references
+ borrowed = "expected between 0 and 100";
+ }
+ }
+ println!("borrowed: {}", borrowed);
+
+ // Below would cause compile-time error if uncommented...
+
+ // println!("string: {}", string);
+
+ // ...namely: error: use of possibly uninitialized variable: `string`
+}
+
+#[test]
+fn demo_sometimes_initialize() {
+ sometimes_initialize(23); // this invocation will initialize `string`
+ sometimes_initialize(123); // this one will not
+}
+
+
The interesting thing about the above code is that after the match,
+we are not allowed to directly access string, because the compiler
+requires that the variable be initialized on every path through the
+program before it can be accessed.
+At the same time, we can, via borrowed, access data that
+may held within string, because a reference to that data is held by the
+borrowed variable when we go through the first match arm, and we
+ensure borrowed itself is initialized on every execution path
+through the program that reaches the println! that uses borrowed.
+
(The compiler ensures that no outstanding borrows of the
+string data could possibly outlive string itself, and the
+generated code ensures that at the end of the scope of string, its
+data is deallocated if it was previously initialized.)
+
In short, for soundness, the Rust language ensures that data is always
+initialized before it is referenced, but the designers have strived to
+avoid requiring artificial coding patterns adopted solely to placate
+Rust's static analyses (such as requiring one to initialize string
+above with some dummy data, or requiring an expression-oriented style).
+
Matching without moving
+
Matching an input can borrow input substructure, without taking
+ownership; this is crucial for matching a reference (e.g. a value of
+type &T).
+
The "Algebraic Data Types" section above described a tree datatype, and
+showed a program that computed the sum of the integers in a tree
+instance.
+
That version of tree_weight has one big downside, however: it takes
+its input tree by value. Once you pass a tree to tree_weight_v1, that
+tree is gone (as in, deallocated).
+
#[test]
+fn tree_demo_v1_fails() {
+ let tree = sample_tree();
+ assert_eq!(tree_weight_v1(tree), (1 + 2 + 3) + 4 + 5);
+
+ // If you uncomment this line below ...
+
+ // assert_eq!(tree_weight_v1(tree), (1 + 2 + 3) + 4 + 5);
+
+ // ... you will get: error: use of moved value: `tree`
+}
+
+
This is not a consequence, however, of using match; it is rather
+a consequence of the function signature that was chosen:
+
fn tree_weight_v1(t: BinaryTree) -> i32 { 0 }
+// ^~~~~~~~~~ this means this function takes ownership of `t`
+
+
In fact, in Rust, match is designed to work quite well without
+taking ownership. In particular, the input to match is an L-value
+expression; this means that the input expression is evaluated to a
+memory location where the value lives.
+match works by doing this evaluation and then
+inspecting the data at that memory location.
+
(If the input expression is a variable name or a field/pointer
+dereference, then the L-value is just the location of that variable or
+field/memory. If the input expression is a function call or other
+operation that generates an unnamed temporary value, then it will be
+conceptually stored in a temporary area, and that is the memory
+location that match will inspect.)
+
So, if we want a version of tree_weight that merely borrows a tree
+rather than taking ownership of it, then we will need to make use of
+this feature of Rust's match.
+
fn tree_weight_v2(t: &BinaryTree) -> i32 {
+ // ^~~~~~~~~~~ The `&` means we are *borrowing* the tree
+ match *t {
+ BinaryTree::Leaf(payload) => payload,
+ BinaryTree::Node(ref left, payload, ref right) => {
+ tree_weight_v2(left) + payload + tree_weight_v2(right)
+ }
+ }
+}
+
+#[test]
+fn tree_demo_2() {
+ let tree = sample_tree();
+ assert_eq!(tree_weight_v2(&tree), (1 + 2 + 3) + 4 + 5);
+}
+
+
The function tree_weight_v2 looks very much like tree_weight_v1.
+The only differences are: we take t as a borrowed reference (the &
+in its type), we added a dereference *t, and,
+importantly, we use ref-bindings for left and
+right in the Node case.
+
The dereference *t, interpreted as an L-value expression, is just
+extracting the memory address where the BinaryTree is represented
+(since the t: &BinaryTree is just a reference to that data in
+memory). The *t here is not making a copy of the tree, nor moving it
+to a new temporary location, because match is treating it as an
+L-value.
+
The only piece left is the ref-binding, which
+is a crucial part of how destructuring bind of
+L-values works.
+
First, let us carefully state the meaning of a non-ref binding:
+
+-
+
When matching a value of type T, an identifier pattern i will, on
+a successful match, move the value out of the original input and
+into i. Thus we can always conclude in such a case that i has type
+T (or more succinctly, "i: T").
+For some types T, known as copyable T (also pronounced "T
+implements Copy"), the value will in fact be copied into i for such
+identifier patterns. (Note that in general, an arbitrary type T is not copyable.)
+Either way, such pattern bindings do mean that the variable i has
+ownership of a value of type T.
+
+
+
Thus, the bindings of payload in tree_weight_v2 both have type
+i32; the i32 type implements Copy, so the weight is copied into
+payload in both arms.
+
Now we are ready to state what a ref-binding is:
+
+- When matching an L-value of type
T, a ref-pattern ref i
+will, on a successful match, merely borrow a reference into the
+matched data. In other words, a successful ref i match of a value of
+type T will imply that i has the type of a reference to T
+(or more succinctly, "i: &T").
+
+
Thus, in the Node arm of
+tree_weight_v2, left will be a reference to the left-hand box (which
+holds a tree), and right will likewise reference the right-hand tree.
+
We can pass these borrowed references to trees into the recursive calls to tree_weight_v2,
+as the code demonstrates.
+
Likewise, a ref mut-pattern (ref mut i) will, on a successful
+match, borrow a mutable reference into the input: i: &mut T. This allows
+mutation and ensures there are no other active references to that data
+at the same time. A destructuring
+binding form like match allows one to take mutable references to
+disjoint parts of the data simultaneously.
+
This code demonstrates this concept by incrementing all of the
+values in a given tree.
+
fn tree_grow(t: &mut BinaryTree) {
+ // ^~~~~~~~~~~~~~~ `&mut`: we have exclusive access to the tree
+ match *t {
+ BinaryTree::Leaf(ref mut payload) => *payload += 1,
+ BinaryTree::Node(ref mut left, ref mut payload, ref mut right) => {
+ tree_grow(left);
+ *payload += 1;
+ tree_grow(right);
+ }
+ }
+}
+
+#[test]
+fn tree_demo_3() {
+ let mut tree = sample_tree();
+ tree_grow(&mut tree);
+ assert_eq!(tree_weight_v2(&tree), (2 + 3 + 4) + 5 + 6);
+}
+
+
Note that the code above now binds payload by a ref mut-pattern;
+if it did not use a ref pattern, then payload would be bound to a
+local copy of the integer, while we want to modify the actual integer
+in the tree itself. Thus we need a reference to that integer.
+
Note also that the code is able to bind left and right
+simultaneously in the Node arm. The compiler knows that the two
+values cannot alias, and thus it allows both &mut-references to live
+simultaneously.
+
Conclusion
+
Rust takes the ideas of algebraic data types and pattern matching
+pioneered by the functional programming languages, and adapts them to
+imperative programming styles and Rust's own ownership and borrowing
+systems. The enum and match forms provide clean data definitions
+and expressive power, while static analysis ensures that the resulting
+programs are safe.
+
For more information
+on details that were not covered here, such as:
+
+-
+
how to say Higher instead of Answer::Higher in a pattern,
+
+-
+
defining new named constants,
+
+-
+
binding via ident @ pattern, or
+
+-
+
the potentially subtle difference between { let id = expr; ... } versus match expr { id => { ... } },
+
+
+
consult the Rust
+documentation, or quiz our awesome community (in #rust on IRC, or in
+the user group).
+
(Many thanks to those who helped review this post, especially Aaron Turon
+and Niko Matsakis, as well as
+Mutabah, proc, libfud, asQuirrel, and annodomini from #rust.)
+
+
+
+
+
+
+
+
+
+
+
+
+
+(hover for more info)
+(hover for more info)
+(hover for more info)
+(hover for more info)
+(hover for more info)
+(hover for more info)
