Rollup merge of rust-lang#150075 - Kyuuhachi:limit_to, r=ChrisDenton

Implement clamp_to

Implements the revised version of rust-lang#147781. Supersedes rust-lang#147786.

Currently I restrict the ClampBounds trait using a second, perma-unstable feature. I don't know if that's the usual way to deal with this kind of traits, I'd be happy to change it if not.

~~I currently define NaN as equal to no bound. This is consistent with `max` and `min`, but is inconsistent with `clamp`, which panics.~~

Changed so that the float versions panic if any bound is NaN, just like `clamp` does.

Author: JonathanBrouwer

library/core/src/cmp.rs

@@ -26,7 +26,10 @@
 #![stable(feature = "rust1", since = "1.0.0")]
 
 mod bytewise;
+mod clamp;
 pub(crate) use bytewise::BytewiseEq;
+#[unstable(feature = "clamp_bounds", issue = "147781")]
+pub use clamp::ClampBounds;
 
 use self::Ordering::*;
 use crate::marker::{Destruct, PointeeSized};
@@ -1169,6 +1172,35 @@ pub const trait Ord: [const] Eq + [const] PartialOrd<Self> + PointeeSized {
             self
         }
     }
+
+    /// Restrict a value to a certain range.
+    ///
+    /// This is equal to `max`, `min`, or `clamp`, depending on whether the range is `min..`,
+    /// `..=max`, or `min..=max`, respectively. Exclusive ranges are not permitted.
+    ///
+    /// # Panics
+    ///
+    /// Panics on `min..=max` if `min > max`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(clamp_to)]
+    /// assert_eq!((-3).clamp_to(-2..=1), -2);
+    /// assert_eq!(0.clamp_to(-2..=1), 0);
+    /// assert_eq!(2.clamp_to(..=1), 1);
+    /// assert_eq!(5.clamp_to(7..), 7);
+    /// ```
+    #[must_use]
+    #[inline]
+    #[unstable(feature = "clamp_to", issue = "147781")]
+    fn clamp_to<R>(self, range: R) -> Self
+    where
+        Self: Sized + [const] Destruct,
+        R: [const] ClampBounds<Self>,
+    {
+        range.clamp(self)
+    }
 }
 
 /// Derive macro generating an impl of the trait [`Ord`].

library/core/src/cmp/clamp.rs

@@ -0,0 +1,104 @@
+use crate::marker::Destruct;
+use crate::ops::{RangeFrom, RangeFull, RangeInclusive, RangeToInclusive};
+
+/// Trait for ranges supported by [`Ord::clamp_to`].
+#[unstable(feature = "clamp_bounds", issue = "147781")]
+#[rustc_const_unstable(feature = "clamp_bounds", issue = "147781")]
+pub const trait ClampBounds<T>: Sized {
+    /// The implementation of [`Ord::clamp_to`].
+    fn clamp(self, value: T) -> T
+    where
+        T: [const] Destruct;
+}
+
+#[unstable(feature = "clamp_bounds", issue = "147781")]
+#[rustc_const_unstable(feature = "clamp_bounds", issue = "147781")]
+const impl<T> ClampBounds<T> for RangeFrom<T>
+where
+    T: [const] Ord,
+{
+    fn clamp(self, value: T) -> T
+    where
+        T: [const] Destruct,
+    {
+        value.max(self.start)
+    }
+}
+
+#[unstable(feature = "clamp_bounds", issue = "147781")]
+#[rustc_const_unstable(feature = "clamp_bounds", issue = "147781")]
+const impl<T> ClampBounds<T> for RangeToInclusive<T>
+where
+    T: [const] Ord,
+{
+    fn clamp(self, value: T) -> T
+    where
+        T: [const] Destruct,
+    {
+        value.min(self.end)
+    }
+}
+
+#[unstable(feature = "clamp_bounds", issue = "147781")]
+#[rustc_const_unstable(feature = "clamp_bounds", issue = "147781")]
+const impl<T> ClampBounds<T> for RangeInclusive<T>
+where
+    T: [const] Ord,
+{
+    fn clamp(self, value: T) -> T
+    where
+        T: [const] Destruct,
+    {
+        let (start, end) = self.into_inner();
+        value.clamp(start, end)
+    }
+}
+
+#[unstable(feature = "clamp_bounds", issue = "147781")]
+#[rustc_const_unstable(feature = "clamp_bounds", issue = "147781")]
+const impl<T> ClampBounds<T> for RangeFull {
+    fn clamp(self, value: T) -> T {
+        value
+    }
+}
+
+macro impl_for_float($t:ty) {
+    #[unstable(feature = "clamp_bounds", issue = "147781")]
+    #[rustc_const_unstable(feature = "clamp_bounds", issue = "147781")]
+    const impl ClampBounds<$t> for RangeFrom<$t> {
+        fn clamp(self, value: $t) -> $t {
+            assert!(!self.start.is_nan(), "start was NaN");
+            value.max(self.start)
+        }
+    }
+
+    #[unstable(feature = "clamp_bounds", issue = "147781")]
+    #[rustc_const_unstable(feature = "clamp_bounds", issue = "147781")]
+    const impl ClampBounds<$t> for RangeToInclusive<$t> {
+        fn clamp(self, value: $t) -> $t {
+            assert!(!self.end.is_nan(), "end was NaN");
+            value.min(self.end)
+        }
+    }
+
+    #[unstable(feature = "clamp_bounds", issue = "147781")]
+    #[rustc_const_unstable(feature = "clamp_bounds", issue = "147781")]
+    const impl ClampBounds<$t> for RangeInclusive<$t> {
+        #[expect(
+            clippy::neg_cmp_op_on_partial_ord,
+            reason = "NaN check is intentionally included in comparison"
+        )]
+        fn clamp(self, value: $t) -> $t {
+            let (start, end) = self.into_inner();
+            assert!(start <= end, "start > end, or either was NaN");
+            value.clamp(start, end)
+        }
+    }
+}
+
+// #[unstable(feature = "f16", issue = "116909")]
+impl_for_float!(f16);
+impl_for_float!(f32);
+impl_for_float!(f64);
+// #[unstable(feature = "f128", issue = "116909")]
+impl_for_float!(f128);

library/core/src/num/f128.rs

@@ -1483,7 +1483,7 @@ impl f128 {
     ///
     /// ```
     /// #![feature(f128)]
-    /// # #[cfg(target_has_reliable_f128)] {
+    /// # #[cfg(target_has_reliable_f128_math)] {
     ///
     /// assert!((-3.0f128).clamp(-2.0, 1.0) == -2.0);
     /// assert!((0.0f128).clamp(-2.0, 1.0) == 0.0);
@@ -1552,6 +1552,43 @@ impl f128 {
         self.clamp(-limit, limit)
     }
 
+    /// Restrict a value to a certain range, unless it is NaN.
+    ///
+    /// This is largely equal to `max`, `min`, or `clamp`, depending on whether the range is
+    /// `min..`, `..=max`, or `min..=max`, respectively. However, unlike `max` and `min`, it will
+    /// panic if any bound is NaN.
+    ///
+    /// Note that this function returns NaN if the initial value was NaN as
+    /// well.
+    ///
+    /// Exclusive ranges are not permitted.
+    ///
+    /// # Panics
+    ///
+    /// Panics on `min..=max` if `min > max`, or if any bound is NaN.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(f128, clamp_to)]
+    /// # #[cfg(target_has_reliable_f128_math)] {
+    /// assert_eq!((-3.0f128).clamp_to(-2.0..=1.0), -2.0);
+    /// assert_eq!(0.0f128.clamp_to(-2.0..=1.0), 0.0);
+    /// assert_eq!(2.0f128.clamp_to(..=1.0), 1.0);
+    /// assert_eq!(5.0f128.clamp_to(7.0..), 7.0);
+    /// assert!(f128::NAN.clamp_to(1.0..=2.0).is_nan());
+    /// # }
+    /// ```
+    #[must_use]
+    #[inline]
+    #[unstable(feature = "clamp_to", issue = "147781")]
+    pub fn clamp_to<R>(self, range: R) -> Self
+    where
+        R: crate::cmp::ClampBounds<Self>,
+    {
+        range.clamp(self)
+    }
+
     /// Computes the absolute value of `self`.
     ///
     /// This function always returns the precise result.

library/core/src/num/f16.rs

@@ -1469,7 +1469,7 @@ impl f16 {
     ///
     /// ```
     /// #![feature(f16)]
-    /// # #[cfg(target_has_reliable_f16)] {
+    /// # #[cfg(target_has_reliable_f16_math)] {
     ///
     /// assert!((-3.0f16).clamp(-2.0, 1.0) == -2.0);
     /// assert!((0.0f16).clamp(-2.0, 1.0) == 0.0);
@@ -1538,6 +1538,43 @@ impl f16 {
         self.clamp(-limit, limit)
     }
 
+    /// Restrict a value to a certain range, unless it is NaN.
+    ///
+    /// This is largely equal to `max`, `min`, or `clamp`, depending on whether the range is
+    /// `min..`, `..=max`, or `min..=max`, respectively. However, unlike `max` and `min`, it will
+    /// panic if any bound is NaN.
+    ///
+    /// Note that this function returns NaN if the initial value was NaN as
+    /// well.
+    ///
+    /// Exclusive ranges are not permitted.
+    ///
+    /// # Panics
+    ///
+    /// Panics on `min..=max` if `min > max`, or if any bound is NaN.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(f16, clamp_to)]
+    /// # #[cfg(target_has_reliable_f16_math)] {
+    /// assert_eq!((-3.0f16).clamp_to(-2.0..=1.0), -2.0);
+    /// assert_eq!(0.0f16.clamp_to(-2.0..=1.0), 0.0);
+    /// assert_eq!(2.0f16.clamp_to(..=1.0), 1.0);
+    /// assert_eq!(5.0f16.clamp_to(7.0..), 7.0);
+    /// assert!(f16::NAN.clamp_to(1.0..=2.0).is_nan());
+    /// # }
+    /// ```
+    #[must_use]
+    #[inline]
+    #[unstable(feature = "clamp_to", issue = "147781")]
+    pub fn clamp_to<R>(self, range: R) -> Self
+    where
+        R: crate::cmp::ClampBounds<Self>,
+    {
+        range.clamp(self)
+    }
+
     /// Computes the absolute value of `self`.
     ///
     /// This function always returns the precise result.

library/core/src/num/f32.rs

@@ -1709,6 +1709,41 @@ impl f32 {
         self.clamp(-limit, limit)
     }
 
+    /// Restrict a value to a certain range, unless it is NaN.
+    ///
+    /// This is largely equal to `max`, `min`, or `clamp`, depending on whether the range is
+    /// `min..`, `..=max`, or `min..=max`, respectively. However, unlike `max` and `min`, it will
+    /// panic if any bound is NaN.
+    ///
+    /// Note that this function returns NaN if the initial value was NaN as
+    /// well.
+    ///
+    /// Exclusive ranges are not permitted.
+    ///
+    /// # Panics
+    ///
+    /// Panics on `min..=max` if `min > max`, or if any bound is NaN.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(clamp_to)]
+    /// assert_eq!((-3.0f32).clamp_to(-2.0..=1.0), -2.0);
+    /// assert_eq!(0.0f32.clamp_to(-2.0..=1.0), 0.0);
+    /// assert_eq!(2.0f32.clamp_to(..=1.0), 1.0);
+    /// assert_eq!(5.0f32.clamp_to(7.0..), 7.0);
+    /// assert!(f32::NAN.clamp_to(1.0..=2.0).is_nan());
+    /// ```
+    #[must_use]
+    #[inline]
+    #[unstable(feature = "clamp_to", issue = "147781")]
+    pub fn clamp_to<R>(self, range: R) -> Self
+    where
+        R: crate::cmp::ClampBounds<Self>,
+    {
+        range.clamp(self)
+    }
+
     /// Computes the absolute value of `self`.
     ///
     /// This function always returns the precise result.

library/core/src/num/f64.rs

@@ -1687,6 +1687,41 @@ impl f64 {
         self.clamp(-limit, limit)
     }
 
+    /// Restrict a value to a certain range, unless it is NaN.
+    ///
+    /// This is largely equal to `max`, `min`, or `clamp`, depending on whether the range is
+    /// `min..`, `..=max`, or `min..=max`, respectively. However, unlike `max` and `min`, it will
+    /// panic if any bound is NaN.
+    ///
+    /// Note that this function returns NaN if the initial value was NaN as
+    /// well.
+    ///
+    /// Exclusive ranges are not permitted.
+    ///
+    /// # Panics
+    ///
+    /// Panics on `min..=max` if `min > max`, or if any bound is NaN.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(clamp_to)]
+    /// assert_eq!((-3.0f64).clamp_to(-2.0..=1.0), -2.0);
+    /// assert_eq!(0.0f64.clamp_to(-2.0..=1.0), 0.0);
+    /// assert_eq!(2.0f64.clamp_to(..=1.0), 1.0);
+    /// assert_eq!(5.0f64.clamp_to(7.0..), 7.0);
+    /// assert!(f64::NAN.clamp_to(1.0..=2.0).is_nan());
+    /// ```
+    #[must_use]
+    #[inline]
+    #[unstable(feature = "clamp_to", issue = "147781")]
+    pub fn clamp_to<R>(self, range: R) -> Self
+    where
+        R: crate::cmp::ClampBounds<Self>,
+    {
+        range.clamp(self)
+    }
+
     /// Computes the absolute value of `self`.
     ///
     /// This function always returns the precise result.

library/coretests/tests/lib.rs

@@ -14,6 +14,7 @@
 #![feature(cfg_overflow_checks)]
 #![feature(cfg_target_has_reliable_f16_f128)]
 #![feature(char_internals)]
+#![feature(clamp_to)]
 #![feature(clone_to_uninit)]
 #![feature(cmp_minmax)]
 #![feature(cmp_splat)]