^Syntax
MatchExpression :
   match Expression_{except struct expression} {
      InnerAttribute^*
      MatchArms^?
   }

MatchArms :
   ( MatchArm => ( BlockExpression ,^? | Expression , ) )^*
   MatchArm => ( BlockExpression | Expression ) ,^?

MatchArm :
   OuterAttribute^* MatchArmPatterns MatchArmGuard^?

MatchArmPatterns :
   |^? Pattern ( | Pattern )^*

MatchArmGuard :
   if Expression

A match expression branches on a pattern. The exact form of matching that occurs depends on the pattern. A match expression has a scrutinee expression, which is the value to compare to the patterns. The scrutinee expression and the patterns must have the same type.

A match behaves differently depending on whether or not the scrutinee expression is a place expression or value expression. If the scrutinee expression is a value expression, it is first evaluated into a temporary location, and the resulting value is sequentially compared to the patterns in the arms until a match is found. The first arm with a matching pattern is chosen as the branch target of the match, any variables bound by the pattern are assigned to local variables in the arm's block, and control enters the block.

When the scrutinee expression is a place expression, the match does not allocate a temporary location; however, a by-value binding may copy or move from the memory location. When possible, it is preferable to match on place expressions, as the lifetime of these matches inherits the lifetime of the place expression rather than being restricted to the inside of the match.

An example of a match expression:

# #![allow(unused_variables)]
#fn main() {
let x = 1;

match x {
    1 => println!("one"),
    2 => println!("two"),
    3 => println!("three"),
    4 => println!("four"),
    5 => println!("five"),
    _ => println!("something else"),
}
#}

Variables bound within the pattern are scoped to the match guard and the arm's expression. The binding mode (move, copy, or reference) depends on the pattern.

Multiple match patterns may be joined with the | operator:

# #![allow(unused_variables)]
#fn main() {
# let x = 9;
let message = match x {
    0 | 1  => "not many",
    2 ..= 9 => "a few",
    _      => "lots"
};

assert_eq!(message, "a few");
#}

Please notice that the 2..=9 is a Range Pattern, not a Range Expression and, thus, only those types of ranges supported by range patterns can be used in match arms.

Match arms can accept match guards to further refine the criteria for matching a case. Pattern guards appear after the pattern and consist of a bool-typed expression following the if keyword. A pattern guard may refer to the variables bound within the pattern they follow.

When the pattern matches successfully, the pattern guard expression is executed. If the expression is truthy, the pattern is successfully matched against. Otherwise, the next pattern, including other matches with the | operator in the same arm, is tested.

# #![allow(unused_variables)]
#fn main() {
# let maybe_digit = Some(0);
# fn process_digit(i: i32) { }
# fn process_other(i: i32) { }
let message = match maybe_digit {
    Some(x) if x < 10 => process_digit(x),
    Some(x) => process_other(x),
    None => panic!(),
};
#}

Note: Multiple matches using the | operator can cause the pattern guard and and side effects it has to execute multiple times. For example:

use std::cell::Cell;
fn main() {
    let i : Cell<i32> = Cell::new(0);
    match 1 {
        1 | _ if { i.set(i.get() + 1); false } => {}
        _ => {}
    }
    assert_eq!(i.get(), 2);
}

Outer attributes are allowed on match arms. The only attributes that have meaning on match arms are cfg, cold, and the lint check attributes.

Inner attributes are allowed directly after the opening brace of the match expression in the same expression contexts as attributes on block expressions.