Clean up and document code

Author: mtilda

src/float.rs

@@ -2397,79 +2397,100 @@ mod tests {
         check::<f64>(1e-12);
     }
 
+    /// Create a function to test `Float::integer_decode` for a given float type (`f32` or `f64`) and tolerance.
+    ///
+    /// # Examples
+    /// ```rs
+    /// check_integer_decode!(check, f32, 1e-6);
+    /// check(sign_f * 0.0_f32, 0x000000, -150, sign);
+    /// ```
     macro_rules! check_integer_decode {
         (
             $func_name:ident,
-            $T:ty,
+            $float_type:ty,
             $tolerance:expr
         ) => {
-            fn $func_name(x: $T, x_mantissa: u64, x_exponent: i16, x_sign: i8) {
-                let (mantissa, exponent, sign) = crate::float::Float::integer_decode(x);
+            /// Test the behavior of `Float::integer_decode(input)`
+            fn $func_name(input: $float_type, mantissa: u64, exponent: i16, sign: i8) {
+                let output = crate::float::Float::integer_decode(input);
+
+                assert!(
+                    (mantissa, exponent, sign) == output,
+                    "unexpected output of `Float::integer_decode({0:e})`
+\texpected: {1}
+\t   found: {2}",
+                    input,
+                    std::format!("({:#x} {} {})", mantissa, exponent, sign),
+                    std::format!("({:#x} {} {})", output.0, output.1, output.2),
+                );
+
+                // Destructure output and values cast as float
+                let mantissa_f = output.0 as $float_type;
+                let exponent_f = output.1 as $float_type;
+                let sign_f = output.2 as $float_type;
+
+                // Recover input using equation: sign * mantissa * 2^exponent
+                let recovered_input = sign_f * mantissa_f * exponent_f.exp2();
+                let deviation = recovered_input - input;
+
                 assert!(
-                    (x_mantissa, x_exponent, x_sign) == (mantissa, exponent, sign),
-                    "{}\n\t{}\n\t{}",
-                    std::format!("while testing return value of Float::integer_decode({})", x),
-                    std::format!("expected: ({:#x} {} {})", x_mantissa, x_exponent, x_sign),
-                    std::format!("   found: ({:#x} {} {})", mantissa, exponent, sign),
+                    deviation.abs() < $tolerance,
+                    "failed to recover input of `Float::integer_decode({0:e})`
+\t expected: ~ {:e}
+\t    found:   {:e}
+\tdeviation:   {:+e}
+\ttolerance: < {:e}",
+                    input,
+                    recovered_input,
+                    deviation,
+                    $tolerance
                 );
-        
-                let sign_f = sign as $T;
-                let mantissa_f = mantissa as $T;
-                let exponent_f = exponent as $T;
-        
-                let abs_difference = (sign_f * mantissa_f * exponent_f.exp2() - x).abs();
-        
-                assert!(abs_difference < $tolerance, "absolute difference {} must be less than {}", abs_difference, $tolerance);
             }
-        }
+        };
     }
 
     #[test]
     #[cfg(any(feature = "std", feature = "libm"))]
     fn integer_decode_f32() {
-        use core::f32;
-
         check_integer_decode!(check, f32, 1e-6);
 
         for sign in [1, -1] {
             let sign_f = sign as f32;
-            check(sign_f * 0.0_f32, 0x000000, -150, sign);
+            check(sign_f * 0.0__f32, 0x000000, -150, sign);
             check(sign_f * f32::MIN_POSITIVE, 0x800000, -149, sign);
             check(sign_f * 0.25_f32, 0x800000, -25, sign);
-            check(sign_f * 0.5_f32, 0x800000, -24, sign);
-            check(sign_f * 1_f32, 0x800000, -23, sign);
-            check(sign_f * 1.5_f32, 0xc00000, -23, sign);
-            check(sign_f * 2_f32, 0x800000, -22, sign);
-            check(sign_f * 2.5_f32, 0xa00000, -22, sign);
-            check(sign_f * 3_f32, 0xc00000, -22, sign);
-            check(sign_f * 4_f32, 0x800000, -21, sign);
-            check(sign_f * 5_f32, 0xa00000, -21, sign);
-            check(sign_f * 42_f32, 0xa80000, -18, sign);
+            check(sign_f * 0.5__f32, 0x800000, -24, sign);
+            check(sign_f * 1____f32, 0x800000, -23, sign);
+            check(sign_f * 1.5__f32, 0xc00000, -23, sign);
+            check(sign_f * 2____f32, 0x800000, -22, sign);
+            check(sign_f * 2.5__f32, 0xa00000, -22, sign);
+            check(sign_f * 3____f32, 0xc00000, -22, sign);
+            check(sign_f * 4____f32, 0x800000, -21, sign);
+            check(sign_f * 5____f32, 0xa00000, -21, sign);
+            check(sign_f * 42___f32, 0xa80000, -18, sign);
             check(sign_f * f32::MAX, 0xffffff, 104, sign);
         }
     }
 
     #[test]
     #[cfg(any(feature = "std", feature = "libm"))]
     fn integer_decode_f64() {
-        use core::f64;
-
         check_integer_decode!(check, f64, 1e-6);
 
         for sign in [1, -1] {
             let sign_f = sign as f64;
-            check(sign_f * 0.0_f64, 0x00000000000000, -1075, sign);
+            check(sign_f * 0.0__f64, 0x00000000000000, -1075, sign);
             check(sign_f * f64::MIN_POSITIVE, 0x10000000000000, -1074, sign);
             check(sign_f * 0.25_f64, 0x10000000000000, -54, sign);
-            check(sign_f * 0.5_f64, 0x10000000000000, -53, sign);
-            check(sign_f * 1_f64, 0x10000000000000, -52, sign);
-            check(sign_f * 1.5_f64, 0x18000000000000, -52, sign);
-            check(sign_f * 2_f64, 0x10000000000000, -51, sign);
-            check(sign_f * 2.5_f64, 0x14000000000000, -51, sign);
-            check(sign_f * 3_f64, 0x18000000000000, -51, sign);
-            check(sign_f * 4_f64, 0x10000000000000, -50, sign);
-            check(sign_f * 5_f64, 0x14000000000000, -50, sign);
-            check(sign_f * 42_f64, 0x15000000000000, -47, sign);
+            check(sign_f * 0.5__f64, 0x10000000000000, -53, sign);
+            check(sign_f * 1____f64, 0x10000000000000, -52, sign);
+            check(sign_f * 1.5__f64, 0x18000000000000, -52, sign);
+            check(sign_f * 2____f64, 0x10000000000000, -51, sign);
+            check(sign_f * 2.5__f64, 0x14000000000000, -51, sign);
+            check(sign_f * 3____f64, 0x18000000000000, -51, sign);
+            check(sign_f * 4____f64, 0x10000000000000, -50, sign);
+            check(sign_f * 5____f64, 0x14000000000000, -50, sign);
+            check(sign_f * 42___f64, 0x15000000000000, -47, sign);
             check(sign_f * f64::MAX, 0x1fffffffffffff, 971, sign);
         }
     }