repository·master·Indexed 42 days ago
https://github.com/neogenie/fastnumA high-performance Rust library providing fixed-size, exact-precision decimal and integer types for financial and cryptographic applications. Version 0.7.5 features no dynamic allocation, compile-time evaluation via macros, and support for IEEE 754 semantics including NaN and Infinity. It offers various bit sizes (64, 128, 256, 512) and integrates with the Rust ecosystem through optional features for serde, diesel, sqlx, and tokio-postgres.
Any N-bit decimal type in fastnum consists of an N-bit big unsigned integer (coefficient) and a 64-bit control block.
The control block contains:
A fastnum decimal type is composed of two parts:
±0, ±Infinity, and NaN per IEEE 754 semantics).Because they are fixed-size, these types are trivially copyable, require no dynamic allocation, and are highly cache-friendly.
Unlike binary floating-point types (like f64), fastnum provides decimal floating-point arithmetic that represents decimal numbers exactly. This avoids common issues like 1.1 + 2.2 resulting in 3.3000000000000003.
fastnum also supports fixed precision (significant places). It preserves trailing zeros to indicate significance, which is critical for monetary applications. For example, 1.30 + 1.20 results in 2.50, and 1.30 * 1.20 results in 1.5600.
use fastnum::udec256;
// Exact arithmetic
let n = udec256!(1.1) + udec256!(2.2);
assert_eq!(n.to_string(), "3.3");
// Preserving significance (trailing zeros)
let n_add = udec256!(1.30) + udec256!(1.20);
assert_eq!(n_add, udec256!(2.50));
let n_mul = udec256!(1.30) * udec256!(1.20);
assert_eq!(n_mul, udec256!(1.5600));Unlike BigDecimal or BigInt which use dynamic allocation and Vec-based storage, fastnum uses fixed-size decimal numbers.
Each decimal type consists of:
±0, ±Infinity, and NaN with IEEE 754 semantics).Key Advantages:
0.1 + 0.2 != 0.3.from_* methods and mathematical functions are const, allowing for compile-time parsing and complex calculations.A Decimal context defines the rules governing arithmetic operations, specifically rounding_mode and signal_traps (which determine the action taken when signals like OVERFLOW or DIVISION_BY_ZERO occur).
By default, the following signals are trapped (⚠️):
DIVISION_BY_ZEROINVALID_OPERATIONOVERFLOWOther signals like CLAMPED, INEXACT, ROUNDED, SUBNORMAL, and UNDERFLOW are not trapped by default.
fastnum is a high-performance decimal library designed for speed and precision. Compared to other common Rust decimal crates, it offers:
f64, it provides exact decimal representation.bigdecimal and rust_decimal.no-std, compile-time calculations, and handles special values like ±0, ±Infinity, and NaN.inexact, subnormal, round, etc.fastnum, precision is defined as an integral number of decimal digits. The maximum possible precision is constrained by the maximum number of decimal digits that the underlying N-bit unsigned coefficient can hold.fastnum numbers are represented using an abstract model that distinguishes between finite numbers and special values.
A finite number is defined by three components:
0 for positive/zero, 1 for negative/negative zero.Numerical value formula: (-1)^sign * coefficient * 10^exponent.
Quantum: The value of a unit in the least significant position of the coefficient, calculated as 1 * 10^-exponent.
fastnum supports three named special values:
0/0, sqrt(-1)). It can be a quiet NaN or a signaling NaN.+Infinity or -Infinity.+0 and -0. While numerically equal, they can behave differently in specific operations (e.g., 1/-0 = -Infinity).Each fastnum type provides a dedicated macro helper to define constants or variables that are evaluated at compile time. This allows for compile-time parsing and arithmetic checks, ensuring that invalid values or arithmetic errors (like division by zero) are caught during compilation.
use fastnum::udec256;
// Evaluated at compile-time and inlined
const PI: UD256 = udec256!(3.141592653589793115997963468544185161590576171875);
// Compile-time arithmetic
const PI_X_2: UD256 = udec256!(2).mul(udec256!(3.141592653589793115997963468544185161590576171875));When using serde_json, standard parsing can truncate or lose precision by converting numbers to f64. To prevent this, you can use the arbitrary_precision feature of serde_json in conjunction with the serde-arbitrary-precision feature in fastnum.
To avoid global configuration conflicts in complex dependency trees, use the #[serde(with = "...")] attribute to apply arbitrary precision parsing to specific fields using decimal::serde::dec::arbitrary_precision.
// #[cfg(feature="serde-arbitrary-precision")]
{
use serde::Deserialize;
use fastnum::*;
#[derive(Deserialize)]
pub struct Arbitrary {
#[serde(with = "decimal::serde::dec::arbitrary_precision")]
value: D128,
}
let data: Arbitrary = serde_json::from_str(r#"{"value": -1.09861228866810969139524523692252570465}"#).unwrap();
assert_eq!(dec128!(-1.09861228866810969139524523692252570465), data.value);
}To use fastnum in your Rust project, add it to your Cargo.toml dependencies. You can install the base version or enable optional features like serde for serialization.
Base installation:
fastnum = "0.7"Installation with features (e.g., serde):
fastnum = { version = "0.7", features = ["serde"] }To ensure the crate is working correctly and to verify edge cases, run the test suite with all features enabled.
cargo test --all-features