Need common pitfalls for the borrow checker and how to get around them.

[Timmmm]

I really think you need an entire section on common things you might try that actually don't work because of the borrow checker, and how to fix them. The rules of the borrow checker (exactly one mutable borrow, or multiple immutable borrows) are not enough to understand it. Lots of people have the experience "Ok those are simple rules" and then they run into the problems below which the rules suggest should work and think "Wtf Rust?".

Here are a few examples (the first two are pretty long-standing):

Method calls borrow self at the same time as the parameters.

You can't do foo.set(foo.get() + 1).

The fix is to add an extra temporary variable.

Lexical borrows

let mut x = 1;
let y = &mut x;
*y = 1; // Last use of y
let z = &mut x;
*z = 1;

The solution is to add extra scopes.

The map issue

There are a whole lot of issues people have about doing stuff with maps in match statements and the Entry API. E.g. you can't do something like this:

        match mymap.get_mut(key) {
            Some(_) => {...},
            None => {mymap.insert(...)},
        }

I would suggest searching Stackoverflow for 'rust', 'borrow-checker' questions to find the most common questions and solutions.

[carols10cents]

We do discuss the entry API in the HashMaps section of chapter 8.

The other two issues have to do with non-lexical borrow scopes/non-lexical lifetime stuff, of which I am barely up to date on, but I know there's work being done on it currently, now that a good chunk of MIR is done.

For example, here's a thread Niko started last month on the method calls borrowing self at the same time as the parameters problem, as well as the RFC for non-lexical borrowing scopes.

I know Rust has been this way for a while, but I'm really optimistic that there will be progress on improving this soon, possibly before the book is printed even. I'm reluctant to document something in a permanent medium that is a known shortcoming planned to be improved upon.

While I personally love and value resources that are organized by problem/symptom and explain the solution to aid troubleshooting while coding, this book is more of an introduction to build up new Rust programmer's knowledge, read in order before, and interleaved separately with, hands-on coding. So we don't really have any sections that are "here's problem X and here's how to solve it", exactly. I think that sort of resource deserves its own website/book, since there are a lot of things along those lines that we don't have space to cover in this book!

Thank you for your feedback! I do appreciate it, but I don't think we're going to be adding a section like this to the book. ❤️