Result and the ? operator

Result: errors as values

Many languages use exceptions: an error "jumps" out of a function, and you hope someone catches it. In Rust, a function that can fail says so in its return type. Result is a normal enum from the standard library:

enum Result<T, E> {
    Ok(T),     // success, holding the value
    Err(E),    // failure, holding the error
}

Because the error is part of the type, you cannot forget it. You cannot use a Result<u32, ...> as a u32; you must look inside first. Also, if you call a function that returns a Result and ignore it completely, the compiler warns: "unused Result that must be used".

Handling a Result with match

use std::fs;

fn main() {
    match fs::read_to_string("prices.txt") {
        Ok(text) => println!("Read {} bytes", text.len()),
        Err(e) => println!("Could not read prices.txt: {e}"),
    }
}

Writing your own fallible function

fn parse_age(text: &str) -> Result<u8, String> {
    let age: u8 = match text.trim().parse() {
        Ok(n) => n,
        Err(_) => return Err(format!("'{text}' is not a number")),
    };
    if age < 18 {
        return Err(String::from("must be 18 or older"));
    }
    Ok(age)
}

The ? operator

Writing match for every call gets long. The question mark operator ? does the common thing for you: if the Result is Ok, it unwraps the value; if it is Err, it returns that error from the current function immediately. It only works inside a function that itself returns a Result (or an Option).

use std::fs;
use std::io;

fn read_first_line(path: &str) -> Result<String, io::Error> {
    let text = fs::read_to_string(path)?;     // on error: return Err(e) right here
    let first = text.lines().next().unwrap_or("").to_string();
    Ok(first)
}

The ? also converts the error type when needed. If your function returns Result<T, MyError> and the call gives a different error type, ? uses the From trait to convert it, if a conversion exists. You will build such conversions in the next topic.

main can return a Result

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

fn main() -> Result<(), Box<dyn Error>> {
    let text = fs::read_to_string("orders.csv")?;
    let count = text.lines().count();
    println!("{count} orders");
    Ok(())
}

Handy Result and Option helpers

fn find_price(item: &str) -> Option<u32> {
    if item == "chai" { Some(15) } else { None }
}

fn bill(item: &str, qty: &str) -> Result<u32, String> {
    let price = find_price(item).ok_or(format!("unknown item {item}"))?;
    let qty: u32 = qty.parse().map_err(|_| format!("bad quantity {qty}"))?;
    Ok(price * qty)
}

Common mistakes

• Using ? in a function that returns () (like a plain main). Error: "the ? operator can only be used in a function that returns Result or Option". Change the return type.
• Forgetting to wrap the final value: returning age instead of Ok(age).
• Mixing error types so ? cannot convert them. Use map_err, a common error enum, or Box<dyn Error>.
• Silencing a Result with let _ = ...; when the error actually matters.