Merge pull request #42 from zdyxry/master

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

diff --git a/src/part04.rs b/src/part04.rs
index fcfc8d92800cb2a54f592ff360a1b5d6e68dd11b..2381ff4ed00a631618e342ee9abdd47d65253939 100644 (file)
--- a/src/part04.rs
+++ b/src/part04.rs
@@ -37,9 +37,9 @@ fn ownership_demo() {
 //@ 
 //@ If you give a book to your friend, you cannot just come to his place next day and get the book!
 //@ It's no longer yours. Rust makes sure you don't break this rule. Try enabling the commented
 //@ 
 //@ If you give a book to your friend, you cannot just come to his place next day and get the book!
 //@ It's no longer yours. Rust makes sure you don't break this rule. Try enabling the commented

-//@ line in `ownership_demo`. Rust will tell you that `v` has been *moved*, which is to say that ownership
-//@ has been transferred somewhere else. In this particular case, the buffer storing the data
-//@ does not even exist anymore, so we are lucky that Rust caught this problem!
+//@ line in `ownership_demo`. Rust will tell you that `v` has been *moved*, which is to say that
+//@ ownership has been transferred somewhere else. In this particular case, the buffer storing the
+//@ data does not even exist anymore, so we are lucky that Rust caught this problem!

 //@ Essentially, ownership rules out aliasing, hence making the kind of problem discussed above
 //@ impossible.
 
 //@ Essentially, ownership rules out aliasing, hence making the kind of problem discussed above
 //@ impossible.
 


@@ -49,17 +49,17 @@ fn ownership_demo() {
 //@ vector. Hence, when `vec_min` finishes, the entire vector is deleted. That's of course not what
 //@ we wanted! Can't we somehow give `vec_min` access to the vector, while retaining ownership of it?
 //@ 
 //@ vector. Hence, when `vec_min` finishes, the entire vector is deleted. That's of course not what
 //@ 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
-//@ 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,
-//@ at which point you again have full control.
+//@ Rust calls this *a reference* to the vector, and it considers references as *borrowing*
+//@ ownership. This 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 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.
 //@ This is where the book metaphor kind of breaks down... you can give a shared reference to
 //@ *the same data* to lots of different people, who can all access the data. This of course
 //@ 
 //@ Rust distinguishes between two kinds of references. First of all, there's the *shared* reference.
 //@ This is where the book metaphor kind of breaks down... you can give a shared reference to
 //@ *the same data* to lots of different people, who can all access the data. This of course

-//@ introduces aliasing, so in order to live up to its promise of safety, Rust generally does not allow
-//@ mutation through a shared reference.
+//@ introduces aliasing, so in order to live up to its promise of safety, Rust generally does not
+//@ allow mutation through a shared reference.

 
 //@ So, let's re-write `vec_min` to work on a shared reference to a vector, written `&Vec<i32>`.
 //@ I also took the liberty to convert the function from `SomethingOrNothing` to the standard
 
 //@ So, let's re-write `vec_min` to work on a shared reference to a vector, written `&Vec<i32>`.
 //@ I also took the liberty to convert the function from `SomethingOrNothing` to the standard


@@ -68,8 +68,8 @@ fn vec_min(v: &Vec<i32>) -> Option<i32> {
     use std::cmp;
 
     let mut min = None;
     use std::cmp;
 
     let mut min = None;

-    // This time, we explicitly request an iterator for the vector `v`. The method `iter` just borrows the vector
-    // it works on, and provides shared references to the elements.
+    // This time, we explicitly request an iterator for the vector `v`. The method `iter` just
+    // borrows the vector it works on, and provides shared references to the elements.

     for e in v.iter() {
         // In the loop, `e` now has type `&i32`, so we have to dereference it to obtain an `i32`.
         min = Some(match min {
     for e in v.iter() {
         // In the loop, `e` now has type `&i32`, so we have to dereference it to obtain an `i32`.
         min = Some(match min {


@@ -88,23 +88,26 @@ 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.
-//@ `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
+//@ 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.
 //@ 
 //@ Technically, of course, references are pointers. Notice that since `vec_min` only gets a shared
 //@ 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.
 
 //@ references, created for calling `vec_min`, only last for the duration of that respective call.
 //@ 
 //@ Technically, of course, references are pointers. Notice that since `vec_min` only gets a shared
 //@ 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.
 
 //@ 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.
+//@ 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 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;


@@ -118,29 +121,36 @@ fn mutable_ref_demo() {
     vec_inc(&mut v);
     /* println!("The first element is: {}", *first); */             /* BAD! */
 }
     vec_inc(&mut v);
     /* println!("The first element is: {}", *first); */             /* BAD! */
 }

-//@ `&mut` is the operator to create a mutable reference. We have to mark `v` as mutable in order to create such a
-//@ reference: Even though we completely own `v`, Rust tries to protect us from accidentally mutating things.
+//@ `&mut` is the operator to create a mutable reference. We have to mark `v` as mutable in order
+//@ to create such a reference: Even though we completely own `v`, Rust tries to protect us from
+//@ accidentally mutating things.

 //@ Hence owned variables that you intend to mutate have to be annotated with `mut`.
 //@ Hence owned variables that you intend to mutate have to be annotated with `mut`.

-//@ Because the reference passed to `vec_inc` only lasts as long as the function call, we can still call
-//@ `vec_inc` on the same vector twice: The durations of the two references do not overlap, so we never have more
-//@ 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
+//@ Because the reference passed to `vec_inc` only lasts as long as the function call, we can still
+//@ call `vec_inc` on the same vector twice: The durations of the two references do not overlap, so
+//@ we never have more 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`
 //@ 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,
-//@ they do. However, the `v` in `mutable_ref_demo` is not actually usable, it is not *active*: As long as `v` is
-//@ borrowed, Rust will not allow you to do anything with it.
+//@ 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, they do. However, the `v` in `mutable_ref_demo` is not
+//@ actually usable, it is not *active*: As long as `v` is borrowed, Rust will not allow you to do
+//@ anything with it.

 
 // ## Summary
 // The ownership and borrowing system of Rust enforces the following three rules:
 // 
 // * There is always exactly one owner of a piece of data
 // * If there is an active mutable reference, then nobody else can have active access to the data
 
 // ## Summary
 // The ownership and borrowing system of Rust enforces the following three rules:
 // 
 // * There is always exactly one owner of a piece of data
 // * If there is an active mutable reference, then nobody else can have active access to the data

-// * If there is an active shared reference, then every other active access to the data is also a shared reference
+// * If there is an active shared reference, then every other active access to the data is also a
+//   shared reference

 // 
 // 

-// As it turns out, combined with the abstraction facilities of Rust, this is a very powerful mechanism
-// to tackle many problems beyond basic memory safety. You will see some examples for this soon.
+// As it turns out, combined with the abstraction facilities of Rust, this is a very powerful
+// mechanism to tackle many problems beyond basic memory safety. You will see some examples for
+// this soon.

 
 

-//@ [index](main.html) | [previous](part03.html) | [raw source](https://www.ralfj.de/git/rust-101.git/blob_plain/HEAD:/workspace/src/part04.rs) | [next](part05.html)
+//@ [index](main.html) | [previous](part03.html) | [raw source](workspace/src/part04.rs) |
+//@ [next](part05.html)