Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Keywords and Statements

The ref keyword

Reference for Rust ref and ref mut: borrowing part of a value inside a pattern, how match ergonomics made it mostly unnecessary, and where it still matters.

ref is a keyword used inside patterns. Normally a pattern that binds a name moves (or copies) the matched part out of the value. Writing ref name instead makes the binding a shared reference to that part, and ref mut name makes it a mutable reference. The original value stays where it is.

It is different from & in an expression: &x creates a reference, while ref x in a pattern asks the pattern to borrow the part it matches. Since Rust 2018 "default binding modes" (match ergonomics) handle most cases automatically, so you rarely need to write ref yourself.

Rust
let pair = (String::from("a"), 1);
let (ref name, n) = pair;   // name: &String, pair is still whole

Try it

Rust Borrowing instead of moving

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 Move versus borrow in match

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
let ref x = value;          // x: &T
let ref mut y = value;      // y: &mut T
let Struct { ref field, .. } = value;
match value { Some(ref v) => {}, None => {} }
Form Binding type Effect
ref x &T Borrows the matched part immutably.
ref mut x &mut T Borrows it mutably. The scrutinee must be a mutable place.
&x (pattern) T The opposite: destructures an existing reference and copies the value out (needs T: Copy).

Errors: E0507 (cannot move out of a borrowed value) is what you usually see when a pattern binds by value through a reference. ref mut on an immutable place gives E0596.

Usage notes

  • ref in a pattern and & in an expression are opposites in direction. let ref a = x; is equivalent to let a = &x;.
  • Match ergonomics: when you match a &T or &mut T against a non-reference pattern, the compiler switches the bindings to ref or ref mut for you. That is why match &opt { Some(s) => ... } binds s: &String.
  • Edition 2024 restriction: once default binding modes apply, writing an explicit ref, ref mut, mut or & inside such a pattern is an error. Write the pattern without them, or remove the outer reference.
  • Where explicit ref still helps: matching on a value you own while borrowing one field, and ref mut in a plain let/match on an owned mutable place.
  • Partial moves: binding one field by value and another by ref is allowed, but the value can no longer be used as a whole after the by-value part moves.
  • No runtime cost. A ref binding is just a pointer to the matched place.
  • Not related to Rc/RefCell. ref is purely a pattern feature.