src/doc/rust-by-example/src/error/result.md

   1 # `Result`
   2
   3 [`Result`][result] is a richer version of the [`Option`][option] type that
   4 describes possible *error* instead of possible *absence*.
   5
   6 That is, `Result<T, E>` could have one of two outcomes:
   7
   8 * `Ok<T>`: An element `T` was found
   9 * `Err<E>`: An error was found with element `E`
  10
  11 By convention, the expected outcome is `Ok` while the unexpected outcome is `Err`.
  12
  13 Like `Option`, `Result` has many methods associated with it. `unwrap()`, for
  14 example, either yields the element `T` or `panic`s. For case handling,
  15 there are many combinators between `Result` and `Option` that overlap.
  16
  17 In working with Rust, you will likely encounter methods that return the
  18 `Result` type, such as the [`parse()`][parse] method. It might not always
  19 be possible to parse a string into the other type, so `parse()` returns a
  20 `Result` indicating possible failure.
  21
  22 Let's see what happens when we successfully and unsuccessfully `parse()` a string:
  23
  24 ```rust,editable,ignore,mdbook-runnable
  25 fn multiply(first_number_str: &str, second_number_str: &str) -> i32 {
  26     // Let's try using `unwrap()` to get the number out. Will it bite us?
  27     let first_number = first_number_str.parse::<i32>().unwrap();
  28     let second_number = second_number_str.parse::<i32>().unwrap();
  29     first_number * second_number
  30 }
  31
  32 fn main() {
  33     let twenty = multiply("10", "2");
  34     println!("double is {}", twenty);
  35
  36     let tt = multiply("t", "2");
  37     println!("double is {}", tt);
  38 }
  39 ```
  40
  41 In the unsuccessful case, `parse()` leaves us with an error for `unwrap()`
  42 to `panic` on. Additionally, the `panic` exits our program and provides an
  43 unpleasant error message.
  44
  45 To improve the quality of our error message, we should be more specific
  46 about the return type and consider explicitly handling the error.
  47
  48 ## Using `Result` in `main`
  49
  50 The `Result` type can also be the return type of the `main` function if
  51 specified explicitly. Typically the `main` function will be of the form:
  52
  53 ```rust
  54 fn main() {
  55     println!("Hello World!");
  56 }
  57 ```
  58
  59 However `main` is also able to have a return type of `Result`. If an error
  60 occurs within the `main` function it will return an error code and print a debug
  61 representation of the error (using the [`Debug`] trait). The following example
  62 shows such a scenario and touches on aspects covered in [the following section].
  63
  64 ```rust,editable
  65 use std::num::ParseIntError;
  66
  67 fn main() -> Result<(), ParseIntError> {
  68     let number_str = "10";
  69     let number = match number_str.parse::<i32>() {
  70         Ok(number)  => number,
  71         Err(e) => return Err(e),
  72     };
  73     println!("{}", number);
  74     Ok(())
  75 }
  76 ```
  77
  78
  79 [option]: https://doc.rust-lang.org/std/option/enum.Option.html
  80 [result]: https://doc.rust-lang.org/std/result/enum.Result.html
  81 [parse]: https://doc.rust-lang.org/std/primitive.str.html#method.parse
  82 [`Debug`]: https://doc.rust-lang.org/std/fmt/trait.Debug.html
  83 [the following section]: result/early_returns.md