From c03b84c5d6de0b001283b1f4e0dd9bde8a0baafa Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Wed, 20 Nov 2019 11:18:37 +0100 Subject: [PATCH 1/2] document `bind_by_move_pattern_guards` --- src/expressions/match-expr.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/expressions/match-expr.md b/src/expressions/match-expr.md index aea103326..18ee6d0a9 100644 --- a/src/expressions/match-expr.md +++ b/src/expressions/match-expr.md @@ -91,10 +91,11 @@ Every binding in each `|` separated pattern must appear in all of the patterns in the arm. Every binding of the same name must have the same type, and have the same binding mode. +## Match guards + 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. +consist of a `bool`-typed expression following the `if` keyword. When the pattern matches successfully, the pattern guard expression is executed. If the expression evaluates to true, the pattern is successfully matched against. @@ -125,6 +126,15 @@ let message = match maybe_digit { > assert_eq!(i.get(), 2); > ``` +A pattern guard may refer to the variables bound within the pattern they follow. +When such a variable's binding mode is by-value, +a shared reference is taken to it before evaluating the guard. +When accessing the variable in the guard by shared reference, +the shared reference taken before evaluating the guard is used. +Only when the guard expression evaluates to true is the by-value variable +moved, or copied, into the arm's body. This allows shared borrows to be used +inside guards without moving out of the scrutinee in case guard fails to match. + ## Attributes on match arms Outer attributes are allowed on match arms. The only attributes that have From 2bb5698ac8bd14a7f3c8d581ae97e1c7aeeeac67 Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Sat, 30 Nov 2019 09:28:55 +0100 Subject: [PATCH 2/2] further improve match guard bind-by-move docs --- src/expressions/match-expr.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/expressions/match-expr.md b/src/expressions/match-expr.md index 18ee6d0a9..dcbf69fe7 100644 --- a/src/expressions/match-expr.md +++ b/src/expressions/match-expr.md @@ -127,13 +127,14 @@ let message = match maybe_digit { > ``` A pattern guard may refer to the variables bound within the pattern they follow. -When such a variable's binding mode is by-value, -a shared reference is taken to it before evaluating the guard. -When accessing the variable in the guard by shared reference, -the shared reference taken before evaluating the guard is used. -Only when the guard expression evaluates to true is the by-value variable -moved, or copied, into the arm's body. This allows shared borrows to be used +Before evaluating the guard, a shared reference is taken to the part of the +scrutinee the variable matches on. While evaluating the guard, +this shared reference is then used when accessing the variable. +Only when the guard evaluates to true is the value moved, or copied, +from the scrutinee into the variable. This allows shared borrows to be used inside guards without moving out of the scrutinee in case guard fails to match. +Moreover, by holding a shared reference while evaluating the guard, +mutation inside guards is also prevented. ## Attributes on match arms