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.
let pair = (String::from("a"), 1); let (ref name, n) = pair; // name: &String, pair is still whole
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
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
refin a pattern and&in an expression are opposites in direction.let ref a = x;is equivalent tolet a = &x;.- Match ergonomics: when you match a
&Tor&mut Tagainst a non-reference pattern, the compiler switches the bindings toreforref mutfor you. That is whymatch &opt { Some(s) => ... }bindss: &String. - Edition 2024 restriction: once default binding modes apply, writing an explicit
ref,ref mut,mutor&inside such a pattern is an error. Write the pattern without them, or remove the outer reference. - Where explicit
refstill helps: matching on a value you own while borrowing one field, andref mutin a plainlet/matchon an owned mutable place. - Partial moves: binding one field by value and another by
refis allowed, but the value can no longer be used as a whole after the by-value part moves. - No runtime cost. A
refbinding is just a pointer to the matched place. - Not related to
Rc/RefCell.refis purely a pattern feature.
Related
match,let,mut,&T and &mut T- Lessons: Patterns, Borrowing, Enums and match