From 31b7ff4a841dbccb007237df86d37be4527436ef Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Wed, 17 Aug 2016 14:51:50 -0400 Subject: [PATCH 1/3] 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 | 66 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 20 deletions(-) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 5a1993e741c60..fe5c3099de3bb 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -68,6 +68,22 @@ //! ``` //! //! 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)] +//! +//! 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")] @@ -1594,11 +1610,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; @@ -1623,12 +1640,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 { @@ -1686,12 +1704,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 { @@ -1736,12 +1755,13 @@ impl> RangeFrom { /// 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 { @@ -1788,10 +1808,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 { @@ -1875,10 +1898,13 @@ impl> RangeInclusive { /// 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 { From b400a43c3eccce1ec82b6ea2474c78c89e4af9e3 Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Tue, 23 Aug 2016 12:26:07 -0400 Subject: [PATCH 2/3] 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 fe5c3099de3bb..8c19902d274ed 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -73,16 +73,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 711333f6c79ee1b35cf61beb814238c5a2c3b645 Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Tue, 23 Aug 2016 17:35:35 -0400 Subject: [PATCH 3/3] 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 8c19902d274ed..73c60d5c2069e 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -85,6 +85,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")]