---

yaml
---
r: 160223
b: refs/heads/snap-stage3
c: 8997b09
h: refs/heads/master
i:
  160221: 5614b3c
  160219: aeef252
  160215: 36d0cfc
  160207: 4a0f782
  160191: 05fc61b
v: v3

Author: Jakub Bukaj

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: bfaa7bcab3459907014c31d3bf980f65ccd14b08
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 2aa241d76f5168dc554583d2347e6c74e9a7d3bc
+refs/heads/snap-stage3: 8997b098d3d5f5c5170cd5b4b5356ae6d6ce7f4a
 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/crates.mk

@@ -53,7 +53,7 @@ TARGET_CRATES := libc std green native flate arena term \
                  serialize sync getopts collections test time rand \
                  log regex graphviz core rbml alloc rustrt \
                  unicode
-HOST_CRATES := syntax rustc rustdoc regex_macros fmt_macros \
+HOST_CRATES := syntax rustc rustc_trans rustdoc regex_macros fmt_macros \
 	       rustc_llvm rustc_back
 CRATES := $(TARGET_CRATES) $(HOST_CRATES)
 TOOLS := compiletest rustdoc rustc
@@ -69,11 +69,12 @@ DEPS_graphviz := std
 DEPS_green := std native:context_switch
 DEPS_native := std
 DEPS_syntax := std term serialize log fmt_macros arena libc
+DEPS_rustc_trans := rustc rustc_back rustc_llvm libc
 DEPS_rustc := syntax flate arena serialize getopts rbml \
               time log graphviz rustc_llvm rustc_back
 DEPS_rustc_llvm := native:rustllvm libc std
 DEPS_rustc_back := std syntax rustc_llvm flate log libc
-DEPS_rustdoc := rustc native:hoedown serialize getopts \
+DEPS_rustdoc := rustc rustc_trans native:hoedown serialize getopts \
                 test time
 DEPS_flate := std native:miniz
 DEPS_arena := std
@@ -96,7 +97,7 @@ DEPS_fmt_macros = std
 
 TOOL_DEPS_compiletest := test getopts native
 TOOL_DEPS_rustdoc := rustdoc native
-TOOL_DEPS_rustc := rustc native
+TOOL_DEPS_rustc := rustc_trans native
 TOOL_SOURCE_compiletest := $(S)src/compiletest/compiletest.rs
 TOOL_SOURCE_rustdoc := $(S)src/driver/driver.rs
 TOOL_SOURCE_rustc := $(S)src/driver/driver.rs
@@ -112,8 +113,8 @@ ONLY_RLIB_unicode := 1
 # You should not need to edit below this line
 ################################################################################
 
-DOC_CRATES := $(filter-out rustc, $(filter-out syntax, $(CRATES)))
-COMPILER_DOC_CRATES := rustc syntax
+DOC_CRATES := $(filter-out rustc, $(filter-out rustc_trans, $(filter-out syntax, $(CRATES))))
+COMPILER_DOC_CRATES := rustc rustc_trans syntax
 
 # This macro creates some simple definitions for each crate being built, just
 # some munging of all of the parameters above.

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

@@ -2513,11 +2513,6 @@ The currently implemented features of the reference compiler are:
                closure as `once` is unlikely to be supported going forward. So
                they are hidden behind this feature until they are to be removed.
 
-* `overloaded_calls` - Allow implementing the `Fn*` family of traits on user
-                       types, allowing overloading the call operator (`()`).
-                       This feature may still undergo changes before being
-                       stabilized.
-
 * `phase` - Usage of the `#[phase]` attribute allows loading compiler plugins
             for custom lints or syntax extensions. The implementation is
             considered unwholesome and in need of overhaul, and it is not clear
@@ -2560,11 +2555,8 @@ The currently implemented features of the reference compiler are:
 * `trace_macros` - Allows use of the `trace_macros` macro, which is a nasty
                    hack that will certainly be removed.
 
-* `unboxed_closure_sugar` - Allows using `|Foo| -> Bar` as a trait bound
-                            meaning one of the `Fn` traits. Still
-                            experimental.
-
-* `unboxed_closures` - A work in progress feature with many known bugs.
+* `unboxed_closures` - Rust's new closure design, which is currently a work in
+                       progress feature with many known bugs.
 
 * `unsafe_destructor` - Allows use of the `#[unsafe_destructor]` attribute,
                         which is considered wildly unsafe and will be
@@ -3565,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.
+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.
 
-[^rustuint]: A Rust `uint` is analogous to a C99 `uintptr_t`.
-[^rustint]: A Rust `int` is analogous to a C99 `intptr_t`.
+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/driver/driver.rs

@@ -12,6 +12,6 @@
 extern crate "rustdoc" as this;
 
 #[cfg(rustc)]
-extern crate "rustc" as this;
+extern crate "rustc_trans" as this;
 
 fn main() { this::main() }