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

9.2.1 The Result Enum

Usually, errors are not serious enough to stop the entire program. A function may fail or encounter an error for reasons that are often easy to explain and respond to. For example, a program may try to open a file that does not exist; in that case, you would usually consider creating the file rather than terminating the program immediately.

Rust provides the Result enum to handle these potentially failing cases. Its definition is:

enum Result<T, E> {
    Ok(T),
    Err(E),
}

It has two generic type parameters, T and E, and two variants, each associated with data. Ok is associated with T, and Err is associated with E. Generics will be discussed in Chapter 10. For now, just know that T is the type of the data returned by the Ok variant when the operation succeeds, and E is the type of the error returned by the Err variant when the operation fails.

Take a look at an example:

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

This code tries to open a file, but that file may not exist. In other words, the function may fail, so the return value of File::open is the Result enum. The first type parameter in this Result is std::fs::File, the file type returned on success, and the second is std::io::Error, the I/O error returned on failure.

9.2.2 Handling Result with match

Like the Option enum, Result and its variants are brought into scope by the prelude, so you do not need to import them explicitly when writing code. For example:

use std::fs::File;
fn main() {
    let f = File::open("6657.txt");
    let f = match f {
        Ok(file) => file,
        Err(e) => panic!("Error: {}", e),
    };
}

If the returned value is Ok, then the value associated with it is bound to file and returned to f. If the returned value is Err, then the error message is bound to e, printed by the panic! macro, and the program stops.

9.2.3 Matching Different Errors

Let’s improve the previous example. If the file is missing, create it. Only if creating the file also fails, or if some other error occurs besides “file not found” — such as not having permission to open it — should panic! be triggered.

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let f = File::open("6657.txt");
    let f = match f {
        Ok(file) => file,
        Err(e) => match e.kind() {
            ErrorKind::NotFound => match File::create("6657.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Problem creating file: {:?}", e),
            },
            other_error => panic!("Problem opening file: {:?}", other_error),
        },
    };
}

• At the outermost level, if f is Ok, then the file is returned to f.
• But the Err case is handled differently. The data carried by Err is of type std::io::Error. This struct has a .kind() method, which returns a value of type std::io::ErrorKind. That type is also an enum, also provided by the standard library, and its variants describe the different errors that io operations may cause.
• ErrorKind has a variant called ErrorKind::NotFound, which means the file does not exist. In that case, the file should be created, which we will discuss below. Besides ErrorKind::NotFound, there may be other errors, such as lacking permission to read. Here, the other errors are bound to other_error, printed by panic!, and then the program stops.
• To create a file, you can use File::create(), whose parameter is the file name. Creating a file can also fail, for example because of insufficient permissions, so the return value of File::create() is also a Result. Then another match expression is used to handle it. If it is Ok (creation succeeded), the value associated with Ok — that is, the contents of the newly created file (which are of course empty because the file is new) — are bound to fc and returned to f. If it is Err (creation failed), the error associated with Err is bound to e, printed by panic!, and the program stops.

match is indeed used quite often, but it is also fairly primitive. The nesting here greatly reduces readability, although compared with some other languages it may still be more readable. Chapter 13 will introduce a concept called a closure. Many methods on Result accept closures as parameters, and those methods are implemented using match, which can make the code much more concise. I am showing an example that uses closures here, but we will not cover it until Chapter 13.

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file = File::open("6657.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("6657.txt").unwrap_or_else(|error| {
                panic!("Problem creating the file: {error:?}");
            })
        } else {
            panic!("Problem opening the file: {error:?}");
        }
    });
}

9.2.4 The unwrap Method

match expressions are flexible and useful, but the code they produce is indeed a bit more complex. The Result enum itself also defines many helper methods for different tasks, and one of the most commonly used is unwrap.

If unwrap receives Ok, it returns the value attached to Ok; if it receives Err, unwrap calls the panic! macro. For example, here is a rewrite of the code from 9.2.2 using unwrap:

use std::fs::File;

fn main() {
    let f = File::open("6657.txt").unwrap();
}

unwrap is essentially a shortcut for a match expression. Its drawback is that the error message cannot be customized.

9.2.5 The expect Method

What if I want the convenience of unwrap but also want a custom error message? For that situation, Rust provides the expect method. If you remember, we already used this method in the number guessing game from Chapter 1.

Try rewriting the unwrap example with expect:

use std::fs::File;

fn main() {
    let f = File::open("6657.txt").expect("file not found");
}