---

yaml
---
r: 126623
b: refs/heads/snap-stage3
c: 50481f5
h: refs/heads/master
i:
  126621: 742f4e0
  126619: 1dec331
  126615: f00e6ce
  126607: 6f1fd0c
  126591: a095654
v: v3

Author: bors

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 7be8f0af0393dcdb077c2f6b1653836fd3fba235
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: d368ffdb26144fd1f451d3d8ba4344b0a8e82f99
+refs/heads/snap-stage3: 50481f55030f02543e1b3b6ae008d77b1cef3e98
 refs/heads/try: 502e4c045236682e9728539dc0d2b3d0b237f55c
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/mk/docs.mk

@@ -30,7 +30,7 @@ DOCS := index intro tutorial guide guide-ffi guide-macros guide-lifetimes \
 	guide-tasks guide-container guide-pointers guide-testing \
 	guide-runtime complement-bugreport \
 	complement-lang-faq complement-design-faq complement-project-faq rust \
-    rustdoc guide-unsafe
+    rustdoc guide-unsafe guide-strings
 
 PDF_DOCS := tutorial rust
 

branches/snap-stage3/src/doc/guide-strings.md

@@ -1,7 +1,5 @@
 % The Strings Guide
 
-# Strings
-
 Strings are an important concept to master in any programming language. If you
 come from a managed language background, you may be surprised at the complexity
 of string handling in a systems programming language. Efficient access and
@@ -14,7 +12,7 @@ Additionally, strings are not null-terminated and can contain null bytes.
 
 Rust has two main types of strings: `&str` and `String`.
 
-## &str
+# &str
 
 The first kind is a `&str`. This is pronounced a 'string slice.' String literals
 are of the type `&str`:
@@ -38,7 +36,7 @@ Like vector slices, string slices are simply a pointer plus a length. This
 means that they're a 'view' into an already-allocated string, such as a
 `&'static str` or a `String`.
 
-## String
+# String
 
 A `String` is a heap-allocated string. This string is growable, and is also
 guaranteed to be UTF-8.
@@ -73,9 +71,9 @@ let x: &[u8] = &[b'a', b'b'];
 let stack_str: &str = str::from_utf8(x).unwrap();
 ```
 
-## Best Practices
+# Best Practices
 
-### `String` vs. `&str`
+## `String` vs. `&str`
 
 In general, you should prefer `String` when you need ownership, and `&str` when
 you just need to borrow a string. This is very similar to using `Vec<T>` vs. `&[T]`,
@@ -98,7 +96,7 @@ need, and it can make your lifetimes more complex. Furthermore, you can pass
 either kind of string into `foo` by using `.as_slice()` on any `String` you
 need to pass in, so the `&str` version is more flexible.
 
-### Comparisons
+## Comparisons
 
 To compare a String to a constant string, prefer `as_slice()`...
 
@@ -123,7 +121,7 @@ fn compare(string: String) {
 Converting a `String` to a `&str` is cheap, but converting the `&str` to a
 `String` involves an allocation.
 
-## Other Documentation
+# Other Documentation
 
 * [the `&str` API documentation](/std/str/index.html)
 * [the `String` API documentation](std/string/index.html)

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

@@ -13,6 +13,7 @@ li {list-style-type: none; }
 
 # Guides
 
+* [Strings](guide-strings.html)
 * [Pointers](guide-pointers.html)
 * [References and Lifetimes](guide-lifetimes.html)
 * [Containers and Iterators](guide-container.html)

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

@@ -716,8 +716,8 @@ When an enum has simple integer discriminators, you can apply the `as` cast
 operator to convert a variant to its discriminator value as an `int`:
 
 ~~~~
-# #[deriving(Show)] enum Direction { North }
-println!( "{} => {}", North, North as int );
+# enum Direction { North, East, South, West }
+println!( "North => {}", North as int );
 ~~~~
 
 It is possible to set the discriminator values to chosen constant values:
@@ -748,15 +748,23 @@ includes an identifier of the actual form that it holds, much like the
 
 This declaration defines a type `Shape` that can refer to such shapes, and two
 functions, `Circle` and `Rectangle`, which can be used to construct values of
-the type. To create a new Circle, write `Circle(Point { x: 0.0, y: 0.0 },
-10.0)`.
+the type.
+
+To create a new `Circle`, write:
+
+~~~~
+# struct Point { x: f64, y: f64 }
+# enum Shape { Circle(Point, f64), Rectangle(Point, Point) }
+let circle = Circle(Point { x: 0.0, y: 0.0 }, 10.0);
+~~~~
 
 All of these variant constructors may be used as patterns. The only way to
 access the contents of an enum instance is the destructuring of a match. For
 example:
 
 ~~~~
 use std::f64;
+
 # struct Point {x: f64, y: f64}
 # enum Shape { Circle(Point, f64), Rectangle(Point, Point) }
 fn area(sh: Shape) -> f64 {
@@ -765,6 +773,9 @@ fn area(sh: Shape) -> f64 {
         Rectangle(Point { x, y }, Point { x: x2, y: y2 }) => (x2 - x) * (y2 - y)
     }
 }
+
+let rect = Rectangle(Point { x: 0.0, y: 0.0 }, Point { x: 2.0, y: 2.0 });
+println!("area: {}", area(rect));
 ~~~~
 
 Use a lone `_` to ignore an individual field. Ignore all fields of a variant
@@ -786,8 +797,9 @@ fn point_from_direction(dir: Direction) -> Point {
 Enum variants may also be structs. For example:
 
 ~~~~
-# #![feature(struct_variant)]
+#![feature(struct_variant)]
 use std::f64;
+
 # struct Point { x: f64, y: f64 }
 # fn square(x: f64) -> f64 { x * x }
 enum Shape {
@@ -802,7 +814,14 @@ fn area(sh: Shape) -> f64 {
         }
     }
 }
-# fn main() {}
+
+fn main() {
+    let rect = Rectangle {
+        top_left: Point { x: 0.0, y: 0.0 },
+        bottom_right: Point { x: 2.0, y: -2.0 }
+    };
+    println!("area: {}", area(rect));
+}
 ~~~~
 
 > *Note:* This feature of the compiler is currently gated behind the
@@ -986,6 +1005,10 @@ that are `Send`, but non-`Send` types can still *contain* types with custom
 destructors. Example of types which are not `Send` are [`Gc<T>`][gc] and
 [`Rc<T>`][rc], the shared-ownership types.
 
+> *Note:* See a [later chapter](#ownership-escape-hatches) for a discussion about
+> [`Gc<T>`][gc] and [`Rc<T>`][rc], and the [chapter about traits](#traits) for
+> a discussion about `Send`.
+
 [gc]: http://doc.rust-lang.org/std/gc/struct.Gc.html
 [rc]: http://doc.rust-lang.org/std/rc/struct.Rc.html
 
@@ -1645,6 +1668,13 @@ let string = "foobar";
 let view: &str = string.slice(0, 3);
 ~~~
 
+Square brackets denote indexing into a slice or fixed-size vector:
+
+~~~~
+let crayons: [&str, ..3] = ["BananaMania", "Beaver", "Bittersweet"];
+println!("Crayon 2 is '{}'", crayons[2]);
+~~~~
+
 Mutable slices also exist, just as there are mutable references. However, there
 are no mutable string slices. Strings are a multi-byte encoding (UTF-8) of
 Unicode code points, so they cannot be freely mutated without the ability to
@@ -1659,20 +1689,6 @@ view[0] = 5;
 let ys: &mut [int] = &mut [1i, 2i, 3i];
 ~~~
 
-Square brackets denote indexing into a slice or fixed-size vector:
-
-~~~~
-# enum Crayon { Almond, AntiqueBrass, Apricot,
-#               Aquamarine, Asparagus, AtomicTangerine,
-#               BananaMania, Beaver, Bittersweet };
-# fn draw_scene(c: Crayon) { }
-let crayons: [Crayon, ..3] = [BananaMania, Beaver, Bittersweet];
-match crayons[0] {
-    Bittersweet => draw_scene(crayons[0]),
-    _ => ()
-}
-~~~~
-
 A slice or fixed-size vector can be destructured using pattern matching:
 
 ~~~~
@@ -1738,6 +1754,8 @@ via dynamic checks and can fail at runtime.
 The `Rc` and `Gc` types are not sendable, so they cannot be used to share memory between tasks. Safe
 immutable and mutable shared memory is provided by the `sync::arc` module.
 
+> *Note:* See a [later chapter](#traits) for a discussion about `Send` and sendable types.
+
 # Closures
 
 Named functions, like those we've seen so far, may not refer to local
@@ -2609,7 +2627,7 @@ let nonsense = mycircle.radius() * mycircle.area();
 
 ## Deriving implementations for traits
 
-A small number of traits in `std` and `extra` can have implementations
+A small number of traits in can have implementations
 that can be automatically derived. These instances are specified by
 placing the `deriving` attribute on a data type declaration. For
 example, the following will mean that `Circle` has an implementation
@@ -2618,6 +2636,7 @@ of type `ABC` can be randomly generated and converted to a string:
 
 ~~~
 extern crate rand;
+use std::rand::{task_rng, Rng};
 
 #[deriving(PartialEq)]
 struct Circle { radius: f64 }
@@ -2628,6 +2647,13 @@ enum ABC { A, B, C }
 fn main() {
     // Use the Show trait to print "A, B, C."
     println!("{}, {}, {}", A, B, C);
+
+    let mut rng = task_rng();
+
+    // Use the Rand trait to generate a random variants.
+    for _ in range(0i, 10) {
+        println!("{}", rng.gen::<ABC>());
+    }
 }
 ~~~
 
@@ -3136,8 +3162,8 @@ In Rust terminology, we need a way to refer to other crates.
 For that, Rust offers you the `extern crate` declaration:
 
 ~~~
+// `num` ships with Rust.
 extern crate num;
-// `num` ships with Rust (much like `extra`; more details further down).
 
 fn main() {
     // The rational number '1/2':

branches/snap-stage3/src/libcollections/dlist.rs

@@ -87,12 +87,14 @@ impl<T> Rawlink<T> {
     }
 
     /// Convert the `Rawlink` into an Option value
-    fn resolve_immut(&self) -> Option<&T> {
-        unsafe { self.p.to_option() }
+    fn resolve_immut<'a>(&self) -> Option<&'a T> {
+        unsafe {
+            mem::transmute(self.p.to_option())
+        }
     }
 
     /// Convert the `Rawlink` into an Option value
-    fn resolve(&mut self) -> Option<&mut T> {
+    fn resolve<'a>(&mut self) -> Option<&'a mut T> {
         if self.p.is_null() {
             None
         } else {
@@ -278,6 +280,23 @@ impl<T> DList<T> {
     /// Move the last element to the front of the list.
     ///
     /// If the list is empty, do nothing.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::collections::{DList, Deque};
+    ///
+    /// let mut dl = DList::new();
+    /// dl.push_back(1i);
+    /// dl.push_back(2);
+    /// dl.push_back(3);
+    ///
+    /// dl.rotate_forward();
+    ///
+    /// for e in dl.iter() {
+    ///     println!("{}", e); // prints 3, then 1, then 2
+    /// }
+    /// ```
     #[inline]
     pub fn rotate_forward(&mut self) {
         self.pop_back_node().map(|tail| {
@@ -288,6 +307,23 @@ impl<T> DList<T> {
     /// Move the first element to the back of the list.
     ///
     /// If the list is empty, do nothing.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::collections::{DList, Deque};
+    ///
+    /// let mut dl = DList::new();
+    /// dl.push_back(1i);
+    /// dl.push_back(2);
+    /// dl.push_back(3);
+    ///
+    /// dl.rotate_backward();
+    ///
+    /// for e in dl.iter() {
+    ///     println!("{}", e); // prints 2, then 3, then 1
+    /// }
+    /// ```
     #[inline]
     pub fn rotate_backward(&mut self) {
         self.pop_front_node().map(|head| {
@@ -298,6 +334,25 @@ impl<T> DList<T> {
     /// Add all elements from `other` to the end of the list
     ///
     /// O(1)
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::collections::{DList, Deque};
+    ///
+    /// let mut a = DList::new();
+    /// let mut b = DList::new();
+    /// a.push_back(1i);
+    /// a.push_back(2);
+    /// b.push_back(3i);
+    /// b.push_back(4);
+    ///
+    /// a.append(b);
+    ///
+    /// for e in a.iter() {
+    ///     println!("{}", e); // prints 1, then 2, then 3, then 4
+    /// }
+    /// ```
     pub fn append(&mut self, mut other: DList<T>) {
         match self.list_tail.resolve() {
             None => *self = other,
@@ -320,6 +375,25 @@ impl<T> DList<T> {
     /// Add all elements from `other` to the beginning of the list
     ///
     /// O(1)
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::collections::{DList, Deque};
+    ///
+    /// let mut a = DList::new();
+    /// let mut b = DList::new();
+    /// a.push_back(1i);
+    /// a.push_back(2);
+    /// b.push_back(3i);
+    /// b.push_back(4);
+    ///
+    /// a.prepend(b);
+    ///
+    /// for e in a.iter() {
+    ///     println!("{}", e); // prints 3, then 4, then 1, then 2
+    /// }
+    /// ```
     #[inline]
     pub fn prepend(&mut self, mut other: DList<T>) {
         mem::swap(self, &mut other);
@@ -330,6 +404,25 @@ impl<T> DList<T> {
     /// or at the end.
     ///
     /// O(N)
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::collections::{DList, Deque};
+    ///
+    /// let mut a: DList<int> = DList::new();
+    /// a.push_back(2i);
+    /// a.push_back(4);
+    /// a.push_back(7);
+    /// a.push_back(8);
+    ///
+    /// // insert 11 before the first odd number in the list
+    /// a.insert_when(11, |&e, _| e % 2 == 1);
+    ///
+    /// for e in a.iter() {
+    ///     println!("{}", e); // prints 2, then 4, then 11, then 7, then 8
+    /// }
+    /// ```
     pub fn insert_when(&mut self, elt: T, f: |&T, &T| -> bool) {
         {
             let mut it = self.mut_iter();