Rust Reference ยท Patterns
Reference patterns
Reference for Rust reference patterns: &pat, &mut pat, ref and ref mut, default binding modes, and how to match through references and Box without moving.
A reference pattern starts with & (or &mut) and destructures a reference: the pattern &x matches a &T and binds x to the T behind it. It is the mirror image of the expression &x, and it needs T: Copy because the value is copied out.
Rust also has default binding modes, often called match ergonomics. When you match a reference against a pattern that is not a reference pattern, the compiler dereferences automatically and switches the bindings to ref or ref mut. Most code therefore never writes & or ref in a pattern.
for &n in &[1, 2, 3] {} // &n destructures the reference match &opt { Some(s) => {}, None => {} } // s: &String by default binding mode
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
&pat // match a &T, pat matches T &mut pat // match a &mut T ref ident // bind a shared reference to the matched place ref mut ident // bind a mutable reference
| Form | Matches | Result |
|---|---|---|
&x |
&T where T: Copy |
x: T |
&(a, b) |
&(A, B) |
a: A, b: B copied (both must be Copy) |
ref x |
any place | x: &T, nothing moves |
ref mut x |
a mutable place | x: &mut T |
no marker, scrutinee is &T |
T's shape |
bindings become references |
Errors and edge cases: for s in &strings { let &t = s; } fails with E0507 (cannot move out of a shared reference) because String is not Copy. Using & on a value that is not a reference is a type mismatch (E0308). In edition 2024, writing &, ref or mut inside a pattern that is already in a by-reference default binding mode is an error: remove the explicit marker.
Usage notes
&in a pattern removes a reference,&in an expression adds one.let &x = &5;givesx = 5.- Default binding modes see through references, not through
Box. ABox<Tree>field is bound as a&Box<Tree>, and there is no stable pattern that opens a box, so dereference it in the arm (**l) or rely on auto-deref in calls, as the example does. refis mostly for owned values in older code; seeref.- Closure arguments.
|&x|and|(a, b)|are the usual shapes foriter()anditer().enumerate(); use|&&x|when filteringiter()withfilter, becausefilterpasses&&T. - Copying cost.
&xcopies the value, so it is best for smallCopytypes; for big types bind by reference instead. - Mutable borrows work the same way:
match &mut value { Some(v) => *v += 1, None => {} }.
Related
ref,&T and &mut T, Destructuring,Box<T>- Lessons: Patterns, Borrowing, Enums and match