Exhaustive
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 type | Covered by | _ => arm |
|---|---|---|
| A variant or an enum | one unguarded arm per case | allowed, but hides new cases |
bool | a true arm and a false arm | not needed |
A tuple of bools | every combination | not needed |
| An integer | nothing 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.
// 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
- Add a
Bufferingcase toPlayerand runrux check. Which function fails, and which one keeps compiling? - Rewrite
IsPlayingwithout the_arm, so that a future case is reported instead of quietly counted as "not playing"..Stopped | .Paused(_) => falsekeeps it to two arms. - Give
Loudnessarms that between them cover0..=10, then delete the_arm. Read why it still does not compile. - In
Main, add a statementmatchthat prints a line only for volume10, and give it the_ => {}arm it needs.
Learn more
- Exhaustiveness of
matchand enumerations in the Rux Reference - Enum and Variant match — the closed lists that make the check possible
- Presence — the same rule for optionals, where the case you cannot forget is
none
7.5 Character pattern
Match character literals and escapes such as 'w' and '\n', and a whole class of characters with a range such as 'a'..='z'.
Overview
A value that may be absent: T?. Six lessons on none, presence patterns, fallbacks with ??, early exits with ?? return, passing absence up with ?, and int??.