po4yka/rust-skills / skills/rust-pattern-semantics
rust-pattern-semantics
VerifiedUse 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:
- The crate edition and the MSRV (
rust-versioninCargo.toml). They decide which syntax compiles. See Version gates. - Whether the scrutinee is a place or a value expression.
- The alternatives of each or-pattern.
- The default binding mode at each nesting level.
- Whether each binding is by value,
ref, orref mut, and which fields a partial move leaves initialized. - When the guard runs, and whether it can run more than once.
- 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
| Feature | Needs |
|---|---|
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 reservations | Edition 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
| Claim | Check | What a pass does not prove |
|---|---|---|
| Binding type or mode | let () = binding; and read the E0308 label; or a typed call as in Binding modes | Drop timing or guard repetition |
| Guard count, drop point, lock hold | A #[test] or a doctest (it runs by default) that asserts on a counter or on Mutex::try_lock, built with the crate's edition | Behavior on another edition |
| Pattern shape in a test | std::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 compile | A 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 stderr | The reason for the failure. Stable rustdoc accepts any compile error and ignores a named code; only nightly rustdoc checks it |
| Syntax builds on the MSRV | cargo +<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
| Symptom | Likely cause | First action |
|---|---|---|
| Value is partly usable after destructuring | The pattern made a partial move | List moved and initialized fields |
Partial move fails only after adding Drop (E0509) | The destructor needs the whole value | Move Drop to a one-field guard, or mem::take the field. See Partial moves |
| Guard side effect occurs twice | Overlapping or-pattern alternatives both matched | Remove 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 binding | Move the mutation into the arm body. A signature change does not help |
| Lock or borrow stays held inside the arm | The lock is in the match scrutinee or an if let guard | Copy the value out first. See Guard temporaries |
Binding became &T after a refactor | Match ergonomics changed the default binding mode | Probe the binding type in the target edition |
... within an implicitly-borrowing pattern | Edition 2024 reservation | Apply the fix from the edition 2024 table |
let chains are only allowed in Rust 2024 or later | Let chain in an edition 2021 if or while | Nest 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 gate | Raise rust-version or use the fallback. Do not add #![feature] |
| Wildcard fixes exhaustiveness but tests fail | The missing variant needed a semantic policy | Add 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
&mutmethod call through it, such asv.push(2), gives E0596. Both carry the note "variables bound in patterns are immutable until the end of the pattern guard". This applies toref mutbindings 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.
| Scrutinee | Ownership question |
|---|---|
match local | Which fields move from or borrow the local? |
match &local | Which bindings inherit a reference binding mode? |
match make() | Does the temporary hold a lock or borrow through the arms? |
match *pointer | Is 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |