dec2flt: Split up the RawFloat trait

`RawFloat` is currently used specifically for the implementation of the
lemire algorithm, but it is useful for more than that. Split it into
three different traits:

* `Float`: Anything that is reasonably applicable to all floating point
  types.
* `FloatExt`: Items that should be part of `Float` but don't work for
  all float types. This will eventually be merged back into `Float`.
* `Lemire`: Items that are specific to the Lemire algorithm.

Author: tgross35

library/core/src/num/imp/dec2flt/decimal.rs

@@ -1,9 +1,8 @@
 //! Representation of a float as the significant digits and exponent.
 
-use dec2flt::float::RawFloat;
-use dec2flt::fpu::set_precision;
-
 use crate::num::imp::dec2flt;
+use dec2flt::float::Lemire;
+use dec2flt::fpu::set_precision;
 
 const INT_POW10: [u64; 16] = [
     1,
@@ -36,7 +35,7 @@ pub struct Decimal {
 impl Decimal {
     /// Detect if the float can be accurately reconstructed from native floats.
     #[inline]
-    fn can_use_fast_path<F: RawFloat>(&self) -> bool {
+    fn can_use_fast_path<F: Lemire>(&self) -> bool {
         F::MIN_EXPONENT_FAST_PATH <= self.exponent
             && self.exponent <= F::MAX_EXPONENT_DISGUISED_FAST_PATH
             && self.mantissa <= F::MAX_MANTISSA_FAST_PATH
@@ -53,7 +52,7 @@ impl Decimal {
     ///
     /// There is an exception: disguised fast-path cases, where we can shift
     /// powers-of-10 from the exponent to the significant digits.
-    pub fn try_fast_path<F: RawFloat>(&self) -> Option<F> {
+    pub fn try_fast_path<F: Lemire>(&self) -> Option<F> {
         // Here we need to work around <https://github.com/rust-lang/rust/issues/114479>.
         // The fast path crucially depends on arithmetic being rounded to the correct number of bits
         // without any intermediate rounding. On x86 (without SSE or SSE2) this requires the precision

library/core/src/num/imp/dec2flt/float.rs

@@ -48,12 +48,8 @@ macro_rules! int {
 int!(u16, u32, u64);
 
 /// A helper trait to avoid duplicating basically all the conversion code for IEEE floats.
-///
-/// See the parent module's doc comment for why this is necessary.
-///
-/// Should **never ever** be implemented for other types or be used outside the `dec2flt` module.
 #[doc(hidden)]
-pub trait RawFloat:
+pub trait Float:
     Sized
     + Div<Output = Self>
     + Neg<Output = Self>
@@ -128,8 +124,6 @@ pub trait RawFloat:
     const MIN_EXPONENT_ROUND_TO_EVEN: i32;
     const MAX_EXPONENT_ROUND_TO_EVEN: i32;
 
-    /* limits related to Fast pathing */
-
     /// Largest decimal exponent for a non-infinite value.
     ///
     /// This is the max exponent in binary converted to the max exponent in decimal. Allows fast
@@ -151,41 +145,19 @@ pub trait RawFloat:
     /// compile time since intermediates exceed the range of an `f64`.
     const SMALLEST_POWER_OF_TEN: i32;
 
-    /// Maximum exponent for a fast path case, or `⌊(SIG_BITS+1)/log2(5)⌋`
-    // assuming FLT_EVAL_METHOD = 0
-    const MAX_EXPONENT_FAST_PATH: i64 = {
-        let log2_5 = f64::consts::LOG2_10 - 1.0;
-        (Self::SIG_TOTAL_BITS as f64 / log2_5) as i64
-    };
-
-    /// Minimum exponent for a fast path case, or `-⌊(SIG_BITS+1)/log2(5)⌋`
-    const MIN_EXPONENT_FAST_PATH: i64 = -Self::MAX_EXPONENT_FAST_PATH;
-
-    /// Maximum exponent that can be represented for a disguised-fast path case.
-    /// This is `MAX_EXPONENT_FAST_PATH + ⌊(SIG_BITS+1)/log2(10)⌋`
-    const MAX_EXPONENT_DISGUISED_FAST_PATH: i64 =
-        Self::MAX_EXPONENT_FAST_PATH + (Self::SIG_TOTAL_BITS as f64 / f64::consts::LOG2_10) as i64;
-
-    /// Maximum mantissa for the fast-path (`1 << 53` for f64).
-    const MAX_MANTISSA_FAST_PATH: u64 = 1 << Self::SIG_TOTAL_BITS;
-
-    /// Converts integer into float through an as cast.
-    /// This is only called in the fast-path algorithm, and therefore
-    /// will not lose precision, since the value will always have
-    /// only if the value is <= Self::MAX_MANTISSA_FAST_PATH.
-    fn from_u64(v: u64) -> Self;
-
-    /// Performs a raw transmutation from an integer.
-    fn from_u64_bits(v: u64) -> Self;
-
-    /// Gets a small power-of-ten for fast-path multiplication.
-    fn pow10_fast_path(exponent: usize) -> Self;
-
     /// Returns the category that this number falls into.
     fn classify(self) -> FpCategory;
 
     /// Transmute to the integer representation
     fn to_bits(self) -> Self::Int;
+}
+
+/// Items that ideally would be on `Float`, but don't apply to all float types because they
+/// rely on the mantissa fitting into a `u64` (which isn't true for `f128`).
+#[doc(hidden)]
+pub trait FloatExt: Float {
+    /// Performs a raw transmutation from an integer.
+    fn from_u64_bits(v: u64) -> Self;
 
     /// Returns the mantissa, exponent and sign as integers.
     ///
@@ -212,14 +184,49 @@ pub trait RawFloat:
     }
 }
 
+/// Extension to `Float` that are necessary for parsing using the Lemire method.
+///
+/// See the parent module's doc comment for why this is necessary.
+///
+/// Not intended for use outside of the `dec2flt` module.
+#[doc(hidden)]
+pub trait Lemire: FloatExt {
+    /// Maximum exponent for a fast path case, or `⌊(SIG_BITS+1)/log2(5)⌋`
+    // assuming FLT_EVAL_METHOD = 0
+    const MAX_EXPONENT_FAST_PATH: i64 = {
+        let log2_5 = f64::consts::LOG2_10 - 1.0;
+        (Self::SIG_TOTAL_BITS as f64 / log2_5) as i64
+    };
+
+    /// Minimum exponent for a fast path case, or `-⌊(SIG_BITS+1)/log2(5)⌋`
+    const MIN_EXPONENT_FAST_PATH: i64 = -Self::MAX_EXPONENT_FAST_PATH;
+
+    /// Maximum exponent that can be represented for a disguised-fast path case.
+    /// This is `MAX_EXPONENT_FAST_PATH + ⌊(SIG_BITS+1)/log2(10)⌋`
+    const MAX_EXPONENT_DISGUISED_FAST_PATH: i64 =
+        Self::MAX_EXPONENT_FAST_PATH + (Self::SIG_TOTAL_BITS as f64 / f64::consts::LOG2_10) as i64;
+
+    /// Maximum mantissa for the fast-path (`1 << 53` for f64).
+    const MAX_MANTISSA_FAST_PATH: u64 = 1 << Self::SIG_TOTAL_BITS;
+
+    /// Gets a small power-of-ten for fast-path multiplication.
+    fn pow10_fast_path(exponent: usize) -> Self;
+
+    /// Converts integer into float through an as cast.
+    /// This is only called in the fast-path algorithm, and therefore
+    /// will not lose precision, since the value will always have
+    /// only if the value is <= Self::MAX_MANTISSA_FAST_PATH.
+    fn from_u64(v: u64) -> Self;
+}
+
 /// Solve for `b` in `10^b = 2^a`
 const fn pow2_to_pow10(a: i64) -> i64 {
     let res = (a as f64) / f64::consts::LOG2_10;
     res as i64
 }
 
 #[cfg(target_has_reliable_f16)]
-impl RawFloat for f16 {
+impl Float for f16 {
     type Int = u16;
 
     const INFINITY: Self = Self::INFINITY;
@@ -236,33 +243,39 @@ impl RawFloat for f16 {
     const MAX_EXPONENT_ROUND_TO_EVEN: i32 = 5;
     const SMALLEST_POWER_OF_TEN: i32 = -27;
 
-    #[inline]
-    fn from_u64(v: u64) -> Self {
-        debug_assert!(v <= Self::MAX_MANTISSA_FAST_PATH);
-        v as _
+    fn to_bits(self) -> Self::Int {
+        self.to_bits()
+    }
+
+    fn classify(self) -> FpCategory {
+        self.classify()
     }
+}
 
+#[cfg(target_has_reliable_f16)]
+impl FloatExt for f16 {
     #[inline]
     fn from_u64_bits(v: u64) -> Self {
         Self::from_bits((v & 0xFFFF) as u16)
     }
+}
 
+#[cfg(target_has_reliable_f16)]
+impl Lemire for f16 {
     fn pow10_fast_path(exponent: usize) -> Self {
         #[allow(clippy::use_self)]
         const TABLE: [f16; 8] = [1e0, 1e1, 1e2, 1e3, 1e4, 0.0, 0.0, 0.];
         TABLE[exponent & 7]
     }
 
-    fn to_bits(self) -> Self::Int {
-        self.to_bits()
-    }
-
-    fn classify(self) -> FpCategory {
-        self.classify()
+    #[inline]
+    fn from_u64(v: u64) -> Self {
+        debug_assert!(v <= Self::MAX_MANTISSA_FAST_PATH);
+        v as _
     }
 }
 
-impl RawFloat for f32 {
+impl Float for f32 {
     type Int = u32;
 
     const INFINITY: Self = f32::INFINITY;
@@ -279,34 +292,38 @@ impl RawFloat for f32 {
     const MAX_EXPONENT_ROUND_TO_EVEN: i32 = 10;
     const SMALLEST_POWER_OF_TEN: i32 = -65;
 
-    #[inline]
-    fn from_u64(v: u64) -> Self {
-        debug_assert!(v <= Self::MAX_MANTISSA_FAST_PATH);
-        v as _
+    fn to_bits(self) -> Self::Int {
+        self.to_bits()
     }
 
+    fn classify(self) -> FpCategory {
+        self.classify()
+    }
+}
+
+impl FloatExt for f32 {
     #[inline]
     fn from_u64_bits(v: u64) -> Self {
         f32::from_bits((v & 0xFFFFFFFF) as u32)
     }
+}
 
+impl Lemire for f32 {
     fn pow10_fast_path(exponent: usize) -> Self {
         #[allow(clippy::use_self)]
         const TABLE: [f32; 16] =
             [1e0, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 0., 0., 0., 0., 0.];
         TABLE[exponent & 15]
     }
 
-    fn to_bits(self) -> Self::Int {
-        self.to_bits()
-    }
-
-    fn classify(self) -> FpCategory {
-        self.classify()
+    #[inline]
+    fn from_u64(v: u64) -> Self {
+        debug_assert!(v <= Self::MAX_MANTISSA_FAST_PATH);
+        v as _
     }
 }
 
-impl RawFloat for f64 {
+impl Float for f64 {
     type Int = u64;
 
     const INFINITY: Self = Self::INFINITY;
@@ -323,17 +340,23 @@ impl RawFloat for f64 {
     const MAX_EXPONENT_ROUND_TO_EVEN: i32 = 23;
     const SMALLEST_POWER_OF_TEN: i32 = -342;
 
-    #[inline]
-    fn from_u64(v: u64) -> Self {
-        debug_assert!(v <= Self::MAX_MANTISSA_FAST_PATH);
-        v as _
+    fn to_bits(self) -> Self::Int {
+        self.to_bits()
     }
 
+    fn classify(self) -> FpCategory {
+        self.classify()
+    }
+}
+
+impl FloatExt for f64 {
     #[inline]
     fn from_u64_bits(v: u64) -> Self {
         f64::from_bits(v)
     }
+}
 
+impl Lemire for f64 {
     fn pow10_fast_path(exponent: usize) -> Self {
         const TABLE: [f64; 32] = [
             1e0, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13, 1e14, 1e15,
@@ -342,11 +365,9 @@ impl RawFloat for f64 {
         TABLE[exponent & 31]
     }
 
-    fn to_bits(self) -> Self::Int {
-        self.to_bits()
-    }
-
-    fn classify(self) -> FpCategory {
-        self.classify()
+    #[inline]
+    fn from_u64(v: u64) -> Self {
+        debug_assert!(v <= Self::MAX_MANTISSA_FAST_PATH);
+        v as _
     }
 }

library/core/src/num/imp/dec2flt/lemire.rs

@@ -1,7 +1,7 @@
 //! Implementation of the Eisel-Lemire algorithm.
 
 use dec2flt::common::BiasedFp;
-use dec2flt::float::RawFloat;
+use dec2flt::float::Float;
 use dec2flt::table::{LARGEST_POWER_OF_FIVE, POWER_OF_FIVE_128, SMALLEST_POWER_OF_FIVE};
 
 use crate::num::imp::dec2flt;
@@ -24,7 +24,7 @@ use crate::num::imp::dec2flt;
 /// at a Gigabyte per Second" in section 5, "Fast Algorithm", and
 /// section 6, "Exact Numbers And Ties", available online:
 /// <https://arxiv.org/abs/2101.11408.pdf>.
-pub fn compute_float<F: RawFloat>(q: i64, mut w: u64) -> BiasedFp {
+pub fn compute_float<F: Float>(q: i64, mut w: u64) -> BiasedFp {
     let fp_zero = BiasedFp::zero_pow2(0);
     let fp_inf = BiasedFp::zero_pow2(F::INFINITE_POWER);
     let fp_error = BiasedFp::zero_pow2(-1);

library/core/src/num/imp/dec2flt/mod.rs

@@ -88,7 +88,7 @@
 )]
 
 use common::BiasedFp;
-use float::RawFloat;
+use float::{FloatExt, Lemire};
 use lemire::compute_float;
 use parse::{parse_inf_nan, parse_number};
 use slow::parse_long_mantissa;
@@ -120,15 +120,15 @@ pub fn pfe_invalid() -> ParseFloatError {
 }
 
 /// Converts a `BiasedFp` to the closest machine float type.
-fn biased_fp_to_float<F: RawFloat>(x: BiasedFp) -> F {
+fn biased_fp_to_float<F: FloatExt>(x: BiasedFp) -> F {
     let mut word = x.m;
     word |= (x.p_biased as u64) << F::SIG_BITS;
     F::from_u64_bits(word)
 }
 
 /// Converts a decimal string into a floating point number.
 #[inline(always)] // Will be inlined into a function with `#[inline(never)]`, see above
-pub fn dec2flt<F: RawFloat>(s: &str) -> Result<F, ParseFloatError> {
+pub fn dec2flt<F: Lemire>(s: &str) -> Result<F, ParseFloatError> {
     let mut s = s.as_bytes();
     let Some(&c) = s.first() else { return Err(pfe_empty()) };
     let negative = c == b'-';

library/core/src/num/imp/dec2flt/parse.rs

@@ -2,7 +2,7 @@
 
 use dec2flt::common::{ByteSlice, is_8digits};
 use dec2flt::decimal::Decimal;
-use dec2flt::float::RawFloat;
+use dec2flt::float::Float;
 
 use crate::num::imp::dec2flt;
 
@@ -197,7 +197,7 @@ pub fn parse_number(s: &[u8]) -> Option<Decimal> {
 }
 
 /// Try to parse a special, non-finite float.
-pub(crate) fn parse_inf_nan<F: RawFloat>(s: &[u8], negative: bool) -> Option<F> {
+pub(crate) fn parse_inf_nan<F: Float>(s: &[u8], negative: bool) -> Option<F> {
     // Since a valid string has at most the length 8, we can load
     // all relevant characters into a u64 and work from there.
     // This also generates much better code.

library/core/src/num/imp/dec2flt/slow.rs

@@ -2,7 +2,7 @@
 
 use dec2flt::common::BiasedFp;
 use dec2flt::decimal_seq::{DecimalSeq, parse_decimal_seq};
-use dec2flt::float::RawFloat;
+use dec2flt::float::Float;
 
 use crate::num::imp::dec2flt;
 
@@ -25,7 +25,7 @@ use crate::num::imp::dec2flt;
 ///
 /// The algorithms described here are based on "Processing Long Numbers Quickly",
 /// available here: <https://arxiv.org/pdf/2101.11408.pdf#section.11>.
-pub(crate) fn parse_long_mantissa<F: RawFloat>(s: &[u8]) -> BiasedFp {
+pub(crate) fn parse_long_mantissa<F: Float>(s: &[u8]) -> BiasedFp {
     const MAX_SHIFT: usize = 60;
     const NUM_POWERS: usize = 19;
     const POWERS: [u8; 19] =

library/core/src/num/imp/flt2dec/decoder.rs

@@ -1,7 +1,7 @@
 //! Decodes a floating-point value into individual parts and error ranges.
 
 use crate::num::FpCategory;
-use crate::num::imp::dec2flt::float::RawFloat;
+use crate::num::imp::dec2flt::float::FloatExt;
 
 /// Decoded unsigned finite value, such that:
 ///
@@ -40,7 +40,7 @@ pub enum FullDecoded {
 }
 
 /// A floating point type which can be `decode`d.
-pub trait DecodableFloat: RawFloat + Copy {
+pub trait DecodableFloat: FloatExt + Copy {
     /// The minimum positive normalized value.
     fn min_pos_norm_value() -> Self;
 }