Crate decimal_scaled

Expand description

Const-generic base-10 fixed-point decimal types for deterministic arithmetic.

§Overview

decimal-scaled provides I128<const SCALE: u32>, a fixed-point decimal type backed by i128. The stored integer encodes actual_value * 10^SCALE, so decimal literals like 1.1 round-trip exactly without any binary approximation. All core arithmetic is integer-only and produces identical bit-patterns on every platform.

§Primary types

I128<SCALE> is the const-generic foundation. Every method is implemented once and is available at any scale.
I128s12 is the concrete alias I128<12>. At SCALE = 12, one LSB equals 10^-12 model units and the representable range is roughly +/-1.7e14 model units.
Scale aliases I128s0 through I128s38 cover every supported scale. SCALE = 39 is not supported because 10^39 overflows i128.

§Equality and hashing

Because each logical value has exactly one representation at a fixed scale, Hash, Eq, PartialEq, PartialOrd, and Ord are all derived from the underlying i128. Two I128<S> values compare equal if and only if their raw bit patterns are identical. This gives predictable behaviour when I128 values are used as HashMap keys, unlike variable-scale decimal types where 1.10 and 1.1 may hash differently.

§`num-traits` compatibility

I128<SCALE> implements the standard num-traits 0.2 surface, including num_traits::Zero, num_traits::One, num_traits::Num, num_traits::Bounded, num_traits::Signed, num_traits::FromPrimitive, num_traits::ToPrimitive, and the Checked{Add,Sub,Mul,Div,Rem,Neg} family. These impls are unconditional (not behind a feature flag) because generic numeric code in the wider ecosystem consumes this surface by default.

§`no_std` support

The crate compiles with no_std + alloc when default features are disabled. alloc is required for Display::to_string and FromStr::from_str. Targets without alloc are not supported.

§Feature flags

std (default): enables the lossy implementations of transcendental functions (trigonometry, logarithms, exponentials, square root, cube root, float power) that delegate to platform f64 intrinsics.
alloc: pulled in automatically; required for string formatting and parsing.
serde: enables serde_helpers for serialisation and deserialisation.
strict: enables integer-only implementations of all transcendental functions. When strict is active each function that would otherwise route through f64 is instead implemented using integer-only algorithms. Explicit float-conversion methods (to_f64_lossy, from_f64_lossy, etc.) remain available regardless; they are type conversions, not mathematical operations. strict does not require std; the integer transcendental implementations compile under no_std + alloc.

Modules§

serde_helpers: serde integration for I128.

Structs§

I128: Scaled fixed-point decimal with 128-bit storage.

Enums§

DecimalConvertError: Error returned by the fallible TryFrom impls on I128.
ParseDecimalError: Error returned by <I128<SCALE> as FromStr>::from_str when the input string is not a valid canonical decimal literal.

Traits§

DecimalConsts: Well-known mathematical constants available on any I128<SCALE>.

Type Aliases§

I128s0: Scale alias: I128<0>. 1 LSB = 1 (thin i128 wrapper, no rescale). Range ~+/-1.7e38.
I128s1: Scale alias: I128<1>. 1 LSB = 10^-1 (1 decimal digit). Range ~+/-1.7e37.
I128s2: Scale alias: I128<2>. 1 LSB = 10^-2 (cents). Range ~+/-1.7e36.
I128s3: Scale alias: I128<3>. 1 LSB = 10^-3 (thousandths; 1 mm at m units). Range ~+/-1.7e35.
I128s4: Scale alias: I128<4>. 1 LSB = 10^-4 (basis points). Range ~+/-1.7e34.
I128s5: Scale alias: I128<5>. 1 LSB = 10^-5. Range ~+/-1.7e33.
I128s6: Scale alias: I128<6>. 1 LSB = 10^-6 (1 um at mm units; ppm). Range ~+/-1.7e32.
I128s7: Scale alias: I128<7>. 1 LSB = 10^-7. Range ~+/-1.7e31.
I128s8: Scale alias: I128<8>. 1 LSB = 10^-8 (satoshi-grade). Range ~+/-1.7e30.
I128s9: Scale alias: I128<9>. 1 LSB = 10^-9 (1 nm at mm units; ppb). Range ~+/-1.7e29.
I128s10: Scale alias: I128<10>. 1 LSB = 10^-10. Range ~+/-1.7e28.
I128s11: Scale alias: I128<11>. 1 LSB = 10^-11. Range ~+/-1.7e27.
I128s12: Scale alias: I128<12>. 1 LSB = 10^-12 (1 pm at mm units). Range ~+/-1.7e14 model units.
I128s13: Scale alias: I128<13>. 1 LSB = 10^-13. Range ~+/-1.7e25.
I128s14: Scale alias: I128<14>. 1 LSB = 10^-14. Range ~+/-1.7e24.
I128s15: Scale alias: I128<15>. 1 LSB = 10^-15 (femto). Range ~+/-1.7e23.
I128s16: Scale alias: I128<16>. 1 LSB = 10^-16. Range ~+/-1.7e22.
I128s17: Scale alias: I128<17>. 1 LSB = 10^-17. Range ~+/-1.7e21.
I128s18: Scale alias: I128<18>. 1 LSB = 10^-18 (atto; high-precision scientific). Range ~+/-1.7e20.
I128s19: Scale alias: I128<19>. 1 LSB = 10^-19. Range ~+/-1.7e19.
I128s20: Scale alias: I128<20>. 1 LSB = 10^-20. Range ~+/-1.7e18.
I128s21: Scale alias: I128<21>. 1 LSB = 10^-21 (zepto). Range ~+/-1.7e17.
I128s22: Scale alias: I128<22>. 1 LSB = 10^-22. Range ~+/-1.7e16.
I128s23: Scale alias: I128<23>. 1 LSB = 10^-23. Range ~+/-1.7e15.
I128s24: Scale alias: I128<24>. 1 LSB = 10^-24 (yocto). Range ~+/-1.7e14.
I128s25: Scale alias: I128<25>. 1 LSB = 10^-25. Range ~+/-1.7e13.
I128s26: Scale alias: I128<26>. 1 LSB = 10^-26. Range ~+/-1.7e12.
I128s27: Scale alias: I128<27>. 1 LSB = 10^-27. Range ~+/-1.7e11.
I128s28: Scale alias: I128<28>. 1 LSB = 10^-28. Range ~+/-1.7e10.
I128s29: Scale alias: I128<29>. 1 LSB = 10^-29. Range ~+/-1.7e9.
I128s30: Scale alias: I128<30>. 1 LSB = 10^-30. Range ~+/-1.7e8.
I128s31: Scale alias: I128<31>. 1 LSB = 10^-31. Range ~+/-1.7e7.
I128s32: Scale alias: I128<32>. 1 LSB = 10^-32. Range ~+/-1.7e6.
I128s33: Scale alias: I128<33>. 1 LSB = 10^-33. Range ~+/-1.7e5.
I128s34: Scale alias: I128<34>. 1 LSB = 10^-34. Range ~+/-1.7e4.
I128s35: Scale alias: I128<35>. 1 LSB = 10^-35. Range ~+/-1.7e3.
I128s36: Scale alias: I128<36>. 1 LSB = 10^-36. Range ~+/-170.
I128s37: Scale alias: I128<37>. 1 LSB = 10^-37. Range ~+/-17.
I128s38: Scale alias: I128<38>. 1 LSB = 10^-38. Range ~+/-1.7 (sub-unit dimensionless ratios).