Document inclusive ranges.

Provides the reference documentation for rust-lang/rust#28237.

Author: Alexis Hunt

src/expressions/match-expr.md

@@ -95,18 +95,23 @@ 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");
 ```
 
+Other forms of [range] \(`..` for an exclusive range, or any range with one or
+both endpoints left unspecified) are not currently supported in matches.
+
 Range patterns only work on scalar types (like integers and characters; not
 like arrays and structs, which have sub-components). A range pattern may not be
 a sub-range of another range pattern inside the same `match`.
@@ -128,4 +133,5 @@ let message = match maybe_digit {
 ```
 
 [place expression]: expressions.html#place-expressions-and-value-expressions
-[value expression]: expressions.html#place-expressions-and-value-expressions
+[value expression]: expressions.html#place-expressions-and-value-expressions
+[range]: range-expr.html

src/expressions/range-expr.md

@@ -6,6 +6,8 @@
 >    | _RangeFromExpr_  
 >    | _RangeToExpr_  
 >    | _RangeFullExpr_  
+>    | _RangeInclusiveExpr_  
+>    | _RangeToInclusiveExpr_  
 >  
 > _RangeExpr_ :  
 >    [_Expression_] `..` [_Expression_]  
@@ -18,16 +20,25 @@
 >  
 > _RangeFullExpr_ :  
 >    `..`  
+>
+> _RangeExpr_ :  
+>    [_Expression_] `..=` [_Expression_]  
+>  
+> _RangeToExpr_ :  
+>    `..=` [_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 ≤ x < end |
 | _RangeFromExpr_        | start`..`     | [std::ops::RangeFrom]        | start ≤ x          |
 | _RangeToExpr_          | `..`end       | [std::ops::RangeTo]          |            x < end |
 | _RangeFullExpr_        | `..`          | [std::ops::RangeFull]        |            -          |
+| _RangeInclusiveExpr_   | start`..=`end | [std::ops::RangeInclusive]   | start ≤ x ≤ end |
+| _RangeToInclusiveExpr_ | `..=`end      | [std::ops::RangeToInclusive] |            x ≤ 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