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 >                             ( [_ExpressionWithoutBlock_][_Expression_] `,`
  13 >                             | [_ExpressionWithBlock_][_Expression_] `,`<sup>?</sup> )
  14 >                           )<sup>\*</sup>\
  15 > &nbsp;&nbsp; _MatchArm_ `=>` [_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 *[scrutinee] expression*, which is the value to compare to the
  29 patterns. The scrutinee expression and the patterns must have the same type.
  30
  31 A `match` behaves differently depending on whether or not the scrutinee
  32 expression is a [place expression or value expression][place expression].
  33 If the scrutinee expression is a [value expression], it is first evaluated into
  34 a 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 scrutinee expression is a [place expression], the match does not
  41 allocate a temporary location; however, a by-value binding may copy or move
  42 from the 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. Each pattern will be
  66 tested in left-to-right sequence until a successful match is found.
  67
  68 ```rust
  69 # let x = 9;
  70 let message = match x {
  71     0 | 1  => "not many",
  72     2 ..= 9 => "a few",
  73     _      => "lots"
  74 };
  75
  76 assert_eq!(message, "a few");
  77
  78 // Demonstration of pattern match order.
  79 struct S(i32, i32);
  80
  81 match S(1, 2) {
  82     S(z @ 1, _) | S(_, z @ 2) => assert_eq!(z, 1),
  83     _ => panic!(),
  84 }
  85 ```
  86
  87 > Note: The `2..=9` is a [Range Pattern], not a [Range Expression]. Thus, only
  88 > those types of ranges supported by range patterns can be used in match arms.
  89
  90 Every binding in each `|` separated pattern must appear in all of the patterns
  91 in the arm. Every binding of the same name must have the same type, and have
  92 the same binding mode.
  93
  94 ## Match guards
  95
  96 Match arms can accept _match guards_ to further refine the
  97 criteria for matching a case. Pattern guards appear after the pattern and
  98 consist of a `bool`-typed expression following the `if` keyword.
  99
 100 When the pattern matches successfully, the pattern guard expression is executed.
 101 If the expression evaluates to true, the pattern is successfully matched against.
 102 Otherwise, the next pattern, including other matches with the `|` operator in
 103 the same arm, is tested.
 104
 105 ```rust
 106 # let maybe_digit = Some(0);
 107 # fn process_digit(i: i32) { }
 108 # fn process_other(i: i32) { }
 109 let message = match maybe_digit {
 110     Some(x) if x < 10 => process_digit(x),
 111     Some(x) => process_other(x),
 112     None => panic!(),
 113 };
 114 ```
 115
 116 > Note: Multiple matches using the `|` operator can cause the pattern guard and
 117 > the side effects it has to execute multiple times. For example:
 118 >
 119 > ```rust
 120 > # use std::cell::Cell;
 121 > let i : Cell<i32> = Cell::new(0);
 122 > match 1 {
 123 >     1 | _ if { i.set(i.get() + 1); false } => {}
 124 >     _ => {}
 125 > }
 126 > assert_eq!(i.get(), 2);
 127 > ```
 128
 129 A pattern guard may refer to the variables bound within the pattern they follow.
 130 Before evaluating the guard, a shared reference is taken to the part of the
 131 scrutinee the variable matches on. While evaluating the guard,
 132 this shared reference is then used when accessing the variable.
 133 Only when the guard evaluates to true is the value moved, or copied,
 134 from the scrutinee into the variable. This allows shared borrows to be used
 135 inside guards without moving out of the scrutinee in case guard fails to match.
 136 Moreover, by holding a shared reference while evaluating the guard,
 137 mutation inside guards is also prevented.
 138
 139 ## Attributes on match arms
 140
 141 Outer attributes are allowed on match arms. The only attributes that have
 142 meaning on match arms are [`cfg`], [`cold`], and the [lint check attributes].
 143
 144 [Inner attributes] are allowed directly after the opening brace of the match
 145 expression in the same expression contexts as [attributes on block
 146 expressions].
 147
 148 [_Expression_]: ../expressions.md
 149 [place expression]: ../expressions.md#place-expressions-and-value-expressions
 150 [value expression]: ../expressions.md#place-expressions-and-value-expressions
 151 [_InnerAttribute_]: ../attributes.md
 152 [_OuterAttribute_]: ../attributes.md
 153 [`cfg`]: ../conditional-compilation.md
 154 [`cold`]: ../attributes/codegen.md#the-cold-attribute
 155 [lint check attributes]: ../attributes/diagnostics.md#lint-check-attributes
 156 [Range Expression]: range-expr.md
 157
 158 [_Pattern_]: ../patterns.md
 159 [pattern]: ../patterns.md
 160 [Inner attributes]: ../attributes.md
 161 [Range Pattern]: ../patterns.md#range-patterns
 162 [attributes on block expressions]: block-expr.md#attributes-on-block-expressions
 163 [binding mode]: ../patterns.md#binding-modes
 164 [scrutinee]: ../glossary.md#scrutinee