Result<T, E>: When an operation might fail

Failure is not an Option<T>, but a Result<T, E>.

Result is the sibling of Option. Where Option says "maybe a value, maybe nothing", Result says "maybe a value, maybe an error":

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

This is how Rust handles fallible operations. There are no exceptions. A function that can fail says so in its signature, and the caller has to deal with both branches.

fn parse_port(input: &str) -> Result<u16, &'static str> {
    match input.parse::<u16>() {
        Ok(n) if n > 0 => Ok(n),
        Ok(_) => Err("port must be greater than 0"),
        Err(_) => Err("not a valid number"),
    }
}

You only need a working reading of three details in this example: &'static str, the ::<u16> after parse, and the if guard on the first match arm.

&'static str

This is a &str whose lifetime is 'static: a fancy way of saying "this string lives for the entire duration of the program." String literals like "port must be greater than 0" are baked into the binary, so they qualify. For now, treat &'static str as the right type to use for hard-coded error messages. Lifetimes receive more detailed treatment later.

Turbofish: parse::<u16>()

.parse() doesn't know which type you want to parse into, so you tell it with the funny-looking ::<T> syntax. It's just a way to spell out a generic type argument at the call site:

let n = "42".parse::<u16>().unwrap();
// equivalent if the type can be inferred from context:
let n: u16 = "42".parse().unwrap();

You'll see this anywhere a function returns T and the type isn't clear from the surrounding code.

Match guards: Ok(n) if n > 0 => ...

The if n > 0 clause on a match arm is called a guard. The arm only fires when both the pattern matches and the guard is true. Without it you'd need a nested if inside the arm body, which reads worse.

match n {
    x if x < 0 => "negative",
    0          => "zero",
    _          => "positive",
}

Handling the two variants

As with Option, you can handle a Result with match, if let, or a combinator when you have a simple fallback:

match safe_divide(10.0, 0.0) {
    Ok(n) => println!("got {n}"),
    Err(e) => println!("oops: {e}"),
}

let n = safe_divide(10.0, 2.0).unwrap_or(0.0);

if let Ok(n) = safe_divide(10.0, 2.0) {
    println!("got {n}");
}

Result has many of the same combinators as Option: .map, .map_or, .and_then, .unwrap_or. The ? operator chains fallible operations without repeating the same match boilerplate each time.

Safe divide

The simplest way to produce a Result: an if checks the failure case, and the else branch returns Ok(...).

The signature is the interesting part: &'static str for the error is the simplest possible error type and is fine while you're learning.

Useful from the standard library

• The Result constructors Ok(value) and Err(message) are in the prelude, so you can use them without importing anything.
• f64 == 0.0 detects the failure case. Floating-point comparison has plenty of nasty edge cases in general, but checking for exact zero is fine here.
• Result::is_err is what the test uses; you don't need it inside the function.

Read config file

Same idea as safe_divide, but returning an owned String. Notice you can mix Ok(String::from("...")) and Err("...") in the same function: the success and error types are independent.

Useful from the standard library

• str::is_empty is the cleanest way to detect an empty filename.
• String::from or .to_string() turns the literal "config content" into the owned String the Ok arm needs.

Validate email

Now the Ok value is a borrow of the input. The &str in the return type implicitly borrows from email, so the compiler infers a lifetime linking input and output via lifetime elision. That lifetime relationship becomes explicit in the memory and ownership material. For now, notice that the function compiles even though no lifetime appears in the signature.

Useful from the standard library

• str::contains takes a char (or another &str) and answers yes/no. So email.contains('@') is exactly the check you need.
• The Ok branch can return the input slice directly: it's already a &str with the right lifetime. No to_string() allocation needed.

Parse percentage

A trailing % is allowed, but the remaining text may still fail to parse, and a parsed u8 may be greater than 100. Those two failures need different error messages.

Note: the error type here is &'static str, which means the message has to be a string literal. If you find yourself wanting format!("{input} is out of range") in an Err, you'd need to change the return type to Result<u8, String>. Stick with literals for this exercise.

Useful from the standard library

• str::strip_suffix removes a trailing pattern if present and returns Option<&str>. input.strip_suffix('%').unwrap_or(input) peels the % when there is one.
• str::parse is the canonical "may fail to parse" call. The turbofish (parse::<u8>()) tells it which numeric type to produce. u8 already rejects negative numbers and anything above 255, which catches a couple of cases for free.
• Result::map_err swaps the error type without touching Ok. Handy to turn the parser's error into your own static message.
• A bounds check if n > 100 { return Err("...") } finishes the job; the u8 type already takes care of n < 0.

Wrapping up `Result`

The examples use simple if checks to build Results with owned and borrowed success values. Combining strip_suffix, parse, and a bounds check produces a validating parser with several failure cases.

What we learned

• Result<T, E> is how Rust expresses fallibility. There are no exceptions; a function that can fail says so in its signature.
• Ok(value) and Err(error) are the constructors. Both are in the prelude.
• Result has the same combinator family as Option: unwrap_or, map, map_or, plus map_err for transforming the error side and ok to drop the error and convert to Option<T>.
• &'static str is a convenient error type when every message is a fixed string literal. Applications often use error enums or owned Strings once errors need data of their own.
• The turbofish (parse::<u8>()) spells out a generic type argument at the call site when the type isn't clear from context.
• Match guards (Ok(n) if n > 0 => ...) attach a boolean condition to a pattern. The arm only fires when both hold.
• The ? operator chains fallible calls without requiring a match each time. For now, match keeps both paths visible.