decimal-scaled 0.5.0

Const-generic base-10 fixed-point decimals (D18/D38/D76/D153/D307 and the half-width tiers up to D1232) with integer-only transcendentals correctly rounded to within 0.5 ULP — exact at the type's last representable place. Deterministic across every platform; no_std-friendly.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

// SPDX-FileCopyrightText: 2026 John Moxley
// SPDX-License-Identifier: MIT OR Apache-2.0

//! The [`DecimalConvert`] trait — round-trip + integer conversion +
//! float bridge shared by every decimal width.
//!
//! Split out of the original [`crate::Decimal`] trait alongside
//! [`crate::DecimalArithmetic`], [`crate::DecimalTranscendental`],
//! and [`crate::DecimalConstants`]; `Decimal` is now a marker
//! supertrait that requires all four. Callers who only need
//! conversions (not the operator surface or transcendentals) can
//! target this narrower bound; supertraits [`DecimalArithmetic`] so
//! `Self::Storage` and `Self::ZERO` / `Self::MAX` / `Self::MIN`
//! (needed for saturation paths) are in scope.
//!
//! See [`crate::types::traits::decimal`] for the full scope rationale.

use crate::support::rounding::RoundingMode;
use crate::types::traits::arithmetic::DecimalArithmetic;

/// Round-trip + conversion surface shared by every decimal width.
///
/// Supertraits [`DecimalArithmetic`] so the storage type and
/// boundary constants are accessible for saturation logic.
pub trait DecimalConvert: DecimalArithmetic {
    // ── Round-trip ───────────────────────────────────────────────────

    /// Constructs from a raw storage value.
    fn from_bits(raw: Self::Storage) -> Self;

    /// Returns the raw storage value.
    fn to_bits(self) -> Self::Storage;

    /// Returns the decimal scale of this value.
    fn scale(self) -> u32;

    // ── Integer conversion ───────────────────────────────────────────
    //
    // Construction from a primitive integer is the fallible
    // `TryFrom<iN>` surface on each concrete width (overflow on scaling
    // returns `ConvertError::Overflow`); there is no width-generic
    // integer constructor on this trait. Only the to-integer direction
    // lives here.

    /// Convert to `i64` using the crate-default rounding mode.
    fn to_int(self) -> i64;

    /// Convert to `i64` using the supplied rounding mode.
    fn to_int_with(self, mode: RoundingMode) -> i64;

    // ── Float bridge (lossy) ─────────────────────────────────────────

    /// Construct from `f64` using the crate-default rounding mode.
    #[cfg(feature = "std")]
    fn from_f64(value: f64) -> Self;

    /// Construct from `f64` using the supplied rounding mode.
    #[cfg(feature = "std")]
    fn from_f64_with(value: f64, mode: RoundingMode) -> Self;

    /// Convert to `f64`. Lossy when the storage magnitude exceeds
    /// `f64`'s ~15-digit exact range.
    #[cfg(feature = "std")]
    fn to_f64(self) -> f64;

    /// Convert to `f32`. Lossy.
    #[cfg(feature = "std")]
    fn to_f32(self) -> f32;
}