src/doc/reference/src/expressions/match-expr.md

   1 # `match` expressions
   2
   3 > **<sup>Syntax</sup>**\
   4 > _MatchExpression_ :\
   5 > &nbsp;&nbsp; `match` [_Expression_]<sub>_except struct expression_</sub> `{`\
   6 > &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
   7 > &nbsp;&nbsp; &nbsp;&nbsp; _MatchArms_<sup>?</sup>\
   8 > &nbsp;&nbsp; `}`
   9 >
  10 > _MatchArms_ :\
  11 > &nbsp;&nbsp; ( _MatchArm_ `=>`
  12 >                             ( [_BlockExpression_] `,`<sup>?</sup>
  13 >                             | [_Expression_] `,` )
  14 >                           )<sup>\*</sup>\
  15 > &nbsp;&nbsp; _MatchArm_ `=>` ( [_BlockExpression_] | [_Expression_] ) `,`<sup>?</sup>
  16 >
  17 > _MatchArm_ :\
  18 > &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> _MatchArmPatterns_ _MatchArmGuard_<sup>?</sup>
  19 >
  20 > _MatchArmPatterns_ :\
  21 > &nbsp;&nbsp; `|`<sup>?</sup> [_Pattern_] ( `|` [_Pattern_] )<sup>\*</sup>
  22 >
  23 > _MatchArmGuard_ :\
  24 > &nbsp;&nbsp; `if` [_Expression_]
  25
  26 A *`match` expression* branches on a pattern. The exact form of matching that
  27 occurs depends on the [pattern]. A `match`
  28 expression has a *head expression*, which is the value to compare to the
  29 patterns. The head expression and the patterns must have the same type.
  30
  31 A `match` behaves differently depending on whether or not the head expression
  32 is a [place expression or value expression][place expression].
  33 If the head expression is a [value expression], it is first evaluated into a
  34 temporary location, and the resulting value is sequentially compared to the
  35 patterns in the arms until a match is found. The first arm with a matching
  36 pattern is chosen as the branch target of the `match`, any variables bound by
  37 the pattern are assigned to local variables in the arm's block, and control
  38 enters the block.
  39
  40 When the head expression is a [place expression], the match does not allocate a
  41 temporary location; however, a by-value binding may copy or move from the
  42 memory location.
  43 When possible, it is preferable to match on place expressions, as the lifetime
  44 of these matches inherits the lifetime of the place expression rather than being
  45 restricted to the inside of the match.
  46
  47 An example of a `match` expression:
  48
  49 ```rust
  50 let x = 1;
  51
  52 match x {
  53     1 => println!("one"),
  54     2 => println!("two"),
  55     3 => println!("three"),
  56     4 => println!("four"),
  57     5 => println!("five"),
  58     _ => println!("something else"),
  59 }
  60 ```
  61
  62 Variables bound within the pattern are scoped to the match guard and the arm's
  63 expression. The [binding mode] (move, copy, or reference) depends on the pattern.
  64
  65 Multiple match patterns may be joined with the `|` operator:
  66
  67 ```rust
  68 # let x = 9;
  69 let message = match x {
  70     0 | 1  => "not many",
  71     2 ..= 9 => "a few",
  72     _      => "lots"
  73 };
  74
  75 assert_eq!(message, "a few");
  76 ```
  77
  78 Please notice that the `2..=9` is a [Range Pattern], not a [Range Expression]
  79 and, thus, only those types of ranges supported by range patterns can be used
  80 in match arms.
  81
  82 Match arms can accept _match guards_ to further refine the
  83 criteria for matching a case. Pattern guards appear after the pattern and
  84 consist of a bool-typed expression following the `if` keyword. A pattern guard
  85 may refer to the variables bound within the pattern they follow.
  86
  87 When the pattern matches successfully, the pattern guard expression is executed.
  88 If the expression is truthy, the pattern is successfully matched against.
  89 Otherwise, the next pattern, including other matches with the `|` operator in
  90 the same arm, is tested.
  91
  92 ```rust
  93 # let maybe_digit = Some(0);
  94 # fn process_digit(i: i32) { }
  95 # fn process_other(i: i32) { }
  96 let message = match maybe_digit {
  97     Some(x) if x < 10 => process_digit(x),
  98     Some(x) => process_other(x),
  99     None => panic!(),
 100 };
 101 ```
 102
 103 > Note: Multiple matches using the `|` operator can cause the pattern guard and
 104 > and side effects it has to execute multiple times. For example:
 105 >
 106 > ```rust
 107 > use std::cell::Cell;
 108 > fn main() {
 109 >     let i : Cell<i32> = Cell::new(0);
 110 >     match 1 {
 111 >         1 | _ if { i.set(i.get() + 1); false } => {}
 112 >         _ => {}
 113 >     }
 114 >     assert_eq!(i.get(), 2);
 115 > }
 116 > ```
 117
 118 ## Attributes on match arms
 119
 120 Outer attributes are allowed on match arms. The only attributes that have
 121 meaning on match arms are [`cfg`], `cold`, and the [lint check attributes].
 122
 123 [_Expression_]: expressions.html
 124 [_BlockExpression_]: expressions/block-expr.html#block-expressions
 125 [place expression]: expressions.html#place-expressions-and-value-expressions
 126 [value expression]: expressions.html#place-expressions-and-value-expressions
 127 [_InnerAttribute_]: attributes.html
 128 [_OuterAttribute_]: attributes.html
 129 [`cfg`]: conditional-compilation.html
 130 [lint check attributes]: attributes.html#lint-check-attributes
 131 [Range Expression]: expressions/range-expr.html
 132
 133 [_Pattern_]: patterns.html
 134 [pattern]: patterns.html
 135 [Identifier Patterns]: patterns.html#identifier-patterns
 136 [Struct Patterns]: patterns.html#struct-patterns
 137 [Tuple Struct Patterns]: patterns.html#tuplestruct-patterns
 138 [Tuple Patterns]: patterns.html#tuple-patterns
 139 [Range Pattern]: patterns.html#range-patterns
 140 [binding mode]: patterns.html#binding-modes