7Pattern Matching

A pattern describes the shape of a value. When a value matches, any variables in the pattern are bound to the corresponding parts.

7.1 Pattern Forms#

A literal or range pattern is of its literal's kind, and that kind must be the subject's own type: an integer pattern matches an integer subject, a string pattern a string, a character pattern a char. A pattern of any other kind is refused at the pattern (E0200) rather than built as an arm that never matches - "x" against a struct subject is an error, not a dead arm.

7.2 Enum Destructuring#

import std::fmt::{ printf, println };

type enum Shape {
    Circle(f64);
    Rectangle(f64, f64);
    Point;
}

function describe(s: Shape) -> void {
    match (s) {
        Shape::Circle(r)        => { printf("Circle r=%f\n", r); }
        Shape::Rectangle(w, h)  => { printf("Rectangle %f x %f\n", w, h); }
        Shape::Point            => { println("A point"); }
    }
}

In each arm, the variables are introduced for the payload of that variant. The compiler enforces that the count and types match the variant's declaration.

If you don't need a payload, use _: Option::Some(_) => { ... }.

The alternatives of an or-pattern bind one variable per name, whichever alternative matched, so every alternative must bind the same names, each at the same type and each written mut alike; otherwise the arm is refused (E0407):

match (s) {
    Shape::Circle(r) | Shape::Rectangle(r, _) => { r }   // one `r`, an f64 either way
    Shape::Rectangle(w, h) | Shape::Circle(w) => { w }   // E0407: `h` is not bound in the second alternative
}

7.3 Range Patterns#

Range patterns match values within an inclusive range. They are most useful for character classification. Both spellings - a..b and the explicit a..=b - are inclusive in pattern position (note this differs from a range expression, where a..b is half-open). Bounds must be integer or char literals of the same kind.

import std::fmt::{ println };

match (ch) {
    '0'..='9'                   => { println("digit"); }
    'a'..'z' | 'A'..'Z' | '_'   => { println("ident-start"); }
    _                           => { println("other"); }
}

7.4 Guard Clauses#

An arm may carry a guard: a boolean condition written if (cond) between the pattern and the =>. The guard is evaluated only after the pattern matches; if it is false, matching falls through to the next arm. Any bindings introduced by the pattern are in scope inside the guard.

match (n) {
    x if (x > 100) => { 3 }
    x if (x > 10)  => { 2 }
    x if (x > 0)   => { 1 }
    _              => { 0 }
}

match (o) {
    Option::Some(v) if (v > 5) => { v * 10; }
    Option::Some(v)            => { v; }
    Option::None               => { -1; }
}

The parentheses around the condition are required. A guarded arm does not count toward exhaustiveness (the guard could always be false), so a match whose only arm for some case is guarded still needs a fall-through arm.

7.5 Exhaustiveness#

The compiler checks that every possible value of the matched type is covered. Forgetting a variant of an enum is an error. The wildcard _ is the explicit way to opt in to a default arm.

import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;

namespace std;

namespace std::fmt;

function printf(fmt: string, args...) -> i32

function println(text: String) -> void

type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }

type enum Name {
    Unit,
    Payload(T),
    Named { x: i32 },
}

type enum Shape

Shape::Circle(f64)

primitive f64

Shape::Rectangle(f64, f64)

Shape::Point

function name<T>(param: Type) -> Ret { ... }

function describe(s: Shape) -> void

(parameter) s: Shape

type enum Shape

primitive void

match (subject) {
    Pattern(x) => { ... }
    _          => { ... }
}

(parameter) s: Shape

Shape::Circle(f64)

r: f64

pattern => { body }

r: f64

Shape::Rectangle(f64, f64)

w: f64

h: f64

w: f64

h: f64

Shape::Point

type enum Shape

Shape::Circle(f64)

Shape::Rectangle(f64, f64)

_

r: f64

w: f64

start..=end

start..end

x

if (condition) { ... } else if (condition) { ... } else { ... }

x

x

x

type enum Option<T> {
    Some(T);
    None;
}

Option::Some(T)

v

v

v

Option::None

true

primitive string

primitive char

function name(count: i32, args...)

mut name: Type = value;