If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

9.3.1 Propagating Errors

When a function you write contains calls that may fail, you can either handle the error inside the function or return the error to the caller and let the caller decide how to handle it.

Take a look at an example:

use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let f = File::open("6657.txt");

    let mut f = match f {
        Ok(file) => file,
        Err(e) => return Err(e),
    };

    let mut s = String::new();
    match f.read_to_string(&mut s) {
        Ok(_) => Ok(s),
        Err(e) => Err(e),
    }
}

fn main() {
    let result = read_username_from_file();
}

The intention of this code is to read a username from a file:

• Its return type is the Result enum. The two type parameters, T and E, correspond to String and io::Error. In other words, when everything goes smoothly, the function returns the Ok variant of Result, and the Ok value contains a String username. If a problem occurs, the function returns the Err variant of Result, and that variant contains an instance of io::Error.

• Looking at the function body, it first uses File::open to try to open a file and assigns the Result to f. Then it performs a match on f (the second f is made mutable because read_to_string below uses &mut self). If the operation succeeds, it returns file and assigns the value to f. If the operation fails, it returns Err(e). Here, e is the specific error that occurred, and when the function body encounters the return keyword, execution ends immediately and the value after return — namely Err(e) — is returned. The error type happens to be io::Error, so the return value matches the Result type parameters.

• If File::open succeeds, the function then creates a mutable String called s and calls read_to_string to read the file contents into s. Of course, read_to_string may also fail, so a match expression follows it.

• This match expression has no semicolon at the end, and it is also the last expression in the function, so it becomes the function’s return value. The match has two branches. If the operation succeeds, it returns the Ok variant of Result and wraps the String value s inside it. If the operation fails, it returns the Err variant, wraps the error e inside it, and returns it. The return type of read_to_string also happens to be io::Error, so the return value matches the Result type parameters.

9.3.2 The ? Operator

Error propagation is very common in Rust, so Rust provides the ? operator specifically to simplify the process.

Use ? to achieve the same effect as the example above:

use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut f = File::open("6657.txt")?;
    let mut s = String::new();
    f.read_to_string(&mut s)?;
    Ok(s)
}

fn main() {
    let result = read_username_from_file();
}

• For the first ? (line 5): File::open returns a Result, and adding ? means that if File::open returns Ok, the value inside Ok becomes the result of the expression and is assigned to f. If File::open returns Err, then function execution stops and Err together with the wrapped error information is returned as the function’s return value — that is, return Err(e). In other words, the effect of line 5 is equivalent to:

let f = File::open("6657.txt");
let mut f = match f {
    Ok(file) => file,
    Err(e) => return Err(e),
};

• For the second ? (line 7): if read_to_string succeeds, execution continues. The successful return value is not actually used in the code, but if it fails, function execution stops and Err together with the wrapped error information is returned as the function’s return value — that is, return Err(e).

• If everything succeeds up to that point, the expression Ok(s) wraps the String value s in Ok and returns it.

To summarize: when ? is used on a Result, if it is Ok, the value inside Ok becomes the result of the expression and execution continues; if the operation fails, that is, if it is Err, then Err becomes the return value of the entire function, just like using return.

9.3.3 ? and the from Function

Rust provides the from function. It comes from the std::convert::From trait, and its job is to convert between errors, turning one error type into another. Errors received by ? are implicitly handled by from, which looks at the error type the current function is supposed to return and converts to that type.

Using the code from just now as an example, the return value of read_username_from_file is Result<String, io::Error>, so from can see that the function needs io::Error as the error return type and will convert different error types into io::Error. In this case, all errors inside the function body happen to already be io::Error, so no conversion is needed.

This feature is very useful when different error causes need to be mapped into the same error type. The prerequisite is that the involved error types implement From trait so they can be converted into the error type being returned.

9.3.4 Chained Calls

In fact, the previous example can be optimized further by using chained calls. The optimized code looks like this:

use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut s = String::new();
    File::open("6657.txt")?.read_to_string(&mut s)?;
    Ok(s)
}

fn main() {
    let result = read_username_from_file();
}

As just mentioned, when ? is used on a Result, if it is Ok, the value inside Ok becomes the result of the expression and execution continues. That means the assignment step in the original code can be eliminated, and chained calls can be used directly.

9.3.5 ? Can Only Be Used in Functions That Return Result

Take a look at an example:

use std::fs::File;
fn main() {
    let result = File::open("6657.txt")?;
}

Output:

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:3:40
  |
2 | fn main() {
  | --------- this function should return `Result` or `Option` to accept `?`
3 |     let result = File::open("6657.txt")?;
  |                                        ^ cannot use the `?` operator in a function that returns `()`
  |
  = help: the trait `FromResidual<Result<Infallible, std::io::Error>>` is not implemented for `()`
help: consider adding return type
  |
2 ~ fn main() -> Result<(), Box<dyn std::error::Error>> {
3 |     let result = File::open("6657.txt")?;
4 +     Ok(())
  |

The error message says that the ? operator can only be used with return types such as Result or Option, which implement the Try trait, while main returns (), the unit type, which is equivalent to returning nothing.

But who says the return type of main must be the unit type? If you change the return type to Result, wouldn’t that solve it?

The code is as follows:

use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let result = File::open("6657.txt")?;

    Ok(())
}

• Changing the return type to Result<(), Box<dyn Error>> means that if the program runs normally, it returns the Ok variant, which contains the unit type. If it does not run normally, it returns the Err variant, which contains Box<dyn Error> (Error here is std::error::Error). This is a trait object, which will be covered later; for now, you can simply think of it as any possible error type.

• If the file is read successfully, ? returns the file data wrapped in Ok, assigns it to result, and then execution continues. Ok(()) is the last expression in main, so it returns the Ok variant and wraps the unit type.

• If the file cannot be read successfully, ? returns Err(e) as the return value of main, and execution ends there.