Rollup merge of rust-lang#35759 - matthew-piziak:refactor-range-examples, r=steveklabnik

refactor range examples

This pull request adds a module-level example of how all the range operators work. It also slims down struct-level examples in lieu of a link to module examples.

Author: steveklabnik

src/libcore/ops.rs

@@ -68,6 +68,26 @@
 //! ```
 //!
 //! See the documentation for each trait for an example implementation.
+//!
+//! This example shows the behavior of the various `Range*` structs.
+//!
+//! ```rust
+//! #![feature(inclusive_range_syntax)]
+//! fn main() {
+//!     let arr = [0, 1, 2, 3, 4];
+//!
+//!     assert_eq!(arr[ .. ], [0,1,2,3,4]); // RangeFull
+//!     assert_eq!(arr[ ..3], [0,1,2    ]); // RangeTo
+//!     assert_eq!(arr[1.. ], [  1,2,3,4]); // RangeFrom
+//!     assert_eq!(arr[1..3], [  1,2    ]); // Range
+//!
+//!     assert_eq!(arr[ ...3], [0,1,2,3 ]); // RangeToIncusive
+//!     assert_eq!(arr[1...3], [  1,2,3 ]); // RangeInclusive
+//! }
+//! ```
+//!
+//! Note: whitespace alignment is not idiomatic Rust. An exception is made in
+//! this case to facilitate comparison.
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
@@ -1736,11 +1756,12 @@ pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
 ///
 /// ```
 /// let arr = [0, 1, 2, 3];
-/// assert_eq!(arr[ .. ], [0,1,2,3]);  // RangeFull
-/// assert_eq!(arr[ ..3], [0,1,2  ]);
-/// assert_eq!(arr[1.. ], [  1,2,3]);
-/// assert_eq!(arr[1..3], [  1,2  ]);
+/// assert_eq!(arr[ .. ], [0, 1, 2, 3]);
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Copy, Clone, PartialEq, Eq, Hash)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct RangeFull;
@@ -1765,12 +1786,13 @@ impl fmt::Debug for RangeFull {
 ///     assert_eq!(3+4+5, (3..6).sum());
 ///
 ///     let arr = [0, 1, 2, 3];
-///     assert_eq!(arr[ .. ], [0,1,2,3]);
-///     assert_eq!(arr[ ..3], [0,1,2  ]);
-///     assert_eq!(arr[1.. ], [  1,2,3]);
-///     assert_eq!(arr[1..3], [  1,2  ]);  // Range
+///     assert_eq!(arr[1..3], [1, 2]);
 /// }
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Clone, PartialEq, Eq, Hash)]  // not Copy -- see #27186
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Range<Idx> {
@@ -1828,12 +1850,13 @@ impl<Idx: PartialOrd<Idx>> Range<Idx> {
 ///     assert_eq!(2+3+4, (2..).take(3).sum());
 ///
 ///     let arr = [0, 1, 2, 3];
-///     assert_eq!(arr[ .. ], [0,1,2,3]);
-///     assert_eq!(arr[ ..3], [0,1,2  ]);
-///     assert_eq!(arr[1.. ], [  1,2,3]);  // RangeFrom
-///     assert_eq!(arr[1..3], [  1,2  ]);
+///     assert_eq!(arr[1.. ], [1, 2, 3]);
 /// }
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Clone, PartialEq, Eq, Hash)]  // not Copy -- see #27186
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct RangeFrom<Idx> {
@@ -1878,12 +1901,13 @@ impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
 ///     assert_eq!((..5), std::ops::RangeTo{ end: 5 });
 ///
 ///     let arr = [0, 1, 2, 3];
-///     assert_eq!(arr[ .. ], [0,1,2,3]);
-///     assert_eq!(arr[ ..3], [0,1,2  ]);  // RangeTo
-///     assert_eq!(arr[1.. ], [  1,2,3]);
-///     assert_eq!(arr[1..3], [  1,2  ]);
+///     assert_eq!(arr[ ..3], [0, 1, 2]);
 /// }
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Copy, Clone, PartialEq, Eq, Hash)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct RangeTo<Idx> {
@@ -1930,10 +1954,13 @@ impl<Idx: PartialOrd<Idx>> RangeTo<Idx> {
 ///     assert_eq!(3+4+5, (3...5).sum());
 ///
 ///     let arr = [0, 1, 2, 3];
-///     assert_eq!(arr[ ...2], [0,1,2  ]);
-///     assert_eq!(arr[1...2], [  1,2  ]);  // RangeInclusive
+///     assert_eq!(arr[1...2], [1, 2]);
 /// }
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Clone, PartialEq, Eq, Hash)]  // not Copy -- see #27186
 #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
 pub enum RangeInclusive<Idx> {
@@ -2017,10 +2044,13 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
 ///     assert_eq!((...5), std::ops::RangeToInclusive{ end: 5 });
 ///
 ///     let arr = [0, 1, 2, 3];
-///     assert_eq!(arr[ ...2], [0,1,2  ]);  // RangeToInclusive
-///     assert_eq!(arr[1...2], [  1,2  ]);
+///     assert_eq!(arr[ ...2], [0, 1, 2]);
 /// }
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Copy, Clone, PartialEq, Eq, Hash)]
 #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
 pub struct RangeToInclusive<Idx> {