---

yaml
---
r: 124559
b: refs/heads/master
c: 8859df7
h: refs/heads/master
i:
  124557: c749d72
  124555: 57bb287
  124551: 66eec27
  124543: 97a6705
v: v3

Author: bors

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: 69127f2f4e467aa206727f431819c5ce98810887
+refs/heads/master: 8859df7fb5feecd7c397566fcb966c9afabbb7b2
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: 9fc8394d3bce22ab483f98842434c84c396212ae
 refs/heads/try: dff46952ab5c4567d1b5b35bfbd8befc45cdd38e

trunk/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
 

trunk/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)

trunk/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)

trunk/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':

trunk/src/liballoc/rc.rs

@@ -148,6 +148,8 @@ fn main() {
 
 */
 
+#![stable]
+
 use core::mem::transmute;
 use core::cell::Cell;
 use core::clone::Clone;
@@ -171,6 +173,7 @@ struct RcBox<T> {
 
 /// Immutable reference counted pointer type
 #[unsafe_no_drop_flag]
+#[stable]
 pub struct Rc<T> {
     // FIXME #12808: strange names to try to avoid interfering with
     // field accesses of the contained type via Deref
@@ -179,6 +182,7 @@ pub struct Rc<T> {
     _noshare: marker::NoShare
 }
 
+#[stable]
 impl<T> Rc<T> {
     /// Construct a new reference-counted box
     pub fn new(value: T) -> Rc<T> {
@@ -203,6 +207,7 @@ impl<T> Rc<T> {
 
 impl<T> Rc<T> {
     /// Downgrade the reference-counted pointer to a weak reference
+    #[experimental = "Weak pointers may not belong in this module."]
     pub fn downgrade(&self) -> Weak<T> {
         self.inc_weak();
         Weak {
@@ -238,6 +243,7 @@ impl<T: Clone> Rc<T> {
     }
 }
 
+#[experimental = "Deref is experimental."]
 impl<T> Deref<T> for Rc<T> {
     /// Borrow the value contained in the reference-counted box
     #[inline(always)]
@@ -247,6 +253,7 @@ impl<T> Deref<T> for Rc<T> {
 }
 
 #[unsafe_destructor]
+#[experimental = "Drop is experimental."]
 impl<T> Drop for Rc<T> {
     fn drop(&mut self) {
         unsafe {
@@ -269,7 +276,7 @@ impl<T> Drop for Rc<T> {
     }
 }
 
-#[unstable]
+#[unstable = "Clone is unstable."]
 impl<T> Clone for Rc<T> {
     #[inline]
     fn clone(&self) -> Rc<T> {
@@ -278,22 +285,26 @@ impl<T> Clone for Rc<T> {
     }
 }
 
+#[stable]
 impl<T: Default> Default for Rc<T> {
     #[inline]
     fn default() -> Rc<T> {
         Rc::new(Default::default())
     }
 }
 
+#[unstable = "PartialEq is unstable."]
 impl<T: PartialEq> PartialEq for Rc<T> {
     #[inline(always)]
     fn eq(&self, other: &Rc<T>) -> bool { **self == **other }
     #[inline(always)]
     fn ne(&self, other: &Rc<T>) -> bool { **self != **other }
 }
 
+#[unstable = "Eq is unstable."]
 impl<T: Eq> Eq for Rc<T> {}
 
+#[unstable = "PartialOrd is unstable."]
 impl<T: PartialOrd> PartialOrd for Rc<T> {
     #[inline(always)]
     fn partial_cmp(&self, other: &Rc<T>) -> Option<Ordering> {
@@ -313,11 +324,13 @@ impl<T: PartialOrd> PartialOrd for Rc<T> {
     fn ge(&self, other: &Rc<T>) -> bool { **self >= **other }
 }
 
+#[unstable = "Ord is unstable."]
 impl<T: Ord> Ord for Rc<T> {
     #[inline]
     fn cmp(&self, other: &Rc<T>) -> Ordering { (**self).cmp(&**other) }
 }
 
+#[experimental = "Show is experimental."]
 impl<T: fmt::Show> fmt::Show for Rc<T> {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         (**self).fmt(f)
@@ -326,6 +339,7 @@ impl<T: fmt::Show> fmt::Show for Rc<T> {
 
 /// Weak reference to a reference-counted box
 #[unsafe_no_drop_flag]
+#[experimental = "Weak pointers may not belong in this module."]
 pub struct Weak<T> {
     // FIXME #12808: strange names to try to avoid interfering with
     // field accesses of the contained type via Deref
@@ -334,6 +348,7 @@ pub struct Weak<T> {
     _noshare: marker::NoShare
 }
 
+#[experimental = "Weak pointers may not belong in this module."]
 impl<T> Weak<T> {
     /// Upgrade a weak reference to a strong reference
     pub fn upgrade(&self) -> Option<Rc<T>> {
@@ -347,6 +362,7 @@ impl<T> Weak<T> {
 }
 
 #[unsafe_destructor]
+#[experimental = "Weak pointers may not belong in this module."]
 impl<T> Drop for Weak<T> {
     fn drop(&mut self) {
         unsafe {
@@ -364,6 +380,7 @@ impl<T> Drop for Weak<T> {
 }
 
 #[unstable]
+#[experimental = "Weak pointers may not belong in this module."]
 impl<T> Clone for Weak<T> {
     #[inline]
     fn clone(&self) -> Weak<T> {