Add round_ties_even to Float and Real

Also add example to `FloatCore::round_ties_even` documentation

Author: bushrat011899

src/float.rs

@@ -798,6 +798,24 @@ pub trait FloatCore: Num + NumCast + Neg<Output = Self> + PartialOrd + Copy {
     fn integer_decode(self) -> (u64, i16, i8);
 
     /// Rounds to the nearest integer, with ties biasing towards an even result.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use num_traits::float::FloatCore;
+    ///
+    /// fn check<T: FloatCore>(x: T, rounded: T) {
+    ///     assert!(x.round_ties_even() == rounded);
+    /// }
+    ///
+    /// check(1.0f32, 1.0);
+    /// check(1.25f32, 1.0);
+    /// check(1.75f32, 2.0);
+    /// check(1.5f32, 2.0);
+    /// check(2.5f32, 2.0);
+    /// check(3.5f32, 4.0);
+    /// check(-3.5f32, -4.0);
+    /// ```
     fn round_ties_even(self) -> Self {
         let half = (Self::one() + Self::one()).recip();
 
@@ -1944,6 +1962,49 @@ pub trait Float: Num + Copy + NumCast + PartialOrd + Neg<Output = Self> {
             self.neg()
         }
     }
+
+    /// Rounds to the nearest integer, with ties biasing towards an even result.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use num_traits::Float;
+    ///
+    /// fn check<T: Float>(x: T, rounded: T) {
+    ///     assert!(x.round_ties_even() == rounded);
+    /// }
+    ///
+    /// check(1.0f32, 1.0);
+    /// check(1.25f32, 1.0);
+    /// check(1.75f32, 2.0);
+    /// check(1.5f32, 2.0);
+    /// check(2.5f32, 2.0);
+    /// check(3.5f32, 4.0);
+    /// check(-3.5f32, -4.0);
+    /// ```
+    fn round_ties_even(self) -> Self {
+        let half = (Self::one() + Self::one()).recip();
+
+        if self.fract().abs() != half {
+            self.round()
+        } else {
+            let i = self.abs().trunc();
+
+            let value = if (i * half).fract() == half {
+                // -1.5, 1.5, 3.5, ...
+                self.abs() + half
+            } else {
+                // -0.5, 0.5, 2.5, ...
+                self.abs() - half
+            };
+
+            if self.signum() != value.signum() {
+                -value
+            } else {
+                value
+            }
+        }
+    }
 }
 
 #[cfg(feature = "std")]
@@ -2024,6 +2085,11 @@ macro_rules! float_impl_std {
                 Self::atanh(self) -> Self;
                 Self::copysign(self, sign: Self) -> Self;
             }
+
+            #[cfg(has_round_ties_even)]
+            forward! {
+                Self::round_ties_even(self) -> Self;
+            }
         }
     };
 }

src/real.rs

@@ -777,6 +777,49 @@ pub trait Real: Num + Copy + NumCast + PartialOrd + Neg<Output = Self> {
     /// assert!(abs_difference < 1.0e-10);
     /// ```
     fn atanh(self) -> Self;
+
+    /// Rounds to the nearest integer, with ties biasing towards an even result.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use num_traits::real::Real;
+    ///
+    /// fn check<T: Real>(x: T, rounded: T) {
+    ///     assert!(x.round_ties_even() == rounded);
+    /// }
+    ///
+    /// check(1.0f32, 1.0);
+    /// check(1.25f32, 1.0);
+    /// check(1.75f32, 2.0);
+    /// check(1.5f32, 2.0);
+    /// check(2.5f32, 2.0);
+    /// check(3.5f32, 4.0);
+    /// check(-3.5f32, -4.0);
+    /// ```
+    fn round_ties_even(self) -> Self {
+        let half = (Self::one() + Self::one()).recip();
+
+        if self.fract().abs() != half {
+            self.round()
+        } else {
+            let i = self.abs().trunc();
+
+            let value = if (i * half).fract() == half {
+                // -1.5, 1.5, 3.5, ...
+                self.abs() + half
+            } else {
+                // -0.5, 0.5, 2.5, ...
+                self.abs() - half
+            };
+
+            if self.signum() != value.signum() {
+                -value
+            } else {
+                value
+            }
+        }
+    }
 }
 
 impl<T: Float> Real for T {
@@ -830,5 +873,6 @@ impl<T: Float> Real for T {
         Float::asinh(self) -> Self;
         Float::acosh(self) -> Self;
         Float::atanh(self) -> Self;
+        Float::round_ties_even(self) -> Self;
     }
 }