Skip to content

po4yka/rust-skills / skills/rust-pattern-semantics

rust-pattern-semantics

Verified

Use when a Rust pattern, match guard, or if let guard decides what moves, borrows, or drops, or when an edition 2024 pattern or let chain fails to compile. Triggers on partial move, binding mode, match ergonomics, ref pattern, let chains, implicitly-borrowing pattern, guard runs twice, E0510, E0594, or E0596 in a guard.

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

FeatureNeeds
Let chains in if and while (if let A = a && cond)Edition 2024 and rustc 1.88+
if let guards, and a let chain inside a guard (if let P = e && cond)rustc 1.95+, every edition
std::assert_matches!rustc 1.96+
Match ergonomics reservationsEdition 2024

Read references/edition-2024-patterns.md when an error from one of these gates appears: it has the exact message for each toolchain.

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 lists other repair hazards.

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

Verify

ClaimCheckWhat a pass does not prove
Binding type or modelet () = binding; and read the E0308 label; or a typed call as in Binding modesDrop timing or guard repetition
Guard count, drop point, lock holdA #[test] or a doctest (it runs by default) that asserts on a counter or on Mutex::try_lock, built with the crate's editionBehavior on another edition
Pattern shape in a teststd::assert_matches!(value, Some(n) if n > 2); on MSRV 1.96+; else assert!(matches!(..))Fields that the pattern does not name
A pattern must not compileA compile_fail doctest that holds only the probe code: compile_fail,E0xxx when rustc prints a code (E0004, E0509, E0510, E0594, E0596), a bare compile_fail for the uncoded edition 2024 errors. To prove the code on stable, run cargo check --message-format=short on the probe and find error[E0xxx], or use a trybuild case, which compares the full stderrThe reason for the failure. Stable rustdoc accepts any compile error and ignores a named code; only nightly rustdoc checks it
Syntax builds on the MSRVcargo +<msrv> check --locked for a let chain, an if let guard, or assert_matches!Behavior, and code behind other features or targets

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

SymptomLikely causeFirst action
Value is partly usable after destructuringThe pattern made a partial moveList moved and initialized fields
Partial move fails only after adding Drop (E0509)The destructor needs the whole valueMove Drop to a one-field guard, or mem::take the field. See Partial moves
Guard side effect occurs twiceOverlapping or-pattern alternatives both matchedRemove the side effect or split the arms
E0510, or E0594/E0596 with "immutable for the pattern guard"The guard mutates or mutably borrows the scrutinee or a pattern bindingMove the mutation into the arm body. A signature change does not help
Lock or borrow stays held inside the armThe lock is in the match scrutinee or an if let guardCopy the value out first. See Guard temporaries
Binding became &T after a refactorMatch ergonomics changed the default binding modeProbe the binding type in the target edition
... within an implicitly-borrowing patternEdition 2024 reservationApply the fix from the edition 2024 table
let chains are only allowed in Rust 2024 or laterLet chain in an edition 2021 if or whileNest the if let and repeat the else branch at each level, or migrate to edition 2024 with MSRV 1.88+ (the cargo-workflows skill)
E0658 on a let chain, an if let guard, or assert_matches!The toolchain is older than the version gateRaise rust-version or use the fallback. Do not add #![feature]
Wildcard fixes exhaustiveness but tests failThe missing variant needed a semantic policyAdd an explicit arm and behavior test

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}");
}

A consuming method fails the same way: fn into_name(self) -> String { self.name } is E0509 on this type. Take the field out instead: fn into_name(mut self) -> String { mem::take(&mut self.name) }, or Option::take or mem::replace from &mut self. The rust-discipline skill, when it is installed, owns the guard design that avoids E0509: put impl Drop on a one-field guard type, not on the aggregate.

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. Read references/guard-probes.md when you need a runnable proof of the guard count, a guard mutation error, or a guard lock hold.

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

Guard mutation

A guard can mutate a local that the pattern does not bind. 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.

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.

Guard temporaries

An if let guard keeps its scrutinee temporaries until the arm body ends, or drops them before the next arm when the guard fails. A boolean guard (if cond) drops them as soon as the condition is evaluated. A lock() in an if let guard therefore holds the lock through the arm body.

Copy the value out before the match to release the lock first.

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.

ScrutineeOwnership question
match localWhich fields move from or borrow the local?
match &localWhich bindings inherit a reference binding mode?
match make()Does the temporary hold a lock or borrow through the arms?
match *pointerIs the dereference a safe place, and what can move from it?

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, owns when each scrutinee temporary drops, on each edition.

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 rejects a mut, ref, or ref mut modifier on a binding while the default binding mode is ref or ref mut, and a & or &mut pattern unless the default binding mode is move. The errors have no error code; do not invent one for a probe. Read references/edition-2024-patterns.md when a ... within an implicitly-borrowing pattern error appears, or before you migrate a crate: it has the message-to-fix table, the edition 2021 meaning of mut, and the rust_2024_incompatible_pat migration steps.

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

Related skills

When installed: rust-borrow-semantics owns temporary scopes and two-phase borrows, rust-compiler-errors owns general E0382, E0507, and E0499 triage, and rust-callback-bounds owns closure patterns and higher-ranked callback bounds.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall