---

yaml
---
r: 272479
b: refs/heads/master
c: c584283
h: refs/heads/master
i:
  272477: 78d9eef
  272475: f2a2d0d
  272471: 98f366c
  272463: a4edd3f
  272447: 26311af

Author: steveklabnik

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: b2db97347bc4373deea24eb7b7c6ecffb117fd8c
+refs/heads/master: c5842837b86abc720446055118bf714dabe30730
 refs/heads/snap-stage3: 235d77457d80b549dad3ac36d94f235208a1eafb
 refs/heads/try: 49312a405e14a449b98fe0056b12a40ac128be4a
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105

trunk/src/doc/book/concurrency.md

@@ -162,7 +162,7 @@ The same [ownership system](ownership.html) that helps prevent using pointers
 incorrectly also helps rule out data races, one of the worst kinds of
 concurrency bugs.
 
-As an example, here is a Rust program that could have a data race in many
+As an example, here is a Rust program that would have a data race in many
 languages. It will not compile:
 
 ```ignore
@@ -174,7 +174,7 @@ fn main() {
 
     for i in 0..3 {
         thread::spawn(move || {
-            data[i] += 1;
+            data[0] += i;
         });
     }
 
@@ -186,7 +186,7 @@ This gives us an error:
 
 ```text
 8:17 error: capture of moved value: `data`
-        data[i] += 1;
+        data[0] += i;
         ^~~~
 ```
 
@@ -195,11 +195,6 @@ thread, and the thread takes ownership of the reference, we'd have three owners!
 `data` gets moved out of `main` in the first call to `spawn()`, so subsequent
 calls in the loop cannot use this variable.
 
-Note that this specific example will not cause a data race since different array
-indices are being accessed. But this can't be determined at compile time, and in
-a similar situation where `i` is a constant or is random, you would have a data
-race.
-
 So, we need some type that lets us have more than one owning reference to a
 value. Usually, we'd use `Rc<T>` for this, which is a reference counted type
 that provides shared ownership. It has some runtime bookkeeping that keeps track
@@ -223,7 +218,7 @@ fn main() {
 
         // use it in a thread
         thread::spawn(move || {
-            data_ref[i] += 1;
+            data_ref[0] += i;
         });
     }
 
@@ -266,7 +261,7 @@ fn main() {
     for i in 0..3 {
         let data = data.clone();
         thread::spawn(move || {
-            data[i] += 1;
+            data[0] += i;
         });
     }
 
@@ -281,7 +276,7 @@ And... still gives us an error.
 
 ```text
 <anon>:11:24 error: cannot borrow immutable borrowed content as mutable
-<anon>:11                    data[i] += 1;
+<anon>:11                    data[0] += i;
                              ^~~~
 ```
 
@@ -317,7 +312,7 @@ fn main() {
         let data = data.clone();
         thread::spawn(move || {
             let mut data = data.lock().unwrap();
-            data[i] += 1;
+            data[0] += i;
         });
     }
 
@@ -360,7 +355,7 @@ Let's examine the body of the thread more closely:
 #         let data = data.clone();
 thread::spawn(move || {
     let mut data = data.lock().unwrap();
-    data[i] += 1;
+    data[0] += i;
 });
 #     }
 #     thread::sleep(Duration::from_millis(50));

trunk/src/libcore/result.rs

@@ -19,7 +19,7 @@
 //! # #[allow(dead_code)]
 //! enum Result<T, E> {
 //!    Ok(T),
-//!    Err(E)
+//!    Err(E),
 //! }
 //! ```
 //!
@@ -39,7 +39,7 @@
 //!         None => Err("invalid header length"),
 //!         Some(&1) => Ok(Version::Version1),
 //!         Some(&2) => Ok(Version::Version2),
-//!         Some(_) => Err("invalid version")
+//!         Some(_) => Err("invalid version"),
 //!     }
 //! }
 //!
@@ -254,7 +254,7 @@ pub enum Result<T, E> {
 
     /// Contains the error value
     #[stable(feature = "rust1", since = "1.0.0")]
-    Err(#[stable(feature = "rust1", since = "1.0.0")] E)
+    Err(#[stable(feature = "rust1", since = "1.0.0")] E),
 }
 
 /////////////////////////////////////////////////////////////////////////////
@@ -270,6 +270,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let x: Result<i32, &str> = Ok(-3);
     /// assert_eq!(x.is_ok(), true);
@@ -290,6 +292,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let x: Result<i32, &str> = Ok(-3);
     /// assert_eq!(x.is_err(), false);
@@ -314,6 +318,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
     /// assert_eq!(x.ok(), Some(2));
@@ -337,6 +343,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
     /// assert_eq!(x.err(), None);
@@ -362,6 +370,10 @@ impl<T, E> Result<T, E> {
     /// Produces a new `Result`, containing a reference
     /// into the original, leaving the original in place.
     ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
     /// assert_eq!(x.as_ref(), Ok(&2));
@@ -380,6 +392,10 @@ impl<T, E> Result<T, E> {
 
     /// Converts from `Result<T, E>` to `Result<&mut T, &mut E>`
     ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
     /// ```
     /// fn mutate(r: &mut Result<i32, i32>) {
     ///     match r.as_mut() {
@@ -445,6 +461,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// fn stringify(x: u32) -> String { format!("error code: {}", x) }
     ///
@@ -471,6 +489,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let x: Result<u32, &str> = Ok(7);
     /// assert_eq!(x.iter().next(), Some(&7));
@@ -488,6 +508,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let mut x: Result<u32, &str> = Ok(7);
     /// match x.iter_mut().next() {
@@ -513,6 +535,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
     /// let y: Result<&str, &str> = Err("late error");
@@ -545,6 +569,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
     /// fn err(x: u32) -> Result<u32, u32> { Err(x) }
@@ -567,6 +593,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
     /// let y: Result<u32, &str> = Err("late error");
@@ -599,6 +627,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
     /// fn err(x: u32) -> Result<u32, u32> { Err(x) }
@@ -622,6 +652,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let optb = 2;
     /// let x: Result<u32, &str> = Ok(9);
@@ -644,6 +676,8 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// fn count(x: &str) -> usize { x.len() }
     ///
@@ -670,6 +704,8 @@ impl<T, E: fmt::Debug> Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
     /// assert_eq!(x.unwrap(), 2);
@@ -696,6 +732,9 @@ impl<T, E: fmt::Debug> Result<T, E> {
     /// passed message, and the content of the `Err`.
     ///
     /// # Examples
+    ///
+    /// Basic usage:
+    ///
     /// ```{.should_panic}
     /// let x: Result<u32, &str> = Err("emergency failure");
     /// x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
@@ -759,6 +798,8 @@ impl<T, E> IntoIterator for Result<T, E> {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
     /// ```
     /// let x: Result<u32, &str> = Ok(5);
     /// let v: Vec<u32> = x.into_iter().collect();

trunk/src/libcore/slice.rs

@@ -871,6 +871,20 @@ macro_rules! make_mut_slice {
 }
 
 /// Immutable slice iterator
+///
+/// # Examples
+///
+/// Basic usage:
+///
+/// ```
+/// // First, we declare a type which has `iter` method to get the `Iter` struct (&[usize here]):
+/// let slice = &[1, 2, 3];
+///
+/// // Then, we iterate over it:
+/// for element in slice.iter() {
+///     println!("{}", element);
+/// }
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Iter<'a, T: 'a> {
     ptr: *const T,
@@ -897,6 +911,26 @@ impl<'a, T> Iter<'a, T> {
     ///
     /// This has the same lifetime as the original slice, and so the
     /// iterator can continue to be used while this exists.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// // First, we declare a type which has the `iter` method to get the `Iter`
+    /// // struct (&[usize here]):
+    /// let slice = &[1, 2, 3];
+    ///
+    /// // Then, we get the iterator:
+    /// let mut iter = slice.iter();
+    /// // So if we print what `as_slice` method returns here, we have "[1, 2, 3]":
+    /// println!("{:?}", iter.as_slice());
+    ///
+    /// // Next, we move to the second element of the slice:
+    /// iter.next();
+    /// // Now `as_slice` returns "[2, 3]":
+    /// println!("{:?}", iter.as_slice());
+    /// ```
     #[stable(feature = "iter_to_slice", since = "1.4.0")]
     pub fn as_slice(&self) -> &'a [T] {
         make_slice!(self.ptr, self.end)
@@ -928,6 +962,24 @@ impl<'a, T> Clone for Iter<'a, T> {
 }
 
 /// Mutable slice iterator.
+///
+/// # Examples
+///
+/// Basic usage:
+///
+/// ```
+/// // First, we declare a type which has `iter_mut` method to get the `IterMut`
+/// // struct (&[usize here]):
+/// let mut slice = &mut [1, 2, 3];
+///
+/// // Then, we iterate over it and increment each element value:
+/// for element in slice.iter_mut() {
+///     *element += 1;
+/// }
+///
+/// // We now have "[2, 3, 4]":
+/// println!("{:?}", slice);
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct IterMut<'a, T: 'a> {
     ptr: *mut T,
@@ -956,6 +1008,35 @@ impl<'a, T> IterMut<'a, T> {
     /// to consume the iterator. Consider using the `Slice` and
     /// `SliceMut` implementations for obtaining slices with more
     /// restricted lifetimes that do not consume the iterator.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// // First, we declare a type which has `iter_mut` method to get the `IterMut`
+    /// // struct (&[usize here]):
+    /// let mut slice = &mut [1, 2, 3];
+    ///
+    /// {
+    ///     // Then, we get the iterator:
+    ///     let mut iter = slice.iter_mut();
+    ///     // We move to next element:
+    ///     iter.next();
+    ///     // So if we print what `into_slice` method returns here, we have "[2, 3]":
+    ///     println!("{:?}", iter.into_slice());
+    /// }
+    ///
+    /// // Now let's modify a value of the slice:
+    /// {
+    ///     // First we get back the iterator:
+    ///     let mut iter = slice.iter_mut();
+    ///     // We change the value of the first element of the slice returned by the `next` method:
+    ///     *iter.next().unwrap() += 1;
+    /// }
+    /// // Now slice is "[2, 2, 3]":
+    /// println!("{:?}", slice);
+    /// ```
     #[stable(feature = "iter_to_slice", since = "1.4.0")]
     pub fn into_slice(self) -> &'a mut [T] {
         make_mut_slice!(self.ptr, self.end)