1# Use the `Error` type
2
3This pattern is a way to manage errors when you have multiple kinds of failure
4that could occur during a single function. It has several distinct advantages:
5
61. You can start using it without defining any of your own failure types.
72. All types that implement `Fail` can be thrown into the `Error` type using
8the `?` operator.
93. As you start adding new dependencies with their own failure types, you can
10start throwing them without making a breaking change.
11
12To use this pattern, all you need to do is return `Result<_, Error>` from your
13functions:
14
15```rust
16use std::io;
17use std::io::BufRead;
18
19use failure::Error;
20use failure::err_msg;
21
22fn my_function() -> Result<(), Error> {
23    let stdin = io::stdin();
24
25    for line in stdin.lock().lines() {
26        let line = line?;
27
28        if line.chars().all(|c| c.is_whitespace()) {
29            break
30        }
31
32        if !line.starts_with("$") {
33            return Err(format_err!("Input did not begin with `$`"));
34        }
35
36        println!("{}", &line[1..]);
37    }
38
39    Ok(())
40}
41```
42
43## When might you use this pattern?
44
45This pattern is very effective when you know you will usually not need to
46destructure the error this function returns. For example:
47
48- When prototyping.
49- When you know you are going to log this error, or display it to the user,
50  either all of the time or nearly all of the time.
51- When it would be impractical for this API to report more custom context for
52  the error (e.g. because it is a trait that doesn't want to add a new Error
53  associated type).
54
55## Caveats on this pattern
56
57There are two primary downsides to this pattern:
58
59- The `Error` type allocates. There are cases where this would be too
60  expensive. In those cases you should use a [custom failure][custom-fail].
61- You cannot recover more information about this error without downcasting. If
62  your API needs to express more contextual information about the error, use
63  the [Error and ErrorKind][error-errorkind] pattern.
64
65[custom-fail]: ./custom-fail.html
66[error-errorkind]: ./error-errorkind.html
67