---

yaml
---
r: 160221
b: refs/heads/snap-stage3
c: a22f06d
h: refs/heads/master
i:
  160219: aeef252
v: v3

Author: Jakub Bukaj

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: bfaa7bcab3459907014c31d3bf980f65ccd14b08
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 4af3494bb02e80badc978faa65e59625ade0c675
+refs/heads/snap-stage3: a22f06db19851bc437aefefb5688eeb9dab79079
 refs/heads/try: 225de0d60f8ca8dcc62ab2fd8818ebbda4b58cfe
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d

branches/snap-stage3/configure

@@ -1031,6 +1031,7 @@ do
     make_dir $h/test/doc-guide-tasks
     make_dir $h/test/doc-guide-plugin
     make_dir $h/test/doc-guide-crates
+    make_dir $h/test/doc-guide-error-handling
     make_dir $h/test/doc-rust
 done
 

branches/snap-stage3/mk/docs.mk

@@ -27,7 +27,7 @@
 ######################################################################
 DOCS := index intro tutorial guide guide-ffi guide-macros guide-lifetimes \
 	guide-tasks guide-container guide-pointers guide-testing \
-	guide-plugin guide-crates complement-bugreport \
+	guide-plugin guide-crates complement-bugreport guide-error-handling \
 	complement-lang-faq complement-design-faq complement-project-faq \
     rustdoc guide-unsafe guide-strings reference
 

branches/snap-stage3/src/doc/guide-error-handling.md

@@ -0,0 +1,227 @@
+% Error Handling in Rust
+
+> The best-laid plans of mice and men
+> Often go awry
+> 
+> "Tae a Moose", Robert Burns
+
+Sometimes, things just go wrong. It's important to have a plan for when the
+inevitable happens. Rust has rich support for handling errors that may (let's
+be honest: will) occur in your programs.
+
+There are two main kinds of errors that can occur in your programs: failures,
+and panics. Let's talk about the difference between the two, and then discuss
+how to handle each. Then, we'll discuss upgrading failures to panics.
+
+# Failure vs. Panic
+
+Rust uses two terms to differentiate between two forms of error: failure, and
+panic. A **failure** is an error that can be recovered from in some way. A
+**panic** is an error that cannot be recovered from.
+
+What do we mean by 'recover'? Well, in most cases, the possibility of an error
+is expected. For example, consider the `from_str` function:
+
+```{rust,ignore}
+from_str("5");
+```
+
+This function takes a string argument and converts it into another type. But
+because it's a string, you can't be sure that the conversion actually works.
+For example, what should this convert to?
+
+```{rust,ignore}
+from_str("hello5world");
+```
+
+This won't work. So we know that this function will only work properly for some
+inputs. It's expected behavior. We call this kind of error 'failure.'
+
+On the other hand, sometimes, there are errors that are unexpected, or which
+we cannot recover from. A classic example is an `assert!`:
+
+```{rust,ignore}
+assert!(x == 5);
+```
+
+We use `assert!` to declare that something is true. If it's not true, something
+is very wrong. Wrong enough that we can't continue with things in the current
+state. Another example is using the `unreachable!()` macro
+
+```{rust,ignore}
+enum Event {
+    NewRelease,
+}
+
+fn probability(_: &Event) -> f64 {
+    // real implementation would be more complex, of course
+    0.95
+}
+
+fn descriptive_probability(event: Event) -> &'static str {
+    match probability(&event) {
+        1.00          => "certain",
+        0.00          => "impossible",
+        0.00 ... 0.25 => "very unlikely",
+        0.25 ... 0.50 => "unlikely",
+        0.50 ... 0.75 => "likely",
+        0.75 ... 1.00  => "very likely",
+    }
+}
+
+fn main() {
+    std::io::println(descriptive_probability(NewRelease));
+}
+```
+
+This will give us an error:
+
+```{notrust,ignore}
+error: non-exhaustive patterns: `_` not covered [E0004]
+```
+
+While we know that we've covered all possible cases, Rust can't tell. It
+doesn't know that probability is between 0.0 and 1.0. So we add another case:
+
+```rust
+enum Event {
+    NewRelease,
+}
+
+fn probability(_: &Event) -> f64 {
+    // real implementation would be more complex, of course
+    0.95
+}
+
+fn descriptive_probability(event: Event) -> &'static str {
+    match probability(&event) {
+        1.00          => "certain",
+        0.00          => "impossible",
+        0.00 ... 0.25 => "very unlikely",
+        0.25 ... 0.50 => "unlikely",
+        0.50 ... 0.75 => "likely",
+        0.75 ... 1.00  => "very likely",
+        _ => unreachable!()
+    }
+}
+
+fn main() {
+    std::io::println(descriptive_probability(NewRelease));
+}
+```
+
+We shouldn't ever hit the `_` case, so we use the `unreachable!()` macro to
+indicate this. `unreachable!()` gives a different kind of error than `Result`.
+Rust calls these sorts of errors 'panics.'
+
+# Handling errors with `Option` and `Result`
+
+The simplest way to indicate that a function may fail is to use the `Option<T>`
+type. Remember our `from_str()` example? Here's its type signature:
+
+```{rust,ignore}
+pub fn from_str<A: FromStr>(s: &str) -> Option<A>
+```
+
+`from_str()` returns an `Option<A>`. If the conversion succeeds, it will return
+`Some(value)`, and if it fails, it will return `None`.
+
+This is appropriate for the simplest of cases, but doesn't give us a lot of
+information in the failure case. What if we wanted to know _why_ the conversion
+failed? For this, we can use the `Result<T, E>` type. It looks like this:
+
+```rust
+enum Result<T, E> {
+   Ok(T),
+   Err(E)
+}
+```
+
+This enum is provided by Rust itself, so you don't need to define it to use it
+in your code. The `Ok(T)` variant represents a success, and the `Err(E)` variant
+represents a failure. Returning a `Result` instead of an `Option` is recommended
+for all but the most trivial of situations.
+
+Here's an example of using `Result`:
+
+```rust
+#[deriving(Show)]
+enum Version { Version1, Version2 }
+
+#[deriving(Show)]
+enum ParseError { InvalidHeaderLength, InvalidVersion }
+
+
+fn parse_version(header: &[u8]) -> Result<Version, ParseError> {
+    if header.len() < 1 {
+        return Err(InvalidHeaderLength);
+    }
+    match header[0] {
+        1 => Ok(Version1),
+        2 => Ok(Version2),
+        _ => Err(InvalidVersion)
+    }
+}
+
+let version = parse_version(&[1, 2, 3, 4]);
+match version {
+    Ok(v) => {
+        println!("working with version: {}", v);
+    }
+    Err(e) => {
+        println!("error parsing header: {}", e);
+    }
+}
+```
+
+This function makes use of an enum, `ParseError`, to enumerate the various
+errors that can occur.
+
+# Non-recoverable errors with `panic!`
+
+In the case of an error that is unexpected and not recoverable, the `panic!`
+macro will induce a panic. This will crash the current task, and give an error:
+
+```{rust,ignore}
+panic!("boom");
+```
+
+gives
+
+```{notrust,ignore}
+task '<main>' panicked at 'boom', hello.rs:2
+```
+
+when you run it.
+
+Because these kinds of situations are relatively rare, use panics sparingly.
+
+# Upgrading failures to panics
+
+In certain circumstances, even though a function may fail, we may want to treat
+it as a panic instead. For example, `io::stdin().read_line()` returns an
+`IoResult<String>`, a form of `Result`, when there is an error reading the
+line. This allows us to handle and possibly recover from this sort of error.
+
+If we don't want to handle this error, and would rather just abort the program,
+we can use the `unwrap()` method:
+
+```{rust,ignore}
+io::stdin().read_line().unwrap();
+```
+
+`unwrap()` will `panic!` if the `Option` is `None`. This basically says "Give
+me the value, and if something goes wrong, just crash." This is less reliable
+than matching the error and attempting to recover, but is also significantly
+shorter. Sometimes, just crashing is appropriate.
+
+There's another way of doing this that's a bit nicer than `unwrap()`:
+
+```{rust,ignore}
+let input = io::stdin().read_line()
+                       .ok()
+                       .expect("Failed to read line");
+```
+`ok()` converts the `IoResult` into an `Option`, and `expect()` does the same
+thing as `unwrap()`, but takes a message. This message is passed along to the
+underlying `panic!`, providing a better error message if the code errors.

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

@@ -159,6 +159,8 @@ $ ./main # or main.exe on Windows
 Hello, world!
 ```
 
+You can also run these examples on [play.rust-lang.org](http://play.rust-lang.org/) by clicking on the arrow that appears in the upper right of the example when you mouse over the code.
+
 Success! Let's go over what just happened in detail.
 
 ```{rust}

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

@@ -59,6 +59,7 @@ a guide that can help you out:
 * [References and Lifetimes](guide-lifetimes.html)
 * [Crates and modules](guide-crates.html)
 * [Tasks and Communication](guide-tasks.html)
+* [Error Handling](guide-error-handling.html)
 * [Foreign Function Interface](guide-ffi.html)
 * [Writing Unsafe and Low-Level Code](guide-unsafe.html)
 * [Macros](guide-macros.html)

branches/snap-stage3/src/doc/po4a.conf

@@ -20,6 +20,7 @@
 [type: text] src/doc/guide-testing.md $lang:doc/l10n/$lang/guide-testing.md
 [type: text] src/doc/guide-unsafe.md $lang:doc/l10n/$lang/guide-unsafe.md
 [type: text] src/doc/guide-crates.md $lang:doc/l10n/$lang/guide-crates.md
+[type: text] src/doc/guide-error-handling.md $lang:doc/l10n/$lang/guide-error-handling.md
 [type: text] src/doc/guide.md $lang:doc/l10n/$lang/guide.md
 [type: text] src/doc/index.md $lang:doc/l10n/$lang/index.md
 [type: text] src/doc/intro.md $lang:doc/l10n/$lang/intro.md

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

@@ -3557,17 +3557,14 @@ The machine types are the following:
 
 #### Machine-dependent integer types
 
-The Rust type `uint` [^rustuint] is an
-unsigned integer type with target-machine-dependent size. Its size, in
-bits, is equal to the number of bits required to hold any memory address on
-the target machine.
-
-The Rust type `int` [^rustint]  is a two's complement signed integer type with
-target-machine-dependent size. Its size, in bits, is equal to the size of the
-rust type `uint` on the same target machine.
-
-[^rustuint]: A Rust `uint` is analogous to a C99 `uintptr_t`.
-[^rustint]: A Rust `int` is analogous to a C99 `intptr_t`.
+The `uint` type is an unsigned integer type with the same number of bits as the
+platform's pointer type. It can represent every memory address in the process.
+
+The `int` type is a signed integer type with the same number of bits as the
+platform's pointer type. The theoretical upper bound on object and array size
+is the maximum `int` value. This ensures that `int` can be used to calculate
+differences between pointers into an object or array and can address every byte
+within an object along with one byte past the end.
 
 ### Textual types
 

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

@@ -1678,10 +1678,10 @@ impl<'a> Iterator<uint> for TwoBitPositions<'a> {
 mod tests {
     use std::prelude::*;
     use std::iter::range_step;
-    use std::u32;
     use std::rand;
     use std::rand::Rng;
-    use test::Bencher;
+    use std::u32;
+    use test::{Bencher, black_box};
 
     use super::{Bitv, BitvSet, from_fn, from_bytes};
     use bitv;
@@ -2676,8 +2676,8 @@ mod tests {
             for _ in range(0u, 100) {
                 bitv |= 1 << ((r.next_u32() as uint) % u32::BITS);
             }
-            &bitv
-        })
+            black_box(&bitv)
+        });
     }
 
     #[bench]
@@ -2688,8 +2688,8 @@ mod tests {
             for _ in range(0u, 100) {
                 bitv.set((r.next_u32() as uint) % BENCH_BITS, true);
             }
-            &bitv
-        })
+            black_box(&bitv)
+        });
     }
 
     #[bench]
@@ -2700,8 +2700,8 @@ mod tests {
             for _ in range(0u, 100) {
                 bitv.set((r.next_u32() as uint) % BENCH_BITS, r.gen());
             }
-            &bitv
-        })
+            black_box(&bitv);
+        });
     }
 
     #[bench]
@@ -2712,8 +2712,8 @@ mod tests {
             for _ in range(0u, 100) {
                 bitv.set((r.next_u32() as uint) % u32::BITS, true);
             }
-            &bitv
-        })
+            black_box(&bitv);
+        });
     }
 
     #[bench]
@@ -2724,8 +2724,8 @@ mod tests {
             for _ in range(0u, 100) {
                 bitv.insert((r.next_u32() as uint) % u32::BITS);
             }
-            &bitv
-        })
+            black_box(&bitv);
+        });
     }
 
     #[bench]
@@ -2736,8 +2736,8 @@ mod tests {
             for _ in range(0u, 100) {
                 bitv.insert((r.next_u32() as uint) % BENCH_BITS);
             }
-            &bitv
-        })
+            black_box(&bitv);
+        });
     }
 
     #[bench]