Skip to main content

Pattern matching

match​

match compares a value against a list of patterns, and runs the code of the first one that fits:

enum Shape {
Circle(f64),
Rect { w: f64, h: f64 },
Dot,
}

fn area(s: Shape) -> f64 = match s {
Shape.Circle(r) => 3.14 * r * r,
Shape.Rect { w, h } => w * h,
Shape.Dot => 0.0,
};

[area(Shape.Circle(1.0)), area(Shape.Rect { w: 2.0, h: 3.0 }), area(Shape.Dot)];
[3.14, 6.0, 0.0]

Each line of a match is an arm: a pattern, =>, and an expression. Arms are separated by commas. A pattern can give names to the parts of the value it matches, like r, w and h above, which the arm can then use.

Like if, match is an expression, and all its arms must have the same type.

note

Bolt doesn't check yet that a match covers every case. A value that no arm matches is an error when the program runs.

Kinds of patterns​

PatternMatches
xanything, and names it x
_anything, without naming it
42, "hi", 'c', Truethat exact value
1..=9numbers from 1 to 9, inclusive
a | bwhat a or b matches
(a, b)a tuple, with patterns for its elements
[first, .., last]an array; .. stands for any number of elements
Some(x), Shape.Circle(r)a variant or tuple struct
Point { x, y: 0 }a struct or variant with named fields
name @ patternwhat pattern matches, and names the whole value

Patterns nest, so they can look deep inside a value:

fn describe(n: i32) -> String = match n {
0 => "zero",
1 | 2 | 3 => "a few",
4..=9 => "several",
_ => "many",
};

[describe(0), describe(2), describe(7), describe(42)];
["zero", "a few", "several", "many"]
fn label(o: Option[i32]) -> String = match o {
Some(0) => "zero",
Some(n @ 1..=9) => "a digit",
Some(_) => "a big number",
None => "nothing",
};

[label(Some(0)), label(Some(5)), label(Some(50)), label(None)];
["zero", "a digit", "a big number", "nothing"]

The alternatives of a | b must name the same variables, with the same types, so that the arm can use them whichever alternative matched:

enum Shape { Square(i32), Circle(i32), Empty }

fn size(s: Shape) -> i32 = match s {
Shape.Square(n) | Shape.Circle(n) => n,
Shape.Empty => 0,
};

Shape.Square(n) | Shape.Empty is an error, because n would have no value when the shape is empty.

Guards​

An arm can have a guard: an extra condition after if. The arm is only chosen when the pattern matches and the guard is True:

fn classify(n: i32) -> String = match n {
x if x < 0 => "negative",
x if x % 2 == 0 => "even",
_ => "odd",
};

[classify(-1), classify(4), classify(7)];
["negative", "even", "odd"]

Destructuring with let​

let takes a pattern too, which takes a value apart into variables:

struct Point { x: i32, y: i32 }

let (a, b) = (1, 2);
let Point { x, y: height } = Point { x: 10, y: 20 };
let [first, .., last] = [3, 1, 4, 1, 5];
(a + b, x, height, first, last);
(3, 10, 20, 3, 5)

y: height matches the field y and names it height. Patterns work in function parameters as well:

fn add_pair((a, b)) = a + b;

add_pair((20, 22));
42

if let​

When you only care about one pattern, if let is shorter than a match:

fn or_zero(o: Option[i32]) -> i32 {
if let Some(n) = o { n } else { 0 }
}

(or_zero(Some(7)), or_zero(None));
(7, 0)

let ... else​

let pattern = value else { ... }; is for patterns that may not match. When the value doesn't fit, the else block runs, and it must leave the function, with return for example. After the let, the variables of the pattern can be used as usual:

fn double_or_fail(o: Option[i32]) -> i32 {
let Some(n) = o else {
return -1;
};
n * 2
}

(double_or_fail(Some(21)), double_or_fail(None));
(42, -1)

Next: types and inference.