---

yaml
---
r: 206783
b: refs/heads/beta
c: 3981481
h: refs/heads/master
i:
  206781: 6942293
  206779: c66f0d0
  206775: 4a36ead
  206767: 6b1ddc1
  206751: 41a2e75
  206719: 40baf0d
v: v3

Author: Manishearth

[refs]

@@ -29,7 +29,7 @@ refs/tags/0.12.0: f0c419429ef30723ceaf6b42f9b5a2aeb5d2e2d1
 refs/heads/automation-fail: 1bf06495443584539b958873e04cc2f864ab10e4
 refs/heads/batch: b7fd822592a4fb577552d93010c4a4e14f314346
 refs/heads/building: 126db549b038c84269a1e4fe46f051b2c15d6970
-refs/heads/beta: 6faa8d6793e9136cbc2d852504f499144ddd1097
+refs/heads/beta: 398148193b1a536098292a5dcc9832a88d8db764
 refs/heads/windistfix: 7608dbad651f02e837ed05eef3d74a6662a6e928
 refs/tags/1.0.0-alpha: e42bd6d93a1d3433c486200587f8f9e12590a4d7
 refs/heads/tmp: 579e31929feff51dcaf8d444648eff8de735f91a

branches/beta/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/beta/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/beta/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/beta/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/beta/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
 

branches/beta/src/doc/trpl/primitive-types.md

@@ -15,7 +15,7 @@ let x = true;
 let y: bool = false;
 ```
 
-A common use of booleans is in [`if` statements][if].
+A common use of booleans is in [`if` conditionals][if].
 
 [if]: if.html
 

branches/beta/src/doc/trpl/while-loops.md

@@ -1,4 +1,4 @@
-% while loops
+% while Loops
 
 Rust also has a `while` loop. It looks like this:
 

branches/beta/src/libcollections/borrow.rs

@@ -37,6 +37,11 @@ use self::Cow::*;
 /// trait: if `T: Borrow<U>`, then `&U` can be borrowed from `&T`.  A given
 /// type can be borrowed as multiple different types. In particular, `Vec<T>:
 /// Borrow<Vec<T>>` and `Vec<T>: Borrow<[T]>`.
+///
+/// `Borrow` is very similar to, but different than, `AsRef`. See
+/// [the book][book] for more.
+///
+/// [book]: ../../book/borrow-and-asref.html
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Borrow<Borrowed: ?Sized> {
     /// Immutably borrows from an owned value.

branches/beta/src/libcore/convert.rs

@@ -24,6 +24,11 @@ use marker::Sized;
 
 /// A cheap, reference-to-reference conversion.
 ///
+/// `AsRef` is very similar to, but different than, `Borrow`. See
+/// [the book][book] for more.
+///
+/// [book]: ../../book/borrow-and-asref.html
+///
 /// # Examples
 ///
 /// Both `String` and `&str` implement `AsRef<str>`: