From c7b601c235ebf0de5019a91b696459761435363c Mon Sep 17 00:00:00 2001 From: "Edward Z. Yang" Date: Mon, 9 Dec 2013 22:14:43 -0800 Subject: [PATCH] Elaborate manual on matching (dereference patterns, lvalue/rvalue matching) Signed-off-by: Edward Z. Yang --- doc/rust.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/doc/rust.md b/doc/rust.md index 7368ba2b7e7be..30410e59edaf2 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -2868,12 +2868,21 @@ tail value of `@Nil`. The second pattern matches _any_ list constructed with `Co ignoring the values of its arguments. The difference between `_` and `*` is that the pattern `C(_)` is only type-correct if `C` has exactly one argument, while the pattern `C(..)` is type-correct for any enum variant `C`, regardless of how many arguments `C` has. -To execute an `match` expression, first the head expression is evaluated, then -its value is sequentially compared to the patterns in the arms until a match +A `match` behaves differently depending on whether or not the head expression +is an [lvalue or an rvalue](#lvalues-rvalues-and-temporaries). +If the head expression is an rvalue, 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 an lvalue, the match does not allocate a +temporary location (however, a by-value binding may copy or move from +the lvalue). When possible, it is preferable to match on lvalues, as the +lifetime of these matches inherits the lifetime of the lvalue, rather +than being restricted to the inside of the match. + An example of an `match` expression: ~~~~ @@ -2907,6 +2916,15 @@ This can be changed to bind to a borrowed pointer by using the ```ref``` keyword, or to a mutable borrowed pointer using ```ref mut```. +Patterns can also dereference pointers by using the ``&``, +``~`` or ``@`` symbols, as appropriate. For example, these two matches +on ``x: &int`` are equivalent: + +~~~~ +match *x { 0 => "zero", _ => "some" } +match x { &0 => "zero", _ => "some" } +~~~~ + A pattern that's just an identifier, like `Nil` in the previous answer, could either refer to an enum variant that's in scope,