Rollup merge of rust-lang#147786 - Kyuuhachi:clamp-min-max, r=joboet

Implement clamp_min and clamp_max

Implements rust-lang#147781.

Author: Zalathar

library/core/src/cmp.rs

@@ -1096,6 +1096,54 @@ pub const trait Ord: [const] Eq + [const] PartialOrd<Self> + PointeeSized {
             self
         }
     }
+
+    /// Restricts a value to a maximum bound.
+    ///
+    /// Returns `max` if `self` is greater than `max`, otherwise returns `self`.
+    ///
+    /// This is identical to `min`, but is easier to read when using method call syntax.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(clamp_min_max)]
+    /// assert_eq!(12.clamp_max(10), 10);
+    /// assert_eq!(4.clamp_max(7), 4);
+    /// let s = "hello";
+    /// assert_eq!(&s[..32.clamp_max(s.len())], s);
+    /// ```
+    #[must_use]
+    #[inline]
+    #[unstable(feature = "clamp_min_max", issue = "147781")]
+    fn clamp_max(self, min: Self) -> Self
+    where
+        Self: Sized + [const] Destruct,
+    {
+        self.min(min)
+    }
+
+    /// Restricts a value to a minimum bound.
+    ///
+    /// Returns `min` if `self` is less than `min`, otherwise returns `self`.
+    ///
+    /// This is identical to `max`, but is easier to read when using method call syntax.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(clamp_min_max)]
+    /// assert_eq!((-3).clamp_min(0), 0);
+    /// assert_eq!(4.clamp_min(0), 4);
+    /// ```
+    #[must_use]
+    #[inline]
+    #[unstable(feature = "clamp_min_max", issue = "147781")]
+    fn clamp_min(self, min: Self) -> Self
+    where
+        Self: Sized + [const] Destruct,
+    {
+        self.max(min)
+    }
 }
 
 /// Derive macro generating an impl of the trait [`Ord`].

library/core/src/num/f128.rs

@@ -1276,6 +1276,54 @@ impl f128 {
         self
     }
 
+    /// Restrict a value to a maximum bound.
+    ///
+    /// Returns `max` if `self` is greater than `max`. Otherwise this returns `self`. If either `self` or `max` is NaN, the other is returned.
+    ///
+    /// This is identical to [`f128::min`], but is easier to read when using method call syntax.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(f128, clamp_min_max)]
+    /// assert_eq!((3.0f128).clamp_max(1.0), 1.0);
+    /// assert_eq!((0.0f128).clamp_max(1.0), 0.0);
+    /// assert_eq!((f128::NAN).clamp_max(1.0), 1.0);
+    /// assert_eq!((0.0f128).clamp_max(f128::NAN), 0.0);
+    /// ```
+    #[inline]
+    #[unstable(feature = "f128", issue = "116909")]
+    // #[unstable(feature = "clamp_min_max", issue = "147781")]
+    #[rustc_const_unstable(feature = "f128", issue = "116909")]
+    #[must_use = "method returns a new number and does not mutate the original value"]
+    pub const fn clamp_max(self, max: f128) -> f128 {
+        self.min(max)
+    }
+
+    /// Restrict a value to a minimum bound.
+    ///
+    /// Returns `min` if `self` is less than `min`. Otherwise this returns `self`. If either `self` or `min` is NaN, the other is returned.
+    ///
+    /// This is identical to [`f128::max`], but is easier to read when using method call syntax.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(f128, clamp_min_max)]
+    /// assert_eq!((-3.0f128).clamp_min(-2.0), -2.0);
+    /// assert_eq!((0.0f128).clamp_min(-2.0), 0.0);
+    /// assert_eq!((f128::NAN).clamp_min(-2.0), -2.0);
+    /// assert_eq!((0.0f128).clamp_min(f128::NAN), 0.0);
+    /// ```
+    #[inline]
+    #[unstable(feature = "f128", issue = "116909")]
+    // #[unstable(feature = "clamp_min_max", issue = "147781")]
+    #[rustc_const_unstable(feature = "f128", issue = "116909")]
+    #[must_use = "method returns a new number and does not mutate the original value"]
+    pub const fn clamp_min(self, min: f128) -> f128 {
+        self.max(min)
+    }
+
     /// Computes the absolute value of `self`.
     ///
     /// This function always returns the precise result.

library/core/src/num/f16.rs

@@ -1254,6 +1254,54 @@ impl f16 {
         self
     }
 
+    /// Restrict a value to a maximum bound.
+    ///
+    /// Returns `max` if `self` is greater than `max`. Otherwise this returns `self`. If either `self` or `max` is NaN, the other is returned.
+    ///
+    /// This is identical to [`f16::min`], but is easier to read when using method call syntax.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(f16, clamp_min_max)]
+    /// assert_eq!((3.0f16).clamp_max(1.0), 1.0);
+    /// assert_eq!((0.0f16).clamp_max(1.0), 0.0);
+    /// assert_eq!((f16::NAN).clamp_max(1.0), 1.0);
+    /// assert_eq!((0.0f16).clamp_max(f16::NAN), 0.0);
+    /// ```
+    #[inline]
+    #[unstable(feature = "f16", issue = "116909")]
+    // #[unstable(feature = "clamp_min_max", issue = "147781")]
+    #[rustc_const_unstable(feature = "f16", issue = "116909")]
+    #[must_use = "method returns a new number and does not mutate the original value"]
+    pub const fn clamp_max(self, max: f16) -> f16 {
+        self.min(max)
+    }
+
+    /// Restrict a value to a minimum bound.
+    ///
+    /// Returns `min` if `self` is less than `min`. Otherwise this returns `self`. If either `self` or `min` is NaN, the other is returned.
+    ///
+    /// This is identical to [`f16::max`], but is easier to read when using method call syntax.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(f16, clamp_min_max)]
+    /// assert_eq!((-3.0f16).clamp_min(-2.0), -2.0);
+    /// assert_eq!((0.0f16).clamp_min(-2.0), 0.0);
+    /// assert_eq!((f16::NAN).clamp_min(-2.0), -2.0);
+    /// assert_eq!((0.0f16).clamp_min(f16::NAN), 0.0);
+    /// ```
+    #[inline]
+    #[unstable(feature = "f16", issue = "116909")]
+    // #[unstable(feature = "clamp_min_max", issue = "147781")]
+    #[rustc_const_unstable(feature = "f16", issue = "116909")]
+    #[must_use = "method returns a new number and does not mutate the original value"]
+    pub const fn clamp_min(self, min: f16) -> f16 {
+        self.max(min)
+    }
+
     /// Computes the absolute value of `self`.
     ///
     /// This function always returns the precise result.

library/core/src/num/f32.rs

@@ -1431,6 +1431,50 @@ impl f32 {
         self
     }
 
+    /// Restrict a value to a maximum bound.
+    ///
+    /// Returns `max` if `self` is greater than `max`. Otherwise this returns `self`. If either `self` or `max` is NaN, the other is returned.
+    ///
+    /// This is identical to [`f32::min`], but is easier to read when using method call syntax.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(clamp_min_max)]
+    /// assert_eq!((3.0f32).clamp_max(1.0), 1.0);
+    /// assert_eq!((0.0f32).clamp_max(1.0), 0.0);
+    /// assert_eq!((f32::NAN).clamp_max(1.0), 1.0);
+    /// assert_eq!((0.0f32).clamp_max(f32::NAN), 0.0);
+    /// ```
+    #[must_use = "method returns a new number and does not mutate the original value"]
+    #[unstable(feature = "clamp_min_max", issue = "147781")]
+    #[inline]
+    pub const fn clamp_max(self, max: f32) -> f32 {
+        self.min(max)
+    }
+
+    /// Restrict a value to a minimum bound.
+    ///
+    /// Returns `min` if `self` is less than `min`. Otherwise this returns `self`. If either `self` or `min` is NaN, the other is returned.
+    ///
+    /// This is identical to [`f32::max`], but is easier to read when using method call syntax.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(clamp_min_max)]
+    /// assert_eq!((-3.0f32).clamp_min(-2.0), -2.0);
+    /// assert_eq!((0.0f32).clamp_min(-2.0), 0.0);
+    /// assert_eq!((f32::NAN).clamp_min(-2.0), -2.0);
+    /// assert_eq!((0.0f32).clamp_min(f32::NAN), 0.0);
+    /// ```
+    #[must_use = "method returns a new number and does not mutate the original value"]
+    #[unstable(feature = "clamp_min_max", issue = "147781")]
+    #[inline]
+    pub const fn clamp_min(self, min: f32) -> f32 {
+        self.max(min)
+    }
+
     /// Computes the absolute value of `self`.
     ///
     /// This function always returns the precise result.

library/core/src/num/f64.rs

@@ -1429,6 +1429,50 @@ impl f64 {
         self
     }
 
+    /// Restrict a value to a maximum bound.
+    ///
+    /// Returns `max` if `self` is greater than `max`. Otherwise this returns `self`. If either `self` or `max` is NaN, the other is returned.
+    ///
+    /// This is identical to [`f64::min`], but is easier to read when using method call syntax.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(clamp_min_max)]
+    /// assert_eq!((3.0f64).clamp_max(1.0), 1.0);
+    /// assert_eq!((0.0f64).clamp_max(1.0), 0.0);
+    /// assert_eq!((f64::NAN).clamp_max(1.0), 1.0);
+    /// assert_eq!((0.0f64).clamp_max(f64::NAN), 0.0);
+    /// ```
+    #[must_use = "method returns a new number and does not mutate the original value"]
+    #[unstable(feature = "clamp_min_max", issue = "147781")]
+    #[inline]
+    pub const fn clamp_max(self, max: f64) -> f64 {
+        self.min(max)
+    }
+
+    /// Restrict a value to a minimum bound.
+    ///
+    /// Returns `min` if `self` is less than `min`. Otherwise this returns `self`. If either `self` or `min` is NaN, the other is returned.
+    ///
+    /// This is identical to [`f64::max`], but is easier to read when using method call syntax.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(clamp_min_max)]
+    /// assert_eq!((-3.0f64).clamp_min(-2.0), -2.0);
+    /// assert_eq!((0.0f64).clamp_min(-2.0), 0.0);
+    /// assert_eq!((f64::NAN).clamp_min(-2.0), -2.0);
+    /// assert_eq!((0.0f64).clamp_min(f64::NAN), 0.0);
+    /// ```
+    #[must_use = "method returns a new number and does not mutate the original value"]
+    #[unstable(feature = "clamp_min_max", issue = "147781")]
+    #[inline]
+    pub const fn clamp_min(self, min: f64) -> f64 {
+        self.max(min)
+    }
+
     /// Computes the absolute value of `self`.
     ///
     /// This function always returns the precise result.