dashu_base/math/
mod.rs

1//! Trait definitions for math operations
2
3/// Fast estimation of the binary logarithm of a number
4///
5/// # Panics
6///
7/// Panics if the number is 0
8///
9/// # Examples
10///
11/// ```
12/// use dashu_base::EstimatedLog2;
13///
14/// let lb3 = 1.584962500721156f32;
15/// let (lb3_lb, lb3_ub) = 3u8.log2_bounds();
16/// assert!(lb3_lb <= lb3 && lb3 <= lb3_ub);
17/// assert!((lb3 - lb3_lb) / lb3 < 1. / 256.);
18/// assert!((lb3_ub - lb3) / lb3 <= 1. / 256.);
19///
20/// let lb3_est = 3u8.log2_est();
21/// assert!((lb3 - lb3_est).abs() < 1e-3);
22/// ```
23pub trait EstimatedLog2 {
24    /// Estimate the bounds of the binary logarithm.
25    ///
26    /// The result is `(lower bound, upper bound)` such that `lower bound ≤ log2(self) ≤ upper bound`.
27    /// The precision of the bounds must be at least 8 bits (relative error < 2^-8).
28    ///
29    /// With `std` disabled, the precision is about 13 bits. With `std` enabled, the precision
30    /// can be full 24 bits. But the exact precision is not guaranteed and should not be not
31    /// relied on.
32    ///
33    /// For negative values, the logarithm is calculated based on its absolute value. If the number
34    /// is zero, then negative infinity will be returned.
35    ///
36    fn log2_bounds(&self) -> (f32, f32);
37
38    /// Estimate the value of the binary logarithm. It's calculated as the
39    /// average of [log2_bounds][EstimatedLog2::log2_bounds] by default.
40    #[inline]
41    fn log2_est(&self) -> f32 {
42        let (lb, ub) = self.log2_bounds();
43        (lb + ub) / 2.
44    }
45}
46
47/// Compute the multiplicative inverse (aka. reciprocal) of the number.
48///
49/// # Examples
50///
51/// ```
52/// # use dashu_base::Inverse;
53/// assert_eq!(0.1234.inv(), 8.103727714748784);
54/// assert_eq!(f32::INFINITY.inv(), 0f32);
55/// ```
56pub trait Inverse {
57    type Output;
58    fn inv(self) -> Self::Output;
59}
60
61/// Compute the square root of the number.
62///
63/// The result should be rounded towards zero by default.
64///
65/// # Examples
66///
67/// ```
68/// # use dashu_base::SquareRoot;
69/// assert_eq!(256u32.sqrt(), 16);
70/// assert_eq!(257u32.sqrt(), 16);
71/// ```
72pub trait SquareRoot {
73    type Output;
74
75    fn sqrt(&self) -> Self::Output;
76}
77
78/// Compute the cubic root of the number.
79///
80/// The result should be rounded towards zero by default.
81///
82/// # Examples
83///
84/// ```
85/// # use dashu_base::CubicRoot;
86/// assert_eq!(216u32.cbrt(), 6);
87/// assert_eq!(217u32.cbrt(), 6);
88/// ```
89pub trait CubicRoot {
90    type Output;
91
92    fn cbrt(&self) -> Self::Output;
93}
94
95mod inv;
96pub(crate) mod log;
97mod root;
dashu_base/math/mod.rs

dashu_base/math/
mod.rs
