diff --git a/doc/tutorial.md b/doc/tutorial.md index ae045581ad3e0..5fa10a94c6851 100644 --- a/doc/tutorial.md +++ b/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\ 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