re-do deepaksirone's fix on the actual source file

[rust-101.git] / src / part04.rs

diff --git a/src/part04.rs b/src/part04.rs
index fcfc8d92800cb2a54f592ff360a1b5d6e68dd11b..31e80564fdbac017ee4e83fe61378f97b3a15fa5 100644 (file)
--- a/src/part04.rs
+++ b/src/part04.rs
@@ -50,9 +50,9 @@ fn ownership_demo() {
 //@ we wanted! Can't we somehow give `vec_min` access to the vector, while retaining ownership of it?
 //@ 
 //@ Rust calls this *a reference* the vector, and it considers references as *borrowing* ownership. This
 //@ we wanted! Can't we somehow give `vec_min` access to the vector, while retaining ownership of it?
 //@ 
 //@ Rust calls this *a reference* the vector, and it considers references as *borrowing* ownership. This

-//@ works a bit like borrowing does in the real world: If you borrow a book to your friend, your friend
+//@ works a bit like borrowing does in the real world: If your friend borrows a book from you, your friend

 //@ can have it and work on it (and you can't!) as long as the book is still borrowed. Your friend could
 //@ can have it and work on it (and you can't!) as long as the book is still borrowed. Your friend could

-//@ even borrow the book to someone else. Eventually however, your friend has to give the book back to you,
+//@ even lend the book to someone else. Eventually however, your friend has to give the book back to you,

 //@ at which point you again have full control.
 //@ 
 //@ Rust distinguishes between two kinds of references. First of all, there's the *shared* reference.
 //@ at which point you again have full control.
 //@ 
 //@ Rust distinguishes between two kinds of references. First of all, there's the *shared* reference.


@@ -88,7 +88,7 @@ fn shared_ref_demo() {
     vec_min(&v);
     println!("The first element is: {}", *first);
 }
     vec_min(&v);
     println!("The first element is: {}", *first);
 }

-//@ What's going on here? First, `&` is how you borrow ownership to someone - this operator creates a shared reference.
+//@ What's going on here? First, `&` is how you lend ownership to someone - this operator creates a shared reference.

 //@ `shared_ref_demo` creates three shared references to `v`:
 //@ The reference `first` begins in the 2nd line of the function and lasts all the way to the end. The other two
 //@ references, created for calling `vec_min`, only last for the duration of that respective call.
 //@ `shared_ref_demo` creates three shared references to `v`:
 //@ The reference `first` begins in the 2nd line of the function and lasts all the way to the end. The other two
 //@ references, created for calling `vec_min`, only last for the duration of that respective call.


@@ -97,14 +97,14 @@ fn shared_ref_demo() {
 //@ reference, Rust knows that it cannot mutate `v`. Hence the pointer into the buffer of `v`
 //@ that was created before calling `vec_min` remains valid.
 
 //@ reference, Rust knows that it cannot mutate `v`. Hence the pointer into the buffer of `v`
 //@ that was created before calling `vec_min` remains valid.
 

-// ## Exclusive, mutable references
-//@ There is a second way to borrow something, a second kind of reference: The *exclusive reference*. This is a reference that comes with the promise that
-//@ nobody else has *any kind of access* to the referee - there is no aliasing. As a consequence, it is always safe to mutate data through
-//@ an exclusive reference, which is why they are usually called *mutable references*.
+// ## Unique, mutable references
+//@ There is a second way to borrow something, a second kind of reference: The *mutable reference*. This is a reference that comes with the promise
+//@ that nobody else has *any kind of access* to the referee - in contrast to shared references, there is no aliasing with mutable references. It is thus always safe to perform mutation through such a reference.
+//@ Because there cannot be another reference to the same data, we could also call it a *unique* reference, but that is not their official name.

 
 //@ As an example, consider a function which increments every element of a vector by 1.
 //@ The type `&mut Vec<i32>` is the type of mutable references to `vec<i32>`. Because the reference is
 
 //@ As an example, consider a function which increments every element of a vector by 1.
 //@ The type `&mut Vec<i32>` is the type of mutable references to `vec<i32>`. Because the reference is

-//@ mutable, we can use a mutable iterator, providing mutable (exclusive) references to the elements.
+//@ mutable, we can use a mutable iterator, providing mutable references to the elements.

 fn vec_inc(v: &mut Vec<i32>) {
     for e in v.iter_mut() {
         *e += 1;
 fn vec_inc(v: &mut Vec<i32>) {
     for e in v.iter_mut() {
         *e += 1;


@@ -126,7 +126,7 @@ fn mutable_ref_demo() {
 //@ than one mutable reference - we only ever borrow `v` once at a time. However, we can *not* create a shared reference that spans a call to `vec_inc`. Just try
 //@ enabling the commented-out lines, and watch Rust complain. This is because `vec_inc` could mutate
 //@ the vector structurally (i.e., it could add or remove elements), and hence the reference `first`
 //@ than one mutable reference - we only ever borrow `v` once at a time. However, we can *not* create a shared reference that spans a call to `vec_inc`. Just try
 //@ enabling the commented-out lines, and watch Rust complain. This is because `vec_inc` could mutate
 //@ the vector structurally (i.e., it could add or remove elements), and hence the reference `first`

-//@ could become invalid. In other words, Rust keeps us safe from bugs like the one in the C++ snipped above.
+//@ could become invalid. In other words, Rust keeps us safe from bugs like the one in the C++ snippet above.

 //@ 
 //@ Above, I said that having a mutable reference excludes aliasing. But if you look at the code above carefully,
 //@ you may say: "Wait! Don't the `v` in `mutable_ref_demo` and the `v` in `vec_inc` alias?" And you are right,
 //@ 
 //@ Above, I said that having a mutable reference excludes aliasing. But if you look at the code above carefully,
 //@ you may say: "Wait! Don't the `v` in `mutable_ref_demo` and the `v` in `vec_inc` alias?" And you are right,