Rust Pattern Semantics

Analysis order

For the pattern that the question or the error names, determine:

1. The crate edition and the MSRV (rust-version in Cargo.toml). They decide which syntax compiles. See Version gates.
2. Whether the scrutinee is a place or a value expression.
3. The alternatives of each or-pattern.
4. The default binding mode at each nesting level.
5. Whether each binding is by value, ref, or ref mut, and which fields a partial move leaves initialized.
6. When the guard runs, and whether it can run more than once.
7. Where the scrutinee temporaries, the guard temporaries, and the bindings drop.

Do not propose a clone, a wildcard arm, or a ref keyword before this pass. Each one can compile and change what the code moves, borrows, or matches.

Version gates

Do not add a #![feature] gate for an E0658 from this table. Raise rust-version, or use the fallback: a nested if let, or assert!(matches!(..)). The rust-compiler-errors skill, when it is installed, lists the other compile-error repair hazards.

A let chain inside a match guard compiles on edition 2021 (measured on rustc 1.98.1). A chain in an if or while condition does not.

Verify

std::assert_matches! is not in the prelude. Call it by path, or import it with use std::assert_matches;. use std::assert_matches::assert_matches; fails with E0432.

Triage

Binding modes

A non-reference pattern binds by value. When a non-reference pattern matches a reference, match ergonomics switches the default binding mode to ref or ref mut, and the inner bindings borrow:

fn shared(_: &String) {}
fn mutable(_: &mut String) {}

let mut value = Some(String::from("x"));
if let Some(text) = &value { shared(text); }
if let Some(text) = &mut value { mutable(text); }

A function argument coerces &mut T to &T, so shared(text) proves only that text is some reference. To see the exact type, write let () = text;. The E0308 label says this expression has type `&String` . Remove the line after you read it.

Edition 2024 restricts explicit mut, ref, ref mut, and & inside a pattern that borrows implicitly. See Edition 2024 match ergonomics.

Partial moves

A pattern can move one field and borrow another. The original value then cannot be used as a whole, but fields that were not moved remain usable.

struct Record {
    name: String,
    count: u32,
}

fn main() {
    let record = Record { name: String::from("job"), count: 3 };
    let Record { name, ref count } = record;
    assert_eq!(name, "job");
    assert_eq!(*count, 3);
    assert_eq!(record.count, 3);
}

A type with a Drop implementation cannot be partially moved because drop must receive the whole value:

struct Resource { name: String }
impl Drop for Resource { fn drop(&mut self) {} }

fn main() {
    let resource = Resource { name: String::from("owned") };
    let Resource { name } = resource;
    println!("{name}");
}

Use Option::take, mem::replace, or an explicit consuming method when a resource owner must release one field before its destructor.

Match guards

A guard runs after the pattern matches and before the arm body. The bindings are shared borrows while the guard runs. A by-value binding moves or copies only after the guard succeeds.

A guard on an or-pattern can run more than once

The guard applies to the complete or-pattern. It runs once for each alternative that matches until one succeeds. Do not put metrics, mutation, I/O, or one-shot work in it.

fn main() {
    let mut calls = 0;
    match 1 {
        1 | 1 if {
            calls += 1;
            false
        } => unreachable!(),
        1 => {}
        _ => unreachable!(),
    }
    assert_eq!(calls, 2);
}

If a guard needs expensive or stateful work, match first and run ordinary control flow in the arm.

Guard mutation

The example above mutates calls, a local that the pattern does not bind. That is legal. rustc rejects two other mutations:

• Assigning to or mutably borrowing the scrutinee gives E0510 (cannot assign ... in match guard, cannot mutably borrow ... in match guard).
• Assignment through a pattern binding gives E0594. A &mut method call through it, such as v.push(2), gives E0596. Both carry the note "variables bound in patterns are immutable until the end of the pattern guard". This applies to ref mut bindings too.

fn main() {
    let mut slot = Some(1);
    match slot {
        Some(_) if { slot = None; false } => {}
        _ => {}
    }
}

fn main() {
    let mut slot = Some(1);
    match slot {
        Some(ref mut n) if { *n += 1; false } => {}
        _ => {}
    }
}

Move the mutation into the arm body, or compute a boolean before the match. When rustc rejects a guard, keep the exact pattern in the probe. A rewrite into an if proves a different program.

Temporaries: scrutinee, if let guard, boolean guard

The three positions drop temporaries at different points. A lock() in the wrong position holds the lock through the arm body:

use std::sync::Mutex;

fn main() {
    let state = Mutex::new(Some(1));

    match *state.lock().unwrap() {
        Some(_) => assert!(state.try_lock().is_err()),
        None => unreachable!(),
    }

    match 0 {
        _ if let Some(_) = *state.lock().unwrap() => assert!(state.try_lock().is_err()),
        _ => unreachable!(),
    }

    match 0 {
        _ if state.lock().unwrap().is_some() => assert!(state.try_lock().is_ok()),
        _ => unreachable!(),
    }
}

To release the lock before the arm body, copy or clone the value out before the match (let v = state.lock().expect("state mutex poisoned").clone();), or bind the guard inside a braced block that returns an owned value. Do not bind the guard itself to a local in the same block: it then lives to the end of the block.

An arm with any guard does not count toward exhaustiveness. This includes an if let guard whose pattern cannot fail. rustc still reports E0004 for the value that the guard covers.

Scrutinee place versus value

Matching a place inspects existing storage. Matching a value expression creates a temporary. The match scrutinee is not a temporary scope, so that temporary lives until the end of the enclosing temporary scope. That is usually the statement. For a match that is a block tail on edition 2024, it is right after the tail expression.

Do not change a scrutinee between a place and a value (a named guard versus an inline lock()), and do not rewrite match into if let or the reverse, without checking destructor and borrow timing. The rust-borrow-semantics skill, when it is installed, has the full temporary-scope analysis.

Or-patterns

Every alternative must bind the same names with the same types and binding modes. Prefer one arm per case when alternatives need different guards or side effects. Use an or-pattern when the alternatives have the same binding contract and the same body.

Match exhaustiveness is a behavior decision

Do not add _ => {} only to satisfy rustc. A new variant then takes the wildcard path silently. For a closed enum this crate owns, list every variant. The rust-discipline skill, when it is installed, holds the exhaustiveness policy and the wildcard_enum_match_arm lint.

Edition 2024 match ergonomics

Edition 2024 adds two rules:

• A mut, ref, or ref mut modifier on a binding is an error when the default binding mode is ref or ref mut.
• A reference pattern (& or &mut) can match only while the default binding mode is move.

The errors have no error code. Do not invent one for a probe.

In edition 2021, mut on a binding resets the default binding mode to move. Some(mut n) on &Option<u32> compiles there and makes n a u32 copy, not a &u32. On &Option<String> it fails with E0507.

To migrate:

1. List the affected patterns with cargo clippy --locked --all-targets --all-features -- -W rust_2024_incompatible_pat. Use --all-features only when the features are additive. Otherwise run it once per supported feature set. Repeat it once per shipping --target <triple>, as the cargo-workflows skill describes when it is installed.
2. cargo fix --edition applies this lint, which is part of rust-2024-compatibility. It rewrites each pattern to a fully explicit form with the same meaning in every edition.
3. Review each rewrite. The explicit form keeps the 2021 meaning, including a silent copy. Decide per site whether a borrow was intended.

Do not copy a pattern from an edition 2021 example into an edition 2024 crate without compiling it in the target crate.

Related skills

Each applies when it is installed.