---

yaml
---
r: 191191
b: refs/heads/try
c: e4010d1
h: refs/heads/master
i:
  191189: 3050699
  191187: 3014376
  191183: 8d3ed03
v: v3

Author: Manishearth

[refs]

@@ -2,7 +2,7 @@
 refs/heads/master: 809a554fca2d0ebc2ba50077016fe282a4064752
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: c64d671671aea2e44ee7fc6eb00ee75fc30ed7b9
-refs/heads/try: 33751ff8a7e2e013609d79f43da3d9a6d2c1f71e
+refs/heads/try: e4010d1bf6451447607b40c12dc683b9a53a9c78
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596

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

@@ -28,7 +28,7 @@ The other kind of comment is a doc comment. Doc comments use `///` instead of
 ///
 /// * `name` - The name of the person you'd like to greet.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// let name = "Steve";

branches/try/src/doc/trpl/static-and-dynamic-dispatch.md

@@ -102,49 +102,88 @@ reason.
 Rust provides dynamic dispatch through a feature called 'trait objects.' Trait
 objects, like `&Foo` or `Box<Foo>`, are normal values that store a value of
 *any* type that implements the given trait, where the precise type can only be
-known at runtime. The methods of the trait can be called on a trait object via
-a special record of function pointers (created and managed by the compiler).
+known at runtime.
 
-A function that takes a trait object is not specialized to each of the types
-that implements `Foo`: only one copy is generated, often (but not always)
-resulting in less code bloat. However, this comes at the cost of requiring
-slower virtual function calls, and effectively inhibiting any chance of
-inlining and related optimisations from occurring.
+A trait object can be obtained from a pointer to a concrete type that
+implements the trait by *casting* it (e.g. `&x as &Foo`) or *coercing* it
+(e.g. using `&x` as an argument to a function that takes `&Foo`).
 
-Trait objects are both simple and complicated: their core representation and
-layout is quite straight-forward, but there are some curly error messages and
-surprising behaviors to discover.
+These trait object coercions and casts also work for pointers like `&mut T` to
+`&mut Foo` and `Box<T>` to `Box<Foo>`, but that's all at the moment. Coercions
+and casts are identical.
 
-### Obtaining a trait object
+This operation can be seen as "erasing" the compiler's knowledge about the
+specific type of the pointer, and hence trait objects are sometimes referred to
+as "type erasure".
 
-There's two similar ways to get a trait object value: casts and coercions. If
-`T` is a type that implements a trait `Foo` (e.g. `u8` for the `Foo` above),
-then the two ways to get a `Foo` trait object out of a pointer to `T` look
-like:
+Coming back to the example above, we can use the same trait to perform dynamic
+dispatch with trait objects by casting:
 
-```{rust,ignore}
-let ref_to_t: &T = ...;
+```rust
+# trait Foo { fn method(&self) -> String; }
+# impl Foo for u8 { fn method(&self) -> String { format!("u8: {}", *self) } }
+# impl Foo for String { fn method(&self) -> String { format!("string: {}", *self) } }
 
-// `as` keyword for casting
-let cast = ref_to_t as &Foo;
+fn do_something(x: &Foo) {
+    x.method();
+}
 
-// using a `&T` in a place that has a known type of `&Foo` will implicitly coerce:
-let coerce: &Foo = ref_to_t;
+fn main() {
+    let x = 5u8;
+    do_something(&x as &Foo);
+}
+```
 
-fn also_coerce(_unused: &Foo) {}
-also_coerce(ref_to_t);
+or by coercing:
+
+```rust
+# trait Foo { fn method(&self) -> String; }
+# impl Foo for u8 { fn method(&self) -> String { format!("u8: {}", *self) } }
+# impl Foo for String { fn method(&self) -> String { format!("string: {}", *self) } }
+
+fn do_something(x: &Foo) {
+    x.method();
+}
+
+fn main() {
+    let x = "Hello".to_string();
+    do_something(&x);
+}
 ```
 
-These trait object coercions and casts also work for pointers like `&mut T` to
-`&mut Foo` and `Box<T>` to `Box<Foo>`, but that's all at the moment. Coercions
-and casts are identical.
+A function that takes a trait object is not specialized to each of the types
+that implements `Foo`: only one copy is generated, often (but not always)
+resulting in less code bloat. However, this comes at the cost of requiring
+slower virtual function calls, and effectively inhibiting any chance of
+inlining and related optimisations from occurring.
 
-This operation can be seen as "erasing" the compiler's knowledge about the
-specific type of the pointer, and hence trait objects are sometimes referred to
-as "type erasure".
+### Why pointers?
+
+Rust does not put things behind a pointer by default, unlike many managed
+languages, so types can have different sizes. Knowing the size of the value at
+compile time is important for things like passing it as an argument to a
+function, moving it about on the stack and allocating (and deallocating) space
+on the heap to store it.
+
+For `Foo`, we would need to have a value that could be at least either a
+`String` (24 bytes) or a `u8` (1 byte), as well as any other type for which
+dependent crates may implement `Foo` (any number of bytes at all). There's no
+way to guarantee that this last point can work if the values are stored without
+a pointer, because those other types can be arbitrarily large.
+
+Putting the value behind a pointer means the size of the value is not relevant
+when we are tossing a trait object around, only the size of the pointer itself.
 
 ### Representation
 
+The methods of the trait can be called on a trait object via a special record
+of function pointers traditionally called a 'vtable' (created and managed by
+the compiler).
+
+Trait objects are both simple and complicated: their core representation and
+layout is quite straight-forward, but there are some curly error messages and
+surprising behaviors to discover.
+
 Let's start simple, with the runtime representation of a trait object. The
 `std::raw` module contains structs with layouts that are the same as the
 complicated built-in types, [including trait objects][stdraw]:
@@ -265,23 +304,3 @@ let y = TraitObject {
 If `b` or `y` were owning trait objects (`Box<Foo>`), there would be a
 `(b.vtable.destructor)(b.data)` (respectively `y`) call when they went out of
 scope.
-
-### Why pointers?
-
-The use of language like "fat pointer" implies that a trait object is
-always a pointer of some form, but why?
-
-Rust does not put things behind a pointer by default, unlike many managed
-languages, so types can have different sizes. Knowing the size of the value at
-compile time is important for things like passing it as an argument to a
-function, moving it about on the stack and allocating (and deallocating) space
-on the heap to store it.
-
-For `Foo`, we would need to have a value that could be at least either a
-`String` (24 bytes) or a `u8` (1 byte), as well as any other type for which
-dependent crates may implement `Foo` (any number of bytes at all). There's no
-way to guarantee that this last point can work if the values are stored without
-a pointer, because those other types can be arbitrarily large.
-
-Putting the value behind a pointer means the size of the value is not relevant
-when we are tossing a trait object around, only the size of the pointer itself.

branches/try/src/liballoc/arc.rs

@@ -88,7 +88,7 @@ use heap::deallocate;
 
 /// An atomically reference counted wrapper for shared state.
 ///
-/// # Example
+/// # Examples
 ///
 /// In this example, a large vector of floats is shared between several tasks.
 /// With simple pipes, without `Arc`, a copy would have to be made for each

branches/try/src/liballoc/boxed.rs

@@ -133,7 +133,7 @@ impl<T : ?Sized> Box<T> {
 /// automatically managed that may lead to memory or other resource
 /// leak.
 ///
-/// # Example
+/// # Examples
 /// ```
 /// use std::boxed;
 ///

branches/try/src/liballoc/rc.rs

@@ -264,7 +264,7 @@ pub fn is_unique<T>(rc: &Rc<T>) -> bool {
 ///
 /// If the `Rc<T>` is not unique, an `Err` is returned with the same `Rc<T>`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::rc::{self, Rc};
@@ -298,7 +298,7 @@ pub fn try_unwrap<T>(rc: Rc<T>) -> Result<T, Rc<T>> {
 ///
 /// Returns `None` if the `Rc<T>` is not unique.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::rc::{self, Rc};

branches/try/src/libcollections/borrow.rs

@@ -127,7 +127,7 @@ impl<T> ToOwned for T where T: Clone {
 /// is desired, `to_mut` will obtain a mutable references to an owned
 /// value, cloning if necessary.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::borrow::Cow;

branches/try/src/libcollections/btree/map.rs

@@ -1177,7 +1177,7 @@ impl<'a, K: Ord, V> OccupiedEntry<'a, K, V> {
 impl<K, V> BTreeMap<K, V> {
     /// Gets an iterator over the entries of the map.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::BTreeMap;

branches/try/src/libcollections/fmt.rs

@@ -420,7 +420,7 @@ use string;
 ///
 ///   * args - a structure of arguments generated via the `format_args!` macro.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::fmt;

branches/try/src/libcollections/lib.rs

@@ -175,6 +175,7 @@ mod prelude {
 }
 
 /// An endpoint of a range of keys.
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
 pub enum Bound<T> {
     /// An inclusive bound.
     Included(T),

branches/try/src/libcollections/macros.rs

@@ -48,7 +48,7 @@ macro_rules! vec {
 /// Use the syntax described in `std::fmt` to create a value of type `String`.
 /// See `std::fmt` for more information.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// format!("test");

branches/try/src/libcollections/slice.rs

@@ -277,7 +277,7 @@ pub trait SliceExt {
     ///
     /// Panics if `size` is 0.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Print the adjacent pairs of a slice (i.e. `[1,2]`, `[2,3]`,
     /// `[3,4]`):
@@ -300,7 +300,7 @@ pub trait SliceExt {
     ///
     /// Panics if `size` is 0.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Print the slice two elements at a time (i.e. `[1,2]`,
     /// `[3,4]`, `[5]`):
@@ -390,7 +390,7 @@ pub trait SliceExt {
     /// `Err` is returned, containing the index where a matching
     /// element could be inserted while maintaining sorted order.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Looks up a series of four elements. The first is found, with a
     /// uniquely determined position; the second and third are not
@@ -416,7 +416,7 @@ pub trait SliceExt {
 
     /// Return the number of elements in the slice
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let a = [1, 2, 3];
@@ -427,7 +427,7 @@ pub trait SliceExt {
 
     /// Returns true if the slice has a length of 0
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let a = [1, 2, 3];
@@ -529,7 +529,7 @@ pub trait SliceExt {
     ///
     /// Panics if `a` or `b` are out of bounds.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut v = ["a", "b", "c", "d"];
@@ -549,7 +549,7 @@ pub trait SliceExt {
     ///
     /// Panics if `mid > len`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut v = [1, 2, 3, 4, 5, 6];
@@ -578,7 +578,7 @@ pub trait SliceExt {
 
     /// Reverse the order of elements in a slice, in place.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut v = [1, 2, 3];
@@ -638,7 +638,7 @@ pub trait SliceExt {
     /// shorter of `self.len()` and `src.len()`). Returns the number
     /// of elements copied.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut dst = [0, 0, 0];
@@ -676,7 +676,7 @@ pub trait SliceExt {
     /// `Err` is returned, containing the index where a matching
     /// element could be inserted while maintaining sorted order.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Looks up a series of four elements. The first is found, with a
     /// uniquely determined position; the second and third are not
@@ -707,7 +707,7 @@ pub trait SliceExt {
     /// Returns `true` if successful and `false` if the slice is at the
     /// last-ordered permutation.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let v: &mut [_] = &mut [0, 1, 2];
@@ -727,7 +727,7 @@ pub trait SliceExt {
     /// Returns `true` if successful and `false` if the slice is at the
     /// first-ordered permutation.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let v: &mut [_] = &mut [1, 0, 2];

branches/try/src/libcollections/str.rs

@@ -1377,7 +1377,7 @@ pub trait StrExt: Index<RangeFull, Output = str> {
     ///
     /// Will return `Err` if it's not possible to parse `self` into the type.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// assert_eq!("4".parse::<u32>(), Ok(4));

branches/try/src/libcore/finally.rs

@@ -16,7 +16,7 @@
 //! "finally" case. For advanced cases, the `try_finally` function can
 //! also be used. See that function for more details.
 //!
-//! # Example
+//! # Examples
 //!
 //! ```
 //! # #![feature(unboxed_closures)]
@@ -67,7 +67,7 @@ impl<T, F> Finally<T> for F where F: FnMut() -> T {
 /// function could have panicked at any point, so the values of the shared
 /// state may be inconsistent.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::finally::try_finally;

branches/try/src/libcore/fmt/num.rs

@@ -143,7 +143,7 @@ pub struct RadixFmt<T, R>(T, R);
 
 /// Constructs a radix formatter in the range of `2..36`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::fmt::radix;