Suggestion: another example of borrowing and lifetime

[ljw1004]

I struggled to make the connection between borrowing and lifetime from reading the Rust book. I'm filing this issue to contribute a suggestion for some extra words/paragraphs that would have helped me over this hump. I think that borrowing+lifetimes is such an important part of Rust's value-prop that it might be worth adding. (I'm not sure if you'd prefer this contribution as a PR or an issue, and I'm doing it as an issue first because you might reasonably feel that this area doesn't merit further explanation).

Section 4.2
We call having references as function parameters borrowing. As in real life, if a person owns something, you can borrow it from them. When you’re done, you have to give it back.

[When I read this, I automatically assumed that a function would borrow its parameters when invoked, and return the borrow once the function finished. This indeed is how all examples to date in the book had worked. I suggest the following extra words here in 4.2 after the above quote:]

(We'll see in chapter 10.3 "Lifetimes" that the function borrows its reference parameter not just for the duration of the function call, but for the lifetime of the parameter).

Section 10.3
"The function signature now tells Rust that for some lifetime 'a, the function takes two parameters, both of which are string slices that live at least as long as lifetime 'a. The function signature also tells Rust that the string slice returned from the function will live at least as long as lifetime 'a."
...
"Ultimately, lifetime syntax is about connecting the lifetimes of various parameters and return values of functions. Once they’re connected, Rust has enough information to allow memory-safe operations and disallow operations that would create dangling pointers or otherwise violate memory safety."

[The first quoted paragraph of 10.3 tells the whole story, but it went by so quickly that my brain wasn't able to make the connection between lifetime and borrowing. I suggest the following extra material could follow the second quoted paragraph:]

An important point is that function parameters are borrowed not just for the duration of the function, but for the lifetime of the function parameter. This allows a function to safely return a reference to part of its parameters. Consider this code:

// ERROR CODE
#[test]
fn main() {
  let mut x = S {v: String::from("hello")};
  let y : &str = f(&mut x);

  // Disallowed [1]  
  x.v.push_str(" world");
  println!("{}", y);

  // Disallowed [2]
  // println!("{}", x.v);
  // println!("{}", y);

}

#[derive(Debug)]
struct S {v: String}

fn f<'a>(x: &'a mut S) -> &'a str { &x.v }

The reference y is a reference to an inside part of &mut x. In other languages this would be dangerous - e.g. if you did x.v.push_str("a") then that would mutate x and so the meaning of y would change under your feet.

But Rust's lifetimes and borrowing rules make this safe. It borrows the parameter &mut x not just for the duration of the function, but for the lifetime of the parameter. In this case the lifetime of the parameter is tied to the lifetime of y, so the mutable reference to x remains borrowed until y has gone out of scope. The above code gives the error on x.v.push_str(" world") that you "cannot borrow x.v as mutable more than once at a time" since the first mutable reference &mut x is still alive.

This is a powerful feature. It means a function can safely return a reference to a struct member, rather than pessimistically copying it into a new heap object or relying on garbage collection as happens in other languages. We'll see another use in section 19 for the standard library split_at_mut function, which splits a slice into two mutable references to its parts, and disallows anyone modifying the original slice while those two references are live.

Exercise:

• Why is [2] disallowed? How can you print both x.v and y without violating the borrowing rules? (hint: consider when the lifetime or scope of y ends)