128. Enums and match

One of several things

Your TypeScript VM needed “this is one of several things” in three places, and spelled it three ways. The dispatch loop switched on opcode numbers:

switch (instruction) {
  case OP.NIL: this.push(null); break;
  case OP.NEGATE: /* ... */ break;
  // ...
}

A value was null | boolean | number | Obj, checked with typeof (chapter 49). And when you wanted a tag and a payload, you wrote a discriminated union (chapter 14):

type Tagged =
  | { tag: 'nil' }
  | { tag: 'bool'; as: boolean }
  | { tag: 'num'; as: number };

Rust has a single feature for all three.

Enums

enum Op {
    Constant,
    Add,
    Negate,
    Return,
}

enum Value {
    Nil,
    Bool(bool),
    Number(f64),
}

let op = Op::Add;
let v = Value::Number(2.5);

These are adapted from the Rust Drip VM. Its OpCode (in companion/rust/src/chunk.rs) has 37 variants, and its Value (in value.rs) adds variants for strings, functions, classes and other heap objects.

An Op is exactly one of four things. A Value is one of three, and two of those carry data: Bool holds a bool, Number holds an f64. That is the tagged value of chapter 49, written as a type. A variant can also hold several values, Pair(f64, f64), or named fields like a struct, Move { dx: f64, dy: f64 }^[1].

match

To do anything with an enum you ask which variant it is, and take its data out. That is match:

let n = match v {
    Value::Nil => 0.0,
    Value::Bool(true) => 1.0,
    Value::Bool(false) => 0.0,
    Value::Number(x) => x,
};

Each line inside is an arm: a pattern, =>, and the code to run. Step through what happens to two different values:

let n = match v {
    Value::Nil => 0.0,
    Value::Bool(true) => 1.0,
    Value::Bool(false) => 0.0,
    Value::Number(x) => x,
};

Three things to notice. Arms are tried top to bottom, and the first one that fits wins. There is no falling through to the next arm, so there is no break to forget. And match is an expression, like if in chapter 123, so every arm produces a value of the same type.

The third is the big one. A match must cover every possible value. Leave out Value::Bool(false) and you get this (real rustc 1.97 output, trimmed):

error[E0004]: non-exhaustive patterns:
  `Value::Bool(false)` not covered

In TypeScript you can get the same check, but you have to set it up with a never trick (chapter 14). In Rust it is always on, and it is a hard error, not a warning^[1].

Patterns

The left side of an arm is a pattern: a shape the value is compared with. You have now seen several kinds:

• Literals, like true, 0 or the byte b'('.
• Variants, like Value::Nil, with patterns for their data inside.
• Bindings: a plain name like x fits anything and names it.
• The wildcard _ fits anything and names nothing.
• Or-patterns: p | q fits if either fits.
• Pairs: (p, q) matches two values at once.

Here is Drip’s truthiness from chapter 35, with an or-pattern:

fn is_falsey(v: Value) -> bool {
    match v {
        Value::Nil
        | Value::Bool(false) => true,
        _ => false,
    }
}

and here is + on two numbers, matching a pair. (a, b) is a tuple: a few values grouped in parentheses.

match (a, b) {
    (
        Value::Number(x),
        Value::Number(y),
    ) => Value::Number(x + y),
    _ => Value::Nil, // VM: an error
}

The Rust scanner matches on bytes the same way, one arm per character, like b'(' => self.make(T::LeftParen), and ends with _ for anything it doesn’t recognise.

#[derive(Clone, Copy)]
enum Value {
    Nil,
    Bool(bool),
    Number(f64),
}

fn is_falsey(v: Value) -> bool {
    match v {
        Value::Nil
        | Value::Bool(false) => true,
        _ => false,
    }
}

fn add(a: Value, b: Value) -> Value {
    match (a, b) {
        (
            Value::Number(x),
            Value::Number(y),
        ) => Value::Number(x + y),
        _ => Value::Nil,
    }
}

fn show(v: Value) -> String {
    match v {
        Value::Nil => {
            String::from("nil")
        }
        Value::Bool(b) => b.to_string(),
        Value::Number(n) => {
            n.to_string()
        }
    }
}

fn main() {
    let two = Value::Number(2.0);
    let t = Value::Bool(true);
    println!("{}", show(add(two, two)));
    println!("{}", show(add(two, t)));
    let nil = Value::Nil;
    println!("{}", is_falsey(nil));
    println!("{}", is_falsey(two));
}

match op {
    OpCode::Nil => self.push(Value::Nil),
    OpCode::Add => self.add()?,
    OpCode::Negate => { /* ... */ }
    // ...one arm per opcode
}

Your turn

enum Op {
    Push(f64),
    Add,
    Sub,
    Mul,
    Neg,
}

fn eval(code: &[Op]) -> f64 {
    let mut st = [0.0; 16];
    let mut top = 0;
    let mut i = 0;
    while i < code.len() {
        match code[i] {
            Op::Push(v) => {
                st[top] = v;
                top += 1;
            }
            _ => todo!(),
        }
        i += 1;
    }
    st[top - 1]
}

#[derive(Clone, Copy)]
enum Value {
    Nil,
    Bool(bool),
    Number(f64),
}

fn equal(a: Value, b: Value) -> bool {
    false
}

What you learned

• An enum is one of a fixed set of variants, which can carry data. It is a discriminated union built into the language.
• match tries its arms in order and runs the first that fits. It is an expression, and it must be exhaustive.
• Patterns are shapes: literals, variants, bindings, _, | and tuples. Bindings pull the payload out.
• A wildcard covers cases you haven’t thought of yet. Prefer listing variants when each needs its own answer.
• The Rust VM’s dispatch loop is a single exhaustive match on OpCode.

That’s the end of Day 32. Next: two enums so useful they are built into the standard library, Option and Result, and how Rust handles errors without exceptions.