Skip to content
Tutorials Center
My learning

Topics

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.

Rust
for &n in &[1, 2, 3] {}                // &n destructures the reference
match &opt { Some(s) => {}, None => {} } // s: &String by default binding mode

Try it

Rust &pattern copies out of a reference

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.

Rust Default binding modes in action

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

Rust
&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; gives x = 5.
  • Default binding modes see through references, not through Box. A Box<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.
  • ref is mostly for owned values in older code; see ref.
  • Closure arguments. |&x| and |(a, b)| are the usual shapes for iter() and iter().enumerate(); use |&&x| when filtering iter() with filter, because filter passes &&T.
  • Copying cost. &x copies the value, so it is best for small Copy types; for big types bind by reference instead.
  • Mutable borrows work the same way: match &mut value { Some(v) => *v += 1, None => {} }.