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.
let text = match n { 0 => "zero", 1..=9 => "small", _ => "large", };
Try it
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.
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
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>againstSome(s)givess: &String; you do not write&orrefin modern code. - Moves.
match opt { Some(s) => ... }moves theStringout ofoptunless you match on&optoropt.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
constor a guard. @bindings capture the matched value while testing it:n @ 1..=9.- Integers are exhaustive too.
u8is covered by0..=255;i32needs a wildcard or full ranges. - Arm bodies that are blocks need no comma; single expressions do.
- Alternatives:
if letfor one case,matches!for a boolean answer.