float::clamp: make current treatment of signed zeros explicit

Author: RalfJung

library/core/src/num/f128.rs

@@ -1236,7 +1236,8 @@ impl f128 {
     /// less than `min`. Otherwise this returns `self`.
     ///
     /// Note that this function returns NaN if the initial value was NaN as
-    /// well.
+    /// well. Furthermore, as usual for floating point comparisons, `-0.0` and `+0.0`
+    /// are considered equal.
     ///
     /// # Panics
     ///
@@ -1253,6 +1254,8 @@ impl f128 {
     /// assert!((0.0f128).clamp(-2.0, 1.0) == 0.0);
     /// assert!((2.0f128).clamp(-2.0, 1.0) == 1.0);
     /// assert!((f128::NAN).clamp(-2.0, 1.0).is_nan());
+    /// // `0.0` is considered to be neither less than nor greater than `-0.0`.
+    /// assert!((0.0f128).clamp(-0.0, -0.0).is_sign_positive());
     /// # }
     /// ```
     #[inline]

library/core/src/num/f16.rs

@@ -1215,7 +1215,8 @@ impl f16 {
     /// less than `min`. Otherwise this returns `self`.
     ///
     /// Note that this function returns NaN if the initial value was NaN as
-    /// well.
+    /// well. Furthermore, as usual for floating point comparisons, `-0.0` and `+0.0`
+    /// are considered equal.
     ///
     /// # Panics
     ///
@@ -1231,6 +1232,8 @@ impl f16 {
     /// assert!((0.0f16).clamp(-2.0, 1.0) == 0.0);
     /// assert!((2.0f16).clamp(-2.0, 1.0) == 1.0);
     /// assert!((f16::NAN).clamp(-2.0, 1.0).is_nan());
+    /// // `0.0` is considered to be neither less than nor greater than `-0.0`.
+    /// assert!((0.0f16).clamp(-0.0, -0.0).is_sign_positive());
     /// # }
     /// ```
     #[inline]

library/core/src/num/f32.rs

@@ -1395,7 +1395,8 @@ impl f32 {
     /// less than `min`. Otherwise this returns `self`.
     ///
     /// Note that this function returns NaN if the initial value was NaN as
-    /// well.
+    /// well. Furthermore, as usual for floating point comparisons, `-0.0` and `+0.0`
+    /// are considered equal.
     ///
     /// # Panics
     ///
@@ -1408,6 +1409,8 @@ impl f32 {
     /// assert!((0.0f32).clamp(-2.0, 1.0) == 0.0);
     /// assert!((2.0f32).clamp(-2.0, 1.0) == 1.0);
     /// assert!((f32::NAN).clamp(-2.0, 1.0).is_nan());
+    /// // `0.0` is considered to be neither less than nor greater than `-0.0`.
+    /// assert!((0.0f32).clamp(-0.0, -0.0).is_sign_positive());
     /// ```
     #[must_use = "method returns a new number and does not mutate the original value"]
     #[stable(feature = "clamp", since = "1.50.0")]

library/core/src/num/f64.rs

@@ -1393,7 +1393,8 @@ impl f64 {
     /// less than `min`. Otherwise this returns `self`.
     ///
     /// Note that this function returns NaN if the initial value was NaN as
-    /// well.
+    /// well. Furthermore, as usual for floating point comparisons, `-0.0` and `+0.0`
+    /// are considered equal.
     ///
     /// # Panics
     ///
@@ -1406,6 +1407,8 @@ impl f64 {
     /// assert!((0.0f64).clamp(-2.0, 1.0) == 0.0);
     /// assert!((2.0f64).clamp(-2.0, 1.0) == 1.0);
     /// assert!((f64::NAN).clamp(-2.0, 1.0).is_nan());
+    /// // `0.0` is considered to be neither less than nor greater than `-0.0`.
+    /// assert!((0.0f64).clamp(-0.0, -0.0).is_sign_positive());
     /// ```
     #[must_use = "method returns a new number and does not mutate the original value"]
     #[stable(feature = "clamp", since = "1.50.0")]