diff options
Diffstat (limited to 'src/doc/book/nostarch/chapter09.md')
| -rw-r--r-- | src/doc/book/nostarch/chapter09.md | 646 |
1 files changed, 257 insertions, 389 deletions
diff --git a/src/doc/book/nostarch/chapter09.md b/src/doc/book/nostarch/chapter09.md index 693dc1be0..4aa81123f 100644 --- a/src/doc/book/nostarch/chapter09.md +++ b/src/doc/book/nostarch/chapter09.md @@ -18,7 +18,7 @@ deployed your code to production! Rust groups errors into two major categories: *recoverable* and *unrecoverable* errors. For a recoverable error, such as a *file not found* error, we most likely just want to report the problem to the user and retry the operation. -Unrecoverable errors are always symptoms of bugs, like trying to access a +Unrecoverable errors are always symptoms of bugs, such as trying to access a location beyond the end of an array, and so we want to immediately stop the program. @@ -31,9 +31,9 @@ about returning `Result<T, E>` values. Additionally, we’ll explore considerations when deciding whether to try to recover from an error or to stop execution. -## Unrecoverable Errors with `panic!` +## Unrecoverable Errors with panic! -Sometimes, bad things happen in your code, and there’s nothing you can do about +Sometimes bad things happen in your code, and there’s nothing you can do about it. In these cases, Rust has the `panic!` macro. There are two ways to cause a panic in practice: by taking an action that causes our code to panic (such as accessing an array past the end) or by explicitly calling the `panic!` macro. @@ -42,39 +42,22 @@ print a failure message, unwind, clean up the stack, and quit. Via an environment variable, you can also have Rust display the call stack when a panic occurs to make it easier to track down the source of the panic. -<!-- does Rust invoke the panic, or do we? Or sometimes it can be either? /LC ---> -<!-- We will have done *something* through a combination of the code we've -written and the data the program gets at runtime. It *might* involve us -literally typing `panic!` into our code, or it might be part of Rust that we're -using that calls `panic!` for us because of something else we've done. Does -that make sense? I've tried to clarify the last sentence a bit here /Carol --> -<!--- -One way we could explain it is to say there are two ways to cause a panic in -practice: by doing an action that causes our code to panic, like accessing an -array past the end or dividing by zero, or by explicitly calling the `panic!` -macro. In both cases, we cause a panic in our application. By default, these -panics will unwind and clean up the stack. Via an environment setting, you can -also have Rust display the call stack when a panic occurs to make it easier to -track down the source of the panic. -/JT ---> -<!-- I've taken JT's suggestion with some edits in the paragraph above /Carol ---> > ### Unwinding the Stack or Aborting in Response to a Panic > -> By default, when a panic occurs, the program starts *unwinding*, which -> means Rust walks back up the stack and cleans up the data from each function -> it encounters. However, this walking back and cleanup is a lot of work. Rust, -> therefore, allows you to choose the alternative of immediately *aborting*, -> which ends the program without cleaning up. +> By default, when a panic occurs the program starts *unwinding*, which means +Rust walks back up the stack and cleans up the data from each function it +encounters. However, walking back and cleaning up is a lot of work. Rust, +therefore, allows you to choose the alternative of immediately *aborting*, +which ends the program without cleaning up. > -> Memory that the program was using will then need to be cleaned -> up by the operating system. If in your project you need to make the resulting -> binary as small as possible, you can switch from unwinding to aborting upon a -> panic by adding `panic = 'abort'` to the appropriate `[profile]` sections in -> your *Cargo.toml* file. For example, if you want to abort on panic in release -> mode, add this: +> Memory that the program was using will then need to be cleaned up by the +operating system. If in your project you need to make the resultant binary as +small as possible, you can switch from unwinding to aborting upon a panic by +adding `panic = 'abort'` to the appropriate `[profile]` sections in your +*Cargo.toml* file. For example, if you want to abort on panic in release mode, +add this: > -> ```toml +> ``` > [profile.release] > panic = 'abort' > ``` @@ -93,7 +76,8 @@ When you run the program, you’ll see something like this: ``` thread 'main' panicked at 'crash and burn', src/main.rs:2:5 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace +note: run with `RUST_BACKTRACE=1` environment variable to display +a backtrace ``` The call to `panic!` causes the error message contained in the last two lines. @@ -105,17 +89,14 @@ In this case, the line indicated is part of our code, and if we go to that line, we see the `panic!` macro call. In other cases, the `panic!` call might be in code that our code calls, and the filename and line number reported by the error message will be someone else’s code where the `panic!` macro is -called, not the line of our code that eventually led to the `panic!` call. We -can use the backtrace of the functions the `panic!` call came from to figure -out the part of our code that is causing the problem. We’ll discuss backtraces -in more detail next. - -### Using a `panic!` Backtrace +called, not the line of our code that eventually led to the `panic!` call. -Let’s look at another example to see what it’s like when a `panic!` call comes -from a library because of a bug in our code instead of from our code calling -the macro directly. Listing 9-1 has some code that attempts to access an -index in a vector beyond the range of valid indexes. +We can use the backtrace of the functions the `panic!` call came from to figure +out the part of our code that is causing the problem. To understand how to use +a `panic!` backtrace, let’s look at another example and see what it’s like when +a `panic!` call comes from a library because of a bug in our code instead of +from our code calling the macro directly. Listing 9-1 has some code that +attempts to access an index in a vector beyond the range of valid indexes. Filename: src/main.rs @@ -131,10 +112,10 @@ Listing 9-1: Attempting to access an element beyond the end of a vector, which will cause a call to `panic!` Here, we’re attempting to access the 100th element of our vector (which is at -index 99 because indexing starts at zero), but the vector has only 3 elements. -In this situation, Rust will panic. Using `[]` is supposed to return an -element, but if you pass an invalid index, there’s no element that Rust could -return here that would be correct. +index 99 because indexing starts at zero), but the vector has only three +elements. In this situation, Rust will panic. Using `[]` is supposed to return +an element, but if you pass an invalid index, there’s no element that Rust +could return here that would be correct. In C, attempting to read beyond the end of a data structure is undefined behavior. You might get whatever is at the location in memory that would @@ -149,44 +130,55 @@ element at an index that doesn’t exist, Rust will stop execution and refuse to continue. Let’s try it and see: ``` -thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', src/main.rs:4:5 +thread 'main' panicked at 'index out of bounds: the len is 3 but the index is +99', src/main.rs:4:5 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` -This error points at line 4 of our `main.rs` where we attempt to access index -99. The next note line tells us that we can set the `RUST_BACKTRACE` -environment variable to get a backtrace of exactly what happened to cause the -error. A *backtrace* is a list of all the functions that have been called to -get to this point. Backtraces in Rust work as they do in other languages: the -key to reading the backtrace is to start from the top and read until you see -files you wrote. That’s the spot where the problem originated. The lines above -that spot are code that your code has called; the lines below are code that -called your code. These before-and-after lines might include core Rust code, -standard library code, or crates that you’re using. Let’s try getting a -backtrace by setting the `RUST_BACKTRACE` environment variable to any value -except 0. Listing 9-2 shows output similar to what you’ll see. +This error points at line 4 of our *main.rs* where we attempt to access `index`. + +The `note:` line tells us that we can set the `RUST_BACKTRACE` environment +variable to get a backtrace of exactly what happened to cause the error. A +*backtrace* is a list of all the functions that have been called to get to this +point. Backtraces in Rust work as they do in other languages: the key to +reading the backtrace is to start from the top and read until you see files you +wrote. That’s the spot where the problem originated. The lines above that spot +are code that your code has called; the lines below are code that called your +code. These before-and-after lines might include core Rust code, standard +library code, or crates that you’re using. Let’s try getting a backtrace by +setting the `RUST_BACKTRACE` environment variable to any value except `0`. +Listing 9-2 shows output similar to what you’ll see. ``` $ RUST_BACKTRACE=1 cargo run -thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', src/main.rs:4:5 +thread 'main' panicked at 'index out of bounds: the len is 3 but the index is +99', src/main.rs:4:5 stack backtrace: 0: rust_begin_unwind - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/std/src/panicking.rs:483 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/std +/src/panicking.rs:584:5 1: core::panicking::panic_fmt - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/panicking.rs:85 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core +/src/panicking.rs:142:14 2: core::panicking::panic_bounds_check - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/panicking.rs:62 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core +/src/panicking.rs:84:5 3: <usize as core::slice::index::SliceIndex<[T]>>::index - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/slice/index.rs:255 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core +/src/slice/index.rs:242:10 4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/slice/index.rs:15 - 5: <alloc::vec::Vec<T> as core::ops::index::Index<I>>::index - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/alloc/src/vec.rs:1982 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core +/src/slice/index.rs:18:9 + 5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/alloc +/src/vec/mod.rs:2591:9 6: panic::main - at ./src/main.rs:4 + at ./src/main.rs:4:5 7: core::ops::function::FnOnce::call_once - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/ops/function.rs:227 -note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace. + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core +/src/ops/function.rs:248:5 +note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose +backtrace. ``` Listing 9-2: The backtrace generated by a call to `panic!` displayed when the @@ -208,21 +200,19 @@ panics in the future, you’ll need to figure out what action the code is taking with what values to cause the panic and what the code should do instead. We’ll come back to `panic!` and when we should and should not use `panic!` to -handle error conditions in the “To `panic!` or Not to `panic!`” section later -in this chapter. Next, we’ll look at how to recover from an error using -`Result`. +handle error conditions in “To panic! or Not to panic!” on page XX. Next, we’ll +look at how to recover from an error using `Result`. -## Recoverable Errors with `Result` +## Recoverable Errors with Result Most errors aren’t serious enough to require the program to stop entirely. -Sometimes, when a function fails, it’s for a reason that you can easily -interpret and respond to. For example, if you try to open a file and that -operation fails because the file doesn’t exist, you might want to create the -file instead of terminating the process. +Sometimes when a function fails it’s for a reason that you can easily interpret +and respond to. For example, if you try to open a file and that operation fails +because the file doesn’t exist, you might want to create the file instead of +terminating the process. -Recall from “Handling Potential Failure with the `Result` Type” in Chapter 2 -that the `Result` enum is defined as having two variants, `Ok` and `Err`, as -follows: +Recall from “Handling Potential Failure with Result” on page XX that the +`Result` enum is defined as having two variants, `Ok` and `Err`, as follows: ``` enum Result<T, E> { @@ -237,7 +227,7 @@ the type of the value that will be returned in a success case within the `Ok` variant, and `E` represents the type of the error that will be returned in a failure case within the `Err` variant. Because `Result` has these generic type parameters, we can use the `Result` type and the functions defined on it in -many different situations where the successful value and error value we want to +many different situations where the success value and error value we want to return may differ. Let’s call a function that returns a `Result` value because the function could @@ -255,18 +245,6 @@ fn main() { Listing 9-3: Opening a file -<!--- -This brings up an interesting point - should we teach them to install -rust-analyzer in the setup instructions? If so, then we can tell them to mouse -over the name of what they want the typename of. The "assign something to i32 to -have rustc tell you what it is" feels a bit like old style Rust. -/JT ---> -<!-- I somewhat disagree here; not everyone uses IDE plugins. I'll see what JT -says about mentioning rust-analyzer in chapter 1 rather than in the appendix... -I am in favor of making the book shorter, though, so I've removed the parts -about asking the compiler what the type of something is by deliberately -annotating with the wrong type. /Carol --> - The return type of `File::open` is a `Result<T, E>`. The generic parameter `T` has been filled in by the implementation of `File::open` with the type of the success value, `std::fs::File`, which is a file handle. The type of `E` used in @@ -282,7 +260,7 @@ In the case where `File::open` succeeds, the value in the variable `greeting_file_result` will be an instance of `Ok` that contains a file handle. In the case where it fails, the value in `greeting_file_result` will be an instance of `Err` that contains more information about the kind of error that -happened. +occurred. We need to add to the code in Listing 9-3 to take different actions depending on the value `File::open` returns. Listing 9-4 shows one way to handle the @@ -299,7 +277,9 @@ fn main() { let greeting_file = match greeting_file_result { Ok(file) => file, - Err(error) => panic!("Problem opening the file: {:?}", error), + Err(error) => { + panic!("Problem opening the file: {:?}", error); + } }; } ``` @@ -322,7 +302,9 @@ there’s no file named *hello.txt* in our current directory and we run this code, we’ll see the following output from the `panic!` macro: ``` -thread 'main' panicked at 'Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }', src/main.rs:8:23 +thread 'main' panicked at 'Problem opening the file: Os { code: + 2, kind: NotFound, message: "No such file or directory" }', +src/main.rs:8:23 ``` As usual, this output tells us exactly what has gone wrong. @@ -330,11 +312,11 @@ As usual, this output tells us exactly what has gone wrong. ### Matching on Different Errors The code in Listing 9-4 will `panic!` no matter why `File::open` failed. -However, we want to take different actions for different failure reasons: if +However, we want to take different actions for different failure reasons. If `File::open` failed because the file doesn’t exist, we want to create the file and return the handle to the new file. If `File::open` failed for any other reason—for example, because we didn’t have permission to open the file—we still -want the code to `panic!` in the same way as it did in Listing 9-4. For this we +want the code to `panic!` in the same way it did in Listing 9-4. For this, we add an inner `match` expression, shown in Listing 9-5. Filename: src/main.rs @@ -349,14 +331,22 @@ fn main() { let greeting_file = match greeting_file_result { Ok(file) => file, Err(error) => match error.kind() { - ErrorKind::NotFound => match File::create("hello.txt") { - Ok(fc) => fc, - Err(e) => panic!("Problem creating the file: {:?}", e), + ErrorKind::NotFound => { + match File::create("hello.txt") { + Ok(fc) => fc, + Err(e) => panic!( + "Problem creating the file: {:?}", + e + ), + } } other_error => { - panic!("Problem opening the file: {:?}", other_error); + panic!( + "Problem opening the file: {:?}", + other_error + ); } - } + }, }; } ``` @@ -380,40 +370,41 @@ file can’t be created, a different error message is printed. The second arm of the outer `match` stays the same, so the program panics on any error besides the missing file error. -> ### Alternatives to Using `match` with `Result<T, E>` -> -> That’s a lot of `match`! The `match` expression is very useful but also very -> much a primitive. In Chapter 13, you’ll learn about closures, which are used -> with many of the methods defined on `Result<T, E>`. These methods can be more -> concise than using `match` when handling `Result<T, E>` values in your code. +#### Alternatives to Using match with Result<T, E> -> For example, here’s another way to write the same logic as shown in Listing -> 9-5, this time using closures and the `unwrap_or_else` method: -> -> ``` -> use std::fs::File; -> use std::io::ErrorKind; -> -> fn main() { -> let greeting_file = File::open("hello.txt").unwrap_or_else(|error| { -> if error.kind() == ErrorKind::NotFound { -> File::create("hello.txt").unwrap_or_else(|error| { -> panic!("Problem creating the file: {:?}", error); -> }) -> } else { -> panic!("Problem opening the file: {:?}", error); -> } -> }); -> } -> ``` -> -> Although this code has the same behavior as Listing 9-5, it doesn’t contain -> any `match` expressions and is cleaner to read. Come back to this example -> after you’ve read Chapter 13, and look up the `unwrap_or_else` method in the -> standard library documentation. Many more of these methods can clean up huge -> nested `match` expressions when you’re dealing with errors. +That’s a lot of `match`! The `match` expression is very useful but also very +much a primitive. In Chapter 13, you’ll learn about closures, which are used +with many of the methods defined on `Result<T, E>`. These methods can be more +concise than using `match` when handling `Result<T, E>` values in your code. -### Shortcuts for Panic on Error: `unwrap` and `expect` +For example, here’s another way to write the same logic as shown in Listing +9-5, this time using closures and the `unwrap_or_else` method: + +``` +// src/main.rs +use std::fs::File; +use std::io::ErrorKind; + +fn main() { + let greeting_file = File::open("hello.txt").unwrap_or_else(|error| { + if error.kind() == ErrorKind::NotFound { + File::create("hello.txt").unwrap_or_else(|error| { + panic!("Problem creating the file: {:?}", error); + }) + } else { + panic!("Problem opening the file: {:?}", error); + } + }); +} +``` + +Although this code has the same behavior as Listing 9-5, it doesn’t contain any +`match` expressions and is cleaner to read. Come back to this example after +you’ve read Chapter 13, and look up the `unwrap_or_else` method in the standard +library documentation. Many more of these methods can clean up huge nested +`match` expressions when you’re dealing with errors. + +#### Shortcuts for Panic on Error: unwrap and expect Using `match` works well enough, but it can be a bit verbose and doesn’t always communicate intent well. The `Result<T, E>` type has many helper methods @@ -437,20 +428,11 @@ If we run this code without a *hello.txt* file, we’ll see an error message fro the `panic!` call that the `unwrap` method makes: ``` -thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Error { -repr: Os { code: 2, message: "No such file or directory" } }', -src/libcore/result.rs:906:4 +thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Os { +code: 2, kind: NotFound, message: "No such file or directory" }', +src/main.rs:4:49 ``` -<!--- -More recent rustc versions give a bit better error here (specifically the location): - -thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: -Os { code: 2, kind: NotFound, message: "No such file or directory" }', src/main.rs:4:37 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace -/JT ---> -<!-- I'll update the error output when we're in Word /Carol --> - Similarly, the `expect` method lets us also choose the `panic!` error message. Using `expect` instead of `unwrap` and providing good error messages can convey your intent and make tracking down the source of a panic easier. The syntax of @@ -473,36 +455,20 @@ will be the parameter that we pass to `expect`, rather than the default `panic!` message that `unwrap` uses. Here’s what it looks like: ``` -thread 'main' panicked at 'hello.txt should be included in this project: Error { repr: Os { code: -2, message: "No such file or directory" } }', src/libcore/result.rs:906:4 +thread 'main' panicked at 'hello.txt should be included in this project: Os { +code: 2, kind: NotFound, message: "No such file or directory" }', +src/main.rs:5:10 ``` -<!--- -Ditto with the above: - -thread 'main' panicked at 'Failed to open hello.txt: Os { code: 2, kind: NotFound, -message: "No such file or directory" }', src/main.rs:4:37 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace -/JT ---> -<!-- I'll update the error output when we're in Word /Carol --> - In production-quality code, most Rustaceans choose `expect` rather than `unwrap` and give more context about why the operation is expected to always succeed. That way, if your assumptions are ever proven wrong, you have more information to use in debugging. -<!--- -Now that `unwrap` and `expect` give an improved file location, we may not -need the paragraph above. -/JT ---> -<!-- I've changed the paragraph above, as well as the text in the examaple -usage of `expect`, to better reflect current best practices and the reasons for -them. /Carol --> - ### Propagating Errors When a function’s implementation calls something that might fail, instead of -handling the error within the function itself, you can return the error to the +handling the error within the function itself you can return the error to the calling code so that it can decide what to do. This is known as *propagating* the error and gives more control to the calling code, where there might be more information or logic that dictates how the error should be handled than what @@ -518,19 +484,19 @@ Filename: src/main.rs use std::fs::File; use std::io::{self, Read}; -fn read_username_from_file() -> Result<String, io::Error> [1] { - let username_file_result = File::open("hello.txt"); [2] +1 fn read_username_from_file() -> Result<String, io::Error> { + 2 let username_file_result = File::open("hello.txt"); - let mut username_file [3] = match username_file_result { - Ok(file) => file, [4] - Err(e) => return Err(e), [5] + 3 let mut username_file = match username_file_result { + 4 Ok(file) => file, + 5 Err(e) => return Err(e), }; - let mut username = String::new(); [6] + 6 let mut username = String::new(); - match username_file.read_to_string(&mut username) [7] { - Ok(_) => Ok(username), [8] - Err(e) => Err(e), [9] + 7 match username_file.read_to_string(&mut username) { + 8 Ok(_) => Ok(username), + 9 Err(e) => Err(e), } } ``` @@ -541,12 +507,12 @@ This function can be written in a much shorter way, but we’re going to start b doing a lot of it manually in order to explore error handling; at the end, we’ll show the shorter way. Let’s look at the return type of the function first: `Result<String, io::Error>` [1]. This means the function is returning a -value of the type `Result<T, E>` where the generic parameter `T` has been -filled in with the concrete type `String`, and the generic type `E` has been +value of the type `Result<T, E>`, where the generic parameter `T` has been +filled in with the concrete type `String` and the generic type `E` has been filled in with the concrete type `io::Error`. If this function succeeds without any problems, the code that calls this -function will receive an `Ok` value that holds a `String`—the username that +function will receive an `Ok` value that holds a `String`—the `username` that this function read from the file [8]. If this function encounters any problems, the calling code will receive an `Err` value that holds an instance of `io::Error` that contains more information about what the problems were. We @@ -564,9 +530,9 @@ function continues. In the `Err` case, instead of calling `panic!`, we use the error value from `File::open`, now in the pattern variable `e`, back to the calling code as this function’s error value [5]. -So if we have a file handle in `username_file`, the function then creates a new -`String` in variable `username` [6] and calls the `read_to_string` method on -the file handle in `username_file` to read the contents of the file into +So, if we have a file handle in `username_file`, the function then creates a +new `String` in variable `username` [6] and calls the `read_to_string` method +on the file handle in `username_file` to read the contents of the file into `username` [7]. The `read_to_string` method also returns a `Result` because it might fail, even though `File::open` succeeded. So we need another `match` to handle that `Result`: if `read_to_string` succeeds, then our function has @@ -576,20 +542,6 @@ same way that we returned the error value in the `match` that handled the return value of `File::open`. However, we don’t need to explicitly say `return`, because this is the last expression in the function [9]. -<!--- -Style nit: I'm finding the above two paragraphs a bit difficult to read -comfortably. I think one issue is that we're using a handful of single letter -variable names while also trying to walk someone through an explanation of -multiple concepts. - -Maybe just me? But feels like the above example might be explained a bit better -if we used more complete variable names so the explanation could have a better -flow (without trying to remember what each of the single-letter variables meant) -/JT ---> -<!-- Totally valid! I've changed the variable names in this, previous, and -following examples, broke up these paragraphs a bit, and added wingdings. -/Carol --> - The code that calls this code will then handle getting either an `Ok` value that contains a username or an `Err` value that contains an `io::Error`. It’s up to the calling code to decide what to do with those values. If the calling @@ -602,18 +554,17 @@ it to handle appropriately. This pattern of propagating errors is so common in Rust that Rust provides the question mark operator `?` to make this easier. -#### A Shortcut for Propagating Errors: the `?` Operator +#### A Shortcut for Propagating Errors: The ? Operator Listing 9-7 shows an implementation of `read_username_from_file` that has the -same functionality as in Listing 9-6, but this implementation uses the -`?` operator. +same functionality as in Listing 9-6, but this implementation uses the `?` +operator. Filename: src/main.rs ``` use std::fs::File; -use std::io; -use std::io::Read; +use std::io::{self, Read}; fn read_username_from_file() -> Result<String, io::Error> { let mut username_file = File::open("hello.txt")?; @@ -651,13 +602,6 @@ define `impl From<io::Error> for OurError` to construct an instance of `read_username_from_file` will call `from` and convert the error types without needing to add any more code to the function. -<!--- -It's a bit fuzzy what `impl From<OtherError> for ReturnedError` means. We may -want to use a more concrete example, like: `impl From<OurError> for io::Error`. -/JT ---> -<!-- I've added a more concrete example here, but converting the other way, -which I think is more likely in production code /Carol --> - In the context of Listing 9-7, the `?` at the end of the `File::open` call will return the value inside an `Ok` to the variable `username_file`. If an error occurs, the `?` operator will return early out of the whole function and give @@ -672,8 +616,7 @@ Filename: src/main.rs ``` use std::fs::File; -use std::io; -use std::io::Read; +use std::io::{self, Read}; fn read_username_from_file() -> Result<String, io::Error> { let mut username = String::new(); @@ -718,7 +661,7 @@ into that `String`, and returns it. Of course, using `fs::read_to_string` doesn’t give us the opportunity to explain all the error handling, so we did it the longer way first. -#### Where The `?` Operator Can Be Used +#### Where the ? Operator Can Be Used The `?` operator can only be used in functions whose return type is compatible with the value the `?` is used on. This is because the `?` operator is defined @@ -729,8 +672,8 @@ as the `match` expression we defined in Listing 9-6. In Listing 9-6, the it’s compatible with this `return`. In Listing 9-10, let’s look at the error we’ll get if we use the `?` operator -in a `main` function with a return type incompatible with the type of the value -we use `?` on: +in a `main` function with a return type that is incompatible with the type of +the value we use `?` on. Filename: src/main.rs @@ -743,7 +686,7 @@ fn main() { ``` Listing 9-10: Attempting to use the `?` in the `main` function that returns -`()` won’t compile +`()` won’t compile. This code opens a file, which might fail. The `?` operator follows the `Result` value returned by `File::open`, but this `main` function has the return type of @@ -751,15 +694,19 @@ value returned by `File::open`, but this `main` function has the return type of message: ``` -error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`) - --> src/main.rs:4:36 - | -3 | / fn main() { -4 | | let f = File::open("hello.txt")?; - | | ^ cannot use the `?` operator in a function that returns `()` -5 | | } - | |_- this function should return `Result` or `Option` to accept `?` - | +error[E0277]: the `?` operator can only be used in a function that returns +`Result` or `Option` (or another type that implements `FromResidual`) + --> src/main.rs:4:48 + | +3 | / fn main() { +4 | | let greeting_file = File::open("hello.txt")?; + | | ^ cannot use the `?` +operator in a function that returns `()` +5 | | } + | |_- this function should return `Result` or `Option` to accept `?` + | + = help: the trait `FromResidual<Result<Infallible, std::io::Error>>` is not +implemented for `()` ``` This error points out that we’re only allowed to use the `?` operator in a @@ -768,9 +715,9 @@ function that returns `Result`, `Option`, or another type that implements To fix the error, you have two choices. One choice is to change the return type of your function to be compatible with the value you’re using the `?` operator -on as long as you have no restrictions preventing that. The other technique is -to use a `match` or one of the `Result<T, E>` methods to handle the `Result<T, -E>` in whatever way is appropriate. +on as long as you have no restrictions preventing that. The other choice is to +use a `match` or one of the `Result<T, E>` methods to handle the `Result<T, E>` +in whatever way is appropriate. The error message also mentioned that `?` can be used with `Option<T>` values as well. As with using `?` on `Result`, you can only use `?` on `Option` in a @@ -778,9 +725,9 @@ function that returns an `Option`. The behavior of the `?` operator when called on an `Option<T>` is similar to its behavior when called on a `Result<T, E>`: if the value is `None`, the `None` will be returned early from the function at that point. If the value is `Some`, the value inside the `Some` is the -resulting value of the expression and the function continues. Listing 9-11 has +resultant value of the expression, and the function continues. Listing 9-11 has an example of a function that finds the last character of the first line in the -given text: +given text. ``` fn last_char_of_first_line(text: &str) -> Option<char> { @@ -804,7 +751,7 @@ The `?` extracts the string slice, and we can call `chars` on that string slice to get an iterator of its characters. We’re interested in the last character in this first line, so we call `last` to return the last item in the iterator. This is an `Option` because it’s possible that the first line is the empty -string, for example if `text` starts with a blank line but has characters on +string; for example, if `text` starts with a blank line but has characters on other lines, as in `"\nhi"`. However, if there is a last character on the first line, it will be returned in the `Some` variant. The `?` operator in the middle gives us a concise way to express this logic, allowing us to implement the @@ -819,14 +766,16 @@ you can use methods like the `ok` method on `Result` or the `ok_or` method on `Option` to do the conversion explicitly. So far, all the `main` functions we’ve used return `()`. The `main` function is -special because it’s the entry and exit point of executable programs, and there -are restrictions on what its return type can be for the programs to behave as -expected. +special because it’s the entry point and exit point of an executable program, +and there are restrictions on what its return type can be for the program to +behave as expected. -Luckily, `main` can also return a `Result<(), E>`. Listing 9-12 has the -code from Listing 9-10 but we’ve changed the return type of `main` to be +Luckily, `main` can also return a `Result<(), E>`. Listing 9-12 has the code +from Listing 9-10, but we’ve changed the return type of `main` to be `Result<(), Box<dyn Error>>` and added a return value `Ok(())` to the end. This -code will now compile: +code will now compile. + +Filename: src/main.rs ``` use std::error::Error; @@ -839,51 +788,36 @@ fn main() -> Result<(), Box<dyn Error>> { } ``` -<!--- -The move to `Box<dyn Error>` isn't unexpected for an experienced Rust -developer, but I wonder if we should keep `std::io::Error` here to keep with -the flow of the previous examples? - -I think my instinct was to mention this since we don't use the flexibility -the trait object gives us. Instead, we switch to explaining how exit codes -work with Result values. -/JT ---> -<!-- The idea here was to give the reader code that will work in the future no -matter what errors they're trying to return from main. If we put in -std::io::Error, it'll work for this example, but probably not in the reader's -own projects. I've added a sentence to the end of the paragraph after Listing -9-12's caption to explain this thinking. /Carol --> - Listing 9-12: Changing `main` to return `Result<(), E>` allows the use of the -`?` operator on `Result` values - -The `Box<dyn Error>` type is a *trait object*, which we’ll talk about in the -“Using Trait Objects that Allow for Values of Different Types” section in -Chapter 17. For now, you can read `Box<dyn Error>` to mean “any kind of error.” -Using `?` on a `Result` value in a `main` function with the error type `Box<dyn -Error>` is allowed, because it allows any `Err` value to be returned early. -Even though the body of this `main` function will only ever return errors of -type `std::io::Error`, by specifying `Box<dyn Error>`, this signature will -continue to be correct even if more code that returns other errors is added to -the body of `main`. - -When a `main` function returns a `Result<(), E>`, the executable will -exit with a value of `0` if `main` returns `Ok(())` and will exit with a -nonzero value if `main` returns an `Err` value. Executables written in C return -integers when they exit: programs that exit successfully return the integer -`0`, and programs that error return some integer other than `0`. Rust also -returns integers from executables to be compatible with this convention. +`?` operator on `Result` values. + +The `Box<dyn Error>` type is a *trait object*, which we’ll talk about in “Using +Trait Objects That Allow for Values of Different Types” on page XX. For now, +you can read `Box<dyn Error>` to mean “any kind of error.” Using `?` on a +`Result` value in a `main` function with the error type `Box<dyn Error>` is +allowed because it allows any `Err` value to be returned early. Even though the +body of this `main` function will only ever return errors of type +`std::io::Error`, by specifying `Box<dyn Error>`, this signature will continue +to be correct even if more code that returns other errors is added to the body +of `main`. + +When a `main` function returns a `Result<(), E>`, the executable will exit with +a value of `0` if `main` returns `Ok(())` and will exit with a nonzero value if +`main` returns an `Err` value. Executables written in C return integers when +they exit: programs that exit successfully return the integer `0`, and programs +that error return some integer other than `0`. Rust also returns integers from +executables to be compatible with this convention. The `main` function may return any types that implement the `std::process::Termination` trait, which contains a function `report` that -returns an `ExitCode` Consult the standard library documentation for more +returns an `ExitCode`. Consult the standard library documentation for more information on implementing the `Termination` trait for your own types. Now that we’ve discussed the details of calling `panic!` or returning `Result`, let’s return to the topic of how to decide which is appropriate to use in which cases. -## To `panic!` or Not to `panic!` +## To panic! or Not to panic! So how do you decide when you should call `panic!` and when you should return `Result`? When code panics, there’s no way to recover. You could call `panic!` @@ -904,11 +838,11 @@ some general guidelines on how to decide whether to panic in library code. ### Examples, Prototype Code, and Tests -When you’re writing an example to illustrate some concept, also including robust -error-handling code can make the example less clear. In -examples, it’s understood that a call to a method like `unwrap` that could -panic is meant as a placeholder for the way you’d want your application to -handle errors, which can differ based on what the rest of your code is doing. +When you’re writing an example to illustrate some concept, also including +robust error-handling code can make the example less clear. In examples, it’s +understood that a call to a method like `unwrap` that could panic is meant as a +placeholder for the way you’d want your application to handle errors, which can +differ based on what the rest of your code is doing. Similarly, the `unwrap` and `expect` methods are very handy when prototyping, before you’re ready to decide how to handle errors. They leave clear markers in @@ -931,17 +865,6 @@ that you’ll never have an `Err` variant, it’s perfectly acceptable to call `unwrap`, and even better to document the reason you think you’ll never have an `Err` variant in the `expect` text. Here’s an example: -<!--- -Some Rust devs may have a nuanced take on the above, myself included. I'd say -you'd be safer to use `.expect(...)` and put as the argument the reason why it -should never fail. If, in the future it ever *does* fail for some reason -(probably as a result of many code fixes over time), then you've got a message -to start with telling you what the original expectation was. -/JT ---> -<!-- I agree with this and reinforcing this best practice; I've changed the -`unwrap` to `expect` and demonstrated a good message. I still don't want to -shame people too much for using `unwrap`, though. /Carol --> - ``` use std::net::IpAddr; @@ -960,25 +883,24 @@ valid IP address. If the IP address string came from a user rather than being hardcoded into the program and therefore *did* have a possibility of failure, we’d definitely want to handle the `Result` in a more robust way instead. Mentioning the assumption that this IP address is hardcoded will prompt us to -change `expect` to better error handling code if in the future, we need to get +change `expect` to better error-handling code if, in the future, we need to get the IP address from some other source instead. ### Guidelines for Error Handling -It’s advisable to have your code panic when it’s possible that your code -could end up in a bad state. In this context, a *bad state* is when some -assumption, guarantee, contract, or invariant has been broken, such as when -invalid values, contradictory values, or missing values are passed to your -code—plus one or more of the following: +It’s advisable to have your code panic when it’s possible that your code could +end up in a bad state. In this context, a *bad state* is when some assumption, +guarantee, contract, or invariant has been broken, such as when invalid values, +contradictory values, or missing values are passed to your code—plus one or +more of the following: * The bad state is something that is unexpected, as opposed to something that - will likely happen occasionally, like a user entering data in the wrong - format. +will likely happen occasionally, like a user entering data in the wrong format. * Your code after this point needs to rely on not being in this bad state, - rather than checking for the problem at every step. +rather than checking for the problem at every step. * There’s not a good way to encode this information in the types you use. We’ll - work through an example of what we mean in the “Encoding States and Behavior - as Types” section of Chapter 17. +work through an example of what we mean in “Encoding States and Behavior as +Types” on page XX. If someone calls your code and passes in values that don’t make sense, it’s best to return an error if you can so the user of the library can decide what @@ -989,24 +911,6 @@ development. Similarly, `panic!` is often appropriate if you’re calling external code that is out of your control and it returns an invalid state that you have no way of fixing. -<!--- -Disagree a bit with the above. I don't think libraries should ever panic. They -should always be written defensively so they can be used in a broader range of -applications, which include applications where crashing could result in data -loss. - -Rather than crashing, libraries can encode the reasons they failed based on the -user's input into an error that can be returned to the user. - -In practice, the only time the application should absolutely crash is if -continuing could bring harm to the user's machine, their data, filesystem, and -so on. Otherwise, the user should just be given a warning that the operation -couldn't be completed successfully, so they can take their next action. If we -crash, unfortunately the user never gets that choice. -/JT ---> -<!-- I think we actually agree here but the original text wasn't clear enough; -I've edited. /Carol --> - However, when failure is expected, it’s more appropriate to return a `Result` than to make a `panic!` call. Examples include a parser being given malformed data or an HTTP request returning a status that indicates you have hit a rate @@ -1022,25 +926,12 @@ an out-of-bounds memory access: trying to access memory that doesn’t belong to the current data structure is a common security problem. Functions often have *contracts*: their behavior is only guaranteed if the inputs meet particular requirements. Panicking when the contract is violated makes sense because a -contract violation always indicates a caller-side bug and it’s not a kind of +contract violation always indicates a caller-side bug, and it’s not a kind of error you want the calling code to have to explicitly handle. In fact, there’s no reasonable way for calling code to recover; the calling *programmers* need to fix the code. Contracts for a function, especially when a violation will cause a panic, should be explained in the API documentation for the function. -<!--- -The wording of the first sentence in the above paragraph reads like we should -panic on invalid data, but in the previous paragraph we say malformed data -should be a `Result`. The rest makes sense, where the spirit of when the stdlib -panics is less about invalid data and more about when the user will be put at -risk. -/JT ---> -<!-- I think we were trying to draw a distinction between "malformed" and -"invalid" values that perhaps wasn't very clear. I've tried to clarify by -adding "could put a user at risk", but I don't really want to get into the -specifics of this because only a subset of readers will be writing code like -this... /Carol --> - However, having lots of error checks in all of your functions would be verbose and annoying. Fortunately, you can use Rust’s type system (and thus the type checking done by the compiler) to do many of the checks for you. If your @@ -1064,16 +955,18 @@ numbers before checking it against our secret number; we only validated that the guess was positive. In this case, the consequences were not very dire: our output of “Too high” or “Too low” would still be correct. But it would be a useful enhancement to guide the user toward valid guesses and have different -behavior when a user guesses a number that’s out of range versus when a user -types, for example, letters instead. +behavior when the user guesses a number that’s out of range versus when the +user types, for example, letters instead. One way to do this would be to parse the guess as an `i32` instead of only a `u32` to allow potentially negative numbers, and then add a check for the number being in range, like so: +Filename: src/main.rs + ``` loop { - // --snip-- + --snip-- let guess: i32 = match guess.trim().parse() { Ok(num) => num, @@ -1086,7 +979,7 @@ loop { } match guess.cmp(&secret_number) { - // --snip-- + --snip-- } ``` @@ -1096,7 +989,7 @@ and ask for another guess. After the `if` expression, we can proceed with the comparisons between `guess` and the secret number knowing that `guess` is between 1 and 100. -However, this is not an ideal solution: if it was absolutely critical that the +However, this is not an ideal solution: if it were absolutely critical that the program only operated on values between 1 and 100, and it had many functions with this requirement, having a check like this in every function would be tedious (and might impact performance). @@ -1108,71 +1001,60 @@ confidently use the values they receive. Listing 9-13 shows one way to define a `Guess` type that will only create an instance of `Guess` if the `new` function receives a value between 1 and 100. +Filename: src/lib.rs + ``` -pub struct Guess { +1 pub struct Guess { value: i32, } impl Guess { - pub fn new(value: i32) -> Guess { - if value < 1 || value > 100 { - panic!("Guess value must be between 1 and 100, got {}.", value); + 2 pub fn new(value: i32) -> Guess { + 3 if value < 1 || value > 100 { + 4 panic!( + "Guess value must be between 1 and 100, got {}.", + value + ); } - Guess { value } + 5 Guess { value } } - pub fn value(&self) -> i32 { + 6 pub fn value(&self) -> i32 { self.value } } ``` -<!--- -The above example feels a bit off to me. We talk earlier about user input being -a prime candidate for recoverable errors, and then we talk about encoding only -proper states in the type system. But this examples seems to work with user -input and panic if it's not correct, rather than using recoverable errors or -encoding the state into the type. - -Maybe you could have them guess rock/paper/scissors and encode the -rock/paper/scissor as three enum values, and if they type something outside of -that, we don't allow it. Otherwise we create an enum of that value. -/JT ---> -<!-- The point about this listing panicking is valid, but I disagree a little. -I think this is encoding only valid states into the type system. Also, Chapter -11 builds on this example to show how to use `should_panic`, so I'm going to -leave this the way it is. /Carol --> - Listing 9-13: A `Guess` type that will only continue with values between 1 and 100 -First, we define a struct named `Guess` that has a field named `value` that -holds an `i32`. This is where the number will be stored. +First we define a struct named `Guess` that has a field named `value` that +holds an `i32` [1]. This is where the number will be stored. Then we implement an associated function named `new` on `Guess` that creates -instances of `Guess` values. The `new` function is defined to have one +instances of `Guess` values [2]. The `new` function is defined to have one parameter named `value` of type `i32` and to return a `Guess`. The code in the -body of the `new` function tests `value` to make sure it’s between 1 and 100. -If `value` doesn’t pass this test, we make a `panic!` call, which will alert -the programmer who is writing the calling code that they have a bug they need -to fix, because creating a `Guess` with a `value` outside this range would +body of the `new` function tests `value` to make sure it’s between 1 and 100 +[3]. If `value` doesn’t pass this test, we make a `panic!` call [4], which will +alert the programmer who is writing the calling code that they have a bug they +need to fix, because creating a `Guess` with a `value` outside this range would violate the contract that `Guess::new` is relying on. The conditions in which `Guess::new` might panic should be discussed in its public-facing API documentation; we’ll cover documentation conventions indicating the possibility of a `panic!` in the API documentation that you create in Chapter 14. If `value` does pass the test, we create a new `Guess` with its `value` field set -to the `value` parameter and return the `Guess`. +to the `value` parameter and return the `Guess` [5]. Next, we implement a method named `value` that borrows `self`, doesn’t have any -other parameters, and returns an `i32`. This kind of method is sometimes called -a *getter*, because its purpose is to get some data from its fields and return -it. This public method is necessary because the `value` field of the `Guess` -struct is private. It’s important that the `value` field be private so code -using the `Guess` struct is not allowed to set `value` directly: code outside -the module *must* use the `Guess::new` function to create an instance of -`Guess`, thereby ensuring there’s no way for a `Guess` to have a `value` that -hasn’t been checked by the conditions in the `Guess::new` function. +other parameters, and returns an `i32` [6]. This kind of method is sometimes +called a *getter* because its purpose is to get some data from its fields and +return it. This public method is necessary because the `value` field of the +`Guess` struct is private. It’s important that the `value` field be private so +code using the `Guess` struct is not allowed to set `value` directly: code +outside the module *must* use the `Guess::new` function to create an instance +of `Guess`, thereby ensuring there’s no way for a `Guess` to have a `value` +that hasn’t been checked by the conditions in the `Guess::new` function. A function that has a parameter or returns only numbers between 1 and 100 could then declare in its signature that it takes or returns a `Guess` rather than an @@ -1180,7 +1062,7 @@ then declare in its signature that it takes or returns a `Guess` rather than an ## Summary -Rust’s error handling features are designed to help you write more robust code. +Rust’s error-handling features are designed to help you write more robust code. The `panic!` macro signals that your program is in a state it can’t handle and lets you tell the process to stop instead of trying to proceed with invalid or incorrect values. The `Result` enum uses Rust’s type system to indicate that @@ -1193,17 +1075,3 @@ Now that you’ve seen useful ways that the standard library uses generics with the `Option` and `Result` enums, we’ll talk about how generics work and how you can use them in your code. -<!--- -A meta comment: the coverage of `panic!` here feels helpful in terms of giving -a more complete understanding of Rust, but in practice (and this may depend -on domain), using `panic!` should be a fairly limited thing. - -Something I noticed we don't touch on but may want to is panic hooks, as -unrecoverable errors isn't exactly true. You can recover from an unwinding -panic if you need to code defensively against, say, a dependency panicking and -you don't want your app to go down as a result. -/JT ---> -<!-- Yeahhh I don't want to mention panic hooks, one because I don't think most -people will need to think about them or implement one, and two because a subset -of people will look at that and think "oh look, exception handling!" which... -is not what it's for. /Carol --> |