diff --git a/src/libcore/ops/range.rs b/src/libcore/ops/range.rs index 33258b7a875c..6a405cfdb980 100644 --- a/src/libcore/ops/range.rs +++ b/src/libcore/ops/range.rs @@ -10,10 +10,10 @@ use fmt; -/// An unbounded range. Use `..` (two dots) for its shorthand. +/// An unbounded range (`..`). /// -/// Its primary use case is slicing index. It cannot serve as an iterator -/// because it doesn't have a starting point. +/// `RangeFull` is primarily used as a [slicing index], it's shorthand is `..`. +/// It cannot serve as an [`Iterator`] because it doesn't have a starting point. /// /// # Examples /// @@ -23,8 +23,8 @@ use fmt; /// assert_eq!((..), std::ops::RangeFull); /// ``` /// -/// It does not have an `IntoIterator` implementation, so you can't use it in a -/// `for` loop directly. This won't compile: +/// It does not have an [`IntoIterator`] implementation, so you can't use it in +/// a `for` loop directly. This won't compile: /// /// ```compile_fail,E0277 /// for i in .. { @@ -32,7 +32,7 @@ use fmt; /// } /// ``` /// -/// Used as a slicing index, `RangeFull` produces the full array as a slice. +/// Used as a [slicing index], `RangeFull` produces the full array as a slice. /// /// ``` /// let arr = [0, 1, 2, 3]; @@ -41,6 +41,10 @@ use fmt; /// assert_eq!(arr[1.. ], [ 1,2,3]); /// assert_eq!(arr[1..3], [ 1,2 ]); /// ``` +/// +/// [`IntoIterator`]: ../iter/trait.Iterator.html +/// [`Iterator`]: ../iter/trait.IntoIterator.html +/// [slicing index]: ../slice/trait.SliceIndex.html #[derive(Copy, Clone, PartialEq, Eq, Hash)] #[stable(feature = "rust1", since = "1.0.0")] pub struct RangeFull; @@ -52,24 +56,23 @@ impl fmt::Debug for RangeFull { } } -/// A (half-open) range which is bounded at both ends: { x | start <= x < end }. -/// Use `start..end` (two dots) for its shorthand. +/// A (half-open) range bounded inclusively below and exclusively above +/// (`start..end`). /// -/// See the [`contains`](#method.contains) method for its characterization. +/// The `Range` `start..end` contains all values with `x >= start` and +/// `x < end`. /// /// # Examples /// /// ``` -/// fn main() { -/// assert_eq!((3..5), std::ops::Range{ start: 3, end: 5 }); -/// assert_eq!(3+4+5, (3..6).sum()); +/// assert_eq!((3..5), std::ops::Range { start: 3, end: 5 }); +/// 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 -/// } +/// 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 /// ``` #[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186 #[stable(feature = "rust1", since = "1.0.0")] @@ -91,49 +94,51 @@ impl fmt::Debug for Range { #[unstable(feature = "range_contains", reason = "recently added as per RFC", issue = "32311")] impl> Range { + /// Returns `true` if `item` is contained in the range. + /// /// # Examples /// /// ``` /// #![feature(range_contains)] - /// fn main() { - /// assert!( ! (3..5).contains(2)); - /// assert!( (3..5).contains(3)); - /// assert!( (3..5).contains(4)); - /// assert!( ! (3..5).contains(5)); /// - /// assert!( ! (3..3).contains(3)); - /// assert!( ! (3..2).contains(3)); - /// } + /// # fn main() { + /// assert!(!(3..5).contains(2)); + /// assert!( (3..5).contains(3)); + /// assert!( (3..5).contains(4)); + /// assert!(!(3..5).contains(5)); + /// + /// assert!(!(3..3).contains(3)); + /// assert!(!(3..2).contains(3)); + /// # } /// ``` pub fn contains(&self, item: Idx) -> bool { (self.start <= item) && (item < self.end) } } -/// A range which is only bounded below: { x | start <= x }. -/// Use `start..` for its shorthand. +/// A range only bounded inclusively below (`start..`). /// -/// See the [`contains`](#method.contains) method for its characterization. +/// The `RangeFrom` `start..` contains all values with `x >= start`. /// -/// Note: Currently, no overflow checking is done for the iterator +/// *Note*: Currently, no overflow checking is done for the [`Iterator`] /// implementation; if you use an integer range and the integer overflows, it -/// might panic in debug mode or create an endless loop in release mode. This -/// overflow behavior might change in the future. +/// might panic in debug mode or create an endless loop in release mode. **This +/// overflow behavior might change in the future.** /// /// # Examples /// /// ``` -/// fn main() { -/// assert_eq!((2..), std::ops::RangeFrom{ start: 2 }); -/// assert_eq!(2+3+4, (2..).take(3).sum()); +/// assert_eq!((2..), std::ops::RangeFrom { start: 2 }); +/// 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 ]); -/// } +/// 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 ]); /// ``` +/// +/// [`Iterator`]: ../iter/trait.IntoIterator.html #[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186 #[stable(feature = "rust1", since = "1.0.0")] pub struct RangeFrom { @@ -151,38 +156,39 @@ impl fmt::Debug for RangeFrom { #[unstable(feature = "range_contains", reason = "recently added as per RFC", issue = "32311")] impl> RangeFrom { + /// Returns `true` if `item` is contained in the range. + /// /// # Examples /// /// ``` /// #![feature(range_contains)] - /// fn main() { - /// assert!( ! (3..).contains(2)); - /// assert!( (3..).contains(3)); - /// assert!( (3..).contains(1_000_000_000)); - /// } + /// + /// # fn main() { + /// assert!(!(3..).contains(2)); + /// assert!( (3..).contains(3)); + /// assert!( (3..).contains(1_000_000_000)); + /// # } /// ``` pub fn contains(&self, item: Idx) -> bool { (self.start <= item) } } -/// A range which is only bounded above: { x | x < end }. -/// Use `..end` (two dots) for its shorthand. +/// A range only bounded exclusively above (`..end`). /// -/// See the [`contains`](#method.contains) method for its characterization. -/// -/// It cannot serve as an iterator because it doesn't have a starting point. +/// The `RangeTo` `..end` contains all values with `x < end`. +/// It cannot serve as an [`Iterator`] because it doesn't have a starting point. /// /// # Examples /// -/// The `..{integer}` syntax is a `RangeTo`: +/// The `..end` syntax is a `RangeTo`: /// /// ``` -/// assert_eq!((..5), std::ops::RangeTo{ end: 5 }); +/// assert_eq!((..5), std::ops::RangeTo { end: 5 }); /// ``` /// -/// It does not have an `IntoIterator` implementation, so you can't use it in a -/// `for` loop directly. This won't compile: +/// It does not have an [`IntoIterator`] implementation, so you can't use it in +/// a `for` loop directly. This won't compile: /// /// ```compile_fail,E0277 /// for i in ..5 { @@ -190,7 +196,7 @@ impl> RangeFrom { /// } /// ``` /// -/// When used as a slicing index, `RangeTo` produces a slice of all array +/// When used as a [slicing index], `RangeTo` produces a slice of all array /// elements before the index indicated by `end`. /// /// ``` @@ -200,6 +206,10 @@ impl> RangeFrom { /// assert_eq!(arr[1.. ], [ 1,2,3]); /// assert_eq!(arr[1..3], [ 1,2 ]); /// ``` +/// +/// [`IntoIterator`]: ../iter/trait.Iterator.html +/// [`Iterator`]: ../iter/trait.IntoIterator.html +/// [slicing index]: ../slice/trait.SliceIndex.html #[derive(Copy, Clone, PartialEq, Eq, Hash)] #[stable(feature = "rust1", since = "1.0.0")] pub struct RangeTo { @@ -217,38 +227,42 @@ impl fmt::Debug for RangeTo { #[unstable(feature = "range_contains", reason = "recently added as per RFC", issue = "32311")] impl> RangeTo { + /// Returns `true` if `item` is contained in the range. + /// /// # Examples /// /// ``` /// #![feature(range_contains)] - /// fn main() { - /// assert!( (..5).contains(-1_000_000_000)); - /// assert!( (..5).contains(4)); - /// assert!( ! (..5).contains(5)); - /// } + /// + /// # fn main() { + /// assert!( (..5).contains(-1_000_000_000)); + /// assert!( (..5).contains(4)); + /// assert!(!(..5).contains(5)); + /// # } /// ``` pub fn contains(&self, item: Idx) -> bool { (item < self.end) } } -/// An inclusive range which is bounded at both ends: { x | start <= x <= end }. -/// Use `start...end` (three dots) for its shorthand. +/// An range bounded inclusively below and above (`start...end`). /// -/// See the [`contains`](#method.contains) method for its characterization. +/// The `RangeInclusive` `start...end` contains all values with `x >= start` +/// and `x <= end`. /// /// # Examples /// /// ``` /// #![feature(inclusive_range,inclusive_range_syntax)] -/// fn main() { -/// assert_eq!((3...5), std::ops::RangeInclusive{ start: 3, end: 5 }); -/// 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 -/// } +/// # fn main() { +/// assert_eq!((3...5), std::ops::RangeInclusive { start: 3, end: 5 }); +/// 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 +/// # } /// ``` #[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186 #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")] @@ -274,43 +288,44 @@ impl fmt::Debug for RangeInclusive { #[unstable(feature = "range_contains", reason = "recently added as per RFC", issue = "32311")] impl> RangeInclusive { + /// Returns `true` if `item` is contained in the range. + /// /// # Examples /// /// ``` /// #![feature(range_contains,inclusive_range_syntax)] - /// fn main() { - /// assert!( ! (3...5).contains(2)); - /// assert!( (3...5).contains(3)); - /// assert!( (3...5).contains(4)); - /// assert!( (3...5).contains(5)); - /// assert!( ! (3...5).contains(6)); /// - /// assert!( (3...3).contains(3)); - /// assert!( ! (3...2).contains(3)); - /// } + /// # fn main() { + /// assert!(!(3...5).contains(2)); + /// assert!( (3...5).contains(3)); + /// assert!( (3...5).contains(4)); + /// assert!( (3...5).contains(5)); + /// assert!(!(3...5).contains(6)); + /// + /// assert!( (3...3).contains(3)); + /// assert!(!(3...2).contains(3)); + /// # } /// ``` pub fn contains(&self, item: Idx) -> bool { self.start <= item && item <= self.end } } -/// An inclusive range which is only bounded above: { x | x <= end }. -/// Use `...end` (three dots) for its shorthand. +/// A range only bounded inclusively above (`...end`). /// -/// See the [`contains`](#method.contains) method for its characterization. -/// -/// It cannot serve as an iterator because it doesn't have a starting point. +/// The `RangeToInclusive` `...end` contains all values with `x <= end`. +/// It cannot serve as an [`Iterator`] because it doesn't have a starting point. /// /// # Examples /// -/// The `...{integer}` syntax is a `RangeToInclusive`: +/// The `...end` syntax is a `RangeToInclusive`: /// /// ``` /// #![feature(inclusive_range,inclusive_range_syntax)] /// assert_eq!((...5), std::ops::RangeToInclusive{ end: 5 }); /// ``` /// -/// It does not have an `IntoIterator` implementation, so you can't use it in a +/// It does not have an [`IntoIterator`] implementation, so you can't use it in a /// `for` loop directly. This won't compile: /// /// ```compile_fail,E0277 @@ -320,15 +335,22 @@ impl> RangeInclusive { /// } /// ``` /// -/// When used as a slicing index, `RangeToInclusive` produces a slice of all +/// When used as a [slicing index], `RangeToInclusive` produces a slice of all /// array elements up to and including the index indicated by `end`. /// /// ``` /// #![feature(inclusive_range_syntax)] +/// +/// # fn main() { /// let arr = [0, 1, 2, 3]; /// assert_eq!(arr[ ...2], [0,1,2 ]); // RangeToInclusive /// assert_eq!(arr[1...2], [ 1,2 ]); +/// # } /// ``` +/// +/// [`IntoIterator`]: ../iter/trait.Iterator.html +/// [`Iterator`]: ../iter/trait.IntoIterator.html +/// [slicing index]: ../slice/trait.SliceIndex.html #[derive(Copy, Clone, PartialEq, Eq, Hash)] #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")] pub struct RangeToInclusive { @@ -348,15 +370,18 @@ impl fmt::Debug for RangeToInclusive { #[unstable(feature = "range_contains", reason = "recently added as per RFC", issue = "32311")] impl> RangeToInclusive { + /// Returns `true` if `item` is contained in the range. + /// /// # Examples /// /// ``` /// #![feature(range_contains,inclusive_range_syntax)] - /// fn main() { - /// assert!( (...5).contains(-1_000_000_000)); - /// assert!( (...5).contains(5)); - /// assert!( ! (...5).contains(6)); - /// } + /// + /// # fn main() { + /// assert!( (...5).contains(-1_000_000_000)); + /// assert!( (...5).contains(5)); + /// assert!(!(...5).contains(6)); + /// # } /// ``` pub fn contains(&self, item: Idx) -> bool { (item <= self.end)