v0.4.0
Patterns · Lesson 7.6

Exhaustive

Source
See why a match on a variant must name every case, and why an integer match needs a _ arm.

A match is exhaustive when every value it could meet has an arm. You have already seen the compiler insist on it — a missing case in Variant match, a missing _ arm in Match expression. In Rux every match is held to it, whether it produces a value or is used as a statement. This lesson collects the rules in one place and, more importantly, explains why the check is a feature you want: it is what lets a program grow without silently breaking.

A closed list of cases

A variant or an enum has a closed list of cases, so the compiler knows every value a match on it could meet, and it insists that every one has an arm:

variant Player {
    Stopped,
    Playing(int32),
    Paused(int32)
}
func Describe(player: Player) -> char8[..] {
    return match player {
        .Stopped => "stopped",
        .Playing(second) if second < 5 => "just started",
        .Playing(_) => "playing",
        .Paused(_) => "paused"
    };
}

Every case has an arm, so no _ arm is needed — and none should be written. Notice the two .Playing arms. A guarded arm does not count towards covering its case, because the guard might be false; .Playing(second) still needs the unguarded .Playing(_) below it.

Why the check helps

That check is what makes a variant safe to grow. Suppose you add a Buffering case to Player next year:

flowchart LR
    add["Add a `Buffering` case"] --> q{"How does each<br/>match end?"}
    q -- "names every case" --> err["Fails to build: missing<br/>`Player::Buffering`,<br/>pointing at the spot to fix"]
    q -- "ends with `_`" --> quiet["Builds silently:<br/>`Buffering` takes the<br/>`_` arm's answer"]

Every match that names its cases one by one fails to compile, and the error points at the exact place to decide what buffering means. A match with a _ arm keeps compiling — and quietly gives Buffering whatever answer the _ arm gives.

_ on a variant is a promise

That is the trade-off in IsPlaying:

func IsPlaying(player: Player) -> bool {
    return match player {
        .Playing(_) => true,
        _ => false
    };
}

A _ arm on a variant is allowed, but it is a promise you make on behalf of cases that do not exist yet: a future Buffering would count as "not playing" with no error to warn you. Use it only when that is truly the right answer for any new case.

_ is for the values you cannot list

An integer has billions of values, so a match on an integer must end with a _ arm, and deciding what the leftovers mean is up to you:

func Loudness(volume: int32) -> char8[..] {
    return match volume {
        0 => "muted",
        1..=3 => "quiet",
        10 => "maximum",
        _ => "normal"
    };
}

Even ranges that happened to reach every value would not do instead: a match on an integer needs its _ arm. A bool, on the other hand, has just two values, so a true arm and a false arm cover it.

Matched typeCovered by_ => arm
A variant or an enumone unguarded arm per caseallowed, but hides new cases
boola true arm and a false armnot needed
A tuple of boolsevery combinationnot needed
An integernothing short of _required

Statements are held to the same rule

A match used as a statement, producing no value, must cover every value too. When the values you do not name should simply do nothing, say so with an empty arm:

match volume {
    0 => {
        PrintLine("muted");
    },
    _ => {}
}

The empty _ => {} is not noise: it records that the other values were thought about, and turning the statement into a value-producing match later never changes what it must cover.

The program

The whole lesson is one package in the Examples repository. Its comments explain every step.

Src/Main.rux
// A variant or an enum has a closed list of cases, so the compiler knows every value a match on it
// could meet, and it insists that every one has an arm. Leave a case out and the program does not
// build. Delete the `.Paused` arm below and the compiler names what is missing:
//     error: match on 'Player' is not exhaustive; missing Player::Paused
//     help: add arms for the missing cases, or a '_' arm
//
// That check is what makes a variant safe to grow. Add a case such as `Buffering` to `Player` next
// year, and every match that forgot it fails to compile, pointing at the exact spot to fix. A match
// that names every case therefore has no `_` arm, and should not have one.
//
// `_` is for the values you cannot list. An integer has billions of them, so a match on an integer
// must end with a `_` arm, and deciding what the leftovers mean is up to you. Delete the `_` arm in
// `Loudness` and the compiler stops with
//     error: match on 'int32' is not exhaustive; its arms do not cover every value
//     help: add a '_' arm
// A `bool` has just two values, so `true` and `false` arms cover it, and a missing one is named:
//     error: match on 'bool8' is not exhaustive; missing false
//     help: add an arm for false, or a '_' arm
// The rule holds for every match, including one used as a statement that produces no value. When
// the other values should do nothing, say so with an empty `_ => {}` arm.
import Io::PrintLine;

variant Player {
    Stopped,
    Playing(int32),
    Paused(int32)
}

// Every case has an arm, so no `_` arm is needed. A guarded arm does not count towards that: the
// guard might be false, so `.Playing(second)` still needs an unguarded arm of its own. Without it
// the error would read `missing Player::Playing`.
func Describe(player: Player) -> char8[..] {
    return match player {
        .Stopped => "stopped",
        .Playing(second) if second < 5 => "just started",
        .Playing(_) => "playing",
        .Paused(_) => "paused"
    };
}

// A `_` arm on a variant is allowed, but it is a promise you make on behalf of cases that do not
// exist yet: a future `Buffering` would quietly count as "not playing" here, with no error to
// warn you. Use it only when that is truly the right answer for any new case.
func IsPlaying(player: Player) -> bool {
    return match player {
        .Playing(_) => true,
        _ => false
    };
}

// The arms name a few volume levels, and `_` covers the rest. Even ranges that happened to reach
// every value would not do instead: a match on an integer needs its `_` arm.
func Loudness(volume: int32) -> char8[..] {
    return match volume {
        0 => "muted",
        1..=3 => "quiet",
        10 => "maximum",
        _ => "normal"
    };
}

func Main() -> int {
    let states: Player[4] = [
        Player::Stopped,
        Player::Playing(2),
        Player::Playing(95),
        Player::Paused(95)
    ];
    for index in 0..4 {
        PrintLine("{:12} playing: {}", Describe(states[index]), IsPlaying(states[index]));
    }

    PrintLine("0 {}, 2 {}, 7 {}, 10 {}", Loudness(0), Loudness(2), Loudness(7), Loudness(10));
    return 0;
}

Run it

cd Examples/Patterns/Exhaustive
rux run
stopped      playing: false
just started playing: true
playing      playing: true
paused       playing: false
0 muted, 2 quiet, 7 normal, 10 maximum

Common mistakes

Try it yourself

  1. Add a Buffering case to Player and run rux check. Which function fails, and which one keeps compiling?
  2. Rewrite IsPlaying without the _ arm, so that a future case is reported instead of quietly counted as "not playing". .Stopped | .Paused(_) => false keeps it to two arms.
  3. Give Loudness arms that between them cover 0..=10, then delete the _ arm. Read why it still does not compile.
  4. In Main, add a statement match that prints a line only for volume 10, and give it the _ => {} arm it needs.

Learn more