References and borrowing

The problem from the last module

Passing a String to a function moved it, so we had to pass it back. Rust's answer is the reference. A reference is like a pointer: it holds the address of a value owned by someone else. Unlike a raw pointer, Rust guarantees a reference always points to a valid value. Creating a reference is called borrowing, because you use the value for a while and the owner keeps it.

fn length(s: &String) -> usize {
    s.len()
}

fn main() {
    let city = String::from("Bhopal");
    let n = length(&city);          // lend city to the function
    println!("{city} has {n} bytes"); // city is still ours
}

   main's stack            length's stack           HEAP
  city: ptr ---------------------------------->  B h o p a l
        len 6                 s: ptr --+
        cap 6                          |
     ^                                 |
     +---------------------------------+   s points to city, not to the heap

Mutable references

A plain reference &T is a shared reference: you can read through it but not change the value. To let a function change a borrowed value, the owner must be mut and you pass &mut.

fn add_surname(name: &mut String) {
    name.push_str(" Sharma");
}

fn main() {
    let mut name = String::from("Rohit");
    add_surname(&mut name);
    println!("{name}");   // Rohit Sharma
}

The borrowing rules

1. At any given time, you can have EITHER any number of shared references (&T) OR exactly one mutable reference (&mut T), but not both.
2. References must always be valid: a reference can never outlive the value it points to.

Why rule 1? If one part of the code is changing a value while another part is reading it, the reader can see half-changed data. When this happens between threads it is called a data race, one of the hardest bugs to find. Rust rules it out at compile time, even in single-threaded code, where the same pattern causes bugs such as a list being changed while it is being looped over.

Dereferencing with *

To reach the value behind a reference, you sometimes write * in front of it. This is called dereferencing. Method calls and println! do it for you automatically, so you mostly need * when changing a number through a &mut.

fn add_bonus(points: &mut u32) {
    *points += 50;     // change the value behind the reference
}

fn main() {
    let mut points = 100;
    add_bonus(&mut points);
    println!("{points}");   // 150
}

Common mistakes

• Passing name instead of &name to a function that takes &String: "expected &String, found String". Add the &.
• Calling a &mut function on a variable that is not mut: "cannot borrow as mutable". Declare it with let mut.
• Forgetting * when changing a number through &mut. The compiler suggests it.
• Taking &mut when you only read. Use & so others can read at the same time.