Step 1 of 6

Library errors with thiserror

In the custom errors module you built error enums by hand: the enum, an impl Display with a match giving each variant a message, and an empty impl std::error::Error. That design is exactly right. It's also a lot of typing, and the boilerplate grows with every variant. thiserror is a derive macro that writes those impls for you:

use thiserror::Error;

#[derive(Debug, Error)]
enum WithdrawError {
    #[error("amount must be positive")]
    ZeroAmount,
    #[error("insufficient funds: need {needed}, have {available}")]
    InsufficientFunds { needed: u64, available: u64 },
    #[error("account {0} is frozen")]
    Frozen(String),
}

fn withdraw(balance: u64, amount: u64) -> Result<u64, WithdrawError> {
    if amount == 0 {
        return Err(WithdrawError::ZeroAmount);
    }
    if amount > balance {
        return Err(WithdrawError::InsufficientFunds { needed: amount, available: balance });
    }
    Ok(balance - amount)
}

fn main() {
    println!("{:?}", withdraw(100, 30));
    for amount in [0, 500] {
        match withdraw(100, amount) {
            Ok(left) => println!("left: {left}"),
            Err(e) => println!("error: {e}"),
        }
    }
    println!("{}", WithdrawError::Frozen(String::from("ACC-7")));
}

Ok(70)
error: amount must be positive
error: insufficient funds: need 500, have 100
account ACC-7 is frozen

Piece by piece:

• #[derive(Debug, Error)]: Error (from thiserror) generates impl std::error::Error and impl Display. The Error trait requires Debug too, so derive both.
• Each #[error("...")] is that variant's Display message. Inside it, {0} is the first tuple field and {needed} a named field. Format specs work as in format!: {0:?} uses Debug (quotes around strings), {amount:.2} rounds.
• The result is the same code you'd write by hand: no runtime cost, and thiserror doesn't appear in your public API (callers just see an enum implementing Error), so you could remove it later without breaking anyone.
• Callers can match on the variants and react differently to each one. That's the point of a typed error, and why libraries use them.

A struct works too, for an operation that can fail in only one way:

use thiserror::Error;

#[derive(Debug, Error)]
#[error("invalid color {input:?}: expected #rrggbb")]
struct ParseColorError {
    input: String,
}

fn main() {
    let e = ParseColorError { input: String::from("teal") };
    println!("{e}");
}

invalid color "teal": expected #rrggbb

Writing good messages

The Rust API guidelines say error messages are lowercase, without a trailing period, and short. The reason: messages get chained into sentences like loading config: line 3: invalid number, and capitals and periods in the middle look wrong. Say what went wrong and include the values that help (the amount, the account, the input).

Common mistakes

Every variant needs a message. Forget one and thiserror tells you at compile time:

use thiserror::Error;

#[derive(Debug, Error)]
enum LoadError {
    #[error("file is empty")]
    Empty,
    TooBig(usize),
}

fn main() {
    println!("{}", LoadError::Empty);
}

error: missing #[error("...")] display attribute

• Forgetting Debug in the derive gives error[E0277]: `LoadError` doesn't implement `Debug` : std::error::Error requires it.
• Naming a field that doesn't exist in the message, like {amount} when the field is needed, is a compile error too. Typos can't sneak into production messages.

Your task

Complete TransferError (derive Error, add a message to each variant) and write check_transfer, which returns the balance left after the transfer. Check in this order, with these exact messages:

• from == to: SameAccount, message cannot transfer to the same account
• amount > 1000: OverLimit { limit: 1000 }, message amount exceeds the daily limit of 1000 (use {limit})
• amount > balance: InsufficientFunds { needed: amount, available: balance }, message like insufficient funds: need 250, have 100

Challenge 2

Fill in the blanks: derive thiserror's trait on the struct, and write the message so the program prints invalid size "XXL": expected S, M or L (use Debug formatting of the input field to get the quotes).

Challenge 3

Write an error enum from scratch. TemperatureError has two variants: NotANumber(String) with message "abc" is not a number (Debug-format the text) and BelowAbsoluteZero(f64) with message -300.0 C is below absolute zero (one decimal). Then write fn parse_celsius(s: &str) -> Result<f64, TemperatureError>: trim s, parse it as f64, and reject anything below -273.15.

Next: Wrapping causes: #[from], #[source], transparent