The Rust Programming Language

Patterns pop up in a number of places in Rust. You’ve been using them a lot without realizing it! This section is a reference to all the places where patterns are valid.

As we discussed in Chapter 6, a common place patterns are used is in the arms of match expressions. Formally, match expressions are defined as the keyword match, a value to match on, and one or more match arms that consist of a pattern and an expression to run if the value matches that arm’s pattern:

match VALUE {
    PATTERN => EXPRESSION,
    PATTERN => EXPRESSION,
    PATTERN => EXPRESSION,
}

match expressions are required to be exhaustive. When we put all of the patterns in the arms together, all possibilities for the value in the match expression must be accounted for. One way to ensure you have every possibility covered is to have a catch-all pattern for the last arm, like a variable name. A name matching any value can never fail and thus covers every case remaining after the previous arms’ patterns.

There’s an additional pattern that’s often used in the last match arm: _. It matches anything, but it never binds any variables. This can be useful when you only want to run code for some patterns but ignore any other value, for example.

We discussed if let expressions in Chapter 6, and how they’re mostly a shorter way to write the equivalent of a match that only cares about matching one case. if let can optionally have a corresponding else with code to run if the pattern in the if let doesn’t match.

Listing 18-1 shows that it’s even possible to mix and match if let, else if, and else if let. This code shows a series of checks of a bunch of different conditions to decide what the background color should be. For the purposes of the example, we’ve created variables with hardcoded values that a real program might get by asking the user. If the user has specified a favorite color, we’ll use that as the background color. If today is Tuesday, the background color will be green. If the user has specified their age as a string and we can parse it as a number successfully, we’ll use either purple or orange depending on the value of the parsed number. Finally, if none of these conditions apply, the background color will be blue:

Filename: src/main.rs

fn main() {
    let favorite_color: Option<&str> = None;
    let is_tuesday = false;
    let age: Result<u8, _> = "34".parse();

    if let Some(color) = favorite_color {
        println!("Using your favorite color, {}, as the background", color);
    } else if is_tuesday {
        println!("Tuesday is green day!");
    } else if let Ok(age) = age {
        if age > 30 {
            println!("Using purple as the background color");
        } else {
            println!("Using orange as the background color");
        }
    } else {
        println!("Using blue as the background color");
    }
}

Listing 18-1: Mixing if let, else if, else if let, and else

This conditional structure lets us support complex requirements. With the hardcoded values we have here, this example will print Using purple as the background color.

Note that if let can also introduce shadowed variables like match arms can: if let Ok(age) = age introduces a new shadowed age variable that contains the value inside the Ok variant. This also means the if age > 30 condition needs to go within the block; we aren’t able to combine these two conditions into if let Ok(age) = age && age > 30 since the shadowed age that we want to compare to 30 isn’t valid until the new scope starts with the curly brace.

Also note that conditionals with many cases like these are not as powerful as match expression since exhaustiveness is not checked by the compiler. If we leave off the last else block and miss handling some cases, the compiler will not error. This example might be too complex to rewrite as a readable match, so we should take extra care to check that we’re handling all the cases since the compiler is not checking exhaustiveness for us.

A similar construction to if let is while let: this allows you to do a while loop as long as a pattern continues to match. Listing 18-2 shows an example using a while let loop to use a vector as a stack and print out the values in the vector in the opposite order that we pushed the values in:

# #![allow(unused_variables)]
#fn main() {
let mut stack = Vec::new();

stack.push(1);
stack.push(2);
stack.push(3);

while let Some(top) = stack.pop() {
    println!("{}", top);
}
#}

Listing 18-2: Using a while let loop to print out values as long as stack.pop() returns Some

This example will print 3, 2, then 1. The pop method takes the last element out of the vector and returns Some(value). If the vector is empty, it returns None. The while loop will continue running the code in its block as long as pop is returning Some. Once it returns None, the while loop stops. We can use while let to pop every element off our stack.

Looping with for, as we discussed in Chapter 3, is the most common loop construction in Rust code. What we didn’t talk about in that chapter was that for takes a pattern. In Listing 18-3, we’re demonstrating how we can use a pattern in a for loop to destructure a tuple. The enumerate method adapts an iterator to produce a value and the index of the value in the iterator in a tuple:

# #![allow(unused_variables)]
#fn main() {
let v = vec![1, 2, 3];

for (index, value) in v.iter().enumerate() {
    println!("{} is at index {}", value, index);
}
#}

Listing 18-3: Using a pattern in a for loop to destructure the tuple returned from enumerate into its pieces

This will print:

1 is at index 0
2 is at index 1
3 is at index 2

The first call to enumerate produces the tuple (0, 1). When this value is matched to the pattern (index, value), index will be 0 and value will be 1.

match and if let are the places we’ve explicitly discussed using patterns earlier in the book, but they aren’t the only places we’ve used patterns. For example, consider this straightforward variable assignment with let:

# #![allow(unused_variables)]
#fn main() {
let x = 5;
#}

We’ve done this hundreds of times throughout this book. You may not have realized it, but you were using patterns! A let statement looks like this, more formally:

let PATTERN = EXPRESSION;

We’ve seen statements like let x = 5; with a variable name in the PATTERN slot; a variable name is just a particularly humble form of pattern.

With let, we compare the expression against the pattern, and assign any names we find. So for example, in our let x = 5; case, x is a pattern that says “bind what matches here to the variable x.” And since the name x is the whole pattern, this pattern effectively means “bind everything to the variable x, whatever the value is.”

To see the pattern matching aspect of let a bit more clearly, consider Listing 18-4 where we’re using a pattern with let to destructuring a tuple:

# #![allow(unused_variables)]
#fn main() {
let (x, y, z) = (1, 2, 3);
#}

Listing 18-4: Using a pattern to destructure a tuple and create 3 variables at once

Here, we have a tuple that we’re matching against a pattern. Rust will compare the value (1, 2, 3) to the pattern (x, y, z) and see that the value matches the pattern. In this case, it will bind 1 to x, 2 to y, and 3 to z. You can think of this tuple pattern as nesting three individual variable patterns inside of it.

We saw another example of destructuring a tuple in Chapter 16, Listing 16-6, where we destructured the return value of mpsc::channel() into the tx (transmitter) and rx (receiver) parts.

Similarly to let, function parameters can also be patterns. The code in Listing 18-5 declaring a function named foo that takes one parameter named x of type i32 should look familiar:

# #![allow(unused_variables)]
#fn main() {
fn foo(x: i32) {
    // code goes here
}
#}

Listing 18-5: A function signature uses patterns in the parameters

The x part is a pattern! In a similar way as we did with let, we could match a tuple in a function’s arguments. Listing 18-6 shows how we could split apart the values in a tuple as part of passing the tuple to a function:

Filename: src/main.rs

fn print_coordinates(&(x, y): &(i32, i32)) {
    println!("Current location: ({}, {})", x, y);
}

fn main() {
    let point = (3, 5);
    print_coordinates(&point);
}

Listing 18-6: A function with parameters that destructure a tuple

This will print Current location: (3, 5). When we pass the value &(3, 5) to print_coordinates, the values match the pattern &(x, y). x gets the value 3, and y gets the value 5.

Because closures are similar to functions, as we discussed in Chapter 13, we can use patterns in closure parameter lists as well.

One difference between the places we can use patterns is that with for loops, let, and in function parameters, the patterns must be irrefutable. Let’s discuss that next.