Comment on shadowing with patterns

[rust.git] / src / doc / trpl / patterns.md

diff --git a/src/doc/trpl/patterns.md b/src/doc/trpl/patterns.md
index a365732fe9bd14c115654cb84eb115769b025508..bce147cc71fbe171eac40ef7e732efa858e27f79 100644 (file)
--- a/src/doc/trpl/patterns.md
+++ b/src/doc/trpl/patterns.md
@@ -23,6 +23,31 @@ match x {
 
 This prints `one`.
 
+There’s one pitfall with patterns: like anything that introduces a new binding,
+they introduce shadowing. For example:
+
+```rust
+let x = 'x';
+let c = 'c';
+
+match c {
+    x => println!("x: {} c: {}", x, c),
+}
+
+println!("x: {}", x)
+```
+
+This prints:
+
+```text
+x: c c: c
+x: x
+```
+
+In other words, `x =>` matches the pattern and introduces a new binding named
+`x` that’s in scope for the match arm. Because we already have a binding named
+`x`, this new `x` shadows it.
+
 # Multiple patterns
 
 You can match multiple patterns with `|`: