oxinum_float/
lib.rs

1#![forbid(unsafe_code)]
2//! Arbitrary-precision floating-point arithmetic for the OxiNum ecosystem.
3//!
4//! Provides wrappers over `dashu-float`'s `FBig`/`DBig` with convenience
5//! functions for elementary math: `exp`, `ln`, `sqrt`, `pow`, trigonometric
6//! functions (`sin`, `cos`, `tan`, `atan`, `atan2`), hyperbolic functions
7//! (`sinh`, `cosh`, `tanh`), and high-precision constants (`pi`, `e`, `ln2`).
8//!
9//! Precision-control helpers ([`precision::with_precision`],
10//! [`precision::epsilon`], [`precision::ulp`]) wrap the underlying
11//! `dashu-float` precision primitives in an ergonomic free-function API.
12//!
13//! ## Why `Hash` is not implemented
14//!
15//! `DBig` (`FBig<HalfAway, 10>`) intentionally does **not** implement
16//! [`core::hash::Hash`].  In IEEE 754 (and by extension in essentially
17//! every numeric library that takes the standard seriously) floating
18//! point values defy the `Hash` contract: distinct representations can
19//! compare equal (e.g. `1.0` and `1.00` at different precisions, or
20//! signed zeros `+0` and `-0`), special values like `NaN` are not
21//! equal to themselves, and the canonical form needed to make hashing
22//! well-defined varies by use case (totalOrder vs. mathematical
23//! equality vs. bitwise identity).  Rust's standard library follows
24//! the same convention: `f32` and `f64` deliberately do not implement
25//! `Hash`.  Callers who need a hash key should either use a
26//! canonicalised representation (e.g. a tuple of `(significand,
27//! exponent, precision)`) or wrap `DBig` in a newtype with an
28//! explicit, documented hashing policy.
29//!
30//! ## Features
31//!
32//! * `serde` *(off by default)* — enables `serde::Serialize` /
33//!   `Deserialize` for `DBig` via `dashu-float`'s own `serde` feature.
34
35pub use dashu_float::{Context, DBig, FBig};
36pub use oxinum_core::{OxiNumError, OxiNumResult, RoundingMode};
37
38/// Rounding modes re-exported from `dashu-float` so callers do not need a
39/// direct dependency on `dashu-float` for basic rounding-mode selection.
40pub mod round {
41    pub use dashu_float::round::mode::{Down, HalfAway, HalfEven, Up, Zero};
42}
43
44/// Type alias for decimal big-float.
45pub type BigFloat = DBig;
46
47// Sub-modules
48mod constants;
49mod elementary;
50pub mod precision;
51mod trig;
52
53/// Native binary-base arbitrary-precision floating-point implementation.
54///
55/// This module is additive: the crate-root [`BigFloat`] alias remains
56/// `dashu_float::DBig` (decimal). Reach for [`native::BigFloat`] when you
57/// want ground-up Pure Rust binary float arithmetic with explicit
58/// rounding-mode control. The native type is intentionally **not**
59/// re-exported at the crate root to avoid clashing with the `DBig` alias.
60pub mod native;
61
62pub use constants::{compute_e, compute_ln2, compute_pi};
63pub use elementary::{exp, ln, pow, sqrt};
64pub use trig::{atan, atan2, cos, cosh, sin, sinh, tan, tanh};
oxinum_float/lib.rs

oxinum_float/
lib.rs
