From 7782838a2cb0f544c7dcd315852630c59ec942d2 Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Wed, 17 Aug 2016 14:51:50 -0400 Subject: [PATCH 1/5] 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. add feature for inclusive_range_syntax fix incorrectly closed code fences --- src/libcore/ops.rs | 67 +++++++++++++++++++++++++++++++--------------- 1 file changed, 46 insertions(+), 21 deletions(-) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 14aa2ba3bd429..681071e5e305c 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -140,6 +140,22 @@ //! //! // `consume_and_return_x` can no longer be invoked at this point //! ``` +//! +//! This example shows the behavior of the various `Range*` structs. +//! +//! ```rust +//! #![feature(inclusive_range_syntax)] +//! +//! 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 +//! ``` #![stable(feature = "rust1", since = "1.0.0")] @@ -1881,11 +1897,12 @@ pub trait IndexMut: Index { /// /// ``` /// 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; @@ -1910,12 +1927,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 { @@ -1973,12 +1991,13 @@ impl> Range { /// 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 { @@ -2040,11 +2059,12 @@ impl> RangeFrom { /// /// ``` /// 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 { @@ -2091,10 +2111,13 @@ impl> RangeTo { /// 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 { @@ -2192,11 +2215,13 @@ impl> RangeInclusive { /// array elements up to and including the index indicated by `end`. /// /// ``` -/// #![feature(inclusive_range_syntax)] /// 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 { From c330046cbd4edfcb22ad63717ecc6ca0da10cc43 Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Tue, 23 Aug 2016 12:26:07 -0400 Subject: [PATCH 2/5] add `fn main` wrappers to enable Rust Playground "Run" button --- src/libcore/ops.rs | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 681071e5e305c..52e4da799545d 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -145,16 +145,17 @@ //! //! ```rust //! #![feature(inclusive_range_syntax)] +//! fn main() { +//! let arr = [0, 1, 2, 3, 4]; //! -//! 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[ .. ], [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 +//! assert_eq!(arr[ ...3], [0,1,2,3 ]); // RangeToIncusive +//! assert_eq!(arr[1...3], [ 1,2,3 ]); // RangeInclusive +//! } //! ``` #![stable(feature = "rust1", since = "1.0.0")] From 34be21d9b537449bce6d9730d7cfdfad3fd88117 Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Tue, 23 Aug 2016 17:35:35 -0400 Subject: [PATCH 3/5] add a note that whitespace alignment is nonidiomatic --- src/libcore/ops.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 52e4da799545d..153ac1ec20948 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -157,6 +157,9 @@ //! 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")] From 520b67abe8c854e7292566dd30ab10b636a59270 Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Sat, 3 Sep 2016 09:56:28 -0400 Subject: [PATCH 4/5] restored inclusive_range_syntax flag --- src/libcore/ops.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 153ac1ec20948..daa032e9cb015 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -2219,6 +2219,7 @@ impl> RangeInclusive { /// array elements up to and including the index indicated by `end`. /// /// ``` +/// #![feature(inclusive_range_syntax)] /// let arr = [0, 1, 2, 3]; /// assert_eq!(arr[ ...2], [0, 1, 2]); /// ``` From 6e3878445394d852ced0864131562ce8d166e553 Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Tue, 6 Sep 2016 16:30:23 -0400 Subject: [PATCH 5/5] replace `../#Examples` with `../index.html#examples` --- src/libcore/ops.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index daa032e9cb015..c808c45a623a1 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -1906,7 +1906,7 @@ pub trait IndexMut: Index { /// /// See the [module examples] for the behavior of other range structs. /// -/// [module examples]: ../#Examples +/// [module examples]: ../index.html#examples #[derive(Copy, Clone, PartialEq, Eq, Hash)] #[stable(feature = "rust1", since = "1.0.0")] pub struct RangeFull; @@ -1937,7 +1937,7 @@ impl fmt::Debug for RangeFull { /// /// See the [module examples] for the behavior of other range structs. /// -/// [module examples]: ../#Examples +/// [module examples]: ../index.html#examples #[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186 #[stable(feature = "rust1", since = "1.0.0")] pub struct Range { @@ -2001,7 +2001,7 @@ impl> Range { /// /// See the [module examples] for the behavior of other range structs. /// -/// [module examples]: ../#Examples +/// [module examples]: ../index.html#examples #[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186 #[stable(feature = "rust1", since = "1.0.0")] pub struct RangeFrom { @@ -2068,7 +2068,7 @@ impl> RangeFrom { /// /// See the [module examples] for the behavior of other range structs. /// -/// [module examples]: ../#Examples +/// [module examples]: ../index.html#examples #[derive(Copy, Clone, PartialEq, Eq, Hash)] #[stable(feature = "rust1", since = "1.0.0")] pub struct RangeTo { @@ -2121,7 +2121,7 @@ impl> RangeTo { /// /// See the [module examples] for the behavior of other range structs. /// -/// [module examples]: ../#Examples +/// [module examples]: ../index.html#examples #[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186 #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")] pub enum RangeInclusive { @@ -2226,7 +2226,7 @@ impl> RangeInclusive { /// /// See the [module examples] for the behavior of other range structs. /// -/// [module examples]: ../#Examples +/// [module examples]: ../index.html#examples #[derive(Copy, Clone, PartialEq, Eq, Hash)] #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")] pub struct RangeToInclusive {