Patterns

We've actually used patterns a few times so far: they're used in let statements, in function parameters, and in the match expression. Patterns have a lot more abilities than we have demonstrated so far, so we'll cover some of the most commonly used ones in this section. Any of these abilities work in any place where a pattern is used.

let statements

A basic let statement has this form:

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.

Let’s try a more complex pattern. Change our example program to this:

Filename: src/main.rs

fn main() {
    let (x, y) = (5, 6);

    println!("The value of x is: {}", x);
    println!("The value of y is: {}", y);
}

And run it with cargo run:

$ cargo run
   Compiling patterns v0.1.0 (file:///projects/patterns)
     Running `target/debug/patterns`
The value of x is: 5
The value of y is: 6

We’ve created two variables with one let! Here’s our pattern:

(x, y)

And here’s the value:

(5, 6)

As you can see, the two line up visually, and so let binds the variable x to the value 5 and y to 6. We could have used two let statements as well:

fn main() {
    let x = 5;
    let y = 6;
}

In simple cases like this, two lets may be clearer, but in others, creating multiple variables at once is nice. As we become more proficient in Rust, we’ll figure out which style is better, but it’s mostly a judgment call.

Type annotations

Most of the time, Rust uses type inference, meaning that it attempts to infer the types of your variables rather than you having to declare them explicitly even though Rust is a statically typed language. Occasionally, Rust won't have enough information to infer the type of your value, and you will need to add a type annotation in with the pattern.

Here’s what a let statement with a type annotation looks like:

let x: i32 = 5;

We can add a colon, followed by the type name. Here’s the structure of a let statement with a type annotation:

let PATTERN: TYPE = VALUE;

Note that the colon and the TYPE go after the PATTERN, not in the pattern itself. As an example, here’s our more complex pattern with two variables:

let (x, y): (i32, i32) = (5, 6);

Just like we match up the VALUE with the PATTERN, we match up the TYPE with the PATTERN.

Literals & _

You can match against literals directly, and _ acts as an ‘any’ case:

let x = 1;

match x {
    1 => println!("one"),
    2 => println!("two"),
    3 => println!("three"),
    _ => println!("anything"),
}

This prints one.

Multiple patterns

You can match multiple patterns with |:

let x = 1;

match x {
    1 | 2 => println!("one or two"),
    3 => println!("three"),
    _ => println!("anything"),
}

This prints one or two.

ref and ref mut

Usually, when you match against a pattern, variables are bound to a value. This means you'll end up moving the value into the match:

let name = Some(String::from("Bors"));

match name {
    Some(name) => println!("Found a name: {}", name),
    None => (),
}

// name is moved here. This line will fail to compile:
println!("name is: {:?}", name);

If you'd prefer to bind name to a reference, use the ref keyword:

let name = Some(String::from("Bors"));

match name {
    Some(ref name) => println!("Found a name: {}", name),
    None => (),
}

// name is not moved here; the match only took a reference to its data rather
// than moving it. This will work:
println!("name is: {:?}", name);

And for a mutable reference, ref mut:

let mut name = Some(String::from("Bors"));

match name {
    Some(ref mut name) => *name = String::from("Another name"),
    None => (),
}

// name is not moved here; the match only took a reference to its data rather
// than moving it
println!("name is: {:?}", name);

Destructuring

Patterns can be used to destructure structs and enums:

struct Point {
    x: i32,
    y: i32,
}

let origin = Point { x: 0, y: 0 };

let Point { x, y } = origin;

This brings x and y variables into scope, matching the x and y of origin. While it can be unusual in let, this is the same principle of patterns in match:

struct Point {
    x: i32,
    y: i32,
}

let origin = Point { x: 0, y: 0 };

match origin {
    Point { x, y } => { }, // variables x and y are created here
}

Shadowing

As with all variables, those declared by a pattern will shadow variables outside of the match construct:

let x = Some(5);

match x {
    Some(x) => { }, // x is an i32 here, not an Option<i32>
    None => (),
}

Ignoring values

We discussed using _ as a whole pattern to ignore it above, but you can also use _ inside of another pattern to ignore just part of it:

let x = Some(5);

match x {
    Some(_) => println!("got a Some and I don't care what's inside"),
    None => (),
}

Or like this:

let numbers = (2, 4, 8, 16, 32);

match numbers {
    (first, _, third, _, fifth) => println!("Some numbers: {}, {}, {}", first, third, fifth),
}

If you want, you can use .. to ignore all of the parts you haven't defined:

struct Point {
    x: i32,
    y: i32,
    z: i32,
}

let origin = Point { x: 0, y: 0, z: 0 };

match origin {
    Point { x, .. } => { }, // y and z are ignored
}

Ranges

You can match a range of values with ...:

let x = 5;

match x {
    1 ... 5 => println!("one through five"),
    _ => println!("something else"),
}

Ranges are usually used with integers or chars:

let x = 'c';

match x {
    'a' ... 'j' => println!("early ASCII letter"),
    'k' ... 'z' => println!("late ASCII letter"),
    _ => println!("something else"),
}

Guards

You can introduce ‘match guards’ with if:

let x = Some(5);

match x {
    Some(x) if x < 5 => println!("less than five: {}", x),
    Some(x) => println!("{}", x),
    None => (),
}

If you’re using if with multiple patterns, the if applies to both sides:

let x = 4;
let y = false;

match x {
    4 | 5 if y => println!("yes"),
    _ => println!("no"),
}

This prints no, because the if applies to the whole of 4 | 5, and not to only the 5. In other words, the precedence of if behaves like this:

(4 | 5) if y => ...

not this:

4 | (5 if y) => ...

Bindings

You can bind values to names with @: