Add FloatCore::round_ties_even

Author: bushrat011899

Cargo.toml

@@ -27,6 +27,10 @@ default = ["std"]
 libm = ["dep:libm"]
 std = []
 
+# Allows access to functionality only available in Rust 1.77, such as round_ties_even
+# This increases the MSRV to 1.77
+msrv_1_77 = []
+
 # vestigial features, now always in effect
 i128 = []
 

src/float.rs

@@ -796,6 +796,31 @@ pub trait FloatCore: Num + NumCast + Neg<Output = Self> + PartialOrd + Copy {
     /// check(f64::NEG_INFINITY, 1 << 52, 972, -1);
     /// ```
     fn integer_decode(self) -> (u64, i16, i8);
+
+    /// Rounds to the nearest integer, with ties biasing towards an even result.
+    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 FloatCore for f32 {
@@ -844,6 +869,11 @@ impl FloatCore for f32 {
         Self::powi(self, n: i32) -> Self;
     }
 
+    #[cfg(all(feature = "std", feature = "msrv_1_77"))]
+    forward! {
+        Self::round_ties_even(self) -> Self;
+    }
+
     #[cfg(all(not(feature = "std"), feature = "libm"))]
     forward! {
         libm::floorf as floor(self) -> Self;
@@ -906,6 +936,11 @@ impl FloatCore for f64 {
         Self::powi(self, n: i32) -> Self;
     }
 
+    #[cfg(all(feature = "std", feature = "msrv_1_77"))]
+    forward! {
+        Self::round_ties_even(self) -> Self;
+    }
+
     #[cfg(all(not(feature = "std"), feature = "libm"))]
     forward! {
         libm::floor as floor(self) -> Self;
@@ -2510,4 +2545,170 @@ mod tests {
         check_lt(f32::INFINITY, f32::NAN);
         check_gt(f32::NAN, 1.0_f32);
     }
+
+    /// Compares the fallback implementation of [`round_ties_even`] to the one provided by `f32`.`
+    ///
+    /// [`round_ties_even`]: crate::float::FloatCore::round_ties_even
+    #[cfg(feature = "msrv_1_77")]
+    #[test]
+    fn round_ties_even() {
+        mod wrapped_f32 {
+            use crate::{float::FloatCore, Num, NumCast, One, ToPrimitive, Zero};
+            use core::ops::{Add, Div, Mul, Neg, Rem, Sub};
+
+            #[derive(Clone, Copy, PartialEq, PartialOrd, Debug)]
+            pub struct WrappedF32(pub f32);
+
+            impl ToPrimitive for WrappedF32 {
+                fn to_i64(&self) -> Option<i64> {
+                    f32::to_i64(&self.0)
+                }
+
+                fn to_u64(&self) -> Option<u64> {
+                    f32::to_u64(&self.0)
+                }
+            }
+
+            impl NumCast for WrappedF32 {
+                fn from<T: crate::ToPrimitive>(n: T) -> Option<Self> {
+                    Some(Self(<f32 as NumCast>::from(n)?))
+                }
+            }
+
+            impl Neg for WrappedF32 {
+                type Output = Self;
+
+                fn neg(self) -> Self::Output {
+                    Self(self.0.neg())
+                }
+            }
+
+            impl Mul for WrappedF32 {
+                type Output = Self;
+
+                fn mul(self, rhs: Self) -> Self::Output {
+                    Self(f32::mul(self.0, rhs.0))
+                }
+            }
+
+            impl Add for WrappedF32 {
+                type Output = Self;
+
+                fn add(self, rhs: Self) -> Self::Output {
+                    Self(f32::add(self.0, rhs.0))
+                }
+            }
+
+            impl Rem for WrappedF32 {
+                type Output = Self;
+
+                fn rem(self, rhs: Self) -> Self::Output {
+                    Self(f32::rem(self.0, rhs.0))
+                }
+            }
+
+            impl Div for WrappedF32 {
+                type Output = Self;
+
+                fn div(self, rhs: Self) -> Self::Output {
+                    Self(f32::div(self.0, rhs.0))
+                }
+            }
+
+            impl Sub for WrappedF32 {
+                type Output = Self;
+
+                fn sub(self, rhs: Self) -> Self::Output {
+                    Self(f32::sub(self.0, rhs.0))
+                }
+            }
+
+            impl One for WrappedF32 {
+                fn one() -> Self {
+                    Self(f32::one())
+                }
+            }
+
+            impl Zero for WrappedF32 {
+                fn zero() -> Self {
+                    Self(f32::zero())
+                }
+
+                fn is_zero(&self) -> bool {
+                    self.0.is_zero()
+                }
+            }
+
+            impl Num for WrappedF32 {
+                type FromStrRadixErr = <f32 as Num>::FromStrRadixErr;
+
+                fn from_str_radix(str: &str, radix: u32) -> Result<Self, Self::FromStrRadixErr> {
+                    Ok(Self(f32::from_str_radix(str, radix)?))
+                }
+            }
+
+            impl FloatCore for WrappedF32 {
+                fn infinity() -> Self {
+                    Self(f32::infinity())
+                }
+
+                fn neg_infinity() -> Self {
+                    Self(f32::neg_infinity())
+                }
+
+                fn nan() -> Self {
+                    Self(f32::nan())
+                }
+
+                fn neg_zero() -> Self {
+                    Self(f32::neg_zero())
+                }
+
+                fn min_value() -> Self {
+                    Self(f32::min_value())
+                }
+
+                fn min_positive_value() -> Self {
+                    Self(f32::min_positive_value())
+                }
+
+                fn epsilon() -> Self {
+                    Self(f32::epsilon())
+                }
+
+                fn max_value() -> Self {
+                    Self(f32::max_value())
+                }
+
+                fn classify(self) -> core::num::FpCategory {
+                    f32::classify(self.0)
+                }
+
+                fn to_degrees(self) -> Self {
+                    Self(f32::to_degrees(self.0))
+                }
+
+                fn to_radians(self) -> Self {
+                    Self(f32::to_radians(self.0))
+                }
+
+                fn integer_decode(self) -> (u64, i16, i8) {
+                    f32::integer_decode(self.0)
+                }
+            }
+        }
+
+        use crate::float::FloatCore;
+        use wrapped_f32::WrappedF32;
+
+        for x in [
+            -5.0, -4.5, -4.0, -3.5, -3.0, -2.5, -2.0, -1.5, -1.0, -0.5, 0.0, 0.5, 1.0, 1.5, 2.0,
+            2.5, 3.0, 3.5, 4.0, 4.5, 5.0,
+        ] {
+            for dx in -250_000..=250_000 {
+                let y = x + (dx as f32 / 1_000_000.0);
+                assert_eq!(WrappedF32(y).round_ties_even().0, y.round_ties_even());
+            }
+        }
+    }
 }