start of error handling

Author: steveklabnik

src/SUMMARY.md

@@ -34,7 +34,10 @@
 
 - [Crates & Modules]()
 
-- [Error Handling]()
+- [Error Handling](ch07-01-error-handling.md)
+    - [Unrecoverable errors with panic!](ch07-02-unrecoverable-errors-with-panic.md)
+    - [Recoverable errors with `Result<T, E>`](ch07-03-recoverable-errors-with-result.md)
+    - [Creating your own Error types](ch07-04-creating-your-own-error-types.md)
 
 - [Basic Collections]()
     - [Vectors]()

src/ch07-01-error-handling.md

@@ -0,0 +1,30 @@
+# Error Handling
+
+Rust's laser-focus on safety spills over into a related area: error handling.
+Errors are a fact of life in software. Rust has a number of tools that you can
+use to handle things when something bad happens.
+
+Rust splits errors into two major kinds: errors that are recoverable, and
+errors that are not recoverable. It has two different strategies to handle
+these two different forms of errors.
+
+What does it mean to "recover" from an error? In the simplest sense, it
+relates to the answer of this question:
+
+> If I call a function, and something bad happens, can I do something
+> meaningful? Or should execution stop?
+
+Some kinds of problems have solutions, but with other kinds of errors,
+all you can do is throw up your hands and give up.
+
+We'll start off our examination of error handling by talking about the
+unrecoverable case first. Why? You can think of unrecoverable errors as a
+subset of recoverable errors. If you choose to treat an error as unrecoverable,
+then the function that calls your code has no choice in the matter. However, if
+your function returns a recoverable error, the calling function has a choice:
+handle the error properly, or convert it into an unrecoverable error. This is
+one of the reasons that most Rust code chooses to treat errors as recoverable:
+it's more flexible. We're going to explore an example that starts off as
+unrecoverable, and then, in the next section, we will convert it to a
+convertable error. Finally, we'll talk about how to create our own custom error
+types.

src/ch07-02-unrecoverable-errors-with-panic.md

@@ -0,0 +1,235 @@
+# Unrecoverable errors with panic!
+
+You've already seen the way to signal an unrecoverable error: the `panic!`
+macro. Here's an example of using `panic!`:
+
+```rust
+fn check_guess(number: u32) -> bool {
+    if number > 100 {
+        panic!("Guess was too big: {}", number);
+    }
+
+    number == 34
+}
+```
+
+This function accepts a guess between zero and a hundred, and checks if it's
+equivalent to the correct number, which is `34` in this case. It's kind of a
+silly function, but we need an example, so it works.
+
+There's no number type for "between zero and a hundred" in Rust, so we are
+accepting a `u32`, and then checking in the function's body to make sure the
+guess is in-bounds. If the number is too big, there's been an error: someone
+made a mistake. We then invoke `panic!` to say "something went wrong, we cannot
+continue to run this program."
+
+Checking some sort of condition and then `panic!`ing if something is wrong is a
+common use of `panic!`. In fact, there's a second macro in Rust, `assert!` for
+this case. `assert!` will check some kind of condition, and `panic!` if the
+condition is false. We could also write our function like this:
+
+```rust
+fn check_guess(number: u32) -> bool {
+    assert!(number < 100);
+
+    number == 34
+}
+```
+
+If we try and use `check_guess` in a program, and make an error:
+
+```rust,should_panic
+fn check_guess(number: u32) -> bool {
+    assert!(number < 100);
+
+    number == 34
+}
+
+fn main() {
+    let answer = check_guess(5);
+    println!("answer was: {}", answer);
+
+    let answer = check_guess(34);
+    println!("answer was: {}", answer);
+
+    let answer = check_guess(500);
+    println!("answer was: {}", answer);
+}
+```
+
+We'll see output like this:
+
+```text
+answer was: false
+answer was: true
+
+thread '<main>' panicked at 'assertion failed: number < 100', <anon>:2
+```
+
+First, `5` was okay, but false. Then, `34` was okay, but true. Finally, `500`
+caused a panic.
+
+Panics cause your program to stop executing. To check this, we could move the
+failing case above the good cases:
+
+```rust,should_panic
+# fn check_guess(number: u32) -> bool {
+#     assert!(number < 100);
+# 
+#     number == 34
+# }
+# 
+fn main() {
+    let answer = check_guess(500);
+    println!("answer was: {}", answer);
+
+    let answer = check_guess(5);
+    println!("answer was: {}", answer);
+
+    let answer = check_guess(34);
+    println!("answer was: {}", answer);
+}
+```
+
+If we run it, we'll see that we never check `5` or `34`:
+
+```text
+thread '<main>' panicked at 'assertion failed: number < 100', <anon>:2
+```
+
+This is why we call `panic!` an unrecoverable error: the other code never gets a
+chance to run. Our program just ends.
+
+But what does it mean to "end a program"? As it turns out, there are multiple
+strategies for processing an unrecoverable error. The two main ones are
+'unwinding' and 'aborting'.
+
+## Unwinding
+
+By default, when a `panic!` happens in Rust, it starts doing something called
+"unwinding". To explain unwinding, let's consider a slightly more complex
+program:
+
+```rust,should_panic
+fn step1() {
+    let s = String::from("Step 1");
+    step2();
+}
+
+fn step2() {
+    let s = String::from("Step 2");
+    step3();
+}
+
+fn step3() {
+    let s = String::from("Step 3");
+    check_guess(500);
+}
+
+fn check_guess(number: u32) -> bool {
+    assert!(number < 100);
+
+    number == 34
+}
+
+fn main() {
+    step1();
+}
+```
+
+Here, we have four functions total: `step1` calls `step2` which calls `step3`
+which then calls `check_guess`. Something like this diagram, with each of the
+variable bindings written in:
+
+```text
+> main
+  |
+  > step1 String: "Step 1"
+    |
+    > step2 String: "Step 2"
+      |
+      > step3 String: "Step 3"
+        |
+        > check_guess: u32: 500
+```
+
+When `check_guess` causes a `panic!` via `assert!`, it will walk back through
+each of these functions, and clean them up. We haven't yet talked about
+destructors in Rust, that'll come in Chapter XX. For now, think about it this
+way: simple values like that `u32` can be destroyed by freeing their memory.
+More complicated values, like `String`s, have more complicated needs. In these
+cases, there is a function that does this cleanup. We call this a "drop
+function" in Rust.
+
+So, the first thing that will happen is that `check_guess`, our current
+function, gets cleaned up. There's only one value, the `500`, and so its memory
+will be freed. Now our program looks like this:
+
+```text
+> main
+  |
+  > step1 String: "Step 1"
+    |
+    > step2 String: "Step 2"
+      |
+      > step3 String: "Step 3"
+```
+
+Now we're on `step3`. In the same way, Rust will call the `String`'s drop
+function, deallocating the `String`. Once that's done, we can move on:
+
+```text
+> main
+  |
+  > step1 String: "Step 1"
+    |
+    > step2 String: "Step 2"
+```
+
+The pattern continues: `step2` has a single value, and `"Step 2"` has its
+drop function called. Next!
+
+```text
+> main
+  |
+  > step1 String: "Step 1"
+```
+
+Almost done! `step1` also has a `String`, so Rust will invoke its drop function.
+
+```text
+> main
+```
+
+Finally, all we have left is `main()`. It has no variable bindings or arguments
+in this case, so there's nothing to clean up. Our whole program has been delt
+with, and so terminates execution, after printing a message.
+
+## Aborting
+
+Doing all that is a lot of work! And the end result is that our program
+terminates. Handing panics with unwinding is useful in many scenarios, but some
+applications would rather skip straight to the end, and 'abort'. With some
+configuration, Cargo will allow us to use this alternate implementation of
+`panic!`. What happens when that's enabled? Let's consider what our call stack
+looked like:
+
+```text
+> main
+  |
+  > step1 String: "Step 1"
+    |
+    > step2 String: "Step 2"
+      |
+      > step3 String: "Step 3"
+        |
+        > check_guess: u32: 500
+```
+
+With an abort implementation of `panic!`, instead of walking back up through the
+previous functions and cleaning everything up, we skip straight to the end: our
+program terminates. But what about our resources? In the case of memory, like is
+the case with `String`s, the operating system will reclaim the memory. So for
+this program, the two cases are identical, but aborting is much more efficient.
+Other, more complex resources work differently, however, and so aborting may not
+always be the right choice either. It depends!

src/ch07-03-recoverable-errors-with-result.md

@@ -0,0 +1,116 @@
+# Recoverable errors with `Result<T, E>`
+
+The vast majority of errors in Rust are able to be recovered from. For this
+case, Rust has a special type, `Result<T, E>`, to signal that a function might
+succeed or fail.
+
+Let's take a look at our example function from the last section:
+
+```rust
+fn check_guess(number: u32) -> bool {
+    if number > 100 {
+        panic!("Guess was too big: {}", number);
+    }
+
+    number == 34
+}
+```
+
+We don't want the entire program to end if our `number` was incorrect. That's a
+bit harsh! Instead, we want to signal that an error occurred. Here's a version
+of `check_guess` that uses `Result<T, E>`:
+
+```rust
+fn check_guess(number: u32) -> Result<bool, &'static str> {
+    if number > 100 {
+        return Err("Number was out of range");
+    }
+
+    Ok(number == 34)
+}
+```
+
+There are three big changes here: to the return type, to the error case, and to
+the non-error case. Let's look at each in turn.
+
+```rust
+fn check_guess(number: u32) -> Result<bool, &'static str> {
+#     if number > 100 {
+#         return Err("Number was out of range");
+#     }
+# 
+#     Ok(number == 34)
+# }
+```
+
+Originally, we returned a `bool`, but now we return a
+`Result<bool, &'static str>`. This is a type [provided by the standard library]
+specifically for indicating that a function might have an error. More
+specifically, it's an [`enum`] that looks like this:
+
+```rust
+pub enum Result<T, E> {
+    Ok(T),
+    Err(E),
+}
+```
+
+[provided by the standard library]: https://doc.rust-lang.org/stable/std/result/enum.Result.html
+[`enum]`: ch06-01-enums.html
+
+`Result<T, E>` is generic over two types: `T`, which is the successful case, and
+`E`, which is the error case. It has two variants, `Ok` and `Err`, which also
+correspond to these cases, respectively. So the type `Result<bool, &'static
+str>` means that in the successful, `Ok` case, we will be returning a `bool`.
+But in the failure, `Err` case, we will be returning a string literal.
+
+```rust
+# fn check_guess(number: u32) -> Result<bool, &'static str> {
+#     if number > 100 {
+        return Err("Number was out of range");
+#     }
+# 
+#     Ok(number == 34)
+# }
+```
+
+The second change we need to make is to our error case. Instead of causing a
+`panic!`, we now `return` an `Err`, with a string literal inside. Remember,
+`Result<T, E>` is an enum: `Err` is one of its variants.
+
+```rust
+# fn check_guess(number: u32) -> Result<bool, &'static str> {
+#     if number > 100 {
+#         return Err("Number was out of range");
+#     }
+# 
+     Ok(number == 34)
+# }
+```
+
+We also need to handle the successful case as well, and we make a change
+similarly to the error case: we wrap our return value in `Ok`, which gives it
+the correct type.
+
+## Handling an error
+
+Let's examine how to use this function:
+
+```rust
+fn check_guess(number: u32) -> Result<bool, &'static str> {
+    if number > 100 {
+        return Err("Number was out of range");
+    }
+
+    Ok(number == 34)
+}
+
+fn main() {
+    let answer = check_guess(5);
+
+    match answer {
+        Ok(b) => println!("answer: {}", b),
+        Err(e) => println!("There was an error: {}, e"),
+    };
+}
+```

src/ch07-04-creating-your-own-error-types.md

@@ -0,0 +1 @@
+# Creating your own Error types