Mutable References

Creating a Mutable Reference

Writing &mut value creates a reference that is allowed to modify the data it points to. The variable being referenced must itself have been declared with mut.

Example: Creating a Mutable Reference

fn add_exclamation(s: &mut String) {
    s.push_str("!");
}

fn main() {
    let mut message = String::from("Hello");
    add_exclamation(&mut message);
    println!("{}", message);
}

Only One Mutable Reference at a Time

Rust enforces that at most one mutable reference to a value can exist within a given scope, preventing two pieces of code from unexpectedly changing the same data at once.

Note: Notice r1's scope ends before r2 is created -- that's what makes this compile.

Example: Only One Mutable Reference at a Time

fn main() {
    let mut count = 5;
    {
        let r1 = &mut count;
        *r1 += 1;
    }
    let r2 = &mut count;
    *r2 += 1;
    println!("count = {}", count);
}

Cannot Mix Mutable and Immutable References

You cannot hold a mutable reference at the same time as any immutable references to the same value, since a reader could otherwise see the data change unexpectedly mid-read.

Example: Cannot Mix Mutable and Immutable References

fn main() {
    let mut value = 10;
    {
        let readable = &value;
        println!("Read before mutation: {}", readable);
    }
    let writable = &mut value;
    *writable += 5;
    println!("After mutation: {}", value);
}

Dereferencing to Modify

To change the value behind a mutable reference, use the dereference operator * to access the underlying data directly.

Example: Dereferencing to Modify

fn double(n: &mut i32) {
    *n *= 2;
}

fn main() {
    let mut x = 7;
    double(&mut x);
    println!("x is now {}", x);
}