> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Rust Mutable Reference
The `&mut` operator creates a mutable reference to a value, allowing a binding to read and modify data without taking ownership of it. In Rust's ownership system, this operation is formally known as a "mutable borrow."
Under the hood, `&mut T` is a non-null, aligned pointer to a memory address containing a value of type `T`. Unlike raw pointers (`*mut T`), the Rust compiler statically verifies the lifetime of a `&mut` reference to guarantee it never points to freed or invalid memory.
## Syntax and Type Signatures
The `&mut` syntax is used in two distinct contexts: as an expression to create the reference, and in type signatures to define the reference type.
```rust theme={"dark"}
// 'mut data' makes the binding itself mutable
let mut data = 10;
// '&mut data' is the expression creating the mutable borrow
// '&mut i32' is the type signature of the reference
let ptr: &mut i32 = &mut data;
```
## Core Mechanics and Compiler Rules
The behavior of `&mut` is strictly governed by Rust's Borrow Checker to ensure memory safety and prevent data races at compile time.
**1. Base Mutability Requirement**
You cannot create a mutable reference to an immutable binding. The underlying data must be explicitly declared with the `mut` keyword.
```rust theme={"dark"}
let x = 5;
// let y = &mut x; // COMPILER ERROR: Cannot borrow `x` as mutable
```
**2. Strict Exclusivity (No Aliasing)**
Rust enforces a strict "aliasing XOR mutation" rule. If a `&mut` reference to a piece of data exists, it must be the *only* active reference to that data in the current scope. You cannot simultaneously hold multiple `&mut` references, nor can you hold a `&mut` reference alongside an immutable `&` reference to the same data.
```rust theme={"dark"}
let mut value = 100;
let r1 = &mut value;
// let r2 = &mut value; // COMPILER ERROR: Cannot borrow twice mutably
// let r3 = &value; // COMPILER ERROR: Cannot borrow immutably while mutably borrowed
*r1 += 1; // r1's lifetime ends after its last usage
```
**3. Explicit Dereferencing**
To mutate the underlying data that the `&mut` reference points to, you must use the dereference operator (`*`). This instructs the compiler to follow the pointer to the actual memory location.
```rust theme={"dark"}
let mut counter = 0;
let counter_ref = &mut counter;
// Mutating the value at the memory address
*counter_ref = 5;
```
*Note: Rust provides implicit dereferencing (auto-deref) when calling methods on a mutable reference (e.g., `reference.method()`), but direct assignment or arithmetic requires the explicit `*` operator.*
**4. Move Semantics and Reborrowing**
Because mutable references must guarantee strict exclusivity, `&mut T` does not implement the `Copy` trait. A standard assignment of a mutable reference to another variable **moves** the reference, invalidating the original binding.
```rust theme={"dark"}
let mut x = 10;
let r1 = &mut x;
// Standard assignment moves the mutable reference
let r2 = r1;
// *r1 += 1; // COMPILER ERROR: use of moved value: `r1`
```
To use multiple mutable references to the same data sequentially without losing the original reference, Rust utilizes a mechanism called *reborrowing*. A reborrow creates a new, temporary `&mut` reference with a shorter lifetime, freezing the original reference until the reborrow expires.
Implicit reborrowing occurs *only* at coercion sites, such as when passing a mutable reference to a function argument or when an explicit type annotation is provided during assignment. If a coercion site is not present, you must perform an explicit reborrow using `&mut *`.
```rust theme={"dark"}
let mut x = 10;
let r1 = &mut x;
// Implicit reborrow: triggered by the explicit type annotation
let r2: &mut i32 = r1;
*r2 += 1;
// Explicit reborrow: manually dereferencing and borrowing again
let r3 = &mut *r1;
*r3 += 1;
// r1 is usable again after r2 and r3's lifetimes end
*r1 += 1;
```
Tired of Poor Rust Skills? Fix That With Deep Grasping!
Learn More
