---

yaml
---
r: 97805
b: refs/heads/snap-stage3
c: e33b1da
h: refs/heads/master
i:
  97803: 9318e63
v: v3

Author: ezyang

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 0da105a8b7b6b1e0568e8ff20f6ff4b13cc7ecc2
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: b2cac497e8989fb6d26c1f20441e8354950bbcc3
+refs/heads/snap-stage3: e33b1dabd35685e586f85f3e53783e31871bc5b7
 refs/heads/try: c274a6888410ce3e357e014568b43310ed787d36
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/doc/rust.md

@@ -2893,12 +2893,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:
 
 ~~~~
@@ -2932,6 +2941,15 @@ This can be changed to bind to a reference by
 using the ```ref``` keyword,
 or to a mutable reference 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,