---

yaml
---
r: 153005
b: refs/heads/try2
c: 3806575
h: refs/heads/master
i:
  153003: 18d4176
v: v3

Author: bors

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: c9dcf8ce32893ae94eba5eda6fed1f38e63fe56d
+refs/heads/try2: 380657557cb3793d39dfc0d2321fc946cb3496f5
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/src/doc/intro.md

@@ -252,7 +252,7 @@ fn main() {
 }
 ```
 
-This will result an error indicating that the value is no longer in scope:
+The compiler will produce an error indicating that the value is no longer in scope:
 
 ```text
 concurrency.rs:12:20: 12:27 error: use of moved value: 'numbers'

branches/try2/src/etc/vim/syntax/rust.vim

@@ -77,34 +77,39 @@ syn keyword   rustEnumVariant Ok Err
 "syn keyword rustFunction drop
 
 " Types and traits {{{3
-syn keyword rustTrait Ascii AsciiCast OwnedAsciiCast AsciiStr IntoBytes
+syn keyword rustTrait Ascii AsciiCast OwnedAsciiCast AsciiStr
+syn keyword rustTrait IntoBytes
 syn keyword rustTrait ToCStr
 syn keyword rustTrait Char
 syn keyword rustTrait Clone
-syn keyword rustTrait Eq Ord PartialEq PartialOrd Ordering Equiv
+syn keyword rustTrait PartialEq PartialOrd Eq Ord Equiv
+syn keyword rustEnum Ordering
 syn keyword rustEnumVariant Less Equal Greater
-syn keyword rustTrait Container Mutable Map MutableMap Set MutableSet
-syn keyword rustTrait FromIterator Extendable
-syn keyword rustTrait Iterator DoubleEndedIterator RandomAccessIterator CloneableIterator
-syn keyword rustTrait OrdIterator MutableDoubleEndedIterator ExactSize
-syn keyword rustTrait Num NumCast CheckedAdd CheckedSub CheckedMul
-syn keyword rustTrait Signed Unsigned
-syn keyword rustTrait Primitive Int Float FloatMath ToPrimitive FromPrimitive
-"syn keyword rustTrait Expect
+syn keyword rustTrait Collection Mutable Map MutableMap
+syn keyword rustTrait Set MutableSet
+syn keyword rustTrait FromIterator Extendable ExactSize
+syn keyword rustTrait Iterator DoubleEndedIterator
+syn keyword rustTrait RandomAccessIterator CloneableIterator
+syn keyword rustTrait OrdIterator MutableDoubleEndedIterator
+syn keyword rustTrait Num NumCast CheckedAdd CheckedSub CheckedMul CheckedDiv
+syn keyword rustTrait Signed Unsigned Primitive Int Float
+syn keyword rustTrait FloatMath ToPrimitive FromPrimitive
 syn keyword rustTrait Box
 syn keyword rustTrait GenericPath Path PosixPath WindowsPath
 syn keyword rustTrait RawPtr
 syn keyword rustTrait Buffer Writer Reader Seek
-syn keyword rustTrait Str StrVector StrSlice OwnedStr IntoMaybeOwned
-syn keyword rustTrait StrAllocating
+syn keyword rustTrait Str StrVector StrSlice OwnedStr
+syn keyword rustTrait IntoMaybeOwned StrAllocating
 syn keyword rustTrait ToStr IntoStr
 syn keyword rustTrait Tuple1 Tuple2 Tuple3 Tuple4
 syn keyword rustTrait Tuple5 Tuple6 Tuple7 Tuple8
 syn keyword rustTrait Tuple9 Tuple10 Tuple11 Tuple12
-syn keyword rustTrait CloneableVector ImmutableCloneableVector MutableCloneableVector
+syn keyword rustTrait CloneableVector ImmutableCloneableVector
+syn keyword rustTrait MutableCloneableVector MutableOrdVector
 syn keyword rustTrait ImmutableVector MutableVector
-syn keyword rustTrait ImmutableEqVector ImmutableOrdVector MutableOrdVector
-syn keyword rustTrait Vector VectorVector OwnedVector MutableVectorAllocating
+syn keyword rustTrait ImmutableEqVector ImmutableOrdVector
+syn keyword rustTrait Vector VectorVector
+syn keyword rustTrait MutableVectorAllocating
 syn keyword rustTrait String
 syn keyword rustTrait Vec
 

branches/try2/src/liballoc/rc.rs

@@ -1,4 +1,4 @@
-// Copyright 2013 The Rust Project Developers. See the COPYRIGHT
+// Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.
 //
@@ -10,16 +10,141 @@
 
 /*! Task-local reference-counted boxes (`Rc` type)
 
-The `Rc` type provides shared ownership of an immutable value. Destruction is deterministic, and
-will occur as soon as the last owner is gone. It is marked as non-sendable because it avoids the
-overhead of atomic reference counting.
+The `Rc` type provides shared ownership of an immutable value. Destruction is
+deterministic, and will occur as soon as the last owner is gone. It is marked
+as non-sendable because it avoids the overhead of atomic reference counting.
 
-The `downgrade` method can be used to create a non-owning `Weak` pointer to the box. A `Weak`
-pointer can be upgraded to an `Rc` pointer, but will return `None` if the value has already been
-freed.
+The `downgrade` method can be used to create a non-owning `Weak` pointer to the
+box. A `Weak` pointer can be upgraded to an `Rc` pointer, but will return
+`None` if the value has already been freed.
 
-For example, a tree with parent pointers can be represented by putting the nodes behind `Strong`
-pointers, and then storing the parent pointers as `Weak` pointers.
+For example, a tree with parent pointers can be represented by putting the
+nodes behind strong `Rc` pointers, and then storing the parent pointers as
+`Weak` pointers.
+
+
+## Examples
+
+Consider a scenario where a set of Gadgets are owned by a given Owner.  We want
+to have our Gadgets point to their Owner.  We can't do this with unique
+ownership, because more than one gadget may belong to the same Owner.  Rc
+allows us to share an Owner between multiple Gadgets, and have the Owner kept
+alive as long as any Gadget points at it.
+
+```rust
+use std::rc::Rc;
+
+struct Owner {
+    name: String
+    // ...other fields
+}
+
+struct Gadget {
+    id: int,
+    owner: Rc<Owner>
+    // ...other fields
+}
+
+fn main() {
+    // Create a reference counted Owner.
+    let gadget_owner : Rc<Owner> = Rc::new(
+            Owner { name: String::from_str("Gadget Man") }
+    );
+
+    // Create Gadgets belonging to gadget_owner.  To increment the reference
+    // count we clone the Rc object.
+    let gadget1 = Gadget { id: 1, owner: gadget_owner.clone() };
+    let gadget2 = Gadget { id: 2, owner: gadget_owner.clone() };
+
+    drop(gadget_owner);
+
+    // Despite dropping gadget_owner, we're still able to print out the name of
+    // the Owner of the Gadgets. This is because we've only dropped the
+    // reference count object, not the Owner it wraps. As long as there are
+    // other Rc objects pointing at the same Owner, it will stay alive. Notice
+    // that the Rc wrapper around Gadget.owner gets automatically dereferenced
+    // for us.
+    println!("Gadget {} owned by {}", gadget1.id, gadget1.owner.name);
+    println!("Gadget {} owned by {}", gadget2.id, gadget2.owner.name);
+
+    // At the end of the method, gadget1 and gadget2 get destroyed, and with
+    // them the last counted references to our Owner.  Gadget Man now gets
+    // destroyed as well.
+}
+```
+
+If our requirements change, and we also need to be able to traverse from
+Owner->Gadget, we will run into problems: an Rc pointer from Owner->Gadget
+introduces a cycle between the objects.  This means that their reference counts
+can never reach 0, and the objects will stay alive: a memory leak.  In order to
+get around this, we can use `Weak` pointers.  These are reference counted
+pointers that don't keep an object alive if there are no normal `Rc` (or
+*strong*) pointers left.
+
+Rust actually makes it somewhat difficult to produce this loop in the first
+place: in order to end up with two objects that point at each other, one of
+them needs to be mutable.  This is problematic because Rc enforces memory
+safety by only giving out shared references to the object it wraps, and these
+don't allow direct mutation.  We need to wrap the part of the object we wish to
+mutate in a `RefCell`, which provides *interior mutability*: a method to
+achieve mutability through a shared reference.  `RefCell` enforces Rust's
+borrowing rules at runtime.  Read the `Cell` documentation for more details on
+interior mutability.
+
+```rust
+use std::rc::Rc;
+use std::rc::Weak;
+use std::cell::RefCell;
+
+struct Owner {
+    name: String,
+    gadgets: RefCell<Vec<Weak<Gadget>>>
+    // ...other fields
+}
+
+struct Gadget {
+    id: int,
+    owner: Rc<Owner>
+    // ...other fields
+}
+
+fn main() {
+    // Create a reference counted Owner.  Note the fact that we've put the
+    // Owner's vector of Gadgets inside a RefCell so that we can mutate it
+    // through a shared reference.
+    let gadget_owner : Rc<Owner> = Rc::new(
+            Owner {
+                name: "Gadget Man".to_string(),
+                gadgets: RefCell::new(Vec::new())
+            }
+    );
+
+    // Create Gadgets belonging to gadget_owner as before.
+    let gadget1 = Rc::new(Gadget{id: 1, owner: gadget_owner.clone()});
+    let gadget2 = Rc::new(Gadget{id: 2, owner: gadget_owner.clone()});
+
+    // Add the Gadgets to their Owner.  To do this we mutably borrow from
+    // the RefCell holding the Owner's Gadgets.
+    gadget_owner.gadgets.borrow_mut().push(gadget1.clone().downgrade());
+    gadget_owner.gadgets.borrow_mut().push(gadget2.clone().downgrade());
+
+    // Iterate over our Gadgets, printing their details out
+    for gadget_opt in gadget_owner.gadgets.borrow().iter() {
+
+        // gadget_opt is a Weak<Gadget>.  Since weak pointers can't guarantee
+        // that their object is still alive, we need to call upgrade() on them
+        // to turn them into a strong reference.  This returns an Option, which
+        // contains a reference to our object if it still exists.
+        let gadget = gadget_opt.upgrade().unwrap();
+        println!("Gadget {} owned by {}", gadget.id, gadget.owner.name);
+    }
+
+    // At the end of the method, gadget_owner, gadget1 and gadget2 get
+    // destroyed.  There are now no strong (Rc) references to the gadgets.
+    // Once they get destroyed, the Gadgets get destroyed.  This zeroes the
+    // reference count on Gadget Man, so he gets destroyed as well.
+}
+```
 
 */
 

branches/try2/src/libcollections/str.rs

@@ -97,6 +97,15 @@ Section: Creating a string
 ///
 /// Returns `Err` with the original vector if the vector contains invalid
 /// UTF-8.
+///
+/// # Example
+///
+/// ```rust
+/// use std::str;
+/// let hello_vec = vec![104, 101, 108, 108, 111];
+/// let string = str::from_utf8_owned(hello_vec);
+/// assert_eq!(string, Ok("hello".to_string()));
+/// ```
 pub fn from_utf8_owned(vv: Vec<u8>) -> Result<String, Vec<u8>> {
     String::from_utf8(vv)
 }
@@ -111,22 +120,39 @@ pub fn from_utf8_owned(vv: Vec<u8>) -> Result<String, Vec<u8>> {
 ///
 /// ```rust
 /// use std::str;
-/// let string = str::from_byte(66u8);
-/// assert_eq!(string.as_slice(), "B");
+/// let string = str::from_byte(104);
+/// assert_eq!(string.as_slice(), "h");
 /// ```
 pub fn from_byte(b: u8) -> String {
     assert!(b < 128u8);
     String::from_char(1, b as char)
 }
 
 /// Convert a char to a string
+///
+/// # Example
+///
+/// ```rust
+/// use std::str;
+/// let string = str::from_char('b');
+/// assert_eq!(string.as_slice(), "b");
+/// ```
 pub fn from_char(ch: char) -> String {
     let mut buf = String::new();
     buf.push_char(ch);
     buf
 }
 
 /// Convert a vector of chars to a string
+///
+/// # Example
+///
+/// ```rust
+/// use std::str;
+/// let chars = ['h', 'e', 'l', 'l', 'o'];
+/// let string = str::from_chars(chars);
+/// assert_eq!(string.as_slice(), "hello");
+/// ```
 pub fn from_chars(chs: &[char]) -> String {
     chs.iter().map(|c| *c).collect()
 }