bigdecimal-rs

bigdecimal-rs provides a BigDecimal type for arbitrary-precision decimal arithmetic in pure Rust, avoiding the rounding errors inherent to binary floating-point when working with base-10 numbers such as currency and financial data. It supports addition, subtraction, multiplication, division, square roots, and configurable precision/rounding contexts, along with optional serde and serde_json integration for lossless serialization of decimal values across systems.

What You Get

• A BigDecimal type supporting arithmetic (add, sub, mul, div, sqrt, inverse) with arbitrary precision
• Configurable rounding modes and precision via a Context struct, with compile-time environment variable defaults
• Multiple Display formatting options including scientific notation, fixed precision, and debug representations
• Optional serde/serde-json feature for serializing decimals as strings or as full-precision JSON numbers
• no_std support via the std feature flag for embedded or constrained environments

Common Use Cases

• Representing currency and financial amounts without floating-point rounding drift
• Parsing and formatting decimal numbers from JSON or text input with exact precision preserved
• Scientific or engineering calculations that need arbitrary decimal precision beyond f64
• Interchange of decimal values between systems via serde without losing precision

Under The Hood

Architecture - The crate centers on a BigDecimal struct (src/lib.rs, ~2400 lines) wrapping a BigInt significand plus an i64 scale exponent, with the core value logic split across impl_ops_*.rs files for each arithmetic operator, impl_cmp.rs for comparisons, impl_fmt.rs for Display/Debug, and parsing.rs for string/float parsing; rounding.rs and context.rs implement a separate Context/RoundingMode system that threads through division and sqrt to bound precision for non-terminating results, and impl_serde.rs bridges to serde/serde_json behind feature flags.

Tech Stack - Pure Rust (98.5% of the codebase) targeting edition 2015 for broad compatibility (minimum rustc 1.43), built on num-bigint, num-integer, and num-traits for the underlying big-integer arithmetic, with libm supplying no_std-compatible math functions; build.rs plus autocfg handle compile-time feature detection, and optional serde/serde_json dependencies are gated behind the serde-json Cargo feature.

Code Quality - Tests are embedded directly alongside implementation via included test modules (lib.tests.rs, lib.tests.double.rs, rounding.tests.rs, parsing.tests.parse_from_f32.rs, etc.) totaling 30+ files containing #[test] functions, plus a dedicated property-tests module gated behind a PROPERTY-TESTS feature flag; the crate has no dependency on unsafe code for its core logic and documents formatting/rounding edge cases extensively in both code comments and the README, though the codebase shows some rough edges from an acknowledged in-progress rewrite mentioned in its own README.

API Design - The public API mirrors Rust’s standard numeric traits (Add, Sub, Mul, Div, PartialOrd, FromStr, Display) so BigDecimal behaves like a drop-in numeric type, and configuration is exposed via compile-time environment variables (RUST_BIGDECIMAL_DEFAULT_PRECISION, etc.) for zero-runtime-cost defaults with an escape hatch to explicit Context objects for callers needing per-call control; documentation on docs.rs and the README’s formatting-rules table make the non-obvious scientific-notation thresholds discoverable.