---

yaml
---
r: 229223
b: refs/heads/try
c: 50dd497
h: refs/heads/master
i:
  229221: 8664d4c
  229219: 36fbc79
  229215: d86a610
v: v3

Author: steveklabnik

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: aca2057ed5fb7af3f8905b2bc01f72fa001c35c8
 refs/heads/snap-stage3: 1af31d4974e33027a68126fa5a5a3c2c6491824f
-refs/heads/try: 340c25aebfee25534b8b95fa7ed7afd35e0b2e4b
+refs/heads/try: 50dd4977fda23d857d27ebae432c7a22f60d7489
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try/mk/main.mk

@@ -13,7 +13,7 @@
 ######################################################################
 
 # The version number
-CFG_RELEASE_NUM=1.3.0
+CFG_RELEASE_NUM=1.4.0
 
 # An optional number to put after the label, e.g. '.2' -> '-beta.2'
 # NB Make sure it starts with a dot to conform to semver pre-release

branches/try/src/doc/nomicon/atomics.md

@@ -127,7 +127,7 @@ fundamentally unsynchronized and compilers are free to aggressively optimize
 them. In particular, data accesses are free to be reordered by the compiler on
 the assumption that the program is single-threaded. The hardware is also free to
 propagate the changes made in data accesses to other threads as lazily and
-inconsistently as it wants. Mostly critically, data accesses are how data races
+inconsistently as it wants. Most critically, data accesses are how data races
 happen. Data accesses are very friendly to the hardware and compiler, but as
 we've seen they offer *awful* semantics to try to write synchronized code with.
 Actually, that's too weak.

branches/try/src/doc/nomicon/concurrency.md

@@ -7,7 +7,7 @@ an abstraction over them in a relatively uncontroversial way. Message passing,
 green threads, and async APIs are all diverse enough that any abstraction over
 them tends to involve trade-offs that we weren't willing to commit to for 1.0.
 
-However the way Rust models concurrency makes it relatively easy design your own
+However the way Rust models concurrency makes it relatively easy to design your own
 concurrency paradigm as a library and have everyone else's code Just Work
 with yours. Just require the right lifetimes and Send and Sync where appropriate
 and you're off to the races. Or rather, off to the... not... having... races.

branches/try/src/doc/nomicon/destructors.md

@@ -120,7 +120,7 @@ enum Link {
 will have its inner Box field dropped if and only if an instance stores the
 Next variant.
 
-In general this works really nice because you don't need to worry about
+In general this works really nicely because you don't need to worry about
 adding/removing drops when you refactor your data layout. Still there's
 certainly many valid usecases for needing to do trickier things with
 destructors.

branches/try/src/doc/nomicon/drop-flags.md

@@ -1,7 +1,7 @@
 % Drop Flags
 
 The examples in the previous section introduce an interesting problem for Rust.
-We have seen that's possible to conditionally initialize, deinitialize, and
+We have seen that it's possible to conditionally initialize, deinitialize, and
 reinitialize locations of memory totally safely. For Copy types, this isn't
 particularly notable since they're just a random pile of bits. However types
 with destructors are a different story: Rust needs to know whether to call a

branches/try/src/doc/nomicon/dropck.md

@@ -1,7 +1,7 @@
 % Drop Check
 
 We have seen how lifetimes provide us some fairly simple rules for ensuring
-that never read dangling references. However up to this point we have only ever
+that we never read dangling references. However up to this point we have only ever
 interacted with the *outlives* relationship in an inclusive manner. That is,
 when we talked about `'a: 'b`, it was ok for `'a` to live *exactly* as long as
 `'b`. At first glance, this seems to be a meaningless distinction. Nothing ever

branches/try/src/doc/nomicon/send-and-sync.md

@@ -3,15 +3,15 @@
 Not everything obeys inherited mutability, though. Some types allow you to
 multiply alias a location in memory while mutating it. Unless these types use
 synchronization to manage this access, they are absolutely not thread safe. Rust
-captures this with through the `Send` and `Sync` traits.
+captures this through the `Send` and `Sync` traits.
 
 * A type is Send if it is safe to send it to another thread.
 * A type is Sync if it is safe to share between threads (`&T` is Send).
 
 Send and Sync are fundamental to Rust's concurrency story. As such, a
 substantial amount of special tooling exists to make them work right. First and
 foremost, they're [unsafe traits][]. This means that they are unsafe to
-implement, and other unsafe code can  that they are correctly
+implement, and other unsafe code can assume that they are correctly
 implemented. Since they're *marker traits* (they have no associated items like
 methods), correctly implemented simply means that they have the intrinsic
 properties an implementor should have. Incorrectly implementing Send or Sync can

branches/try/src/doc/nomicon/subtyping.md

@@ -93,8 +93,8 @@ fn main() {
 
 The signature of `overwrite` is clearly valid: it takes mutable references to
 two values of the same type, and overwrites one with the other. If `&mut T` was
-variant over T, then `&mut &'a str` would be a subtype of `&mut &'static str`,
-since `&'a str` is a subtype of `&'static str`. Therefore the lifetime of
+variant over T, then `&mut &'static str` would be a subtype of `&mut &'a str`,
+since `&'static str` is a subtype of `&'a str`. Therefore the lifetime of
 `forever_str` would successfully be "shrunk" down to the shorter lifetime of
 `string`, and `overwrite` would be called successfully. `string` would
 subsequently be dropped, and `forever_str` would point to freed memory when we

branches/try/src/doc/nomicon/unchecked-uninit.md

@@ -77,7 +77,7 @@ contain any `Drop` types.
 However when working with uninitialized memory you need to be ever-vigilant for
 Rust trying to drop values you make like this before they're fully initialized.
 Every control path through that variable's scope must initialize the value
-before it ends, if has a destructor.
+before it ends, if it has a destructor.
 *[This includes code panicking](unwinding.html)*.
 
 And that's about it for working with uninitialized memory! Basically nothing

branches/try/src/doc/reference.md

@@ -538,8 +538,9 @@ balanced, but they are otherwise not special.
 In the matcher, `$` _name_ `:` _designator_ matches the nonterminal in the Rust
 syntax named by _designator_. Valid designators are `item`, `block`, `stmt`,
 `pat`, `expr`, `ty` (type), `ident`, `path`, `tt` (either side of the `=>`
-in macro rules). In the transcriber, the designator is already known, and so
-only the name of a matched nonterminal comes after the dollar sign.
+in macro rules), and `meta` (contents of an attribute). In the transcriber, the
+designator is already known, and so only the name of a matched nonterminal comes
+after the dollar sign.
 
 In both the matcher and transcriber, the Kleene star-like operator indicates
 repetition. The Kleene star operator consists of `$` and parentheses, optionally

branches/try/src/doc/trpl/concurrency.md

@@ -135,28 +135,34 @@ This gives us an error:
         ^~~~
 ```
 
-In this case, we know that our code _should_ be safe, but Rust isn't sure. And
-it's actually not safe: if we had a reference to `data` in each thread, and the
-thread takes ownership of the reference, we have three owners! That's bad. We
-can fix this by using the `Arc<T>` type, which is an atomic reference counted
-pointer. The 'atomic' part means that it's safe to share across threads.
+Rust knows this wouldn't be safe! If we had a reference to `data` in each
+thread, and the thread takes ownership of the reference, we'd have three
+owners!
+
+So, we need some type that lets us have more than one reference to a value and
+that we can share between threads, that is it must implement `Sync`.
+
+We'll use `Arc<T>`, rust's standard atomic reference count type, which
+wraps a value up with some extra runtime bookkeeping which allows us to
+share the ownership of the value between multiple references at the same time.
+
+The bookkeeping consists of a count of how many of these references exist to
+the value, hence the reference count part of the name.
+
+The Atomic part means `Arc<T>` can safely be accessed from multiple threads.
+To do this the compiler guarantees that mutations of the internal count use
+indivisible operations which can't have data races.
 
-`Arc<T>` assumes one more property about its contents to ensure that it is safe
-to share across threads: it assumes its contents are `Sync`. But in our
-case, we want to be able to mutate the value. We need a type that can ensure
-only one person at a time can mutate what's inside. For that, we can use the
-`Mutex<T>` type. Here's the second version of our code. It still doesn't work,
-but for a different reason:
 
 ```ignore
 use std::thread;
-use std::sync::Mutex;
+use std::sync::Arc;
 
 fn main() {
-    let mut data = Mutex::new(vec![1, 2, 3]);
+    let mut data = Arc::new(vec![1, 2, 3]);
 
     for i in 0..3 {
-        let data = data.lock().unwrap();
+        let data = data.clone();
         thread::spawn(move || {
             data[i] += 1;
         });
@@ -166,29 +172,29 @@ fn main() {
 }
 ```
 
-Here's the error:
+We now call `clone()` on our `Arc<T>`, which increases the internal count.
+This handle is then moved into the new thread.
+
+And... still gives us an error.
 
 ```text
-<anon>:9:9: 9:22 error: the trait `core::marker::Send` is not implemented for the type `std::sync::mutex::MutexGuard<'_, collections::vec::Vec<u32>>` [E0277]
-<anon>:11         thread::spawn(move || {
-                  ^~~~~~~~~~~~~
-<anon>:9:9: 9:22 note: `std::sync::mutex::MutexGuard<'_, collections::vec::Vec<u32>>` cannot be sent between threads safely
-<anon>:11         thread::spawn(move || {
-                  ^~~~~~~~~~~~~
+<anon>:11:24 error: cannot borrow immutable borrowed content as mutable
+<anon>:11                    data[i] += 1;
+                             ^~~~
 ```
 
-You see, [`Mutex`](../std/sync/struct.Mutex.html) has a
-[`lock`](../std/sync/struct.Mutex.html#method.lock)
-method which has this signature:
+`Arc<T>` assumes one more property about its contents to ensure that it is safe
+to share across threads: it assumes its contents are `Sync`. This is true for
+our value if it's immutable, but we want to be able to mutate it, so we need
+something else to persuade the borrow checker we know what we're doing.
 
-```ignore
-fn lock(&self) -> LockResult<MutexGuard<T>>
-```
+It looks like we need some type that allows us to safely mutate a shared value,
+for example a type that that can ensure only one thread at a time is able to
+mutate the value inside it at any one time.
 
-Because `Send` is not implemented for `MutexGuard<T>`, we can't transfer the
-guard across thread boundaries, which gives us our error.
+For that, we can use the `Mutex<T>` type!
 
-We can use `Arc<T>` to fix this. Here's the working version:
+Here's the working version:
 
 ```rust
 use std::sync::{Arc, Mutex};
@@ -209,9 +215,31 @@ fn main() {
 }
 ```
 
-We now call `clone()` on our `Arc`, which increases the internal count. This
-handle is then moved into the new thread. Let's examine the body of the
-thread more closely:
+
+If we'd tried to use `Mutex<T>` without wrapping it in an `Arc<T>` we would have
+seen another error like:
+
+```text
+error: the trait `core::marker::Send` is not implemented for the type `std::sync::mutex::MutexGuard<'_, collections::vec::Vec<u32>>` [E0277]
+ thread::spawn(move || {
+                  ^~~~~~~~~~~~~
+note: `std::sync::mutex::MutexGuard<'_, collections::vec::Vec<u32>>` cannot be sent between threads safely
+ thread::spawn(move || {
+                  ^~~~~~~~~~~~~
+```
+
+You see, [`Mutex`](../std/sync/struct.Mutex.html) has a
+[`lock`](../std/sync/struct.Mutex.html#method.lock)
+method which has this signature:
+
+```ignore
+fn lock(&self) -> LockResult<MutexGuard<T>>
+```
+
+and because `Send` is not implemented for `MutexGuard<T>`, we couldn't have
+transferred the guard across thread boundaries on it's own.
+
+Let's examine the body of the thread more closely:
 
 ```rust
 # use std::sync::{Arc, Mutex};

branches/try/src/doc/trpl/generics.md

@@ -6,7 +6,7 @@ Generics are called ‘parametric polymorphism’ in type theory,
 which means that they are types or functions that have multiple forms (‘poly’
 is multiple, ‘morph’ is form) over a given parameter (‘parametric’).
 
-Anyway, enough with type theory, let’s check out some generic code. Rust’s
+Anyway, enough type theory, let’s check out some generic code. Rust’s
 standard library provides a type, `Option<T>`, that’s generic:
 
 ```rust
@@ -27,7 +27,7 @@ let x: Option<i32> = Some(5);
 
 In the type declaration, we say `Option<i32>`. Note how similar this looks to
 `Option<T>`. So, in this particular `Option`, `T` has the value of `i32`. On
-the right-hand side of the binding, we do make a `Some(T)`, where `T` is `5`.
+the right-hand side of the binding, we make a `Some(T)`, where `T` is `5`.
 Since that’s an `i32`, the two sides match, and Rust is happy. If they didn’t
 match, we’d get an error:
 
@@ -101,11 +101,6 @@ fn takes_two_things<T, U>(x: T, y: U) {
 }
 ```
 
-Generic functions are most useful with ‘trait bounds’, which we’ll cover in the
-[section on traits][traits].
-
-[traits]: traits.html
-
 ## Generic structs
 
 You can store a generic type in a `struct` as well:
@@ -122,3 +117,28 @@ let float_origin = Point { x: 0.0, y: 0.0 };
 
 Similarly to functions, the `<T>` is where we declare the generic parameters,
 and we then use `x: T` in the type declaration, too.
+
+When you want to add an implementation for the generic struct, you just
+declare the type parameter after the `impl`:
+
+```rust
+# struct Point<T> {
+#     x: T,
+#     y: T,
+# }
+#
+impl<T> Point<T> {
+    fn swap(&mut self) {
+        std::mem::swap(&mut self.x, &mut self.y);
+    }
+}
+```
+
+So far you’ve seen generics that take absolutely any type. These are useful in
+many cases: you’ve already seen `Option<T>`, and later you’ll meet universal
+container types like [`Vec<T>`][Vec]. On the other hand, often you want to
+trade that flexibility for increased expressive power. Read about [trait
+bounds][traits] to see why and how.
+
+[traits]: traits.html
+[Vec]: ../std/vec/struct.Vec.html

branches/try/src/doc/trpl/operators-and-overloading.md

@@ -81,3 +81,55 @@ will let you do this:
 let p: Point = // ...
 let x: f64 = p + 2i32;
 ```
+
+# Using operator traits in generic structs
+
+Now that we know how operator traits are defined, we can define our `HasArea`
+trait and `Square` struct from the [traits chapter][traits] more generically:
+
+[traits]: traits.html
+
+```rust
+use std::ops::Mul;
+
+trait HasArea<T> {
+    fn area(&self) -> T;
+}
+
+struct Square<T> {
+    x: T,
+    y: T,
+    side: T,
+}
+
+impl<T> HasArea<T> for Square<T>
+        where T: Mul<Output=T> + Copy {
+    fn area(&self) -> T {
+        self.side * self.side
+    }
+}
+
+fn main() {
+    let s = Square {
+        x: 0.0f64,
+        y: 0.0f64,
+        side: 12.0f64,
+    };
+
+    println!("Area of s: {}", s.area());
+}
+```
+
+For `HasArea` and `Square`, we just declare a type parameter `T` and replace
+`f64` with it. The `impl` needs more involved modifications:
+
+```ignore
+impl<T> HasArea<T> for Square<T>
+        where T: Mul<Output=T> + Copy { ... }
+```
+
+The `area` method requires that we can multiply the sides, so we declare that
+type `T` must implement `std::ops::Mul`. Like `Add`, mentioned above, `Mul`
+itself takes an `Output` parameter: since we know that numbers don't change
+type when multiplied, we also set it to `T`. `T` must also support copying, so
+Rust doesn't try to move `self.side` into the return value.