Skip to main content

Crate decimal_scaled

Crate decimal_scaled 

Source
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. The number on every D{N} type is MAX_SCALE — the highest SCALE the storage can hold.

TypeStorageMAX_SCALEFeature gate
D9<SCALE>i329always on
D18<SCALE>i6418always on
D38<SCALE>i12838always on
D56<SCALE>192-bit57d56 or wide
D76<SCALE>256-bit76d76 or wide
D114<SCALE>384-bit115d114 or wide
D153<SCALE>512-bit153d153 or wide
D230<SCALE>768-bit230d230 or wide
D307<SCALE>1024-bit307d307 or wide
D461<SCALE>1536-bit462d461 or x-wide
D615<SCALE>2048-bit616d615 or x-wide
D923<SCALE>3072-bit924d923 or xx-wide
D1231<SCALE>4096-bit1232d1231 or xx-wide

Umbrellas: wide enables D56 / D76 / D114 / D153 / D230 / D307; x-wide adds D461 + D615; xx-wide adds D923 + D1231. Every adjacent pair has lossless .widen() / fallible .narrow() helpers plus From / TryFrom impls.

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.
D56
Scaled fixed-point decimal with 192-bit storage. Half-width tier between D38 and D76 — useful when the D38 i128 ceiling is in reach but D76’s 256-bit storage is wasteful.
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.
D114
Scaled fixed-point decimal with 384-bit storage. Half-width tier between D76 and D153.
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.
D230
Scaled fixed-point decimal with 768-bit storage. Half-width tier between D153 and D307.
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.
D461
Scaled fixed-point decimal with 1536-bit storage. Half-width tier between D307 and D615.
D615
Scaled fixed-point decimal with 2048-bit storage. New top tier beyond D307; supports correctly-rounded transcendentals at scale up to 616 decimal digits.
D923
Scaled fixed-point decimal with 3072-bit storage. Half-width tier between D615 and D1231; supports SCALE up to 924 digits.
D1231
Scaled fixed-point decimal with 4096-bit storage. Widest tier shipped; supports SCALE up to 1232 digits.
Int192
Hand-rolled fixed-width two’s-complement signed integer.
Int256
Hand-rolled fixed-width two’s-complement signed integer.
Int384
Hand-rolled fixed-width two’s-complement signed integer.
Int512
Hand-rolled fixed-width two’s-complement signed integer.
Int768
Hand-rolled fixed-width two’s-complement signed integer.
Int1024
Hand-rolled fixed-width two’s-complement signed integer.
Int1536
Hand-rolled fixed-width two’s-complement signed integer.
Int2048
Hand-rolled fixed-width two’s-complement signed integer.
Int3072
Hand-rolled fixed-width two’s-complement signed integer.
Int4096
Hand-rolled fixed-width two’s-complement signed integer.
Int6144
Hand-rolled fixed-width two’s-complement signed integer.
Int8192
Hand-rolled fixed-width two’s-complement signed integer.
Int12288
Hand-rolled fixed-width two’s-complement signed integer.
Int16384
Hand-rolled fixed-width two’s-complement signed integer.
Uint192
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint256
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint384
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint512
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint768
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint1024
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint1536
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint2048
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint3072
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint4096
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint6144
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint8192
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint12288
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).
Uint16384
Hand-rolled fixed-width unsigned integer, little-endian u64 limbs ($L of them).

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).
D56s0
D56s2
D56s4
D56s6
D56s9
D56s12
D56s18
D56s24
D56s28
D56s32
D56s38
D56s42
D56s48
D56s52
D56s56
D56s57
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.
D114s0
D114s4
D114s8
D114s16
D114s24
D114s32
D114s38
D114s50
D114s57
D114s64
D114s76
D114s90
D114s100
D114s110
D114s114
D114s115
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.
D230s0
D230s6
D230s18
D230s38
D230s57
D230s75
D230s100
D230s115
D230s140
D230s153
D230s175
D230s200
D230s215
D230s225
D230s229
D230s230
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.
D461s0
D461s18
D461s38
D461s75
D461s115
D461s153
D461s200
D461s230
D461s275
D461s307
D461s350
D461s400
D461s440
D461s460
D461s461
D461s462
D615s0
D615s38
D615s75
D615s115
D615s153
D615s200
D615s230
D615s275
D615s308
D615s380
D615s462
D615s500
D615s555
D615s600
D615s615
D615s616
D923s0
D923s75
D923s153
D923s230
D923s307
D923s400
D923s461
D923s462
D923s500
D923s616
D923s700
D923s800
D923s860
D923s900
D923s920
D923s923
D923s924
D1231s0
D1231s75
D1231s153
D1231s230
D1231s307
D1231s461
D1231s616
D1231s700
D1231s800
D1231s900
D1231s924
D1231s1000
D1231s1100
D1231s1180
D1231s1220
D1231s1230
D1231s1231
D1231s1232