125. Borrowing

Lending, not giving

Chapter 124 left you with an awkward rule. Pass a String to a function and it moves in. The caller loses it:

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

fn main() {
    let name = String::from("drip");
    let n = count(name);
    println!("{name} has {n} bytes");
}

That fails with borrow of moved value: name. You could have count hand the string back, but every function that only wants to look at a value would need that round trip.

TypeScript never has this problem. Passing an object passes an arrow to it (chapter 4), and the caller keeps its own arrow. Rust can pass an arrow too. It just keeps track of who holds one.

Put a & in front of the type and in front of the argument:

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

let n = count(&name);
println!("{name} has {n} bytes");

Now name is still usable after the call. &name made a reference to the string without moving it, and when s goes away at the end of count, nothing is dropped.

Borrowing to change something

A plain & lets you read, not write. To change a borrowed value you need a mutable reference, &mut:

fn bump(n: &mut i32) {
    *n += 1;
}

let mut hits = 0;
bump(&mut hits);
bump(&mut hits);
// hits is now 2

*n follows the reference to the number it points at. (Method calls like s.len() follow it for you, so you rarely write * there.) Notice how loud this is. The owner says let mut, the caller says &mut hits, and the parameter says &mut i32. In chapter 4, any function you passed an object to could quietly change it. In Rust you can see it at the call.

Try to write through a plain & and the compiler stops you (real output from rustc 1.97):

error[E0594]: cannot assign to `*n`,
  which is behind a `&` reference

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

fn bump(n: &mut i32) {
    *n += 1;
}

fn main() {
    let name = String::from("drip");
    let n = count(&name);
    println!("{name} has {n} bytes");

    let mut hits = 0;
    bump(&mut hits);
    bump(&mut hits);
    println!("hits: {hits}");
}

Many readers or one writer

Why not let everyone have a &mut? Because a reader who is halfway through a value can be surprised by a writer changing it underneath.

Step through the arrows. Green ones read, the amber one writes, and the bars underneath show how long each borrow lives.

let mut s = String::from("tea");
let a = &s;
let b = &s;
println!("{a} and {b}");
let w = &mut s;
w.push_str("pot");
println!("{s}");

The surprise for most people is step 4. The borrows a and b don’t last until the closing brace. They end at their last use, so w is allowed to start straight after the println!^[1].

The borrow checker

The part of the compiler that enforces the rule is the borrow checker. Here is what it says about the last step of the diagram (real rustc 1.97 output, long lines wrapped, file path removed):

error[E0502]: cannot borrow `s` as
  mutable because it is also borrowed
  as immutable
3 |     let a = &s;
  |             -- immutable borrow
  |                occurs here
4 |     let w = &mut s;
  |             ^^^^^^ mutable borrow
  |                    occurs here
5 |     w.push_str("pot");
6 |     println!("{a}");
  |                - immutable borrow
  |                  later used here

Read it as three points on one timeline: where the reader started, where the writer started, and where the reader was still needed. The fix is to make those stop overlapping. Here, print a before you make w. Two writers at once gets its own error, E0499, with the same three-point shape.

fn main() {
    let mut s = String::from("tea");
    let a = &s;
    let w = &mut s;
    w.push_str("pot");
    // a is still alive here: rejected.
    // Move this line above `let w`.
    println!("{a}");
}

Your turn

fn order(a: &mut i32, b: &mut i32) {
    // your code here
}

fn append_twice(
    s: &mut String,
    t: &String,
) {
    // your code here
}

What you learned

• A reference &T lets you use a value without owning it. Making one is borrowing, and dropping a reference never drops the value.
• A mutable reference &mut T can change the value, through *r. It needs let mut on the owner and &mut at the call.
• The rule: many readers or one writer, never both at once. A borrow ends at its last use.
• The borrow checker enforces the rule at compile time. Its errors name where each borrow starts and where it is still needed.
• A &mut is a promise of no aliases, the very fact Viscosity had to prove for itself in TypeScript.

Next: slices. A reference to part of an array or a string, which is how the Rust Drip scanner reads its source without copying a byte.