---

yaml
---
r: 191189
b: refs/heads/try
c: 8e082f7
h: refs/heads/master
i:
  191187: 3014376
v: v3

Author: Dave Huseby

[refs]

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

branches/try/configure

@@ -760,8 +760,9 @@ fi
 # Force bitrig to build with clang; gcc doesn't like us there
 if [ $CFG_OSTYPE = unknown-bitrig ]
 then
-    step_msg "on Bitrig, forcing use of clang"
+    step_msg "on Bitrig, forcing use of clang, disabling jemalloc"
     CFG_ENABLE_CLANG=1
+    CFG_ENABLE_JEMALLOC=0
 fi
 
 if [ -z "$CFG_ENABLE_CLANG" -a -z "$CFG_GCC" ]

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.
 ///
-/// # Examples
+/// # Example
 ///
 /// ```rust
 /// let name = "Steve";

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

@@ -102,87 +102,48 @@ 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.
-
-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`).
-
-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.
-
-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".
-
-Coming back to the example above, we can use the same trait to perform dynamic
-dispatch with trait objects by casting:
-
-```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 = 5u8;
-    do_something(&x as &Foo);
-}
-```
-
-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);
-}
-```
+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).
 
 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.
 
-### Why pointers?
+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.
 
-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.
+### Obtaining a trait object
 
-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.
+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:
 
-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.
+```{rust,ignore}
+let ref_to_t: &T = ...;
 
-### Representation
+// `as` keyword for casting
+let cast = ref_to_t as &Foo;
 
-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).
+// using a `&T` in a place that has a known type of `&Foo` will implicitly coerce:
+let coerce: &Foo = ref_to_t;
 
-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.
+fn also_coerce(_unused: &Foo) {}
+also_coerce(ref_to_t);
+```
+
+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.
+
+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".
+
+### Representation
 
 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
@@ -304,3 +265,23 @@ 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.
 ///
-/// # Examples
+/// # Example
 ///
 /// 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.
 ///
-/// # Examples
+/// # Example
 /// ```
 /// 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>`.
 ///
-/// # Examples
+/// # Example
 ///
 /// ```
 /// 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.
 ///
-/// # Examples
+/// # Example
 ///
 /// ```
 /// 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.
 ///
-/// # Examples
+/// # Example
 ///
 /// ```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.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// ```
     /// 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.
 ///
-/// # Examples
+/// # Example
 ///
 /// ```rust
 /// use std::fmt;

branches/try/src/libcollections/lib.rs

@@ -175,7 +175,6 @@ 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.
 ///
-/// # Examples
+/// # Example
 ///
 /// ```
 /// format!("test");

branches/try/src/libcollections/slice.rs

@@ -277,7 +277,7 @@ pub trait SliceExt {
     ///
     /// Panics if `size` is 0.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// 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.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// 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.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// 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
     ///
-    /// # Examples
+    /// # Example
     ///
     /// ```
     /// let a = [1, 2, 3];
@@ -427,7 +427,7 @@ pub trait SliceExt {
 
     /// Returns true if the slice has a length of 0
     ///
-    /// # Examples
+    /// # Example
     ///
     /// ```
     /// let a = [1, 2, 3];
@@ -529,7 +529,7 @@ pub trait SliceExt {
     ///
     /// Panics if `a` or `b` are out of bounds.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// ```rust
     /// let mut v = ["a", "b", "c", "d"];
@@ -549,7 +549,7 @@ pub trait SliceExt {
     ///
     /// Panics if `mid > len`.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// ```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.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// ```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.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// ```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.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// 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.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// ```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.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// ```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.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// ```
     /// 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.
 //!
-//! # Examples
+//! # Example
 //!
 //! ```
 //! # #![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.
 ///
-/// # Examples
+/// # Example
 ///
 /// ```
 /// 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`.
 ///
-/// # Examples
+/// # Example
 ///
 /// ```
 /// use std::fmt::radix;