dashu-float 0.6.1

Arbitrary-precision float math library for Rust with arbitrary base and arbitrary rounding mode. Provides FBig, DBig, and CachedFBig with efficient base conversion, the hexadecimal float format used by C++ programs, and parsing and formatting in base 2-36. Transcendentals (exp, ln, trig, hyperbolic, powers, roots, pi) are correctly rounded; optional serde, rand, num-traits, rkyv, and zeroize.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

// Copyright (c) 2022 Jacob Zhong
//
// Licensed under either of
//
// * Apache License, Version 2.0
//   (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
// * MIT license
//   (LICENSE-MIT or https://opensource.org/licenses/MIT)
//
// at your option.
//
// Unless you explicitly state otherwise, any contribution intentionally submitted
// for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
// dual licensed as above, without any additional terms or conditions.

//! A big float library supporting arbitrary precision, arbitrary base and arbitrary rounding mode.
//!
//! The library implements efficient large floating point arithmetic in pure Rust.
//!
//! The main type is [FBig] representing the arbitrary precision floating point numbers, the [DBig] type
//! is an alias supporting decimal floating point numbers.
//!
//! To construct big floats from literals, please use the [`dashu-macro`](https://docs.rs/dashu-macros/latest/dashu_macros/)
//! crate for your convenience.
//!
//! # Examples
//!
//! ```
//! # use dashu_base::ParseError;
//! use core::str::FromStr;
//! use core::convert::TryFrom;
//! use dashu_float::DBig;
//!
//! // due to the limit of rust generics, the default float type
//! // need to be instantiate explicitly
//! type FBig = dashu_float::FBig;
//!
//! let a = FBig::try_from(-12.34_f32).unwrap();
//! let b = DBig::from_str("6.022e23")?;
//! let c = DBig::from_parts(271828.into(), -5);
//! let d: DBig = "-0.0123456789".parse()?;
//! let e = 2 * b.ln() + DBig::ONE;
//! let f = &c * d.powi(10.into()) / 7;
//!
//! assert_eq!(a.precision(), 24); // IEEE 754 single has 24 significant bits
//! assert_eq!(b.precision(), 4); // 4 decimal digits
//!
//! assert!(b > c); // comparison is limited in the same base
//! assert!(a.to_decimal().value() < d);
//! assert_eq!(c.to_string(), "2.71828");
//!
//! // use associated functions of the context to get full result
//! use dashu_base::Approximation::*;
//! use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};
//! let ctxt = Context::<HalfAway>::new(6);
//! assert_eq!(ctxt.exp(DBig::ONE.repr(), None), Ok(Inexact(c, NoOp)));
//! # Ok::<(), ParseError>(())
//! ```
//!
//! # Optional dependencies
//!
//! * `std` (*default*): enable `std` for dependencies.

#![cfg_attr(not(feature = "std"), no_std)]
#![deny(missing_docs)]
#![deny(clippy::dbg_macro)]
#![deny(clippy::undocumented_unsafe_blocks)]
#![deny(clippy::let_underscore_must_use)]

extern crate alloc;
// The rkyv derive macros emit `rkyv::` paths; alias the renamed optional dep back so they resolve.
#[cfg(feature = "rkyv_v07")]
extern crate rkyv_v07 as rkyv;

mod add;
mod ball;
mod cmp;
mod convert;
mod div;
mod error;
mod exp;
mod fbig;
mod fbig_cached;
mod fbig_cached_ops;
mod fmt;
mod helper_macros;
mod iter;
mod log;
mod mag;
pub mod math;
mod mul;
pub mod ops;
mod parse;
mod repr;
mod repr_ops;
mod root;
pub mod round;
mod round_ops;
mod shift;
mod sign;
mod third_party;
mod utils;
mod ziv;

// Retry-count profiling for the Ziv loops (available with the `tuning` feature).
#[cfg(any(all(test, feature = "std"), feature = "tuning"))]
pub use ziv::{ziv_retries, ziv_retries_reset};
// The per-attempt radius trace hook is deliberately `#[doc(hidden)]`: usable by profiling
// harnesses, but not a stable API promise.
#[cfg(any(all(test, feature = "std"), feature = "tuning"))]
#[doc(hidden)]
pub use ziv::{ziv_set_trace_hook, ZivTraceFn};

// The error-propagation substrate (`Ball` over a `Mag` radius), shared in lockstep with
// `dashu-cmplx`: its `CBall` composes complex balls on top of these real ones. Deliberately
// `#[doc(hidden)]` — excluded from the semver and stability guarantees, consumed only by the
// crates of this repository, which are released together.
#[doc(hidden)]
pub use ball::{ulp_mag, Ball};
#[doc(hidden)]
pub use mag::Mag;

// All the public items from third_party will be exposed
#[allow(unused_imports)]
pub use third_party::*;

pub use fbig::FBig;
pub use fbig_cached::CachedFBig;
pub use math::cache::ConstCache;
pub use repr::{Context, Repr};
pub use {crate::error::FpError, crate::math::FpResult};

/// Multi-precision float number with decimal exponent and [HalfAway][round::mode::HalfAway] rounding mode
pub type DBig = FBig<round::mode::HalfAway, 10>;

#[doc(hidden)]
pub use dashu_int::Word; // for macros

// Infinities are now first-class *terminal* values: operations produce them as results
// (1/0 → +inf, ln(0) → -inf, …) but reject infinite *inputs* (FpError::InfiniteInput / panic),
// which structurally avoids the NaN-producing indeterminate forms (inf−inf, inf/inf, 0·inf).
// IEEE signed zero is supported (`-0`), so 1/-0 = -inf is well-defined.