Struct Decimal 

pub struct Decimal { /* private fields */ }

An exact fixed-point decimal: mantissa × 10⁻ˢᶜᵃˡᵉ.

See the module documentation for why the type exists and what it guarantees. Construct with Decimal::new or by parsing the digits:

use chronix_core::Decimal;

let register: Decimal = "1234.5678".parse().unwrap();
assert_eq!(register.mantissa(), 12_345_678);
assert_eq!(register.scale(), 4);
assert_eq!(register.to_string(), "1234.5678");

// Widening is exact; narrowing past a non-zero digit is refused.
assert_eq!(register.rescale(6).unwrap().to_string(), "1234.567800");
assert!(register.rescale(2).is_err());

Implementations

impl Decimal

pub const fn new(mantissa: i128, scale: u8) -> Result<Self, DecimalError>

Construct from an unscaled mantissa and a scale.

Errors

DecimalError::ScaleTooLarge if scale > MAX_DECIMAL_SCALE, and DecimalError::PrecisionOverflow if the mantissa needs more than 38 significant digits.

pub const fn zero(scale: u8) -> Result<Self, DecimalError>

Zero at the given scale.

Errors

DecimalError::ScaleTooLarge if scale > MAX_DECIMAL_SCALE.

pub const fn mantissa(&self) -> i128

The unscaled integer value.

pub const fn scale(&self) -> u8

The number of digits after the decimal point.

pub const fn is_zero(&self) -> bool

true when the value is exactly zero, at any scale.

pub const fn signum(&self) -> i8

-1, 0 or 1 — the sign of the value.

pub const fn abs(&self) -> Self

The absolute value, at the same scale.

Total: |mantissa| cannot overflow because the mantissa is bounded by MAX_DECIMAL_MANTISSA, well inside i128::MIN.

pub const fn neg(&self) -> Self

The negation, at the same scale.

pub fn rescale(&self, target: u8) -> Result<Self, DecimalError>

Return the same value expressed at target scale.

Widening multiplies by a power of ten and is always exact. Narrowing succeeds only when every digit it would drop is a zero — 1.500 to scale 1 is 1.5, 1.55 to scale 1 is an error, never 1.6 and never 1.5.

Errors

• DecimalError::ScaleTooLarge if target > MAX_DECIMAL_SCALE.
• DecimalError::InexactRescale if narrowing would drop a non-zero digit.
• DecimalError::PrecisionOverflow if widening pushes the mantissa past 38 significant digits.

pub fn normalized(&self, min_scale: u8) -> Self

Drop trailing fractional zeros, down to min_scale.

1.2500 normalised to a minimum scale of 0 is 1.25; to a minimum of 3 it is 1.250. Never changes the value.

pub fn checked_add(&self, other: &Self) -> Result<Self, DecimalError>

Exact sum, at the wider of the two scales.

Errors

DecimalError::Overflow if the result needs more than 38 significant digits.

pub fn checked_sub(&self, other: &Self) -> Result<Self, DecimalError>

Exact difference, at the wider of the two scales.

Errors

DecimalError::Overflow if the result needs more than 38 significant digits.

pub fn to_f64_lossy(&self) -> f64

The value as an f64 — lossy, and named so at every call site.

The only conversion to binary floating point this type offers. A settlement quantity must not travel this way; a chart of one may.

pub fn cmp_exact(&self, other: &Self) -> Ordering

Compare against another decimal of any scale, exactly.

Aligning two mantissas at different scales can overflow i128 — 10³⁷ at scale 0 against anything at scale 38 does. An overflow is not an error here but an answer: the side that cannot be represented at the common scale is the side with the larger magnitude, because the other one is representable there.

Trait Implementations

impl Clone for Decimal

fn clone(&self) -> Decimal

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Decimal

impl Debug for Decimal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Decimal

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for Decimal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Render the exact digits: no exponent, no rounding, no f64.

impl Eq for Decimal

impl From<Decimal> for FieldValue

fn from(v: Decimal) -> Self

Converts to this type from the input type.

impl FromStr for Decimal

fn from_str(s: &str) -> Result<Self, Self::Err>

Parse the digits themselves — never via f64.

Accepts an optional sign, digits with an optional fractional part, and an optional decimal exponent (1.5e3). The scale is the number of fractional digits less the exponent; a literal that lands on a scale above MAX_DECIMAL_SCALE is accepted only if the excess digits are trailing zeros that can be dropped without changing the value.

type Err = DecimalError

The associated error which can be returned from parsing.

impl Hash for Decimal

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Decimal

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for Decimal

fn eq(&self, other: &Decimal) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Decimal

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Decimal

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Exact in both directions: the digits as a string for JSON and any other human-readable format, the (mantissa, scale) pair for postcard and the rest of the binary ones.

A decimal must never reach JSON as a JSON number: serde_json parses one back through f64, which is the loss this type exists to prevent.

impl StructuralPartialEq for Decimal

impl TryFrom<Decimal> for Decimal

type Error = DecimalError

The type returned in the event of a conversion error.

fn try_from(value: Decimal) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Decimal> for Decimal

type Error = DecimalError

The type returned in the event of a conversion error.

fn try_from(value: Decimal) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i64> for Decimal

fn try_from(value: i64) -> Result<Self, Self::Error>

An integer is a decimal of scale 0.

type Error = DecimalError

The type returned in the event of a conversion error.