Struct Dec 

pub struct Dec(/* private fields */);

A decimal carrying a fixed Dec::SCALE decimal places, backed by an i128 holding the value scaled by 10^SCALE.

Arithmetic is exact between Dec::MIN and Dec::MAX. Anything that leaves that range becomes Dec::NAN and stays NaN through every later operation, so the fault reaches the boundary where Dec::is_finite is checked rather than being clamped to a plausible number or raised as a panic on a hot path.

The ordering is total: NaN equals itself and sorts below Dec::MIN, which keeps Eq, Ord and Hash derivable and so keeps Dec usable as a BTreeMap or HashMap key. See the design notes for why.

use troy::{Dec, dec};

assert_eq!(dec!(2.5) + dec!(0.25), dec!(2.75));
assert!((Dec::MAX + Dec::ONE).is_nan());

Implementations

impl Dec

pub const SCALE: u32 = 18

Number of decimal places every Dec carries.

pub const ZERO: Self

Zero.

pub const ONE: Self

One.

pub const NEG_ONE: Self

Negative one.

pub const MIN: Self

The smallest finite value, -Dec::MAX. The finite range is symmetric, so negation and Dec::abs are total and exact on it.

pub const MAX: Self

The largest finite value, roughly 1.7e20.

pub const EPSILON: Self

The smallest positive value, one unit in the last place.

pub const NAN: Self

The not-a-number state. Every operation that leaves the finite range returns it, and every operation given it returns it, so an invalid result carries its own invalidity to wherever it is finally checked with Dec::is_finite.

Unlike an IEEE NaN this one is ordered and reflexive: it equals itself and sorts below Dec::MIN, which is what keeps Eq and Ord available. It therefore wins any min reduction and sorts to the front of a collection.

use troy::Dec;

assert_eq!(Dec::NAN, Dec::NAN);
assert!(Dec::NAN < Dec::MIN);
assert!(!Dec::NAN.is_finite());

pub const fn from_raw(raw: i128) -> Self

Wrap a raw scaled integer. Total: i128::MIN is Dec::NAN, so every raw round trips through Dec::into_raw.

pub const fn is_nan(self) -> bool

Whether this is Dec::NAN, the state every overflow collapses to.

pub const fn is_finite(self) -> bool

Whether this is an ordinary number, the check to make where a value leaves the system.

use troy::{Dec, dec};

assert!(dec!(1.5).is_finite());
assert!(Dec::MAX.is_finite());
assert!(!(Dec::MAX * Dec::MAX).is_finite());

pub const fn into_raw(self) -> i128

The underlying scaled integer, the inverse of Dec::from_raw.

pub const fn from_int(value: i64) -> Self

An exact whole number. Every i64 fits the finite range.

pub const fn from_u64(value: u64) -> Self

An exact whole number. Every u64 fits the finite range.

pub const fn parse_const(value: &str) -> Option<Self>

Parse in a const context, None on malformed or out-of-range text. The dec! macro wraps this.

pub const fn is_zero(self) -> bool

Whether this is exactly zero. Dec::NAN is not.

pub const fn is_sign_negative(self) -> bool

Whether this is a finite value below zero. Dec::NAN is neither negative nor positive, so this is not a finiteness test.

pub const fn is_sign_positive(self) -> bool

Whether this is a value above zero. Dec::NAN is not.

pub const fn abs(self) -> Self

The magnitude, exact for every finite value because the range is symmetric. Dec::NAN stays NaN.

pub const fn signum(self) -> Self

Dec::ONE, Dec::NEG_ONE or Dec::ZERO by sign. Dec::NAN stays NaN.

pub fn to_f64(self) -> f64

Convert to f64, rounding to the nearest representable double. Dec::NAN becomes f64::NAN.

pub fn from_f64(value: f64) -> Option<Self>

Convert from f64, or None when the value is not finite or does not fit the finite range. This never yields Dec::NAN: a conversion reports failure directly, since there is no earlier computation for a NaN to have propagated from.

pub const fn floor(self) -> Self

The largest whole number at or below this value, or Dec::NAN when that leaves the finite range, as it does for Dec::MIN.

pub const fn ceil(self) -> Self

The smallest whole number at or above this value, or Dec::NAN when that leaves the finite range, as it does for Dec::MAX.

pub const fn trunc(self) -> Self

The whole part, rounding towards zero. Always finite for a finite input; Dec::NAN stays NaN.

pub const fn checked_add(self, rhs: Self) -> Option<Self>

The sum, or None if it leaves the finite range or either side is Dec::NAN. Use this where an overflow should be handled on the spot rather than propagated.

pub const fn checked_sub(self, rhs: Self) -> Option<Self>

The difference, or None if it leaves the finite range or either side is Dec::NAN.

pub fn checked_mul(self, rhs: Self) -> Option<Self>

The product, or None if it leaves the finite range or either side is Dec::NAN. Exact, with the excess below Dec::SCALE rounded half away from zero.

pub fn checked_div(self, rhs: Self) -> Option<Self>

The quotient, or None on division by zero, if it leaves the finite range, or if either side is Dec::NAN.

pub fn saturating_div(self, rhs: Self) -> Self

The quotient, clamped to Dec::MIN or Dec::MAX on overflow. Division by zero has no side to clamp towards and still gives Dec::NAN, as does a NaN operand.

pub fn saturating_mul(self, rhs: Self) -> Self

The product, clamped to Dec::MIN or Dec::MAX on overflow. A Dec::NAN operand still gives NaN: there is no sign to clamp towards, and clamping an unknown would invent one.

pub const fn saturating_add(self, rhs: Self) -> Self

The sum, clamped to Dec::MIN or Dec::MAX on overflow. A Dec::NAN operand still gives NaN.

pub const fn saturating_sub(self, rhs: Self) -> Self

The difference, clamped to Dec::MIN or Dec::MAX on overflow. A Dec::NAN operand still gives NaN.

pub const fn midpoint(self, rhs: Self) -> Self

The value halfway between the two, which cannot overflow because the sum is formed in a wider space. Dec::NAN on either side gives NaN.

impl Dec

pub fn from_decimal(value: Decimal) -> Option<Self>

Rescale a Decimal, exact unless it carries more than Dec::SCALE decimal places, where the excess rounds half away from zero.

pub fn to_decimal(self) -> Option<Decimal>

Widen to a Decimal at Dec::SCALE decimal places, or None when the value needs more than the 96 bits a Decimal mantissa holds.

impl Dec

pub fn from_f64_round(value: f64, dp: u32) -> Option<Self>

Dec::from_f64 followed by Dec::round_dp, which is how a float carrying binary representation error is best pinned to a known scale.

pub const fn round_dp(self, dp: u32) -> Self

Round to dp decimal places, halves away from zero. A no-op once dp reaches Dec::SCALE. Returns Dec::NAN when the rounded value leaves the finite range, as it does for Dec::MIN at dp 0, and when the input is already NaN.

use troy::{Dec, dec};

assert_eq!(dec!(2.5).round_dp(0), dec!(3));
assert_eq!(dec!(-2.5).round_dp(0), dec!(-3));
assert!(Dec::MAX.round_dp(0).is_nan());

pub const fn round_to_step(self, step: Self) -> Self

Round to the nearest multiple of step, halves away from zero. A non-positive step is a no-op. Returns Dec::NAN when the result leaves the finite range, and when either side is already NaN.

use troy::dec;

assert_eq!(dec!(104_237.28).round_to_step(dec!(0.25)), dec!(104_237.25));

Trait Implementations

impl Add for Dec

The sum, or Dec::NAN on overflow or from a NaN operand. See Dec::checked_add and Dec::saturating_add to handle it on the spot.

type Output = Dec

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self

Performs the + operation.

impl AddAssign for Dec

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl Clone for Dec

fn clone(&self) -> Dec

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Dec

impl Debug for Dec

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

Formats the value using the given formatter.

impl Default for Dec

fn default() -> Dec

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Dec

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

Deserialize this value from the given Serde deserializer.

impl Display for Dec

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

Formats the value using the given formatter.

impl Div for Dec

The quotient, or Dec::NAN on division by zero, on overflow, or from a NaN operand.

There is no infinity in the type, so dividing by zero has no value to return; it is the same fault as an overflow and collapses to the same NaN, which then carries to wherever the result is examined rather than panicking on a hot path. The quotient is exact at Dec::SCALE places, with a tie rounding half away from zero. Dec::checked_div reports the fault, Dec::saturating_div clamps an overflow.

type Output = Dec

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self

Performs the / operation.

impl DivAssign for Dec

fn div_assign(&mut self, rhs: Self)

Performs the /= operation.

impl Eq for Dec

impl From<i32> for Dec

fn from(value: i32) -> Self

Converts to this type from the input type.

impl From<i64> for Dec

fn from(value: i64) -> Self

Converts to this type from the input type.

impl From<u32> for Dec

fn from(value: u32) -> Self

Converts to this type from the input type.

impl From<u64> for Dec

fn from(value: u64) -> Self

Converts to this type from the input type.

impl FromStr for Dec

type Err = ParseDecError

The associated error which can be returned from parsing.

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

Parses a string s to return a value of this type.

impl Hash for Dec

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 Mul for Dec

The product, or Dec::NAN on overflow or from a NaN operand.

The finite range is +/-1.7e20 and no price, size or notional lives near it, so an overflow here is a bug rather than a number: bad input, or an accumulation that ran away. Saturating would answer it with a plausible looking figure that survives every downstream check, so the operators return NaN instead and carry the fault to wherever the result is finally examined. Dec::checked_mul reports it, Dec::saturating_mul clamps it, for callers who would rather decide on the spot.

type Output = Dec

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self

Performs the * operation.

impl MulAssign for Dec

fn mul_assign(&mut self, rhs: Self)

Performs the *= operation.

impl Neg for Dec

Negation, which is exact and total: the finite range is symmetric, so every value has a negation, and the NaN pattern is its own.

type Output = Dec

The resulting type after applying the - operator.

fn neg(self) -> Self

Performs the unary - operation.

impl Ord for Dec

fn cmp(&self, other: &Dec) -> 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 Dec

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for Dec

fn partial_cmp(&self, other: &Dec) -> 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 Dec

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

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Dec

impl Sub for Dec

The difference, or Dec::NAN on overflow or from a NaN operand. See Dec::checked_sub and Dec::saturating_sub to handle it on the spot.

type Output = Dec

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self

Performs the - operation.

impl SubAssign for Dec

fn sub_assign(&mut self, rhs: Self)

Performs the -= operation.

impl Sum for Dec

fn sum<I: Iterator<Item = Self>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by “summing up” the items.

impl<'a> Sum<&'a Dec> for Dec

fn sum<I: Iterator<Item = &'a Self>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by “summing up” the items.

impl TryFrom<Dec> for Decimal

type Error = ParseDecError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Decimal> for Dec

type Error = ParseDecError

The type returned in the event of a conversion error.

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

Performs the conversion.