Rust Reference ยท Keywords and Statements
The mut keyword
Reference for Rust mut: mutable variable bindings, mutable references with &mut, the exclusivity rule, mut in patterns and interior mutability.
mut has two related jobs. On a binding (let mut x) it allows the variable to be reassigned or modified in place. In a reference type (&mut T) it describes a mutable borrow: temporary, exclusive access to a value that someone else owns.
Rust's central rule is that at any moment a value can have either any number of shared references (&T) or exactly one mutable reference (&mut T), never both. The compiler enforces this at compile time, which is how Rust prevents data races and iterator invalidation without a garbage collector.
let mut total = 0; total += 5; let r = &mut total; *r += 1;
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 mut name = value; // mutable binding fn f(mut param: i32) { } // mutable parameter binding fn g(r: &mut T) { } // mutable reference parameter let r = &mut place; // create a mutable reference let ref mut x = value; // mutable by-reference binding in patterns
| Form | Meaning |
|---|---|
let mut x |
The variable can be assigned to and its value mutated through x. |
&mut T |
An exclusive reference. You can read and write through it with *r (often implicit through method calls). |
mut param |
The function owns its parameter and may modify its local copy. The caller is unaffected. |
*mut T |
A raw mutable pointer, a different thing: see raw pointers. |
Errors: E0384 (assigning twice to an immutable variable), E0596 (borrowing an immutable variable as mutable), E0499 (two mutable borrows alive at once) and E0502 (shared and mutable borrow overlap).
Usage notes
- Mutability belongs to the binding, not the type. The same
Vecis immutable underlet vand mutable underlet mut v. Moving a value into a new binding can change its mutability. mut x: &Tis notx: &mut T. The first allows rebindingxto point elsewhere; the second allows changing the pointee.- Only one
&mutat a time, and while it exists you may not use the owner or make shared borrows. Non-lexical lifetimes end the borrow at its last use, not at the end of the block. - Methods that take
&mut selfneed a mutable binding or a&mutreceiver. That is whylet v = Vec::new(); v.push(1);fails. - Interior mutability (
Cell,RefCell,Mutex, atomics) lets you mutate through a shared reference with run-time or atomic checks; seeRefCell<T>andCell<T>. - Closures that modify captured state are
FnMutand must be stored in amutbinding to be called. - Prefer small mutable scopes. Build a value in a
let mutblock and then bind the result to an immutable name. - Unused
muttriggers a warning, a handy cleanup hint.