Document inclusive ranges.

rust-lang · Mar 15, 2018 · 547305f · 547305f
1 parent a8755cc
commit 547305f
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 34 deletions.
diff --git a/src/expressions.md b/src/expressions.md
@@ -65,7 +65,7 @@ evaluated in the order given by their associativity.
 | `==` `!=` `<` `>` `<=` `>=` | Require parentheses |
 | `&&`                        | left to right       |
 | <code>&#124;&#124;</code>   | left to right       |
-| `..` `...`                  | Require parentheses |
+| `..` `..=`                  | Require parentheses |
 | `<-`                        | right to left       |
 | `=` `+=` `-=` `*=` `/=` `%=` <br> `&=` <code>&#124;=</code> `^=` `<<=` `>>=` | right to left |
 | `return` `break` closures   |                     |

diff --git a/src/expressions/match-expr.md b/src/expressions/match-expr.md
@@ -1,27 +1,27 @@
 # `match` expressions
 
-> **<sup>Syntax</sup>**  
-> _MatchExpression_ :  
-> &nbsp;&nbsp; `match` [_Expression_]<sub>_except struct expression_</sub> `{`  
-> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>  
-> &nbsp;&nbsp; &nbsp;&nbsp; _MatchArms_<sup>?</sup>  
-> &nbsp;&nbsp; `}`  
->  
-> _MatchArms_ :  
-> &nbsp;&nbsp; ( _MatchArm_ `=>` 
+> **<sup>Syntax</sup>**
+> _MatchExpression_ :
+> &nbsp;&nbsp; `match` [_Expression_]<sub>_except struct expression_</sub> `{`
+> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>
+> &nbsp;&nbsp; &nbsp;&nbsp; _MatchArms_<sup>?</sup>
+> &nbsp;&nbsp; `}`
+>
+> _MatchArms_ :
+> &nbsp;&nbsp; ( _MatchArm_ `=>`
 >                             ( [_BlockExpression_] `,`<sup>?</sup>
->                             | [_Expression_] `,` ) 
->                           )<sup>\*</sup>  
-> &nbsp;&nbsp; _MatchArm_ `=>` ( [_BlockExpression_] | [_Expression_] ) `,`<sup>?</sup>  
->  
-> _MatchArm_ :  
+>                             | [_Expression_] `,` )
+>                           )<sup>\*</sup>
+> &nbsp;&nbsp; _MatchArm_ `=>` ( [_BlockExpression_] | [_Expression_] ) `,`<sup>?</sup>
+>
+> _MatchArm_ :
 > &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> _MatchArmPatterns_ _MatchArmGuard_<sup>?</sup>
->  
-> _MatchArmPatterns_ :  
-> &nbsp;&nbsp; `|`<sup>?</sup> _Pattern_ ( `|` _Pattern_ )<sup>*</sup>  
->  
-> _MatchArmGuard_ :  
-> &nbsp;&nbsp; `if` [_Expression_]  
+>
+> _MatchArmPatterns_ :
+> &nbsp;&nbsp; `|`<sup>?</sup> _Pattern_ ( `|` _Pattern_ )<sup>*</sup>
+>
+> _MatchArmGuard_ :
+> &nbsp;&nbsp; `if` [_Expression_]
 
 A `match` expression branches on a *pattern*. The exact form of matching that
 occurs depends on the pattern. Patterns consist of some combination of
@@ -41,7 +41,7 @@ the pattern are assigned to local variables in the arm's block, and control
 enters the block.
 
 When the head expression is a [place expression], the match does not allocate a
-temporary location; however, a by-value binding may copy or move from the 
+temporary location; however, a by-value binding may copy or move from the
 memory location.
 When possible, it is preferable to match on place expressions, as the lifetime
 of these matches inherits the lifetime of the place expression rather than being
@@ -118,20 +118,27 @@ match x {
 }
 ```
 
-Multiple match patterns may be joined with the `|` operator. A range of values
-may be specified with `...`. For example:
+Multiple match patterns may be joined with the `|` operator. An inclusive range
+of values may be specified with `..=`. For example:
 
 ```rust
-# let x = 2;
+# let x = 9;
 let message = match x {
     0 | 1  => "not many",
-    2 ... 9 => "a few",
+    2 ..= 9 => "a few",
     _      => "lots"
 };
+
+assert_eq!(message, "a few");
 ```
 
-Range patterns only work on [`char`] and [numeric types]. A range pattern may
-not be a sub-range of another range pattern inside the same `match`.
+Other forms of [range] \(`..` for an exclusive range, or any range with one or
+both endpoints left unspecified) are not supported in matches. The
+syntax `...` is also accepted for inclusive ranges in patterns only, for
+backwards compatibility.
+
+Range patterns only work [`char`] and [numeric types]. A range pattern may not
+be a sub-range of another range pattern inside the same `match`.
 
 Finally, match patterns can accept *pattern guards* to further refine the
 criteria for matching a case. Pattern guards appear after the pattern and
@@ -157,3 +164,4 @@ let message = match maybe_digit {
 [numeric types]: types.html#numeric-types
 [_InnerAttribute_]: attributes.html
 [_OuterAttribute_]: attributes.html
+[range]: range-expr.html
diff --git a/src/expressions/range-expr.md b/src/expressions/range-expr.md
@@ -6,6 +6,8 @@
 > &nbsp;&nbsp; | _RangeFromExpr_  
 > &nbsp;&nbsp; | _RangeToExpr_  
 > &nbsp;&nbsp; | _RangeFullExpr_  
+> &nbsp;&nbsp; | _RangeInclusiveExpr_  
+> &nbsp;&nbsp; | _RangeToInclusiveExpr_  
 >  
 > _RangeExpr_ :  
 > &nbsp;&nbsp; [_Expression_] `..` [_Expression_]  
@@ -18,16 +20,25 @@
 >  
 > _RangeFullExpr_ :  
 > &nbsp;&nbsp; `..`  
+>
+> _RangeExpr_ :  
+> &nbsp;&nbsp; [_Expression_] `..=` [_Expression_]  
+>  
+> _RangeToExpr_ :  
+> &nbsp;&nbsp; `..=` [_Expression_]  
 
-The `..` operator will construct an object of one of the `std::ops::Range` (or
-`core::ops::Range`) variants, according to the following table:
+The `..` and `..=` operators will construct an object of one of the
+`std::ops::Range` (or `core::ops::Range`) variants, according to the following
+table:
 
 | Production             | Syntax        | Type                         | Range                 |
 |------------------------|---------------|------------------------------|-----------------------|
 | _RangeExpr_            | start`..`end  | [std::ops::Range]            | start &le; x &lt; end |
 | _RangeFromExpr_        | start`..`     | [std::ops::RangeFrom]        | start &le; x          |
 | _RangeToExpr_          | `..`end       | [std::ops::RangeTo]          |            x &lt; end |
 | _RangeFullExpr_        | `..`          | [std::ops::RangeFull]        |            -          |
+| _RangeInclusiveExpr_   | start`..=`end | [std::ops::RangeInclusive]   | start &le; x &le; end |
+| _RangeToInclusiveExpr_ | `..=`end      | [std::ops::RangeToInclusive] |            x &le; end |
 
 Examples:
 
@@ -36,6 +47,8 @@ Examples:
 3..;    // std::ops::RangeFrom
 ..4;    // std::ops::RangeTo
 ..;     // std::ops::RangeFull
+5..=6;  // std::ops::RangeInclusive
+..=7;   // std::ops::RangeToInclusive
 ```
 
 The following expressions are equivalent.
@@ -57,7 +70,9 @@ for i in 1..11 {
 
 [_Expression_]: expressions.html
 
-[std::ops::Range]:     https://doc.rust-lang.org/std/ops/struct.Range.html
-[std::ops::RangeFrom]: https://doc.rust-lang.org/std/ops/struct.RangeFrom.html
-[std::ops::RangeTo]:   https://doc.rust-lang.org/std/ops/struct.RangeTo.html
-[std::ops::RangeFull]: https://doc.rust-lang.org/std/ops/struct.RangeFull.html
+[std::ops::Range]:            https://doc.rust-lang.org/std/ops/struct.Range.html
+[std::ops::RangeFrom]:        https://doc.rust-lang.org/std/ops/struct.RangeFrom.html
+[std::ops::RangeTo]:          https://doc.rust-lang.org/std/ops/struct.RangeTo.html
+[std::ops::RangeFull]:        https://doc.rust-lang.org/std/ops/struct.RangeFull.html
+[std::ops::RangeInclusive]:   https://doc.rust-lang.org/std/ops/struct.RangeInclusive.html
+[std::ops::RangeToInclusive]: https://doc.rust-lang.org/std/ops/struct.RangeToInclusive.html