Matching Values

The match keyword lets you match a value against one or more patterns. The comparisons are done from top to bottom and the first match wins.

The patterns can be simple values, similarly to switch in C and C++:

  1. #[rustfmt::skip]
  2. fn main() {
  3.     let input = 'x';
  4.     match input {
  5.         'q'                       => println!("Quitting"),
  6.         'a' | 's' | 'w' | 'd'     => println!("Moving around"),
  7.         '0'..='9'                 => println!("Number input"),
  8.         key if key.is_lowercase() => println!("Lowercase: {key}"),
  9.         _                         => println!("Something else"),
  10.     }
  11. }

The _ pattern is a wildcard pattern which matches any value. The expressions must be exhaustive, meaning that it covers every possibility, so _ is often used as the final catch-all case.

Match can be used as an expression. Just like if, each match arm must have the same type. The type is the last expression of the block, if any. In the example above, the type is ().

A variable in the pattern (key in this example) will create a binding that can be used within the match arm.

A match guard causes the arm to match only if the condition is true.

This slide should take about 10 minutes.

Key Points:

  • You might point out how some specific characters are being used when in a pattern

    • | as an or
    • .. can expand as much as it needs to be
    • 1..=5 represents an inclusive range
    • _ is a wild card

  • Match guards as a separate syntax feature are important and necessary when we wish to concisely express more complex ideas than patterns alone would allow.

  • They are not the same as separate if expression inside of the match arm. An if expression inside of the branch block (after =>) happens after the match arm is selected. Failing the if condition inside of that block won’t result in other arms of the original match expression being considered.

  • The condition defined in the guard applies to every expression in a pattern with an |.

More To Explore

  • Another piece of pattern syntax you can show students is the @ syntax which binds a part of a pattern to a variable. For example:

    1. #![allow(unused)]
    2. fn main() {
    3. let opt = Some(123);
    4. match opt {
    5.     outer @ Some(inner) => {
    6.         println!("outer: {outer:?}, inner: {inner}");
    7.     }
    8.     None => {}
    9. }
    10. }

    In this example inner has the value 123 which it pulled from the Option via destructuring, outer captures the entire Some(inner) expression, so it contains the full Option::Some(123). This is rarely used but can be useful in more complex patterns.