---

yaml
---
r: 208376
b: refs/heads/snap-stage3
c: e216057
h: refs/heads/master
v: v3

Author: Manishearth

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 38a97becdf3e6a6157f6f7ec2d98ade8d8edc193
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: d13f765be8d202450bf106057e19d6bd57f51f6c
+refs/heads/snap-stage3: e216057dac596904478430858affa1e0bf2cf7d7
 refs/heads/try: 7b4ef47b7805a402d756fb8157101f64880a522f
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d

branches/snap-stage3/src/doc/index.md

@@ -5,15 +5,14 @@ to jump to any particular section.
 
 # Getting Started
 
-If you haven't seen Rust at all yet, the first thing you should read is the [30
-minute intro](intro.html). It will give you an overview of the basic ideas of Rust
-at a high level.
-
-Once you know you really want to learn Rust, the next step is reading [The
-Rust Programming Language](book/index.html). It is a lengthy explanation of
-Rust, its syntax, and its concepts. Upon completing the book, you'll be an
-intermediate Rust developer, and will have a good grasp of the fundamental
-ideas behind Rust.
+If you haven't seen Rust at all yet, the first thing you should read is the
+introduction to [The Rust Programming Language](book/index.html). It'll give
+you a good idea of what Rust is like.
+
+The book provides a lengthy explanation of Rust, its syntax, and its
+concepts. Upon completing the book, you'll be an intermediate Rust
+developer, and will have a good grasp of the fundamental ideas behind
+Rust.
 
 [Rust By Example][rbe] was originally a community resource, but was then
 donated to the Rust project. As the name implies, it teaches you Rust through a

branches/snap-stage3/src/doc/reference.md

@@ -31,23 +31,27 @@ You may also be interested in the [grammar].
 
 ## Unicode productions
 
-A few productions in Rust's grammar permit Unicode code points outside the ASCII
-range. We define these productions in terms of character properties specified
-in the Unicode standard, rather than in terms of ASCII-range code points. The
-section [Special Unicode Productions](#special-unicode-productions) lists these
-productions.
+A few productions in Rust's grammar permit Unicode code points outside the
+ASCII range. We define these productions in terms of character properties
+specified in the Unicode standard, rather than in terms of ASCII-range code
+points. The grammar has a [Special Unicode Productions][unicodeproductions]
+section that lists these productions.
+
+[unicodeproductions]: grammar.html#special-unicode-productions
 
 ## String table productions
 
 Some rules in the grammar — notably [unary
 operators](#unary-operator-expressions), [binary
-operators](#binary-operator-expressions), and [keywords](#keywords) — are
+operators](#binary-operator-expressions), and [keywords][keywords] — are
 given in a simplified form: as a listing of a table of unquoted, printable
 whitespace-separated strings. These cases form a subset of the rules regarding
 the [token](#tokens) rule, and are assumed to be the result of a
 lexical-analysis phase feeding the parser, driven by a DFA, operating over the
 disjunction of all such string table entries.
 
+[keywords]: grammar.html#keywords
+
 When such a string enclosed in double-quotes (`"`) occurs inside the grammar,
 it is an implicit reference to a single member of such a string table
 production. See [tokens](#tokens) for more information.
@@ -75,7 +79,7 @@ An identifier is any nonempty Unicode[^non_ascii_idents] string of the following
 - The first character has property `XID_start`
 - The remaining characters have property `XID_continue`
 
-that does _not_ occur in the set of [keywords](#keywords).
+that does _not_ occur in the set of [keywords][keywords].
 
 > **Note**: `XID_start` and `XID_continue` as character properties cover the
 > character ranges used to form the more familiar C and Java language-family
@@ -401,7 +405,7 @@ Symbols are a general class of printable [token](#tokens) that play structural
 roles in a variety of grammar productions. They are catalogued here for
 completeness as the set of remaining miscellaneous printable tokens that do not
 otherwise appear as [unary operators](#unary-operator-expressions), [binary
-operators](#binary-operator-expressions), or [keywords](#keywords).
+operators](#binary-operator-expressions), or [keywords][keywords].
 
 
 ## Paths
@@ -547,7 +551,7 @@ _name_ s that occur in its body. At the "current layer", they all must repeat
 the same number of times, so ` ( $( $i:ident ),* ; $( $j:ident ),* ) => ( $(
 ($i,$j) ),* )` is valid if given the argument `(a,b,c ; d,e,f)`, but not
 `(a,b,c ; d,e)`. The repetition walks through the choices at that layer in
-lockstep, so the former input transcribes to `( (a,d), (b,e), (c,f) )`.
+lockstep, so the former input transcribes to `(a,d), (b,e), (c,f)`.
 
 Nested repetitions are allowed.
 
@@ -611,7 +615,7 @@ module needs its own source file: [module definitions](#modules) can be nested
 within one file.
 
 Each source file contains a sequence of zero or more `item` definitions, and
-may optionally begin with any number of [attributes](#Items and attributes)
+may optionally begin with any number of [attributes](#items-and-attributes)
 that apply to the containing module, most of which influence the behavior of
 the compiler. The anonymous crate module can have additional attributes that
 apply to the crate as a whole.
@@ -653,7 +657,7 @@ There are several kinds of item:
 * [`use` declarations](#use-declarations)
 * [modules](#modules)
 * [functions](#functions)
-* [type aliases](#type-aliases)
+* [type definitions](grammar.html#type-definitions)
 * [structures](#structures)
 * [enumerations](#enumerations)
 * [constant items](#constant-items)
@@ -773,7 +777,7 @@ extern crate std as ruststd; // linking to 'std' under another name
 A _use declaration_ creates one or more local name bindings synonymous with
 some other [path](#paths). Usually a `use` declaration is used to shorten the
 path required to refer to a module item. These declarations may appear at the
-top of [modules](#modules) and [blocks](#blocks).
+top of [modules](#modules) and [blocks](grammar.html#block-expressions).
 
 > **Note**: Unlike in many languages,
 > `use` declarations in Rust do *not* declare linkage dependency with external crates.
@@ -1144,9 +1148,7 @@ let px: i32 = match p { Point(x, _) => x };
 ```
 
 A _unit-like struct_ is a structure without any fields, defined by leaving off
-the list of fields entirely. Such types will have a single value, just like
-the [unit value `()`](#unit-and-boolean-literals) of the unit type. For
-example:
+the list of fields entirely. Such types will have a single value. For example:
 
 ```
 struct Cookie;
@@ -2436,11 +2438,6 @@ comma:
 (0); // zero in parentheses
 ```
 
-### Unit expressions
-
-The expression `()` denotes the _unit value_, the only value of the type with
-the same name.
-
 ### Structure expressions
 
 There are several forms of structure expressions. A _structure expression_
@@ -3281,7 +3278,7 @@ constructor or `struct` field may refer, directly or indirectly, to the
 enclosing `enum` or `struct` type itself. Such recursion has restrictions:
 
 * Recursive types must include a nominal type in the recursion
-  (not mere [type definitions](#type-definitions),
+  (not mere [type definitions](grammar.html#type-definitions),
    or other structural types such as [arrays](#array,-and-slice-types) or [tuples](#tuple-types)).
 * A recursive `enum` item must have at least one non-recursive constructor
   (in order to give the recursion a basis case).

branches/snap-stage3/src/doc/trpl/SUMMARY.md

@@ -15,6 +15,7 @@
     * [Concurrency](concurrency.md)
     * [Error Handling](error-handling.md)
     * [FFI](ffi.md)
+    * [Borrow and AsRef](borrow-and-asref.md)
 * [Syntax and Semantics](syntax-and-semantics.md)
     * [Variable Bindings](variable-bindings.md)
     * [Functions](functions.md)

branches/snap-stage3/src/doc/trpl/borrow-and-asref.md

@@ -0,0 +1,93 @@
+% Borrow and AsRef
+
+The [`Borrow`][borrow] and [`AsRef`][asref] traits are very similar, but
+different. Here’s a quick refresher on what these two traits mean.
+
+[borrow]: ../std/borrow/trait.Borrow.html
+[asref]: ../std/convert/trait.AsRef.html
+
+# Borrow
+
+The `Borrow` trait is used when you’re writing a datastructure, and you want to
+use either an owned or borrowed type as synonymous for some purpose.
+
+For example, [`HashMap`][hashmap] has a [`get` method][get] which uses `Borrow`:
+
+```rust,ignore
+fn get<Q: ?Sized>(&self, k: &Q) -> Option<&V>
+    where K: Borrow<Q>,
+          Q: Hash + Eq
+```
+
+[hashmap]: ../std/collections/struct.HashMap.html
+[get]: ../std/collections/struct.HashMap.html#method.get
+
+This signature is pretty complicated. The `K` parameter is what we’re interested
+in here. It refers to a parameter of the `HashMap` itself:
+
+```rust,ignore
+struct HashMap<K, V, S = RandomState> {
+```
+
+The `K` parameter is the type of _key_ the `HashMap` uses. So, looking at
+the signature of `get()` again, we can use `get()` when the key implements
+`Borrow<Q>`. That way, we can make a `HashMap` which uses `String` keys,
+but use `&str`s when we’re searching:
+
+```rust
+use std::collections::HashMap;
+
+let mut map = HashMap::new();
+map.insert("Foo".to_string(), 42);
+
+assert_eq!(map.get("Foo"), Some(&42));
+```
+
+This is because the standard library has `impl Borrow<str> for String`.
+
+For most types, when you want to take an owned or borrowed type, a `&T` is
+enough. But one area where `Borrow` is effective is when there’s more than one
+kind of borrowed value. Slices are an area where this is especially true: you
+can have both an `&[T]` or a `&mut [T]`. If we wanted to accept both of these
+types, `Borrow` is up for it:
+
+```
+use std::borrow::Borrow;
+use std::fmt::Display;
+
+fn foo<T: Borrow<i32> + Display>(a: T) {
+    println!("a is borrowed: {}", a);
+}
+
+let mut i = 5;
+
+foo(&i);
+foo(&mut i);
+```
+
+This will print out `a is borrowed: 5` twice.
+
+# AsRef
+
+The `AsRef` trait is a conversion trait. It’s used for converting some value to
+a reference in generic code. Like this:
+
+```rust
+let s = "Hello".to_string();
+
+fn foo<T: AsRef<str>>(s: T) {
+    let slice = s.as_ref();
+}
+```
+
+# Which should I use?
+
+We can see how they’re kind of the same: they both deal with owned and borrowed
+versions of some type. However, they’re a bit different.
+
+Choose `Borrow` when you want to abstract over different kinds of borrowing, or
+when you’re building a datastructure that treats owned and borrowed values in
+equivalent ways, such as hashing and comparison.
+
+Choose `AsRef` when you want to convert something to a reference directly, and
+you’re writing generic code.

branches/snap-stage3/src/doc/trpl/compiler-plugins.md

@@ -176,7 +176,7 @@ for a full example, the core of which is reproduced here:
 
 ```ignore
 declare_lint!(TEST_LINT, Warn,
-              "Warn about items named 'lintme'")
+              "Warn about items named 'lintme'");
 
 struct Pass;
 

branches/snap-stage3/src/doc/trpl/lifetimes.md

@@ -5,7 +5,7 @@ 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. There are a few distinct concepts, each with its own chapter:
 
-* [ownership][ownership], ownership, the key concept
+* [ownership][ownership], the key concept
 * [borrowing][borrowing], and their associated feature ‘references’
 * lifetimes, which you’re reading now
 

branches/snap-stage3/src/doc/trpl/method-syntax.md

@@ -127,12 +127,12 @@ fn grow(&self) -> Circle {
 We just say we’re returning a `Circle`. With this method, we can grow a new
 circle to any arbitrary size.
 
-# Static methods
+# Associated functions
 
-You can also define static methods that do not take a `self` parameter. Here’s a
-pattern that’s very common in Rust code:
+You can also define associated functions that do not take a `self` parameter.
+Here’s a pattern that’s very common in Rust code:
 
-```
+```rust
 struct Circle {
     x: f64,
     y: f64,

branches/snap-stage3/src/doc/trpl/ownership.md

@@ -6,7 +6,7 @@ become quite acquainted. Ownership is how Rust achieves its largest goal,
 memory safety. There are a few distinct concepts, each with its own
 chapter:
 
-* ownership, which you’re reading now.
+* ownership, which you’re reading now
 * [borrowing][borrowing], and their associated feature ‘references’
 * [lifetimes][lifetimes], an advanced concept of borrowing
 
@@ -23,7 +23,7 @@ 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
+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.
 
@@ -41,7 +41,7 @@ With that in mind, let’s learn about ownership.
 
 # Ownership
 
-[`Variable bindings`][bindings] have a property in Rust: they ‘have ownership’
+[Variable bindings][bindings] have a property in Rust: they ‘have ownership’
 of what they’re bound to. This means that when a binding goes out of scope, the
 resource that they’re bound to are freed. For example:
 
@@ -106,8 +106,8 @@ take(v);
 println!("v[0] is: {}", v[0]);
 ```
 
-Same error: “use of moved value.” When we transfer ownership to something else,
-we say that we’ve ‘moved’ the thing we refer to. You don’t need some sort of
+Same error: ‘use of moved value’. When we transfer ownership to something else,
+we say that we’ve ‘moved’ the thing we refer to. You don’t need any sort of
 special annotation here, it’s the default thing that Rust does.
 
 ## The details
@@ -121,19 +121,19 @@ let v = vec![1, 2, 3];
 let v2 = v;
 ```
 
-The first line creates some data for the vector on the [stack][sh], `v`. The
-vector’s data, however, is stored on the [heap][sh], and so it contains a
-pointer to that data. When we move `v` to `v2`, it creates a copy of that pointer,
-for `v2`. Which would mean two pointers to the contents of the vector on the
-heap. That would be a problem: it would violate Rust’s safety guarantees by
-introducing a data race. Therefore, Rust forbids using `v` after we’ve done the
-move.
+The first line allocates memory for the vector object, `v`, and for the data it
+contains. The vector object is stored on the [stack][sh] and contains a pointer
+to the content (`[1, 2, 3]`) stored on the [heap][sh]. When we move `v` to `v2`,
+it creates a copy of that pointer, for `v2`. Which means that there would be two
+pointers to the content of the vector on the heap. It would violate Rust’s
+safety guarantees by introducing a data race. Therefore, Rust forbids using `v`
+after we’ve done the move.
 
 [sh]: the-stack-and-the-heap.html
 
 It’s also important to note that optimizations may remove the actual copy of
-the bytes, depending on circumstances. So it may not be as inefficient as it
-initially seems.
+the bytes on the stack, depending on circumstances. So it may not be as
+inefficient as it initially seems.
 
 ## `Copy` types