From 15a0299299e438b1e8624989231c44cc3738896a Mon Sep 17 00:00:00 2001 From: Jonathan Price Date: Mon, 27 Jun 2016 18:06:40 -0500 Subject: [PATCH] many small grammatical and stylistic changes grammatical: "Here's" should be "Here are", "rules" is plural. stylistic: "rules for" is more idiomatic than "rules about". grammatical: No verb in "One or the other"; changed to "It's one or the other". code: added implied `fn main() { ... }` because it is referenced in "note: previous borrow ends here" semantic: "But" seems like the wrong word here, there is now, contrast, only further explanation. "so", "thus" or "therefor" is clearer. grammatical: Another misuse of "Here's", should be "Here are" (or possibly "Here're"). grammatical: "use" should be capitalized. All other subheadings capitalize the first word. --- src/doc/book/references-and-borrowing.md | 36 +++++++++++++----------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/src/doc/book/references-and-borrowing.md b/src/doc/book/references-and-borrowing.md index 2b7aa339c0f9..57bfbce8b84d 100644 --- a/src/doc/book/references-and-borrowing.md +++ b/src/doc/book/references-and-borrowing.md @@ -179,7 +179,7 @@ As it turns out, there are rules. # The Rules -Here’s the rules about borrowing in Rust: +Here are the rules for borrowing in Rust: First, any borrow must last for a scope no greater than that of the owner. Second, you may have one or the other of these two kinds of borrows, but not @@ -208,12 +208,14 @@ With this in mind, let’s consider our example again. Here’s the code: ```rust,ignore -let mut x = 5; -let y = &mut x; +fn main() { + let mut x = 5; + let y = &mut x; -*y += 1; + *y += 1; -println!("{}", x); + println!("{}", x); +} ``` This code gives us this error: @@ -225,7 +227,7 @@ error: cannot borrow `x` as immutable because it is also borrowed as mutable ``` This is because we’ve violated the rules: we have a `&mut T` pointing to `x`, -and so we aren’t allowed to create any `&T`s. One or the other. The note +and so we aren’t allowed to create any `&T`s. It's one or the other. The note hints at how to think about this problem: ```text @@ -243,14 +245,16 @@ In Rust, borrowing is tied to the scope that the borrow is valid for. And our scopes look like this: ```rust,ignore -let mut x = 5; +fn main() { + let mut x = 5; -let y = &mut x; // -+ &mut borrow of x starts here - // | -*y += 1; // | - // | -println!("{}", x); // -+ - try to borrow x here - // -+ &mut borrow of x ends here + let y = &mut x; // -+ &mut borrow of x starts here + // | + *y += 1; // | + // | + println!("{}", x); // -+ - try to borrow x here +} // -+ &mut borrow of x ends here + ``` The scopes conflict: we can’t make an `&x` while `y` is in scope. @@ -269,12 +273,12 @@ println!("{}", x); // <- try to borrow x here ``` There’s no problem. Our mutable borrow goes out of scope before we create an -immutable one. But scope is the key to seeing how long a borrow lasts for. +immutable one. So scope is the key to seeing how long a borrow lasts for. ## Issues borrowing prevents Why have these restrictive rules? Well, as we noted, these rules prevent data -races. What kinds of issues do data races cause? Here’s a few. +races. What kinds of issues do data races cause? Here are a few. ### Iterator invalidation @@ -323,7 +327,7 @@ for i in &v { We can’t modify `v` because it’s borrowed by the loop. -### use after free +### Use after free References must not live longer than the resource they refer to. Rust will check the scopes of your references to ensure that this is true.