^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. Patterns consist of some combination of literals, destructured arrays or enum constructors, structs and tuples, variable binding specifications, wildcards (..), and placeholders (_). A match expression has a head expression, which is the value to compare to the patterns. The type of the patterns must equal the type of the head expression.

A match behaves differently depending on whether or not the head expression is a place expression or value expression. If the head 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 head 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"),
}
#}

Patterns that bind variables default to binding to a copy or move of the matched value (depending on the matched value's type). This can be changed to bind to a reference by using the ref keyword, or to a mutable reference using ref mut.

Patterns can be used to destructure structs, enums, and tuples. Destructuring breaks a value up into its component pieces. The syntax used is the same as when creating such values. When destructing a data structure with named (but not numbered) fields, it is allowed to write fieldname as a shorthand for fieldname: fieldname. In a pattern whose head expression has a struct, enum or tupl type, a placeholder (_) stands for a single data field, whereas a wildcard .. stands for all the fields of a particular variant.

# #![allow(unused_variables)]
#fn main() {
# enum Message {
#     Quit,
#     WriteString(String),
#     Move { x: i32, y: i32 },
#     ChangeColor(u8, u8, u8),
# }
# let message = Message::Quit;
match message {
    Message::Quit => println!("Quit"),
    Message::WriteString(write) => println!("{}", &write),
    Message::Move{ x, y: 0 } => println!("move {} horizontally", x),
    Message::Move{ .. } => println!("other move"),
    Message::ChangeColor { 0: red, 1: green, 2: _ } => {
        println!("color change, red: {}, green: {}", red, green);
    }
};
#}

Patterns can also dereference pointers by using the &, &mut and box symbols, as appropriate. For example, these two matches on x: &i32 are equivalent:

# #![allow(unused_variables)]
#fn main() {
# let x = &3;
let y = match *x { 0 => "zero", _ => "some" };
let z = match x { &0 => "zero", _ => "some" };

assert_eq!(y, z);
#}

Subpatterns can also be bound to variables by the use of the syntax variable @ subpattern. For example:

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

match x {
    e @ 1 ... 5 => println!("got a range element {}", e),
    _ => println!("anything"),
}
#}

Multiple match patterns may be joined with the | operator. An inclusive range of values may be specified with ..=. For example:

# #![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");
#}

Other forms of [range] (.. for an exclusive range, or any range with one or both endpoints left unspecified) are not supported in matches. The syntax ... is also accepted for inclusive ranges in patterns only, for backwards compatibility.

Range patterns only work char and numeric types. A range pattern may not be a sub-range of another range pattern inside the same match.

Slice patterns can match both arrays of fixed size and slices of dynamic size.

# #![allow(unused_variables)]
#fn main() {
// Fixed size
let arr = [1, 2, 3];
match arr {
    [1, _, _] => "starts with one",
    [a, b, c] => "starts with something else",
};
#}

# #![allow(unused_variables)]
#fn main() {
// Dynamic size
let v = vec![1, 2, 3];
match v[..] {
    [a, b] => { /* this arm will not apply because the length doesn't match */ }
    [a, b, c] => { /* this arm will apply */ }
    _ => { /* this wildcard is required, since we don't know length statically */ }
}
#}

Finally, match patterns can accept pattern 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.

# #![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!(),
};
#}