Pattern matching

What it is and why it exists

A Rust pattern describes the structure a value must have and may create bindings for data inside that structure. Patterns can match enum variants, struct fields, tuples, slices, literals, and ranges; they aren’t merely switch labels that compare one scalar.

match compares one subject with its arms from top to bottom and executes only the first successful arm. The compiler requires every possible value to go somewhere and warns about arms that can never be reached, so adding an enum variant immediately exposes omissions wherever variants are listed explicitly.

A pattern combines checking and extraction. Some(order) proves that an Option isn’t None and binds its inner value as order; there’s no separate state query followed by an extraction that might fail.

You encounter patterns in match arms, let, function parameters, for, if let, while let, let-else, and matches!. They share one pattern language but permit failure in different ways, so they aren’t interchangeable based only on code length. Macro-generated patterns, heavily nested patterns, and API-evolution strategies belong in rust/pattern-matching-advanced and aren’t repeated here.

How it works

Arm selection and exhaustiveness

match subject { pattern => expression, ... } evaluates subject once, then tries arms in source order. The selected arm supplies the value of the entire match expression, so all reachable arms must produce compatible result types.

Exhaustiveness checking reasons from the type and the coverage of each pattern; it doesn’t execute code to infer conditions. A Boolean has two possible values, an ordinary enum has its declared variants, and integers normally need ranges or a catch-all; an arbitrary Boolean expression in a match guard doesn’t count as static coverage.

Order changes behavior. A broad range, variable binding, or _ placed early masks more specific patterns below it, and the compiler normally points out such arms with an unreachable_patterns warning.

Destructuring and binding

A pattern can test and bind at once. Request::Read { id } first requires the Read variant, then creates the local binding id; Request::Read { id: 0 } tests the field without creating a same-named variable.

_ matches and ignores one value, while .. ignores the remaining parts of a structure or sequence. name @ subpattern requires subpattern to succeed and binds the complete matched part as name, which is useful when you need both a range check and the original value.

You can join alternatives with |, but every alternative must create the same names with the same types and binding modes. 1 | 2 | 3 creates no variable; a bare lowercase identifier normally introduces a new binding rather than referring to a same-named outer variable.

Refutability determines where a pattern fits

An irrefutable pattern matches every possible value of its type. let (x, y) = pair must succeed, so ordinary let, function parameters, and for bindings can use it directly.

A refutable pattern can fail, as with Some(value), 1..=9, or a fixed-length slice pattern. It belongs somewhere with a failure path, such as a match arm, if let, while let, or let-else; a let-else else block must leave the current path with return, break, continue, or a diverging expression.

Binding modes and ownership

Pattern bindings follow Rust’s move, copy, and borrow rules. When an owned value is matched by value, a non-Copy field moves by default and a Copy field is copied; moving only some fields creates a partial move , after which remaining fields may be used separately but the original structure can’t be used as a whole.

When the subject is borrowed, match ergonomics automatically dereferences common structural patterns and makes the bindings references. In match &job { Job { owner, .. } => ... }, owner is therefore borrowed rather than moving the String out of job.

Read the ownership choice from the subject first: match value can take its contents, match &value borrows for reading, and match &mut value borrows for mutation. ref and ref mut can still borrow individual fields explicitly, but borrowing the complete subject is usually easier to review in new code.

Guards and failure paths

A match guard is the if condition after an arm’s pattern. The guard runs only after the pattern succeeds; when it returns false, matching continues with later arms.

A guard can use bindings created by its pattern and can read outside variables. It doesn’t add its condition to the exhaustiveness proof, so an arm for Some(x) if x > 0 still needs coverage for other Some values and for None.

In A | B if condition, the guard applies to the complete A | B, not only to B. If the alternatives need different conditions, split them into separate arms so both the ordering and condition boundaries are explicit.

Examples

These four examples cover exhaustive branching, slice parsing, borrowing versus moving, and repeated matching. Every output shown below came from compiling and running the corresponding program with local rustc.

Seal the state space with an enum

The routing function handles every Request variant explicitly and returns its match expression directly. The guard on Write handles only an oversized request; the following Write arm remains responsible for every other size.

Adding Request::Delete makes this function stop compiling because the match is no longer exhaustive. Replacing the last two explicit variant arms with _ removes that reminder, which is why a wildcard can weaken evolution safety.

id: 0 is a field subpattern and doesn’t bind id. The next arm uses .. to say that the variant’s remaining fields don’t affect this decision; it also makes no promise to read fields added later.

Parse a command with slice patterns

split_first() removes empty input from the main path, and let-else makes verb and args available afterward. The match then checks the verb and the argument slice’s length as one command shape.

#![allow(dead_code)]

#[derive(Debug)]
enum Command<'a> {
    Show { id: u32 },
    Tag { id: u32, label: &'a str },
}

fn parse_command<'a>(parts: &[&'a str]) -> Result<Command<'a>, String> {
    let Some((verb, args)) = parts.split_first() else {
        return Err(String::from("empty command"));
    };

    match (*verb, args) {
        ("show", [id]) => id
            .parse::<u32>()
            .map(|id| Command::Show { id })
            .map_err(|_| String::from("invalid id")),
        ("tag", [id, label @ ("urgent" | "normal")]) => id
            .parse::<u32>()
            .map(|id| Command::Tag { id, label })
            .map_err(|_| String::from("invalid id")),
        _ => Err(String::from("unknown command")),
    }
}

fn main() {
    for parts in [
        &[][..],
        &["show", "17"][..],
        &["tag", "17", "urgent"][..],
        &["tag", "17", "later"][..],
    ] {
        println!("{:?}", parse_command(parts));
    }
}

Err("empty command")
Ok(Show { id: 17 })
Ok(Tag { id: 17, label: "urgent" })
Err("unknown command")

[id] matches exactly one argument, while [id, label] matches exactly two, so extra arguments aren’t silently ignored. label @ ("urgent" | "normal") restricts the allowed values and retains the chosen label.

The catch-all is appropriate here because input strings form an open state space and the function’s contract groups unsupported shapes into one error. That differs from a closed internal enum; whether _ is right depends on the type boundary and error policy.

Borrow for inspection, then extract by value

inspect() matches a &Job, so its field bindings are borrows. The main function still owns job afterward and can pass it to take_owner(), where destructuring by value moves the String field.

struct Job {
    owner: String,
    retries: u8,
}

fn inspect(job: &Job) {
    match job {
        Job {
            owner,
            retries: attempts @ 1..=3,
        } => println!("retry {attempts} for {owner}"),
        Job { owner, retries: 0 } => println!("first attempt for {owner}"),
        Job { owner, retries } => println!("retry {retries} for {owner}"),
    }
}

fn take_owner(job: Job) -> String {
    let Job { owner, .. } = job;
    owner
}

fn main() {
    let job = Job {
        owner: String::from("Mina"),
        retries: 2,
    };

    inspect(&job);
    println!("owner: {}", take_owner(job));
}

retry 2 for Mina
owner: Mina

attempts @ 1..=3 tests an inclusive range and retains the actual retry count. Because the subject is a shared reference, owner doesn’t move the string; that borrow ends when inspect() returns.

take_owner() consumes the complete Job, so moving owner agrees with its function contract. If the caller still needs job, the usual fix is to accept &Job or &str, not to clone the entire value merely to keep the old signature compiling.

Process consecutive successful states in a loop

while let fits a stateful operation that repeatedly returns Option or Result. This example pops one string at a time, uses let-else to skip parse failures, then classifies valid numbers with a range and guard.

fn main() {
    let mut pending = vec!["101", "bad", "42", "7"];

    while let Some(text) = pending.pop() {
        let Ok(value) = text.parse::<i32>() else {
            println!("skip: {text}");
            continue;
        };

        match value {
            even @ 0..=100 if even % 2 == 0 => println!("even: {even}"),
            odd @ 0..=100 => println!("odd: {odd}"),
            outside => println!("outside: {outside}"),
        }
    }

    println!("empty: {}", pending.is_empty());
}

odd: 7
even: 42
skip: bad
outside: 101
empty: true

The vector is last-in, first-out, so output begins with "7". The parse failure uses continue to satisfy the requirement that let-else leave the current path; whether invalid input should be skipped is a caller contract decision.

The first arm’s guard selects only even values, so the second range arm must still catch odd values in the interval. Removing the second arm doesn’t make the first guard stand for all of 0..=100, and the compiler doesn’t include an arbitrary % condition in its coverage proof.

Pitfalls

Further reading

• Rust 1.98 Reference: patterns
• Rust 1.98 Reference: match expressions
• The Rust Programming Language: patterns and matching
• The Rust Programming Language: pattern syntax
• Rust 1.98 standard library: matches!