Merge pull request #7 from leesper/master
[rust-101.git] / src / part14.rs
index eb2011a958f5377f2a36642aa79794427a42fce8..e16837ce352a6f10cde0595047c74c9898346b45 100644 (file)
@@ -15,8 +15,8 @@
 //@ `[T]` is the type of an (unsized) *array*, with elements of type `T`. All this means is that there's a contiguous
 //@ region of memory, where a bunch of `T` are stored. How many? We can't tell! This is an unsized type. Just like for
 //@ trait objects, this means we can only operate on pointers to that type, and these pointers will carry the missing
 //@ `[T]` is the type of an (unsized) *array*, with elements of type `T`. All this means is that there's a contiguous
 //@ region of memory, where a bunch of `T` are stored. How many? We can't tell! This is an unsized type. Just like for
 //@ trait objects, this means we can only operate on pointers to that type, and these pointers will carry the missing
-//@ information - namely, the length. Such a pointer is called a *slice*. As we will see, a slice can be split.
-//@ Our function can thus take a borrowed slice, and promise to sort all elements in there.
+//@ information - namely, the length (they will be *fat pointers*). Such a reference to an array is called a *slice*. As we will see, a slice can be split.
+//@ Our function can thus take a mutable slice, and promise to sort all elements in there.
 pub fn sort<T: PartialOrd>(data: &mut [T]) {
     if data.len() < 2 { return; }
 
 pub fn sort<T: PartialOrd>(data: &mut [T]) {
     if data.len() < 2 { return; }
 
@@ -38,7 +38,7 @@ pub fn sort<T: PartialOrd>(data: &mut [T]) {
     // Finally, we split our slice to sort the two halves. The nice part about slices is that splitting them is cheap:
     //@ They are just a pointer to a start address, and a length. We can thus get two pointers, one at the beginning and
     //@ one in the middle, and set the lengths appropriately such that they don't overlap. This is what `split_at_mut` does.
     // Finally, we split our slice to sort the two halves. The nice part about slices is that splitting them is cheap:
     //@ They are just a pointer to a start address, and a length. We can thus get two pointers, one at the beginning and
     //@ one in the middle, and set the lengths appropriately such that they don't overlap. This is what `split_at_mut` does.
-    //@ Since the two slices don't overlap, there is no aliasing and we can have them both mutably borrowed.
+    //@ Since the two slices don't overlap, there is no aliasing and we can have both of them as unique, mutable slices.
     let (part1, part2) = data.split_at_mut(lpos);
     //@ The index operation can not only be used to address certain elements, it can also be used for *slicing*: Giving a range
     //@ of indices, and obtaining an appropriate part of the slice we started with. Here, we remove the last element from
     let (part1, part2) = data.split_at_mut(lpos);
     //@ The index operation can not only be used to address certain elements, it can also be used for *slicing*: Giving a range
     //@ of indices, and obtaining an appropriate part of the slice we started with. Here, we remove the last element from
@@ -59,7 +59,7 @@ fn sort_nums(data: &mut Vec<i32>) {
 }
 
 // ## Arrays
 }
 
 // ## Arrays
-//@ An *array* in Rust is given be the type `[T; n]`, where `n` is some *fixed* number. So, `[f64; 10]` is an array of 10 floating-point
+//@ An *array* in Rust is given by the type `[T; n]`, where `n` is some *fixed* number. So, `[f64; 10]` is an array of 10 floating-point
 //@ numbers, all one right next to the other in memory. Arrays are sized, and hence can be used like any other type. But we can also
 //@ borrow them as slices, e.g., to sort them.
 fn sort_array() {
 //@ numbers, all one right next to the other in memory. Arrays are sized, and hence can be used like any other type. But we can also
 //@ borrow them as slices, e.g., to sort them.
 fn sort_array() {
@@ -69,7 +69,7 @@ fn sort_array() {
 
 // ## External Dependencies
 //@ This leaves us with just one more piece to complete rgrep: Taking arguments from the command-line. We could now directly work on
 
 // ## External Dependencies
 //@ This leaves us with just one more piece to complete rgrep: Taking arguments from the command-line. We could now directly work on
-//@ [`std::env::args`](http://doc.rust-lang.org/stable/std/env/fn.args.html) to gain access to those arguments, and this would become
+//@ [`std::env::args`](https://doc.rust-lang.org/stable/std/env/fn.args.html) to gain access to those arguments, and this would become
 //@ a pretty boring lesson in string manipulation. Instead, I want to use this opportunity to show how easy it is to benefit from
 //@ other people's work in your program.
 //@ 
 //@ a pretty boring lesson in string manipulation. Instead, I want to use this opportunity to show how easy it is to benefit from
 //@ other people's work in your program.
 //@ 
@@ -95,7 +95,7 @@ pub mod rgrep {
     // We also import some other pieces that we will need.
     extern crate docopt;
     use self::docopt::Docopt;
     // We also import some other pieces that we will need.
     extern crate docopt;
     use self::docopt::Docopt;
-    use part12::{run, Options, OutputMode};
+    use part13::{run, Options, OutputMode};
     use std::process;
 
     // The `USAGE` string documents how the program is to be called. It's written in a format that `docopt` can parse.
     use std::process;
 
     // The `USAGE` string documents how the program is to be called. It's written in a format that `docopt` can parse.
@@ -131,8 +131,8 @@ Options:
         //@ encoded string, that is, a bunch of bytes in memory (`[u8]`) that are valid according of UTF-8. `str` is unsized. `&str`
         //@ stores the address of the character data, and their length. String literals like "this one" are
         //@ of type `&'static str`: They point right to the constant section of the binary, so 
         //@ encoded string, that is, a bunch of bytes in memory (`[u8]`) that are valid according of UTF-8. `str` is unsized. `&str`
         //@ stores the address of the character data, and their length. String literals like "this one" are
         //@ of type `&'static str`: They point right to the constant section of the binary, so 
-        //@ However, the borrow is valid for as long as the program runs, hence it has lifetime `'static`. Calling
-        //@ `to_string` will copy the string data into an owned buffer on the heap, and thus convert it to `String`.
+        //@ the reference is valid for the entire program. The bytes pointed to by `pattern`, on the other hand, are owned by someone else, 
+        //@ and we call `to_string` on it to copy the string data into a buffer on the heap that we own.
         let mode = if count {
             OutputMode::Count
         } else if sort {
         let mode = if count {
             OutputMode::Count
         } else if sort {
@@ -159,4 +159,4 @@ Options:
 // the pattern to regular-expression mode, and change `filter_lines` to honor this option. The documentation of regex is available from its crates.io site.
 // (You won't be able to use the `regex!` macro if you are on the stable or beta channel of Rust. But it wouldn't help for our use-case anyway.)
 
 // the pattern to regular-expression mode, and change `filter_lines` to honor this option. The documentation of regex is available from its crates.io site.
 // (You won't be able to use the `regex!` macro if you are on the stable or beta channel of Rust. But it wouldn't help for our use-case anyway.)
 
-//@ [index](main.html) | [previous](part13.html) | [next](part15.html)
+//@ [index](main.html) | [previous](part13.html) | [raw source](https://www.ralfj.de/git/rust-101.git/blob_plain/HEAD:/workspace/src/part14.rs) | [next](part15.html)