Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Keywords and Statements

The match expression

Reference for Rust match: arms and patterns, exhaustiveness checking, guards, bindings, matching references, wildcard arms and the value of a match.

match compares a value against a list of patterns, runs the arm of the first pattern that fits, and produces that arm's value. The compiler checks that the arms are exhaustive: every possible value must be covered, so you can never forget a case. Adding a variant to an enum later turns every incomplete match into a compile error, which makes refactoring safe.

Patterns can be literals, ranges, names that bind parts of the value, tuples, structs, enum variants, references, slices and combinations joined with |. An arm may add an if guard for conditions that patterns cannot express.

Rust
let text = match n {
    0 => "zero",
    1..=9 => "small",
    _ => "large",
};

Try it

Rust Enums, ranges and guards

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Bindings, alternatives and at-patterns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Rust
match scrutinee {
    pattern1 => expression,
    pattern2 | pattern3 if guard => { block }
    name @ pattern => expression,
    _ => expression,
}
Part Description
scrutinee Any expression. It is evaluated once; it is moved or borrowed depending on the patterns.
pattern See the Patterns pages. `
if guard Extra boolean test evaluated only when the pattern matched. Guards do not count toward exhaustiveness.
_ Matches anything without binding it. Place it last.

Type rule: all arms must have the same type (a diverging arm such as return or panic! has type ! and fits anywhere). Error: a missing case is E0004, "non-exhaustive patterns", and the message names an example that is not covered.

Usage notes

  • Arms are tried top to bottom. Put specific patterns before general ones; the compiler warns about unreachable arms.
  • Match ergonomics. Matching a &Option<String> against Some(s) gives s: &String; you do not write & or ref in modern code.
  • Moves. match opt { Some(s) => ... } moves the String out of opt unless you match on &opt or opt.as_ref().
  • Avoid _ for your own enums when you want the compiler to flag new variants; list them explicitly instead.
  • Binding versus constant. A lowercase name in a pattern is a new binding that matches everything. To compare against a value, use a literal, a const or a guard.
  • @ bindings capture the matched value while testing it: n @ 1..=9.
  • Integers are exhaustive too. u8 is covered by 0..=255; i32 needs a wildcard or full ranges.
  • Arm bodies that are blocks need no comma; single expressions do.
  • Alternatives: if let for one case, matches! for a boolean answer.