Skip to content
Tutorials Center
My learning

Topics

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.

Rust
let mut total = 0;
total += 5;
let r = &mut total;
*r += 1;

Try it

Rust Mutable bindings and references

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 The exclusivity rule

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 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 Vec is immutable under let v and mutable under let mut v. Moving a value into a new binding can change its mutability.
  • mut x: &T is not x: &mut T. The first allows rebinding x to point elsewhere; the second allows changing the pointee.
  • Only one &mut at 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 self need a mutable binding or a &mut receiver. That is why let 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; see RefCell<T> and Cell<T>.
  • Closures that modify captured state are FnMut and must be stored in a mut binding to be called.
  • Prefer small mutable scopes. Build a value in a let mut block and then bind the result to an immutable name.
  • Unused mut triggers a warning, a handy cleanup hint.