Crate decimal_scaled 

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

Overview

decimal-scaled provides a family of fixed-point decimal types whose stored integer encodes actual_value * 10^SCALE. Decimal literals like 1.1 round-trip exactly without any binary approximation, and all core arithmetic is integer-only — identical bit-patterns on every platform.

Primary types

Each width has a D<digits><const SCALE: u32> const-generic shape with the same method surface; pick the narrowest that fits your range.

Type	Storage	Max safe decimal digits	Feature gate
D9<SCALE>	i32	9	always on
D18<SCALE>	i64	18	always on
D38<SCALE>	i128	38	always on
[D76<SCALE>]	256-bit	76	d76 or wide
[D153<SCALE>]	512-bit	153	d153 or wide
[D307<SCALE>]	1024-bit	307	d307 or wide

Concrete scale aliases such as D38s12 = D38<12> are emitted for every supported SCALE. SCALE = MAX_SCALE + 1 is rejected at compile time — 10^(MAX_SCALE+1) overflows the storage type.

The width-generic Decimal trait carries the surface that is identical across widths (constants, arithmetic operators, sign methods, integer variants, pow / checked / wrapping / saturating / overflowing, float bridge, Euclidean / floor / ceil division, etc.). Use it to write helpers that work across widths; reach for the concrete type for width-specific operations like rescale::<TARGET>() whose const-generic parameter cannot live on a trait method.

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 integer storage. Two Dxx<S> values compare equal if and only if their raw bit patterns are identical. This gives predictable behaviour when decimal values are used as HashMap keys, unlike variable-scale decimal types where 1.10 and 1.1 may hash differently.

num-traits compatibility

Every width implements the standard num-traits 0.2 surface: Zero, One, Num, Bounded, Signed, FromPrimitive, ToPrimitive, and the Checked{Add,Sub,Mul,Div,Rem,Neg} family (see ::num_traits). 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 fast 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, from_f64, 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 every decimal width.

Structs

D9

Scaled fixed-point decimal with 32-bit storage. See D38 for the shape documentation; D9 has the same surface scaled to i32 and MAX_SCALE = 9.

D18

Scaled fixed-point decimal with 64-bit storage. See D38 for the shape documentation; D18 has the same surface scaled to i64 and MAX_SCALE = 18.

D38

Scaled fixed-point decimal with 128-bit storage.

Enums

ConvertError

Error returned by the fallible TryFrom impls.

ParseError

Error returned by FromStr when the input is not a valid canonical decimal literal.

RoundingMode

Selector for the rounding rule applied when a scale-narrowing operation discards fractional digits.

Traits

Decimal

Scaled fixed-point decimal type with a compile-time SCALE and a fixed-width integer Storage.

DecimalConsts

Well-known mathematical constants available on any D38<SCALE>.

Type Aliases

D9s0

Scale alias: D9<0>. 1 LSB = 1 (thin i32 wrapper). Range ±2.1 × 10⁹.

D9s1

Scale alias: D9<1>. 1 LSB = 10^-1. Range ±2.1 × 10⁸.

D9s2

Scale alias: D9<2>. 1 LSB = 10^-2 (cents). Range ±2.1 × 10⁷.

D9s3

Scale alias: D9<3>. 1 LSB = 10^-3 (mills). Range ±2.1 × 10⁶.

D9s4

Scale alias: D9<4>. 1 LSB = 10^-4 (basis points). Range ±2.1 × 10⁵.

D9s5

Scale alias: D9<5>. 1 LSB = 10^-5. Range ±2.1 × 10⁴.

D9s6

Scale alias: D9<6>. 1 LSB = 10^-6 (ppm). Range ±2.1 × 10³.

D9s7

Scale alias: D9<7>. 1 LSB = 10^-7. Range ±214.

D9s8

Scale alias: D9<8>. 1 LSB = 10^-8 (satoshi). Range ±21.4.

D9s9

Scale alias: D9<9>. 1 LSB = 10^-9 (nano). Range ±2.1.

D18s0

Scale alias: D18<0>. 1 LSB = 1. Range ±9.2 × 10¹⁸.

D18s1

Scale alias: D18<1>. 1 LSB = 10^-1. Range ±9.2 × 10¹⁷.

D18s2

Scale alias: D18<2>. 1 LSB = 10^-2 (cents). Range ±9.2 × 10¹⁶.

D18s3

Scale alias: D18<3>. 1 LSB = 10^-3 (mills). Range ±9.2 × 10¹⁵.

D18s4

Scale alias: D18<4>. 1 LSB = 10^-4 (basis points). Range ±9.2 × 10¹⁴.

D18s5

Scale alias: D18<5>. 1 LSB = 10^-5. Range ±9.2 × 10¹³.

D18s6

Scale alias: D18<6>. 1 LSB = 10^-6 (ppm). Range ±9.2 × 10¹².

D18s7

Scale alias: D18<7>. 1 LSB = 10^-7. Range ±9.2 × 10¹¹.

D18s8

Scale alias: D18<8>. 1 LSB = 10^-8 (satoshi). Range ±9.2 × 10¹⁰.

D18s9

Scale alias: D18<9>. 1 LSB = 10^-9 (nano). Range ±9.2 × 10⁹.

D18s10

Scale alias: D18<10>. 1 LSB = 10^-10. Range ±9.2 × 10⁸.

D18s11

Scale alias: D18<11>. 1 LSB = 10^-11. Range ±9.2 × 10⁷.

D18s12

Scale alias: D18<12>. 1 LSB = 10^-12 (pico). Range ±9.2 × 10⁶.

D18s13

Scale alias: D18<13>. 1 LSB = 10^-13. Range ±9.2 × 10⁵.

D18s14

Scale alias: D18<14>. 1 LSB = 10^-14. Range ±9.2 × 10⁴.

D18s15

Scale alias: D18<15>. 1 LSB = 10^-15 (femto). Range ±9200.

D18s16

Scale alias: D18<16>. 1 LSB = 10^-16. Range ±920.

D18s17

Scale alias: D18<17>. 1 LSB = 10^-17. Range ±92.

D18s18

Scale alias: D18<18>. 1 LSB = 10^-18 (atto). Range ±9.2.

D38s0

Scale alias: D38<0>. 1 LSB = 1 (thin i128 wrapper, no rescale). Range ~+/-1.7e38.

D38s1

Scale alias: D38<1>. 1 LSB = 10^-1 (1 decimal digit). Range ~+/-1.7e37.

D38s2

Scale alias: D38<2>. 1 LSB = 10^-2 (cents). Range ~+/-1.7e36.

D38s3

Scale alias: D38<3>. 1 LSB = 10^-3 (thousandths; 1 mm at m units). Range ~+/-1.7e35.

D38s4

Scale alias: D38<4>. 1 LSB = 10^-4 (basis points). Range ~+/-1.7e34.

D38s5

Scale alias: D38<5>. 1 LSB = 10^-5. Range ~+/-1.7e33.

D38s6

Scale alias: D38<6>. 1 LSB = 10^-6 (1 um at mm units; ppm). Range ~+/-1.7e32.

D38s7

Scale alias: D38<7>. 1 LSB = 10^-7. Range ~+/-1.7e31.

D38s8

Scale alias: D38<8>. 1 LSB = 10^-8 (satoshi-grade). Range ~+/-1.7e30.

D38s9

Scale alias: D38<9>. 1 LSB = 10^-9 (1 nm at mm units; ppb). Range ~+/-1.7e29.

D38s10

Scale alias: D38<10>. 1 LSB = 10^-10. Range ~+/-1.7e28.

D38s11

Scale alias: D38<11>. 1 LSB = 10^-11. Range ~+/-1.7e27.

D38s12

Scale alias: D38<12>. 1 LSB = 10^-12 (1 pm at mm units). Range ~+/-1.7e14 model units.

D38s13

Scale alias: D38<13>. 1 LSB = 10^-13. Range ~+/-1.7e25.

D38s14

Scale alias: D38<14>. 1 LSB = 10^-14. Range ~+/-1.7e24.

D38s15

Scale alias: D38<15>. 1 LSB = 10^-15 (femto). Range ~+/-1.7e23.

D38s16

Scale alias: D38<16>. 1 LSB = 10^-16. Range ~+/-1.7e22.

D38s17

Scale alias: D38<17>. 1 LSB = 10^-17. Range ~+/-1.7e21.

D38s18

Scale alias: D38<18>. 1 LSB = 10^-18 (atto; high-precision scientific). Range ~+/-1.7e20.

D38s19

Scale alias: D38<19>. 1 LSB = 10^-19. Range ~+/-1.7e19.

D38s20

Scale alias: D38<20>. 1 LSB = 10^-20. Range ~+/-1.7e18.

D38s21

Scale alias: D38<21>. 1 LSB = 10^-21 (zepto). Range ~+/-1.7e17.

D38s22

Scale alias: D38<22>. 1 LSB = 10^-22. Range ~+/-1.7e16.

D38s23

Scale alias: D38<23>. 1 LSB = 10^-23. Range ~+/-1.7e15.

D38s24

Scale alias: D38<24>. 1 LSB = 10^-24 (yocto). Range ~+/-1.7e14.

D38s25

Scale alias: D38<25>. 1 LSB = 10^-25. Range ~+/-1.7e13.

D38s26

Scale alias: D38<26>. 1 LSB = 10^-26. Range ~+/-1.7e12.

D38s27

Scale alias: D38<27>. 1 LSB = 10^-27. Range ~+/-1.7e11.

D38s28

Scale alias: D38<28>. 1 LSB = 10^-28. Range ~+/-1.7e10.

D38s29

Scale alias: D38<29>. 1 LSB = 10^-29. Range ~+/-1.7e9.

D38s30

Scale alias: D38<30>. 1 LSB = 10^-30. Range ~+/-1.7e8.

D38s31

Scale alias: D38<31>. 1 LSB = 10^-31. Range ~+/-1.7e7.

D38s32

Scale alias: D38<32>. 1 LSB = 10^-32. Range ~+/-1.7e6.

D38s33

Scale alias: D38<33>. 1 LSB = 10^-33. Range ~+/-1.7e5.

D38s34

Scale alias: D38<34>. 1 LSB = 10^-34. Range ~+/-1.7e4.

D38s35

Scale alias: D38<35>. 1 LSB = 10^-35. Range ~+/-1.7e3.

D38s36

Scale alias: D38<36>. 1 LSB = 10^-36. Range ~+/-170.

D38s37

Scale alias: D38<37>. 1 LSB = 10^-37. Range ~+/-17.

D38s38

Scale alias: D38<38>. 1 LSB = 10^-38. Range ~+/-1.7 (sub-unit dimensionless ratios).