1 ## Recoverable Errors with `Result`
3 Most errors aren’t serious enough to require the program to stop entirely.
4 Sometimes, when a function fails, it’s for a reason that you can easily
5 interpret and respond to. For example, if you try to open a file and that
6 operation fails because the file doesn’t exist, you might want to create the
7 file instead of terminating the process.
9 Recall from [“Handling Potential Failure with the `Result`
10 Type”][handle_failure]<!-- ignore --> in Chapter 2 that the `Result` enum is
11 defined as having two variants, `Ok` and `Err`, as follows:
20 The `T` and `E` are generic type parameters: we’ll discuss generics in more
21 detail in Chapter 10. What you need to know right now is that `T` represents
22 the type of the value that will be returned in a success case within the `Ok`
23 variant, and `E` represents the type of the error that will be returned in a
24 failure case within the `Err` variant. Because `Result` has these generic type
25 parameters, we can use the `Result` type and the functions defined on it in
26 many different situations where the successful value and error value we want to
29 Let’s call a function that returns a `Result` value because the function could
30 fail. In Listing 9-3 we try to open a file.
32 <span class="filename">Filename: src/main.rs</span>
35 {{#rustdoc_include ../listings/ch09-error-handling/listing-09-03/src/main.rs}}
38 <span class="caption">Listing 9-3: Opening a file</span>
40 The return type of `File::open` is a `Result<T, E>`. The generic parameter `T`
41 has been filled in by the implementation of `File::open` with the type of the
42 success value, `std::fs::File`, which is a file handle. The type of `E` used in
43 the error value is `std::io::Error`. This return type means the call to
44 `File::open` might succeed and return a file handle that we can read from or
45 write to. The function call also might fail: for example, the file might not
46 exist, or we might not have permission to access the file. The `File::open`
47 function needs to have a way to tell us whether it succeeded or failed and at
48 the same time give us either the file handle or error information. This
49 information is exactly what the `Result` enum conveys.
51 In the case where `File::open` succeeds, the value in the variable
52 `greeting_file_result` will be an instance of `Ok` that contains a file handle.
53 In the case where it fails, the value in `greeting_file_result` will be an
54 instance of `Err` that contains more information about the kind of error that
57 We need to add to the code in Listing 9-3 to take different actions depending
58 on the value `File::open` returns. Listing 9-4 shows one way to handle the
59 `Result` using a basic tool, the `match` expression that we discussed in
62 <span class="filename">Filename: src/main.rs</span>
65 {{#rustdoc_include ../listings/ch09-error-handling/listing-09-04/src/main.rs}}
68 <span class="caption">Listing 9-4: Using a `match` expression to handle the
69 `Result` variants that might be returned</span>
71 Note that, like the `Option` enum, the `Result` enum and its variants have been
72 brought into scope by the prelude, so we don’t need to specify `Result::`
73 before the `Ok` and `Err` variants in the `match` arms.
75 When the result is `Ok`, this code will return the inner `file` value out of
76 the `Ok` variant, and we then assign that file handle value to the variable
77 `greeting_file`. After the `match`, we can use the file handle for reading or
80 The other arm of the `match` handles the case where we get an `Err` value from
81 `File::open`. In this example, we’ve chosen to call the `panic!` macro. If
82 there’s no file named *hello.txt* in our current directory and we run this
83 code, we’ll see the following output from the `panic!` macro:
86 {{#include ../listings/ch09-error-handling/listing-09-04/output.txt}}
89 As usual, this output tells us exactly what has gone wrong.
91 ### Matching on Different Errors
93 The code in Listing 9-4 will `panic!` no matter why `File::open` failed.
94 However, we want to take different actions for different failure reasons: if
95 `File::open` failed because the file doesn’t exist, we want to create the file
96 and return the handle to the new file. If `File::open` failed for any other
97 reason—for example, because we didn’t have permission to open the file—we still
98 want the code to `panic!` in the same way as it did in Listing 9-4. For this we
99 add an inner `match` expression, shown in Listing 9-5.
101 <span class="filename">Filename: src/main.rs</span>
103 <!-- ignore this test because otherwise it creates hello.txt which causes other
104 tests to fail lol -->
107 {{#rustdoc_include ../listings/ch09-error-handling/listing-09-05/src/main.rs}}
110 <span class="caption">Listing 9-5: Handling different kinds of errors in
111 different ways</span>
113 The type of the value that `File::open` returns inside the `Err` variant is
114 `io::Error`, which is a struct provided by the standard library. This struct
115 has a method `kind` that we can call to get an `io::ErrorKind` value. The enum
116 `io::ErrorKind` is provided by the standard library and has variants
117 representing the different kinds of errors that might result from an `io`
118 operation. The variant we want to use is `ErrorKind::NotFound`, which indicates
119 the file we’re trying to open doesn’t exist yet. So we match on
120 `greeting_file_result`, but we also have an inner match on `error.kind()`.
122 The condition we want to check in the inner match is whether the value returned
123 by `error.kind()` is the `NotFound` variant of the `ErrorKind` enum. If it is,
124 we try to create the file with `File::create`. However, because `File::create`
125 could also fail, we need a second arm in the inner `match` expression. When the
126 file can’t be created, a different error message is printed. The second arm of
127 the outer `match` stays the same, so the program panics on any error besides
128 the missing file error.
130 > ### Alternatives to Using `match` with `Result<T, E>`
132 > That’s a lot of `match`! The `match` expression is very useful but also very
133 > much a primitive. In Chapter 13, you’ll learn about closures, which are used
134 > with many of the methods defined on `Result<T, E>`. These methods can be more
135 > concise than using `match` when handling `Result<T, E>` values in your code.
137 > For example, here’s another way to write the same logic as shown in Listing
138 > 9-5, this time using closures and the `unwrap_or_else` method:
140 > <!-- CAN'T EXTRACT SEE https://github.com/rust-lang/mdBook/issues/1127 -->
144 > use std::io::ErrorKind;
147 > let greeting_file = File::open("hello.txt").unwrap_or_else(|error| {
148 > if error.kind() == ErrorKind::NotFound {
149 > File::create("hello.txt").unwrap_or_else(|error| {
150 > panic!("Problem creating the file: {:?}", error);
153 > panic!("Problem opening the file: {:?}", error);
159 > Although this code has the same behavior as Listing 9-5, it doesn’t contain
160 > any `match` expressions and is cleaner to read. Come back to this example
161 > after you’ve read Chapter 13, and look up the `unwrap_or_else` method in the
162 > standard library documentation. Many more of these methods can clean up huge
163 > nested `match` expressions when you’re dealing with errors.
165 ### Shortcuts for Panic on Error: `unwrap` and `expect`
167 Using `match` works well enough, but it can be a bit verbose and doesn’t always
168 communicate intent well. The `Result<T, E>` type has many helper methods
169 defined on it to do various, more specific tasks. The `unwrap` method is a
170 shortcut method implemented just like the `match` expression we wrote in
171 Listing 9-4. If the `Result` value is the `Ok` variant, `unwrap` will return
172 the value inside the `Ok`. If the `Result` is the `Err` variant, `unwrap` will
173 call the `panic!` macro for us. Here is an example of `unwrap` in action:
175 <span class="filename">Filename: src/main.rs</span>
178 {{#rustdoc_include ../listings/ch09-error-handling/no-listing-04-unwrap/src/main.rs}}
181 If we run this code without a *hello.txt* file, we’ll see an error message from
182 the `panic!` call that the `unwrap` method makes:
184 <!-- manual-regeneration
185 cd listings/ch09-error-handling/no-listing-04-unwrap
187 copy and paste relevant text
191 thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Os {
192 code: 2, kind: NotFound, message: "No such file or directory" }',
196 Similarly, the `expect` method lets us also choose the `panic!` error message.
197 Using `expect` instead of `unwrap` and providing good error messages can convey
198 your intent and make tracking down the source of a panic easier. The syntax of
199 `expect` looks like this:
201 <span class="filename">Filename: src/main.rs</span>
204 {{#rustdoc_include ../listings/ch09-error-handling/no-listing-05-expect/src/main.rs}}
207 We use `expect` in the same way as `unwrap`: to return the file handle or call
208 the `panic!` macro. The error message used by `expect` in its call to `panic!`
209 will be the parameter that we pass to `expect`, rather than the default
210 `panic!` message that `unwrap` uses. Here’s what it looks like:
212 <!-- manual-regeneration
213 cd listings/ch09-error-handling/no-listing-05-expect
215 copy and paste relevant text
219 thread 'main' panicked at 'hello.txt should be included in this project: Os {
220 code: 2, kind: NotFound, message: "No such file or directory" }',
224 In production-quality code, most Rustaceans choose `expect` rather than
225 `unwrap` and give more context about why the operation is expected to always
226 succeed. That way, if your assumptions are ever proven wrong, you have more
227 information to use in debugging.
229 ### Propagating Errors
231 When a function’s implementation calls something that might fail, instead of
232 handling the error within the function itself, you can return the error to the
233 calling code so that it can decide what to do. This is known as *propagating*
234 the error and gives more control to the calling code, where there might be more
235 information or logic that dictates how the error should be handled than what
236 you have available in the context of your code.
238 For example, Listing 9-6 shows a function that reads a username from a file. If
239 the file doesn’t exist or can’t be read, this function will return those errors
240 to the code that called the function.
242 <span class="filename">Filename: src/main.rs</span>
244 <!-- Deliberately not using rustdoc_include here; the `main` function in the
245 file panics. We do want to include it for reader experimentation purposes, but
246 don't want to include it for rustdoc testing purposes. -->
249 {{#include ../listings/ch09-error-handling/listing-09-06/src/main.rs:here}}
252 <span class="caption">Listing 9-6: A function that returns errors to the
253 calling code using `match`</span>
255 This function can be written in a much shorter way, but we’re going to start by
256 doing a lot of it manually in order to explore error handling; at the end,
257 we’ll show the shorter way. Let’s look at the return type of the function
258 first: `Result<String, io::Error>`. This means the function is returning a
259 value of the type `Result<T, E>` where the generic parameter `T` has been
260 filled in with the concrete type `String`, and the generic type `E` has been
261 filled in with the concrete type `io::Error`.
263 If this function succeeds without any problems, the code that calls this
264 function will receive an `Ok` value that holds a `String`—the username that
265 this function read from the file. If this function encounters any problems, the
266 calling code will receive an `Err` value that holds an instance of `io::Error`
267 that contains more information about what the problems were. We chose
268 `io::Error` as the return type of this function because that happens to be the
269 type of the error value returned from both of the operations we’re calling in
270 this function’s body that might fail: the `File::open` function and the
271 `read_to_string` method.
273 The body of the function starts by calling the `File::open` function. Then we
274 handle the `Result` value with a `match` similar to the `match` in Listing 9-4.
275 If `File::open` succeeds, the file handle in the pattern variable `file`
276 becomes the value in the mutable variable `username_file` and the function
277 continues. In the `Err` case, instead of calling `panic!`, we use the `return`
278 keyword to return early out of the function entirely and pass the error value
279 from `File::open`, now in the pattern variable `e`, back to the calling code as
280 this function’s error value.
282 So if we have a file handle in `username_file`, the function then creates a new
283 `String` in variable `username` and calls the `read_to_string` method on
284 the file handle in `username_file` to read the contents of the file into
285 `username`. The `read_to_string` method also returns a `Result` because it
286 might fail, even though `File::open` succeeded. So we need another `match` to
287 handle that `Result`: if `read_to_string` succeeds, then our function has
288 succeeded, and we return the username from the file that’s now in `username`
289 wrapped in an `Ok`. If `read_to_string` fails, we return the error value in the
290 same way that we returned the error value in the `match` that handled the
291 return value of `File::open`. However, we don’t need to explicitly say
292 `return`, because this is the last expression in the function.
294 The code that calls this code will then handle getting either an `Ok` value
295 that contains a username or an `Err` value that contains an `io::Error`. It’s
296 up to the calling code to decide what to do with those values. If the calling
297 code gets an `Err` value, it could call `panic!` and crash the program, use a
298 default username, or look up the username from somewhere other than a file, for
299 example. We don’t have enough information on what the calling code is actually
300 trying to do, so we propagate all the success or error information upward for
301 it to handle appropriately.
303 This pattern of propagating errors is so common in Rust that Rust provides the
304 question mark operator `?` to make this easier.
306 #### A Shortcut for Propagating Errors: the `?` Operator
308 Listing 9-7 shows an implementation of `read_username_from_file` that has the
309 same functionality as in Listing 9-6, but this implementation uses the
312 <span class="filename">Filename: src/main.rs</span>
314 <!-- Deliberately not using rustdoc_include here; the `main` function in the
315 file panics. We do want to include it for reader experimentation purposes, but
316 don't want to include it for rustdoc testing purposes. -->
319 {{#include ../listings/ch09-error-handling/listing-09-07/src/main.rs:here}}
322 <span class="caption">Listing 9-7: A function that returns errors to the
323 calling code using the `?` operator</span>
325 The `?` placed after a `Result` value is defined to work in almost the same way
326 as the `match` expressions we defined to handle the `Result` values in Listing
327 9-6. If the value of the `Result` is an `Ok`, the value inside the `Ok` will
328 get returned from this expression, and the program will continue. If the value
329 is an `Err`, the `Err` will be returned from the whole function as if we had
330 used the `return` keyword so the error value gets propagated to the calling
333 There is a difference between what the `match` expression from Listing 9-6 does
334 and what the `?` operator does: error values that have the `?` operator called
335 on them go through the `from` function, defined in the `From` trait in the
336 standard library, which is used to convert values from one type into another.
337 When the `?` operator calls the `from` function, the error type received is
338 converted into the error type defined in the return type of the current
339 function. This is useful when a function returns one error type to represent
340 all the ways a function might fail, even if parts might fail for many different
343 For example, we could change the `read_username_from_file` function in Listing
344 9-7 to return a custom error type named `OurError` that we define. If we also
345 define `impl From<io::Error> for OurError` to construct an instance of
346 `OurError` from an `io::Error`, then the `?` operator calls in the body of
347 `read_username_from_file` will call `from` and convert the error types without
348 needing to add any more code to the function.
350 In the context of Listing 9-7, the `?` at the end of the `File::open` call will
351 return the value inside an `Ok` to the variable `username_file`. If an error
352 occurs, the `?` operator will return early out of the whole function and give
353 any `Err` value to the calling code. The same thing applies to the `?` at the
354 end of the `read_to_string` call.
356 The `?` operator eliminates a lot of boilerplate and makes this function’s
357 implementation simpler. We could even shorten this code further by chaining
358 method calls immediately after the `?`, as shown in Listing 9-8.
360 <span class="filename">Filename: src/main.rs</span>
362 <!-- Deliberately not using rustdoc_include here; the `main` function in the
363 file panics. We do want to include it for reader experimentation purposes, but
364 don't want to include it for rustdoc testing purposes. -->
367 {{#include ../listings/ch09-error-handling/listing-09-08/src/main.rs:here}}
370 <span class="caption">Listing 9-8: Chaining method calls after the `?`
373 We’ve moved the creation of the new `String` in `username` to the beginning of
374 the function; that part hasn’t changed. Instead of creating a variable
375 `username_file`, we’ve chained the call to `read_to_string` directly onto the
376 result of `File::open("hello.txt")?`. We still have a `?` at the end of the
377 `read_to_string` call, and we still return an `Ok` value containing `username`
378 when both `File::open` and `read_to_string` succeed rather than returning
379 errors. The functionality is again the same as in Listing 9-6 and Listing 9-7;
380 this is just a different, more ergonomic way to write it.
382 Listing 9-9 shows a way to make this even shorter using `fs::read_to_string`.
384 <span class="filename">Filename: src/main.rs</span>
386 <!-- Deliberately not using rustdoc_include here; the `main` function in the
387 file panics. We do want to include it for reader experimentation purposes, but
388 don't want to include it for rustdoc testing purposes. -->
391 {{#include ../listings/ch09-error-handling/listing-09-09/src/main.rs:here}}
394 <span class="caption">Listing 9-9: Using `fs::read_to_string` instead of
395 opening and then reading the file</span>
397 Reading a file into a string is a fairly common operation, so the standard
398 library provides the convenient `fs::read_to_string` function that opens the
399 file, creates a new `String`, reads the contents of the file, puts the contents
400 into that `String`, and returns it. Of course, using `fs::read_to_string`
401 doesn’t give us the opportunity to explain all the error handling, so we did it
402 the longer way first.
404 #### Where The `?` Operator Can Be Used
406 The `?` operator can only be used in functions whose return type is compatible
407 with the value the `?` is used on. This is because the `?` operator is defined
408 to perform an early return of a value out of the function, in the same manner
409 as the `match` expression we defined in Listing 9-6. In Listing 9-6, the
410 `match` was using a `Result` value, and the early return arm returned an
411 `Err(e)` value. The return type of the function has to be a `Result` so that
412 it’s compatible with this `return`.
414 In Listing 9-10, let’s look at the error we’ll get if we use the `?` operator
415 in a `main` function with a return type incompatible with the type of the value
418 <span class="filename">Filename: src/main.rs</span>
420 ```rust,ignore,does_not_compile
421 {{#rustdoc_include ../listings/ch09-error-handling/listing-09-10/src/main.rs}}
424 <span class="caption">Listing 9-10: Attempting to use the `?` in the `main`
425 function that returns `()` won’t compile</span>
427 This code opens a file, which might fail. The `?` operator follows the `Result`
428 value returned by `File::open`, but this `main` function has the return type of
429 `()`, not `Result`. When we compile this code, we get the following error
433 {{#include ../listings/ch09-error-handling/listing-09-10/output.txt}}
436 This error points out that we’re only allowed to use the `?` operator in a
437 function that returns `Result`, `Option`, or another type that implements
440 To fix the error, you have two choices. One choice is to change the return type
441 of your function to be compatible with the value you’re using the `?` operator
442 on as long as you have no restrictions preventing that. The other technique is
443 to use a `match` or one of the `Result<T, E>` methods to handle the `Result<T,
444 E>` in whatever way is appropriate.
446 The error message also mentioned that `?` can be used with `Option<T>` values
447 as well. As with using `?` on `Result`, you can only use `?` on `Option` in a
448 function that returns an `Option`. The behavior of the `?` operator when called
449 on an `Option<T>` is similar to its behavior when called on a `Result<T, E>`:
450 if the value is `None`, the `None` will be returned early from the function at
451 that point. If the value is `Some`, the value inside the `Some` is the
452 resulting value of the expression and the function continues. Listing 9-11 has
453 an example of a function that finds the last character of the first line in the
457 {{#rustdoc_include ../listings/ch09-error-handling/listing-09-11/src/main.rs:here}}
460 <span class="caption">Listing 9-11: Using the `?` operator on an `Option<T>`
463 This function returns `Option<char>` because it’s possible that there is a
464 character there, but it’s also possible that there isn’t. This code takes the
465 `text` string slice argument and calls the `lines` method on it, which returns
466 an iterator over the lines in the string. Because this function wants to
467 examine the first line, it calls `next` on the iterator to get the first value
468 from the iterator. If `text` is the empty string, this call to `next` will
469 return `None`, in which case we use `?` to stop and return `None` from
470 `last_char_of_first_line`. If `text` is not the empty string, `next` will
471 return a `Some` value containing a string slice of the first line in `text`.
473 The `?` extracts the string slice, and we can call `chars` on that string slice
474 to get an iterator of its characters. We’re interested in the last character in
475 this first line, so we call `last` to return the last item in the iterator.
476 This is an `Option` because it’s possible that the first line is the empty
477 string, for example if `text` starts with a blank line but has characters on
478 other lines, as in `"\nhi"`. However, if there is a last character on the first
479 line, it will be returned in the `Some` variant. The `?` operator in the middle
480 gives us a concise way to express this logic, allowing us to implement the
481 function in one line. If we couldn’t use the `?` operator on `Option`, we’d
482 have to implement this logic using more method calls or a `match` expression.
484 Note that you can use the `?` operator on a `Result` in a function that returns
485 `Result`, and you can use the `?` operator on an `Option` in a function that
486 returns `Option`, but you can’t mix and match. The `?` operator won’t
487 automatically convert a `Result` to an `Option` or vice versa; in those cases,
488 you can use methods like the `ok` method on `Result` or the `ok_or` method on
489 `Option` to do the conversion explicitly.
491 So far, all the `main` functions we’ve used return `()`. The `main` function is
492 special because it’s the entry and exit point of executable programs, and there
493 are restrictions on what its return type can be for the programs to behave as
496 Luckily, `main` can also return a `Result<(), E>`. Listing 9-12 has the
497 code from Listing 9-10 but we’ve changed the return type of `main` to be
498 `Result<(), Box<dyn Error>>` and added a return value `Ok(())` to the end. This
499 code will now compile:
502 {{#rustdoc_include ../listings/ch09-error-handling/listing-09-12/src/main.rs}}
505 <span class="caption">Listing 9-12: Changing `main` to return `Result<(), E>`
506 allows the use of the `?` operator on `Result` values</span>
508 The `Box<dyn Error>` type is a *trait object*, which we’ll talk about in the
509 [“Using Trait Objects that Allow for Values of Different
510 Types”][trait-objects]<!-- ignore --> section in Chapter 17. For now, you can
511 read `Box<dyn Error>` to mean “any kind of error.” Using `?` on a `Result`
512 value in a `main` function with the error type `Box<dyn Error>` is allowed,
513 because it allows any `Err` value to be returned early. Even though the body of
514 this `main` function will only ever return errors of type `std::io::Error`, by
515 specifying `Box<dyn Error>`, this signature will continue to be correct even if
516 more code that returns other errors is added to the body of `main`.
518 When a `main` function returns a `Result<(), E>`, the executable will
519 exit with a value of `0` if `main` returns `Ok(())` and will exit with a
520 nonzero value if `main` returns an `Err` value. Executables written in C return
521 integers when they exit: programs that exit successfully return the integer
522 `0`, and programs that error return some integer other than `0`. Rust also
523 returns integers from executables to be compatible with this convention.
525 The `main` function may return any types that implement [the
526 `std::process::Termination` trait][termination]<!-- ignore -->, which contains
527 a function `report` that returns an `ExitCode` Consult the standard library
528 documentation for more information on implementing the `Termination` trait for
531 Now that we’ve discussed the details of calling `panic!` or returning `Result`,
532 let’s return to the topic of how to decide which is appropriate to use in which
535 [handle_failure]: ch02-00-guessing-game-tutorial.html#handling-potential-failure-with-the-result-type
536 [trait-objects]: ch17-02-trait-objects.html#using-trait-objects-that-allow-for-values-of-different-types
537 [termination]: ../std/process/trait.Termination.html