⚙️ Introduction

Dec19x19 is a high-precision, high-performance fixed-point decimal type for Rust.

It is designed for environments where accuracy, determinism, and raw speed are non-negotiable: financial systems, trading engines, technical analysis, backtesting, and anywhere floating-point drift or arbitrary-precision overhead are unacceptable.

Internally, values are stored as i128 integers with the last 19 digits interpreted as the fractional part. This allows all operations to perform without rounding or approximations within the full range of exactly 19 fractional and 19 integer digits:

±9_999_999_999_999_999_999.999_999_999_999_999_999_9

The actual representable bounds are wider:

• Max: +17_014_118_346_046_923_173.168_730_371_588_410_572_7
• Min: −17_014_118_346_046_923_173.168_730_371_588_410_572_8

Overflow is safely handled via checked_* and saturating_* variants.

🧭 When to Use Dec19x19

Dec19x19 is built for applications where exact decimal precision, deterministic behavior, and high performance are essential. This includes financial software, trading platforms, simulations, and systems where rounding errors are unacceptable.

In many domains—especially finance and crypto—values are represented using fixed decimal precision. For example, most cryptocurrencies (including Ethereum) define token values using 18 decimal places, meaning the smallest unit is 10^-18. Floating-point numbers (f64, f32) can't accurately represent these values without precision loss, and results can vary across architectures due to non-deterministic behavior.

Unlike floating-point types, Dec19x19 guarantees:

• No rounding drift. Every operation is exact within the supported range.
• Deterministic results. Same input always produces the same output.
• Consistent decimal scale. Precisely 19 digits after the decimal, matching or exceeding most domain requirements (e.g. Ethereum's 18).
• No hidden costs. All operations are performed using fast, predictable i128 arithmetic with zero allocations.

Use Dec19x19 when:

• You need to model money, token balances, or prices with exact decimal behavior.
• Performance matters, and you can't afford the overhead of heap-based decimal libraries.
• You require deterministic and audit-friendly results (e.g. blockchain logic, financial reconciliation).
• You want a wide range type, e.g. for time. If you interpret Dec19x19!(1) as 1 millisecond, it covers the range of 100 million years with precision down to the zeptosecond (travel time of a photon across a hydrogen molecule = 247 zeptoseconds).

In short, Dec19x19 provides the precision of big-decimal, performance close to primitive types, and the reliability that floating-point types can't offer.

✅ Features

• 🔬 Exact Decimal Precision
  Fixed 19 integer + 19 fractional digits. No approximations.

• 🛡️ Safety by Default
  Checked and saturating arithmetic built in. No panics, no surprises.

• 🚀 High Performance
  Lean i128 math optimized for speed. Compiles to minimal instructions.

• 🧪 Proven Correctness
  Verified via extensive tests, fuzzing, and comparison with other crates.

• 🧱 Clean and simple implementation
  Internally just a scaled i128. Easy to audit, maintain, and extend.

🛠️ Usage

Construct values via:

• Dec19x19!(...) macro to parse a decimal literal at compile time,
• Dec19x19::from_str(...) method to parse a decimal literal at runtime,
• Dec19x19::from(...) method to convert from other narrower types,
• Dec19x19::try_from(...) method to convert from other wider types.

use fixed_num::Dec19x19 as Dec;
use std::str::FromStr;

let price = Dec::from(123_u8) + Dec!(0.456);
let fee = Dec!(1e-3);
let total = price + fee;

assert_eq!(Ok(total), Dec::from_str("123.457"));
assert_eq!(format!("{total}"), "123.457");

You can print Dec19x19 values using the Display trait with all the usual formatting options:

use fixed_num::Dec19x19 as Dec;

let dec = Dec!(7_654_321.123_456_7);
assert_eq!(&format!("{dec}"),          "7654321.1234567");

// Human-readable form.
assert_eq!(&format!("{dec:#}"),        "7_654_321.123_456_7");

// Precision rounding.
assert_eq!(&format!("{dec:.0}"),       "7654321");
assert_eq!(&format!("{dec:.1}"),       "7654321.1");
assert_eq!(&format!("{dec:.2}"),       "7654321.12");
assert_eq!(&format!("{dec:.3}"),       "7654321.123");
assert_eq!(&format!("{dec:.4}"),       "7654321.1235");
assert_eq!(&format!("{dec:#.0}"),      "7_654_321");
assert_eq!(&format!("{dec:#.4}"),      "7_654_321.123_5");
assert_eq!(&format!("{dec:#.19}"),     "7_654_321.123_456_700_000_000_000_0");

// Padding and alignment.
assert_eq!(&format!("{dec:#24}"),      "     7_654_321.123_456_7");
assert_eq!(&format!("{dec:<#24}"),     "     7_654_321.123_456_7");
assert_eq!(&format!("{dec:>#24}"),     "7_654_321.123_456_7     ");
assert_eq!(&format!("{dec:^#24}"),     "  7_654_321.123_456_7   ");
assert_eq!(&format!("{dec:^#24.4}"),   "    7_654_321.123_5     ");
assert_eq!(&format!("{dec:_^#24.4}"),  "____7_654_321.123_5_____");

// Explicit + sign display.
assert_eq!(&format!("{dec:^+#24.4}"),  "    +7_654_321.123_5    ");

We highly recommend setting overflow-checks = true in your Cargo.toml, especially when developing financial or precision-critical libraries. This option introduces minimal overhead in release builds, but it can be invaluable for catching arithmetic bugs during development. For best results, we suggest the following configuration:

# Cargo.toml
[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
panic = "abort"
overflow-checks = true
strip = true

# .cargo/config.toml
[build]
rustflags = ["-C", "target-cpu=native"]

🛠️ Operations

Dec19x19 implements most standard arithmetic operations. The list of supported operations can be found here. Operations that never panic are marked with the ✅ symbol.

📊 Comparison to Other Libraries

🚀 Benchmarks (higher is better)

Benchmarks measure normalized throughput. 1.00 = Dec19x19 baseline.

• 1.25 means 25% faster
• 0.50 means 2× slower
• ⚠️ indicates unsupported or panicking behavior

⚠️ Note: The fixed crate was excluded due to frequent panics during arithmetic operations in benchmarks.