129. Option and Result

Where did the value go?

You have written this TypeScript many times:

const xs = [4, 5, 6];
const i = xs.indexOf(9);   // -1
const p = ps.find((p) => p.x > 100);
console.log(p.x);  // crash if none matched

Two ways of saying “nothing here”: -1 and undefined. With strictNullChecks, TypeScript flags the second, because find returns P | undefined, but -1 is a perfectly good number. And failures are another story. When the Drip VM from Part IV meets 1 - true, it throws, and nothing in the type of the function that threw warns you.

Rust takes both ideas away. There is no null or undefined, and there are no exceptions. Absence and failure are ordinary values, of two enums you already know how to read.

Option: maybe a value

Option is an enum from the standard library, just like the ones in chapter 128. Simplified, its definition is:

enum Option<T> {
    None,
    Some(T),
}

The <T> says “some type, to be filled in”: Option<usize> is maybe a usize, Option<&str> maybe a string slice. (Chapter 132 is all about those angle brackets; for now read them as TypeScript’s Array<T>.) Option, Some and None are so common that you can use them without importing anything.

Here is indexOf done honestly:

fn find(xs: &[i32], t: i32)
    -> Option<usize> {
    for i in 0..xs.len() {
        if xs[i] == t {
            return Some(i);
        }
    }
    None
}

(for i in 0..xs.len() counts i from 0 up to the length minus one, like TypeScript’s counting loop; chapter 134 explains Rust’s for fully.) The return type now says “maybe an index”, and the caller can’t pretend otherwise. Try to use the answer as a number:

let i = find(&[4, 5], 5);
println!("{}", i + 1);

Rust 1.97 on this machine refuses (trimmed):

error[E0369]: cannot add `{integer}`
  to `Option<usize>`
12 |     println!("{}", i + 1);
   |                    - ^ - {integer}
   |                    Option<usize>

An Option<usize> is not a usize, so you have to open the slip.

Opening the slip

Option is an enum, so match works, and it must cover both Some(i) and None. When you only care about one arm, if let is a one-arm match: if let Some(i) = find(&xs, 5) { ... } runs the block only for Some, with i bound. Two methods cover common cases. unwrap_or(d) gives the value or a default d. unwrap() gives the value or panics: it stops the program with a message. Use it only where None would be a bug, as in a test.

You have met this idea before: Option<T> is a discriminated union, like the ones in chapter 14, and match is narrowing that the compiler checks for exhaustiveness.

fn find(xs: &[i32], t: i32)
    -> Option<usize> {
    for i in 0..xs.len() {
        if xs[i] == t {
            return Some(i);
        }
    }
    None
}

fn main() {
    let xs = [4, 5, 6];
    match find(&xs, 5) {
        Some(i) => println!("at {}", i),
        None => println!("absent"),
    }
    if let Some(i) = find(&xs, 6) {
        println!("6 is at {}", i);
    }
    let i = find(&xs, 9).unwrap_or(99);
    println!("{}", i);
    println!("{:?}", find(&xs, 4));
    // Try: find(&xs, 9).unwrap()
}

Result: it worked, or here is why not

Option says whether there is a value. When something fails you usually want to know why. That is Result:

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

Ok carries the answer, of type T. Err carries the error, of type E, which can be any type you like: a String message, or an enum of error kinds (chapter 144). Here is the operand check from Drip’s VM, cut down to two value kinds:

enum Value {
    Num(f64),
    Bool(bool),
}

fn as_num(v: &Value)
    -> Result<f64, String> {
    match v {
        Value::Num(n) => Ok(*n),
        _ => Err(String::from(
            "Operands must be numbers.")),
    }
}

The message is the real one: drip-rs and the TypeScript VM both print Operands must be numbers. for 1 - true.

Passing it up with ?

Subtraction needs two numbers. Written with match, it would check each operand and return early on Err, twice. That pattern is so common that Rust gives it one character:

fn sub(a: &Value, b: &Value)
    -> Result<f64, String> {
    let x = as_num(a)?;
    let y = as_num(b)?;
    Ok(x - y)
}

as_num(a)? means: if this is Ok(n), the expression is n; if it is Err(e), return Err(e) from sub right now. Step through a failing call:

fn sub(a: &Value, b: &Value)
    -> Result<f64, String> {
    let x = as_num(a)?;
    let y = as_num(b)?;
    Ok(x - y)
}
// main:  sub(&one, &t)

That last rule is checked. Put ? in a function that returns i32 and the compiler says (trimmed):

error[E0277]: the `?` operator can
  only be used in a function that
  returns `Result` or `Option` ...

enum Value {
    Num(f64),
    Bool(bool),
}

fn as_num(v: &Value)
    -> Result<f64, String> {
    match v {
        Value::Num(n) => Ok(*n),
        _ => Err(String::from(
            "Operands must be numbers."
        )),
    }
}

fn sub(a: &Value, b: &Value)
    -> Result<f64, String> {
    let x = as_num(a)?;
    let y = as_num(b)?;
    Ok(x - y)
}

fn main() {
    let one = Value::Num(1.0);
    let t = Value::Bool(true);
    println!("{:?}", sub(&one, &one));
    println!("{:?}", sub(&one, &t));
    match sub(&t, &one) {
        Ok(n) => println!("{}", n),
        Err(e) => println!("{}", e),
    }
}

Your turn

enum Value {
    Num(f64),
    Bool(bool),
}

fn as_num(v: &Value)
    -> Result<f64, String> {
    match v {
        Value::Num(n) => Ok(*n),
        _ => Err(String::from(
            "Operands must be numbers."
        )),
    }
}

fn add_top(st: &[Value])
    -> Result<f64, String> {
    todo!()
}

fn top_two(st: &[f64])
    -> Option<(f64, f64)> {
    todo!()
}

What you learned

• Option<T> is Some(value) or None. It replaces null, undefined and magic values like -1.
• Get the value out with match, if let, unwrap_or, or unwrap (which panics on None).
• Result<T, E> is Ok(value) or Err(error). Failure is in the function’s type, instead of thrown past it.
• ? unwraps Ok or Some, and otherwise returns early with the Err (converted with From) or the None. It only works in functions that return a matching type.
• drip-rs returns its runtime errors where the TypeScript VM throws them.