Documenting binding syntax for pattern matching

doc/tutorial.md

@@ -476,7 +476,7 @@ can be expressed with two dots, as in `M..N`. The underscore (`_`) is
 a wildcard pattern that matches any single value. (`..`) is a different
 wildcard that can match one or more fields in an `enum` variant.
 
-The patterns in a match arm are followed by a fat arrow, `=>`, then an
+The patterns in a `match` arm are followed by a fat arrow, `=>`, then an
 expression to evaluate. Each case is separated by commas. It's often
 convenient to use a block expression for each case, in which case the
 commas are optional.
@@ -542,6 +542,45 @@ Let bindings only work with _irrefutable_ patterns: that is, patterns
 that can never fail to match. This excludes `let` from matching
 literals and most `enum` variants.
 
+The pattern of a `match` arm can also be bound to a variable for use in the
+`match` arm's expression. In Haskell, this is known as an [as-pattern].
+
+
+~~~~
+match (1, 2) {
+    c @ (a, b) => println!("{} {} {:?}", a, b, c)
+}
+~~~~
+
+This will print `1 2 (1, 2)`. `c` is bound to the pattern `(a, b)`, and as
+`a` and `b` are respectively bound to `1` and `2`, `c` comes out to `(1, 2)`.
+The bound variable `c` is only usable in the corresponding arm.
+
+Pattern binding can also be used in conjuntion with guard clauses.
+
+~~~~
+match (1, 2) {
+    c @ (a, b) if a > 0 => println!("First arm {:?}", c),
+    c @ (_, b) if b < 2 => println!("Second arm {:?}", c),
+    _ => {}
+}
+~~~~
+
+Here is an example of a subpattern as-pattern:
+
+> ***Note:*** The following code makes use of Option\<T\> which is explained
+> in section 17 and the [Error-handling and Conditions][conditions] tutorial.
+
+~~~
+let x: Option<(u8, i16)> = Some((10u8, 5i16));
+match x {
+    Some(tuple @ (a, b)) => { println!("{:?}", tuple) },
+    None => { println!("Nothing to see here.") }
+}
+~~~
+
+This will print `(10u8, 5i16)`.
+
 ## Loops
 
 `while` denotes a loop that iterates as long as its given condition
@@ -3239,3 +3278,4 @@ more out of date than this document.
 
 [wiki]: https://github.com/mozilla/rust/wiki/Docs
 [wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools
+[as-pattern]: https://en.wikibooks.org/wiki/Haskell/Pattern_matching#As-patterns