Crate decimal_scaled

Expand description

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.

Macros§

d9: The narrow-tier proc-macros are always available with the macros feature; the wide-tier proc-macros are additionally feature-gated to match their target type’s availability. d9! — construct a decimal_scaled::D9<SCALE> value at compile time. See the crate-level docs and macros/README.md.
d9s0: d9s0!(value) — equivalent to d9!(value, scale 0).
d9s2: d9s2!(value) — equivalent to d9!(value, scale 2).
d9s4: d9s4!(value) — equivalent to d9!(value, scale 4).
d9s6: d9s6!(value) — equivalent to d9!(value, scale 6).
d9s9: d9s9!(value) — equivalent to d9!(value, scale 9).
d18: The narrow-tier proc-macros are always available with the macros feature; the wide-tier proc-macros are additionally feature-gated to match their target type’s availability. d18! — construct a decimal_scaled::D18<SCALE> value at compile time. See the crate-level docs and macros/README.md.
d38: The narrow-tier proc-macros are always available with the macros feature; the wide-tier proc-macros are additionally feature-gated to match their target type’s availability. d38! — construct a decimal_scaled::D38<SCALE> value at compile time. See the crate-level docs and macros/README.md.
d76: d76! — construct a decimal_scaled::D76<SCALE> value at compile time. Requires the parent crate’s d76 / wide feature.
d18s0: d18s0!(value) — equivalent to d18!(value, scale 0).
d18s2: d18s2!(value) — equivalent to d18!(value, scale 2).
d18s4: d18s4!(value) — equivalent to d18!(value, scale 4).
d18s6: d18s6!(value) — equivalent to d18!(value, scale 6).
d18s9: d18s9!(value) — equivalent to d18!(value, scale 9).
d18s12: d18s12!(value) — equivalent to d18!(value, scale 12).
d18s18: d18s18!(value) — equivalent to d18!(value, scale 18).
d38s0: d38s0!(value) — equivalent to d38!(value, scale 0).
d38s2: d38s2!(value) — equivalent to d38!(value, scale 2).
d38s4: d38s4!(value) — equivalent to d38!(value, scale 4).
d38s6: d38s6!(value) — equivalent to d38!(value, scale 6).
d38s8: d38s8!(value) — equivalent to d38!(value, scale 8).
d38s9: d38s9!(value) — equivalent to d38!(value, scale 9).
d38s12: d38s12!(value) — equivalent to d38!(value, scale 12).
d38s15: d38s15!(value) — equivalent to d38!(value, scale 15).
d38s18: d38s18!(value) — equivalent to d38!(value, scale 18).
d38s24: d38s24!(value) — equivalent to d38!(value, scale 24).
d38s35: d38s35!(value) — equivalent to d38!(value, scale 35).
d38s38: d38s38!(value) — equivalent to d38!(value, scale 38).
d76s0: d76s0!(value) — equivalent to d76!(value, scale 0).
d76s2: d76s2!(value) — equivalent to d76!(value, scale 2).
d76s6: d76s6!(value) — equivalent to d76!(value, scale 6).
d76s12: d76s12!(value) — equivalent to d76!(value, scale 12).
d76s18: d76s18!(value) — equivalent to d76!(value, scale 18).
d76s35: d76s35!(value) — equivalent to d76!(value, scale 35).
d76s50: d76s50!(value) — equivalent to d76!(value, scale 50).
d76s76: d76s76!(value) — equivalent to d76!(value, scale 76).
d153: d153! — construct a decimal_scaled::D153<SCALE> value at compile time. Requires the parent crate’s d153 / wide feature.
d307: d307! — construct a decimal_scaled::D307<SCALE> value at compile time. Requires the parent crate’s d307 / x-wide feature.
d153s0: d153s0!(value) — equivalent to d153!(value, scale 0).
d153s35: d153s35!(value) — equivalent to d153!(value, scale 35).
d153s75: d153s75!(value) — equivalent to d153!(value, scale 75).
d153s150: d153s150!(value) — equivalent to d153!(value, scale 150).
d153s153: d153s153!(value) — equivalent to d153!(value, scale 153).
d307s0: d307s0!(value) — equivalent to d307!(value, scale 0).
d307s35: d307s35!(value) — equivalent to d307!(value, scale 35).
d307s150: d307s150!(value) — equivalent to d307!(value, scale 150).
d307s300: d307s300!(value) — equivalent to d307!(value, scale 300).
d307s307: d307s307!(value) — equivalent to d307!(value, scale 307).

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.
D76: Scaled fixed-point decimal with 256-bit storage. See D38 for the shape documentation; D76 has the same surface scaled to a 256-bit signed integer and MAX_SCALE = 76.
D153: Scaled fixed-point decimal with 512-bit storage. See D38 for the shape documentation; D153 has the same surface scaled to a 512-bit signed integer and MAX_SCALE = 153.
D307: Scaled fixed-point decimal with 1024-bit storage. See D38 for the shape documentation; D307 has the same surface scaled to a 1024-bit signed integer and MAX_SCALE = 307.
Int256: Hand-rolled fixed-width two’s-complement signed integer.
Int512: Hand-rolled fixed-width two’s-complement signed integer.
Int1024: Hand-rolled fixed-width two’s-complement signed integer.
Int2048: Hand-rolled fixed-width two’s-complement signed integer.
Int4096: Hand-rolled fixed-width two’s-complement signed integer.
Uint256: Hand-rolled fixed-width unsigned integer, little-endian limbs.
Uint512: Hand-rolled fixed-width unsigned integer, little-endian limbs.
Uint1024: Hand-rolled fixed-width unsigned integer, little-endian limbs.
Uint2048: Hand-rolled fixed-width unsigned integer, little-endian limbs.
Uint4096: Hand-rolled fixed-width unsigned integer, little-endian limbs.

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 every decimal width (D9 / D18 / D38 / D76 / D153 / D307).

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).
D76s0: Scale alias: D76<0>. 1 LSB = 1 (256-bit integer ledger).
D76s2: Scale alias: D76<2>. 1 LSB = 10^-2 (cents).
D76s6: Scale alias: D76<6>. 1 LSB = 10^-6 (ppm).
D76s12: Scale alias: D76<12>. 1 LSB = 10^-12 (pico; financial standard).
D76s18: Scale alias: D76<18>. 1 LSB = 10^-18 (atto).
D76s35: Scale alias: D76<35>. 1 LSB = 10^-35 (matches SCALE_REF).
D76s50: Scale alias: D76<50>. 1 LSB = 10^-50 (deep scientific precision).
D76s76: Scale alias: D76<76>. 1 LSB = 10^-76. Maximum supported scale.
D153s0: Scale alias: D153<0>. 1 LSB = 1 (512-bit integer ledger).
D153s35: Scale alias: D153<35>. 1 LSB = 10^-35 (matches SCALE_REF).
D153s75: Scale alias: D153<75>. 1 LSB = 10^-75 (wide-scientific midpoint).
D153s150: Scale alias: D153<150>. 1 LSB = 10^-150.
D153s153: Scale alias: D153<153>. 1 LSB = 10^-153. Maximum supported scale.
D307s0: Scale alias: D307<0>. 1 LSB = 1 (1024-bit integer ledger).
D307s35: Scale alias: D307<35>. 1 LSB = 10^-35 (matches SCALE_REF).
D307s150: Scale alias: D307<150>. 1 LSB = 10^-150.
D307s300: Scale alias: D307<300>. 1 LSB = 10^-300.
D307s307: Scale alias: D307<307>. 1 LSB = 10^-307. Maximum supported scale.