Trait DecimalConstants

Source

pub trait DecimalConstants: Sized {
Show 18 methods    // Required methods
    fn pi() -> Self;
    fn tau() -> Self;
    fn half_pi() -> Self;
    fn quarter_pi() -> Self;
    fn golden() -> Self;
    fn e() -> Self;
    fn deg_per_rad() -> Self;
    fn rad_per_deg() -> Self;
    fn log10_2() -> Self;
    fn pi_with(mode: RoundingMode) -> Self;
    fn tau_with(mode: RoundingMode) -> Self;
    fn half_pi_with(mode: RoundingMode) -> Self;
    fn quarter_pi_with(mode: RoundingMode) -> Self;
    fn golden_with(mode: RoundingMode) -> Self;
    fn e_with(mode: RoundingMode) -> Self;
    fn deg_per_rad_with(mode: RoundingMode) -> Self;
    fn rad_per_deg_with(mode: RoundingMode) -> Self;
    fn log10_2_with(mode: RoundingMode) -> Self;
}

Expand description

Well-known mathematical constants available on every decimal width (D18 / D38 / D76 / D153 / D307).

Import this trait to call D38s12::pi(), D76::<35>::e(), etc.

All returned values are computed from a raw integer reference at the tier’s maximum storage precision (75 digits for D18/D38 and D76; 153 for D153; 307 for D307) without passing through f64, then rescaled down to the caller’s SCALE with half-to-even rounding. The result is within 0.5 ULP of the canonical decimal expansion at every supported scale on every width.

The one situation where a method does not return a value is when the constant’s magnitude exceeds the type’s storage range at the caller’s SCALE — e.g. D38<38>::pi() would need 3.14 × 10³⁸, which exceeds i128::MAX ≈ 1.7×10³⁸. The method panics with a clear “constant out of storage range” message in that case.

§Crossing into f64

to_f64() is itself correctly rounded, but it can only round to the decimal value the type holds — not to the underlying ideal constant. f64 carries ~15.95 decimal digits of mantissa, so any constant produced at SCALE < 15 is intrinsically coarser than the f64 grid: D38<12>::pi().to_f64() lands ~466 ULPs from std::f64::consts::PI, because the 12-digit decimal rounds differently than the closest-f64 to true π. At SCALE ≥ 15 the round-trip is bit-exact for these constants (the decimal value has enough digits to disambiguate the f64 grid).

Practical rule for downstream code that crosses into f64 — CAD bulge-arc tessellation, OpenGL/GLSL, hardware drivers — and uses the f64 value to count, bucket, or seed a fixed-iteration loop: source mathematical constants from std::f64::consts directly at the boundary rather than going through Decimal::pi().to_f64(). Otherwise pick a SCALE of 15 or more so the decimal value can round-trip to the canonical f64.

Required Methods§

Source

fn pi() -> Self

Pi (~3.14159265…). One half-turn in radians.

Source: ISO 80000-2 / OEIS A000796. Rescaled per-tier (see the module-level table) to the caller’s SCALE via the crate-default rounding mode.