Struct Decimal 

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

A 128-bit decimal number with deterministic arithmetic.

This type wraps rust_decimal::Decimal and provides checked arithmetic operations that explicitly handle overflow, underflow, and division by zero. All operations are deterministic across platforms.

Implementations

impl Decimal

pub const ZERO: Self

Zero.

pub const ONE: Self

One.

pub const NEGATIVE_ONE: Self

Negative one.

pub const TEN: Self

Ten.

pub const ONE_HUNDRED: Self

One hundred.

pub const ONE_THOUSAND: Self

One thousand.

pub const MAX: Self

Maximum representable value.

pub const MIN: Self

Minimum representable value.

pub fn new(mantissa: i64, scale: u32) -> Self

Creates a new decimal from integer mantissa and scale.

The value is mantissa * 10^(-scale).

Panics

Panics if scale exceeds 28.

pub const fn from_parts( lo: u32, mid: u32, hi: u32, negative: bool, scale: u32, ) -> Self

Creates a decimal from raw parts.

The 96-bit mantissa is stored as three 32-bit words in little-endian order. The sign is true for negative values.

pub fn try_from_i128(value: i128) -> Result<Self, ArithmeticError>

Creates a decimal from a 128-bit integer.

Returns an error if the value is too large to represent.

pub fn to_parts(self) -> (i128, u32)

Returns the mantissa as a 128-bit integer and the scale.

pub fn scale(self) -> u32

Returns the scale (number of decimal places).

pub fn is_zero(self) -> bool

Returns true if the value is zero.

pub fn is_negative(self) -> bool

Returns true if the value is negative.

pub fn is_positive(self) -> bool

Returns true if the value is positive.

pub fn abs(self) -> Self

Returns the absolute value.

pub fn signum(self) -> Self

Returns the sign of the value: -1, 0, or 1.

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

Checked addition. Returns None on overflow.

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

Checked subtraction. Returns None on overflow.

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

Checked multiplication. Returns None on overflow.

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

Checked division. Returns None on division by zero or overflow.

pub fn checked_rem(self, other: Self) -> Option<Self>

Checked remainder. Returns None on division by zero.

pub fn saturating_add(self, other: Self) -> Self

Saturating addition. Returns MAX or MIN on overflow.

pub fn saturating_sub(self, other: Self) -> Self

Saturating subtraction. Returns MAX or MIN on overflow.

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

Saturating multiplication. Returns MAX or MIN on overflow.

pub fn try_add(self, other: Self) -> Result<Self, ArithmeticError>

Addition with explicit error on overflow.

pub fn try_sub(self, other: Self) -> Result<Self, ArithmeticError>

Subtraction with explicit error on overflow.

pub fn try_mul(self, other: Self) -> Result<Self, ArithmeticError>

Multiplication with explicit error on overflow.

pub fn try_div(self, other: Self) -> Result<Self, ArithmeticError>

Division with explicit error handling.

pub fn round(self, dp: u32, mode: RoundingMode) -> Self

Rounds to the specified number of decimal places using the given mode.

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

Rounds to the specified number of decimal places using banker’s rounding.

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

Truncates to the specified number of decimal places.

pub fn floor(self) -> Self

Returns the floor (round toward negative infinity).

pub fn ceil(self) -> Self

Returns the ceiling (round toward positive infinity).

pub fn normalize(self) -> Self

Normalizes the scale by removing trailing zeros.

pub fn rescale(&mut self, scale: u32) -> Result<(), ArithmeticError>

Rescales to the specified number of decimal places.

Returns an error if the scale would exceed MAX_SCALE.

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

Returns the minimum of two values.

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

Returns the maximum of two values.

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

Clamps the value to the specified range.

pub fn into_inner(self) -> RustDecimal

Returns the internal representation for interop.

pub fn from_inner(inner: RustDecimal) -> Self

Creates from the internal representation.

pub fn sqrt(self) -> Option<Self>

Computes the square root.

Returns None if the value is negative.

Example

use precision_core::Decimal;

let x = Decimal::from(4i64);
assert_eq!(x.sqrt(), Some(Decimal::from(2i64)));

let neg = Decimal::from(-1i64);
assert_eq!(neg.sqrt(), None);

pub fn try_sqrt(self) -> Result<Self, ArithmeticError>

Computes the square root, returning an error for negative inputs.

pub fn exp(self) -> Option<Self>

Computes e^self (the exponential function).

Returns None on overflow.

Example

use precision_core::Decimal;

let x = Decimal::ZERO;
assert_eq!(x.exp(), Some(Decimal::ONE));

pub fn try_exp(self) -> Result<Self, ArithmeticError>

Computes e^self, returning an error on overflow.

pub fn ln(self) -> Option<Self>

Computes the natural logarithm (ln).

Returns None if the value is not positive.

Example

use precision_core::Decimal;
use core::str::FromStr;

let e = Decimal::from_str("2.718281828459045").unwrap();
let ln_e = e.ln().unwrap();
// ln(e) ≈ 1
assert!((ln_e - Decimal::ONE).abs() < Decimal::from_str("0.0001").unwrap());

pub fn try_ln(self) -> Result<Self, ArithmeticError>

Computes the natural logarithm, returning an error for non-positive inputs.

pub fn log10(self) -> Option<Self>

Computes the base-10 logarithm.

Returns None if the value is not positive.

pub fn pow(self, exponent: Self) -> Option<Self>

Computes self^exponent using the formula: x^y = e^(y * ln(x)).

Returns None if the computation would fail (e.g., negative base with non-integer exponent, or overflow).

Note: For integer exponents, use powi for exact results.

Example

use precision_core::Decimal;
use core::str::FromStr;

let base = Decimal::from(2i64);
let exp = Decimal::from(3i64);
let result = base.pow(exp).unwrap();
// Note: small precision loss due to exp/ln computation
let diff = (result - Decimal::from(8i64)).abs();
assert!(diff < Decimal::from_str("0.001").unwrap());

pub fn try_pow(self, exponent: Self) -> Result<Self, ArithmeticError>

Computes self^exponent, returning an error on failure.

pub fn powi(self, n: i32) -> Option<Self>

Computes self^n for integer exponent using repeated squaring.

This is more accurate than pow() for integer exponents as it avoids the exp/ln computation. Returns None on overflow.

Example

use precision_core::Decimal;

let base = Decimal::from(2i64);
assert_eq!(base.powi(10), Some(Decimal::from(1024i64)));

pub fn try_powi(self, n: i32) -> Result<Self, ArithmeticError>

Computes self^n for integer exponent, returning error on failure.

pub fn e() -> Self

Euler’s number e ≈ 2.718281828459045.

pub fn pi() -> Self

Pi ≈ 3.141592653589793.

Trait Implementations

impl Add for Decimal

type Output = Decimal

The resulting type after applying the + operator.

fn add(self, other: Self) -> Self::Output

Performs the + operation.

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 Debug for Decimal

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

Formats the value using the given formatter.

impl Default for Decimal

fn default() -> Self

Returns the “default value” for a type.

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

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Decimal

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

Formats the value using the given formatter.

impl Div for Decimal

type Output = Decimal

The resulting type after applying the / operator.

fn div(self, other: Self) -> Self::Output

Performs the / operation.

impl From<i128> for Decimal

fn from(n: i128) -> Self

Converts to this type from the input type.

impl From<i16> for Decimal

fn from(n: i16) -> Self

Converts to this type from the input type.

impl From<i32> for Decimal

fn from(n: i32) -> Self

Converts to this type from the input type.

impl From<i64> for Decimal

fn from(n: i64) -> Self

Converts to this type from the input type.

impl From<i8> for Decimal

fn from(n: i8) -> Self

Converts to this type from the input type.

impl From<u128> for Decimal

fn from(n: u128) -> Self

Converts to this type from the input type.

impl From<u16> for Decimal

fn from(n: u16) -> Self

Converts to this type from the input type.

impl From<u32> for Decimal

fn from(n: u32) -> Self

Converts to this type from the input type.

impl From<u64> for Decimal

fn from(n: u64) -> Self

Converts to this type from the input type.

impl From<u8> for Decimal

fn from(n: u8) -> Self

Converts to this type from the input type.

impl FromStr for Decimal

type Err = ParseError

The associated error which can be returned from parsing.

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

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

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

type Output = Decimal

The resulting type after applying the * operator.

fn mul(self, other: Self) -> Self::Output

Performs the * operation.

impl Neg for Decimal

type Output = Decimal

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

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.

impl PartialEq for Decimal

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub for Decimal

type Output = Decimal

The resulting type after applying the - operator.

fn sub(self, other: Self) -> Self::Output

Performs the - operation.

impl Copy for Decimal

impl Eq for Decimal

impl StructuralPartialEq for Decimal