Pattern Syntax in Rust

Patterns are one of Rust’s most powerful features, providing a way to express complex logic for matching and destructuring data. They are used in match statements, if let expressions, let bindings, and function parameters. This guide serves as a reference to the various syntaxes you can use to construct patterns.

1. Matching Literals

The simplest pattern is a literal value. This allows you to match against fixed values like numbers, characters, and string literals.

fn match_literal(x: i32) {
    match x {
        1 => println!("one"),
        2 => println!("two"),
        _ => println!("something else"),
    }
}

2. Matching Named Variables

A pattern that consists of a variable name will match any value, binding that value to the variable name for use in the match arm’s expression.

let x = Some(5);
let y = 10;

match x {
    Some(50) => println!("Got 50"),
    // `y` here is a new variable that shadows the outer `y`. It will match any value inside `Some`.
    Some(y) => println!("Matched, y = {:?}", y),
    _ => println!("Default case, x = {:?}", x),
}

println!("at the end: x = {:?}, y = {:?}", x, y); // Outer y is still 10.

3. Multiple Patterns with `|`

You can match against multiple patterns in a single arm using the | (or) operator.

let x = 1;

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

4. Matching Ranges with `..=`

You can match against an inclusive range of values using the ..= syntax. This is only allowed for char and numeric values.

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

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

5. Destructuring

Patterns can be used to dismantle structs, enums, tuples, and references to access their inner values.

Destructuring Structs

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

let p = Point { x: 0, y: 7 };

// Destructure and rename variables
let Point { x: a, y: b } = p;
println!("a = {}, b = {}", a, b);

// Destructure with shorthand
match p {
    Point { x, y: 0 } => println!("On the x axis at {}", x),
    Point { x: 0, y } => println!("On the y axis at {}", y),
    Point { x, y } => println!("On neither axis: ({}, {})", x, y),
}

Destructuring Enums

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
}

let msg = Message::Move { x: 3, y: 4 };

match msg {
    Message::Quit => println!("Quit"),
    Message::Move { x, y } => println!("Move to ({}, {})", x, y),
    Message::Write(s) => println!("Write: {}", s),
}

6. Ignoring Values in a Pattern

Sometimes you need to ignore parts of a value.

_ ignores a single value.
.. ignores all remaining values in a struct, tuple, or slice.

// Ignoring with _
let numbers = (2, 4, 8, 16, 32);
match numbers {
    (first, _, third, _, fifth) => {
        println!("Some numbers: {}, {}, {}", first, third, fifth);
    }
}

// Ignoring with ..
struct Point3D { x: i32, y: i32, z: i32 }
let point = Point3D { x: 10, y: 5, z: -2 };
match point {
    Point3D { x, .. } => println!("x is {}", x),
}

match numbers {
    (first, .., last) => {
        println!("The first number is {} and the last is {}", first, last);
    }
}

7. Match Guards with `if`

A match guard is an additional if condition that can be placed after a pattern in a match arm. This allows for more complex filtering.

let num = Some(4);

match num {
    Some(x) if x % 2 == 0 => println!("The number {} is even", x),
    Some(x) => println!("The number {} is odd", x),
    None => (),
}

8. `@` Bindings

The @ operator lets you create a variable that holds a value while simultaneously testing that value against a pattern.

enum Message {
    Hello { id: i32 },
}

let msg = Message::Hello { id: 5 };

match msg {
    Message::Hello {
        // Bind the value of `id` to `id_variable` while also testing
        // that it falls within the range 3..=7.
        id: id_variable @ 3..=7,
    } => {
        println!("Found an id in range: {}", id_variable);
    }
    Message::Hello { id: 10..=12 } => {
        println!("Found an id in another range");
    }
    Message::Hello { id } => {
        println!("Found some other id: {}", id);
    }
}

By combining these syntactical elements, you can create highly expressive and safe patterns to control your program’s logic.