New API: Range::cmp_scalar; comparison (less/equal/greater) to a primitive of the Range

library/core/src/lib.rs

@@ -163,6 +163,7 @@
 #![feature(const_slice_index)]
 #![feature(const_is_char_boundary)]
 #![feature(const_cstr_methods)]
+#![feature(range_cmp_scalar)]
 //
 // Language features:
 #![feature(abi_unadjusted)]

library/core/src/ops/range.rs

@@ -145,6 +145,62 @@ impl<Idx: PartialOrd<Idx>> Range<Idx> {
     pub fn is_empty(&self) -> bool {
         !(self.start < self.end)
     }
+
+    /// Compares the range to a scalar. Returns `Some(Ordering::Equal)`,
+    /// if the range contains the scalar. If not, returns `Some(Ordering::Less)`
+    /// or `Some(Ordering::Greater)`, depending on whether the range is
+    /// below or above the scalar. Returns `None` if the values are
+    /// uncomparable (for example, NaN) or if the range is degenerate
+    /// (i.e. end < start).
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// #![feature(range_cmp_scalar)]
+    /// # use core::cmp::Ordering;
+    /// assert_eq!((1..10).cmp_scalar(-1234), Some(Ordering::Greater));
+    /// assert_eq!((1..10).cmp_scalar(0), Some(Ordering::Greater));
+    /// assert_eq!((1..10).cmp_scalar(1), Some(Ordering::Equal));
+    /// assert_eq!((1..10).cmp_scalar(5), Some(Ordering::Equal));
+    /// assert_eq!((1..10).cmp_scalar(9), Some(Ordering::Equal));
+    /// assert_eq!((1..10).cmp_scalar(10), Some(Ordering::Less));
+    /// assert_eq!((1..10).cmp_scalar(1234), Some(Ordering::Less));
+    /// assert_eq!((20..10).cmp_scalar(15), None);
+    /// assert_eq!((f32::NAN..f32::NAN).cmp_scalar(10.0), None);
+    /// ```
+    ///
+    /// ```rust
+    /// #![feature(range_cmp_scalar)]
+    /// # fn main() -> Result<(), usize> {
+    /// # struct File {
+    /// #    seqnum: u32,
+    /// #    range: core::ops::Range<usize>,
+    /// # }
+    /// let files = vec![
+    ///     File { seqnum: 0, range: 0..1000 },
+    ///     File { seqnum: 1, range: 1000..2200 },
+    ///     File { seqnum: 2, range: 2200..3900 },
+    ///     File { seqnum: 3, range: 3900..5000 },
+    /// ];
+    /// let target = 1600;
+    /// let index = files.binary_search_by(|f| f.range.cmp_scalar(target).unwrap())?;
+    /// assert_eq!(files[index].seqnum, 1);
+    /// # Ok(()) }
+    /// ```
+    #[unstable(feature = "range_cmp_scalar", issue = "none")]
+    pub fn cmp_scalar(&self, scalar: Idx) -> Option<core::cmp::Ordering> {
+        if self.end < self.start {
+            None
+        } else if self.end <= scalar {
+            Some(core::cmp::Ordering::Less)
+        } else if scalar < self.start {
+            Some(core::cmp::Ordering::Greater)
+        } else if self.start <= scalar && scalar < self.end {
+            Some(core::cmp::Ordering::Equal)
+        } else {
+            None
+        }
+    }
 }
 
 /// A range only bounded inclusively below (`start..`).
@@ -221,6 +277,31 @@ impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
     {
         <Self as RangeBounds<Idx>>::contains(self, item)
     }
+
+    /// Compares the range to a scalar. Returns `Some(Ordering::Equal)`,
+    /// if the range contains the scalar. If not, the range
+    /// can be only above the scalar, so returns `Some(Ordering::Greater)`.
+    /// Returns `None` if the values are uncomparable (for example, NaN).
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// #![feature(range_cmp_scalar)]
+    /// # use core::cmp::Ordering;
+    /// assert_eq!((100..).cmp_scalar(50), Some(Ordering::Greater));
+    /// assert_eq!((100..).cmp_scalar(100), Some(Ordering::Equal));
+    /// assert_eq!((100..).cmp_scalar(150), Some(Ordering::Equal));
+    /// ```
+    #[unstable(feature = "range_cmp_scalar", issue = "none")]
+    pub fn cmp_scalar(&self, scalar: Idx) -> Option<core::cmp::Ordering> {
+        if scalar < self.start {
+            Some(core::cmp::Ordering::Greater)
+        } else if self.start <= scalar {
+            Some(core::cmp::Ordering::Equal)
+        } else {
+            None
+        }
+    }
 }
 
 /// A range only bounded exclusively above (`..end`).
@@ -302,6 +383,31 @@ impl<Idx: PartialOrd<Idx>> RangeTo<Idx> {
     {
         <Self as RangeBounds<Idx>>::contains(self, item)
     }
+
+    /// Compares the range to a scalar. Returns `Some(Ordering::Equal)`,
+    /// if the range contains the scalar. If not, the range
+    /// can be only below the scalar, so returns `Some(Ordering::Less)`.
+    /// Returns `None` if the values are uncomparable (for example, NaN).
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// #![feature(range_cmp_scalar)]
+    /// # use core::cmp::Ordering;
+    /// assert_eq!((..100).cmp_scalar(50), Some(Ordering::Equal));
+    /// assert_eq!((..100).cmp_scalar(100), Some(Ordering::Less));
+    /// assert_eq!((..100).cmp_scalar(150), Some(Ordering::Less));
+    /// ```
+    #[unstable(feature = "range_cmp_scalar", issue = "none")]
+    pub fn cmp_scalar(&self, scalar: Idx) -> Option<core::cmp::Ordering> {
+        if self.end <= scalar {
+            Some(core::cmp::Ordering::Less)
+        } else if scalar < self.end {
+            Some(core::cmp::Ordering::Equal)
+        } else {
+            None
+        }
+    }
 }
 
 /// A range bounded inclusively below and above (`start..=end`).
@@ -539,6 +645,62 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
     pub fn is_empty(&self) -> bool {
         self.exhausted || !(self.start <= self.end)
     }
+
+    /// Compares the range to a scalar. Returns `Some(Ordering::Equal)`,
+    /// if the range contains the scalar. If not, returns `Some(Ordering::Less)`
+    /// or `Some(Ordering::Greater)`, depending on whether the range is
+    /// below or above the scalar. Returns `None` if the values are
+    /// uncomparable (for example, NaN) or if the range is degenerate
+    /// (i.e. end < start).
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// #![feature(range_cmp_scalar)]
+    /// # use core::cmp::Ordering;
+    /// assert_eq!((1..=10).cmp_scalar(-1234), Some(Ordering::Greater));
+    /// assert_eq!((1..=10).cmp_scalar(0), Some(Ordering::Greater));
+    /// assert_eq!((1..=10).cmp_scalar(1), Some(Ordering::Equal));
+    /// assert_eq!((1..=10).cmp_scalar(5), Some(Ordering::Equal));
+    /// assert_eq!((1..=10).cmp_scalar(9), Some(Ordering::Equal));
+    /// assert_eq!((1..=10).cmp_scalar(10), Some(Ordering::Equal));
+    /// assert_eq!((1..=10).cmp_scalar(1234), Some(Ordering::Less));
+    /// assert_eq!((20..=10).cmp_scalar(15), None);
+    /// assert_eq!((f32::NAN..=f32::NAN).cmp_scalar(10.0), None);
+    /// ```
+    ///
+    /// ```rust
+    /// #![feature(range_cmp_scalar)]
+    /// # fn main() -> Result<(), usize> {
+    /// # struct File {
+    /// #    seqnum: u32,
+    /// #    range: core::ops::RangeInclusive<usize>,
+    /// # }
+    /// let files = vec![
+    ///     File { seqnum: 0, range: 0..=999 },
+    ///     File { seqnum: 1, range: 1000..=2199 },
+    ///     File { seqnum: 2, range: 2200..=3899 },
+    ///     File { seqnum: 3, range: 3900..=4999 },
+    /// ];
+    /// let target = 1600;
+    /// let index = files.binary_search_by(|f| f.range.cmp_scalar(target).unwrap())?;
+    /// assert_eq!(files[index].seqnum, 1);
+    /// # Ok(()) }
+    /// ```
+    #[unstable(feature = "range_cmp_scalar", issue = "none")]
+    pub fn cmp_scalar(&self, scalar: Idx) -> Option<core::cmp::Ordering> {
+        if *self.end() < *self.start() {
+            None
+        } else if *self.end() < scalar {
+            Some(core::cmp::Ordering::Less)
+        } else if scalar < *self.start() {
+            Some(core::cmp::Ordering::Greater)
+        } else if *self.start() <= scalar && scalar <= *self.end() {
+            Some(core::cmp::Ordering::Equal)
+        } else {
+            None
+        }
+    }
 }
 
 /// A range only bounded inclusively above (`..=end`).
@@ -620,6 +782,31 @@ impl<Idx: PartialOrd<Idx>> RangeToInclusive<Idx> {
     {
         <Self as RangeBounds<Idx>>::contains(self, item)
     }
+
+    /// Compares the range to a scalar. Returns `Some(Ordering::Equal)`,
+    /// if the range contains the scalar. If not, the range
+    /// can be only below the scalar, so returns `Some(Ordering::Less)`.
+    /// Returns `None` if the values are uncomparable (for example, NaN).
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// #![feature(range_cmp_scalar)]
+    /// # use core::cmp::Ordering;
+    /// assert_eq!((..=100).cmp_scalar(50), Some(Ordering::Equal));
+    /// assert_eq!((..=100).cmp_scalar(100), Some(Ordering::Equal));
+    /// assert_eq!((..=100).cmp_scalar(150), Some(Ordering::Less));
+    /// ```
+    #[unstable(feature = "range_cmp_scalar", issue = "none")]
+    pub fn cmp_scalar(&self, scalar: Idx) -> Option<core::cmp::Ordering> {
+        if self.end < scalar {
+            Some(core::cmp::Ordering::Less)
+        } else if scalar <= self.end {
+            Some(core::cmp::Ordering::Equal)
+        } else {
+            None
+        }
+    }
 }
 
 // RangeToInclusive<Idx> cannot impl From<RangeTo<Idx>>

library/core/tests/lib.rs

@@ -101,6 +101,7 @@
 #![feature(slice_flatten)]
 #![feature(provide_any)]
 #![feature(utf8_chunks)]
+#![feature(range_cmp_scalar)]
 #![deny(unsafe_op_in_unsafe_fn)]
 
 extern crate test;