TRPL: ownership, borrowing, and lifetimes

Also, as @huonw guessed, move semantics really _does_ make more sense as
a sub-chapter of ownership.

Author: steveklabnik

src/doc/trpl/SUMMARY.md

@@ -26,7 +26,6 @@
     * [References and Borrowing](references-and-borrowing.md)
     * [Lifetimes](lifetimes.md)
     * [Mutability](mutability.md)
-    * [Move semantics](move-semantics.md)
     * [Enums](enums.md)
     * [Match](match.md)
     * [Structs](structs.md)

src/doc/trpl/lifetimes.md

@@ -1,3 +1,298 @@
 % Lifetimes
 
-Coming Soon! Until then, check out the [ownership](ownership.html) chapter.
+This guide is one of three presenting Rust’s ownership system. This is one of
+Rust’s most unique and compelling features, with which Rust developers should
+become quite acquainted. Ownership is how Rust achieves its largest goal,
+memory safety. The there are a few distinct concepts, each with its own
+chapter:
+
+* [ownership][ownership], ownership, the key concept
+* [borrowing][borrowing], and their associated feature ‘references’
+* lifetimes, which you’re reading now
+
+These three chapters are related, and in order. You’ll need all three to fully
+understand the ownership system.
+
+[ownership]: ownership.html
+[borrowing]: references-and-borrowing.html
+
+# Meta
+
+Before we get to the details, two important notes about the ownership system.
+
+Rust has a focus on safety and speed. It accomplishes these goals through many
+‘zero-cost abstractions’, which means that in Rust, abstractions cost as little
+as possible in order to make them work. The ownership system is a prime example
+of a zero cost abstraction. All of the analysis we’ll talk about in this guide
+is _done at compile time_. You do not pay any run-time cost for any of these
+features.
+
+However, this system does have a certain cost: learning curve. Many new users
+to Rust experience something we like to call ‘fighting with the borrow
+checker’, where the Rust compiler refuses to compile a program that the author
+thinks is valid. This often happens because the programmer’s mental model of
+how ownership should work doesn’t match the actual rules that Rust implements.
+You probably will experience similar things at first. There is good news,
+however: more experienced Rust developers report that once they work with the
+rules of the ownership system for a period of time, they fight the borrow
+checker less and less.
+
+With that in mind, let’s learn about lifetimes.
+
+# Lifetimes
+
+Lending out a reference to a resource that someone else owns can be
+complicated, however. For example, imagine this set of operations:
+
+- I acquire a handle to some kind of resource.
+- I lend you a reference to the resource.
+- I decide I’m done with the resource, and deallocate it, while you still have
+  your reference.
+- You decide to use the resource.
+
+Uh oh! Your reference is pointing to an invalid resource. This is called a
+dangling pointer or ‘use after free’, when the resource is memory.
+
+To fix this, we have to make sure that step four never happens after step
+three. The ownership system in Rust does this through a concept called
+lifetimes, which describe the scope that a reference is valid for.
+
+When we have a function that takes a reference by argument, we can be implicit
+or explicit about the lifetime of the reference:
+
+```rust
+// implicit
+fn foo(x: &i32) {
+}
+
+// explicit
+fn bar<'a>(x: &'a i32) {
+}
+```
+
+The `'a` reads ‘the lifetime a’. Technically, every reference has some `'foo`
+associated with it, but the compiler lets you elide them in common cases.
+Before we get to that, though, let’s break the explicit example down:
+
+```rust,ignore
+fn bar<'a>(...)
+```
+
+This part declares our lifetimes. This says that `foo` has one lifetime, `'a`.
+If we had two parameters, it would look like this:
+
+```rust,ignore
+fn bar<'a, 'b>(...)
+```
+
+Then in our parameter list, we use the lifetimes we’ve named:
+
+```rust,ignore
+...(x: &'a i32)
+```
+
+If we wanted an `&mut` reference, we’d do this:
+
+```rust,ignore
+...(x: &' i32)
+```
+
+If you compare `&mut i32` to `&'a mut i32`, they’re the same, it’s just that
+the lifetime `'a` has snuck in between the `&` and the `mut i32`. We read `&mut
+i32` as ‘a mutable reference to an i32’ and `&'a mut i32` as ‘a mutable
+reference to an `i32` with the lifetime `'a`’.
+
+You’ll also need explicit lifetimes when working with [`struct`][structs]s:
+
+```rust
+struct Foo<'a> {
+    x: &'a i32,
+}
+
+fn main() {
+    let y = &5; // this is the same as `let _y = 5; let y = &_y;`
+    let f = Foo { x: y };
+
+    println!("{}", f.x);
+}
+```
+
+[struct]: structs.html
+
+As you can see, `struct`s can also have lifetimes. In a similar way to functions,
+
+```rust
+struct Foo<'a> {
+# x: &'a i32,
+# }
+```
+
+declares a lifetime, and
+
+```rust
+# struct Foo<'a> {
+x: &'a i32,
+# }
+```
+
+uses it. So why do we need a lifetime here? We need to ensure that any reference
+to a `Foo` cannot outlive the reference to an `i32` it contains.
+
+## Thinking in scopes
+
+A way to think about lifetimes is to visualize the scope that a reference is
+valid for. For example:
+
+```rust
+fn main() {
+    let y = &5;     // -+ y goes into scope
+                    //  |
+    // stuff        //  |
+                    //  |
+}                   // -+ y goes out of scope
+```
+
+Adding in our `Foo`:
+
+```rust
+struct Foo<'a> {
+    x: &'a i32,
+}
+
+fn main() {
+    let y = &5;           // -+ y goes into scope
+    let f = Foo { x: y }; // -+ f goes into scope
+    // stuff              //  |
+                          //  |
+}                         // -+ f and y go out of scope
+```
+
+Our `f` lives within the scope of `y`, so everything works. What if it didn’t?
+This code won’t work:
+
+```rust,ignore
+struct Foo<'a> {
+    x: &'a i32,
+}
+
+fn main() {
+    let x;                    // -+ x goes into scope
+                              //  |
+    {                         //  |
+        let y = &5;           // ---+ y goes into scope
+        let f = Foo { x: y }; // ---+ f goes into scope
+        x = &f.x;             //  | | error here
+    }                         // ---+ f and y go out of scope
+                              //  |
+    println!("{}", x);        //  |
+}                             // -+ x goes out of scope
+```
+
+Whew! As you can see here, the scopes of `f` and `y` are smaller than the scope
+of `x`. But when we do `x = &f.x`, we make `x` a reference to something that’s
+about to go out of scope.
+
+Named lifetimes are a way of giving these scopes a name. Giving something a
+name is the first step towards being able to talk about it.
+
+## 'static
+
+The lifetime named ‘static’ is a special lifetime. It signals that something
+has the lifetime of the entire program. Most Rust programmers first come across
+`'static` when dealing with strings:
+
+```rust
+let x: &'static str = "Hello, world.";
+```
+
+String literals have the type `&'static str` because the reference is always
+alive: they are baked into the data segment of the final binary. Another
+example are globals:
+
+```rust
+static FOO: i32 = 5;
+let x: &'static i32 = &FOO;
+```
+
+This adds an `i32` to the data segment of the binary, and `x` is a reference
+to it.
+
+## Lifetime Elision
+
+Rust supports powerful local type inference in function bodies, but it’s
+forbidden in item signatures to allow reasoning about the types just based in
+the item signature alone. However, for ergonomic reasons a very restricted
+secondary inference algorithm called “lifetime elision” applies in function
+signatures. It infers only based on the signature components themselves and not
+based on the body of the function, only infers lifetime parameters, and does
+this with only three easily memorizable and unambiguous rules. This makes
+lifetime elision a shorthand for writing an item signature, while not hiding
+away the actual types involved as full local inference would if applied to it.
+
+When talking about lifetime elision, we use the term *input lifetime* and
+*output lifetime*. An *input lifetime* is a lifetime associated with a parameter
+of a function, and an *output lifetime* is a lifetime associated with the return
+value of a function. For example, this function has an input lifetime:
+
+```rust,ignore
+fn foo<'a>(bar: &'a str)
+```
+
+This one has an output lifetime:
+
+```rust,ignore
+fn foo<'a>() -> &'a str
+```
+
+This one has a lifetime in both positions:
+
+```rust,ignore
+fn foo<'a>(bar: &'a str) -> &'a str
+```
+
+Here are the three rules:
+
+* Each elided lifetime in a function’s arguments becomes a distinct lifetime
+  parameter.
+
+* If there is exactly one input lifetime, elided or not, that lifetime is
+  assigned to all elided lifetimes in the return values of that function.
+
+* If there are multiple input lifetimes, but one of them is `&self` or `&mut
+  self`, the lifetime of `self` is assigned to all elided output lifetimes.
+
+Otherwise, it is an error to elide an output lifetime.
+
+### Examples
+
+Here are some examples of functions with elided lifetimes.  We’ve paired each
+example of an elided lifetime with its expanded form.
+
+```rust,ignore
+fn print(s: &str); // elided
+fn print<'a>(s: &'a str); // expanded
+
+fn debug(lvl: u32, s: &str); // elided
+fn debug<'a>(lvl: u32, s: &'a str); // expanded
+
+// In the preceding example, `lvl` doesn’t need a lifetime because it’s not a
+// reference (`&`). Only things relating to references (such as a `struct`
+// which contains a reference) need lifetimes.
+
+fn substr(s: &str, until: u32) -> &str; // elided
+fn substr<'a>(s: &'a str, until: u32) -> &'a str; // expanded
+
+fn get_str() -> &str; // ILLEGAL, no inputs
+
+fn frob(s: &str, t: &str) -> &str; // ILLEGAL, two inputs
+fn frob<'a, 'b>(s: &'a str, t: &'b str) -> &str; // Expanded: Output lifetime is unclear
+
+fn get_mut(&mut self) -> &mut T; // elided
+fn get_mut<'a>(&'a mut self) -> &'a mut T; // expanded
+
+fn args<T:ToCStr>(&mut self, args: &[T]) -> &mut Command // elided
+fn args<'a, 'b, T:ToCStr>(&'a mut self, args: &'b [T]) -> &'a mut Command // expanded
+
+fn new(buf: &mut [u8]) -> BufWriter; // elided
+fn new<'a>(buf: &'a mut [u8]) -> BufWriter<'a> // expanded
+```