Struct Decimal 

pub struct Decimal { /* private fields */ }

Decimal

Owned fixed-point decimal with an explicit i128 mantissa and base-10 scale.

Arithmetic saturates on overflow, division by zero resolves to ZERO, and normalization keeps equivalent values on one canonical representation.

Implementations

impl Decimal

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

Checked addition; returns None when scale alignment or mantissa addition overflows the fixed decimal representation.

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

Checked subtraction; returns None when negating the right side, scale alignment, or mantissa addition overflows.

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

Checked multiplication; returns None when scale or mantissa multiplication overflows the fixed decimal representation.

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

Checked division; returns None when the divisor is zero or the rounded fixed-scale result cannot be represented.

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

Round to a given number of decimal places.

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

Truncate toward zero to a given number of decimal places.

pub const fn abs(&self) -> Self

Return the absolute value of the decimal.

pub const fn floor_dp0(&self) -> Self

Return the greatest integral decimal less than or equal to the value.

pub const fn ceil_dp0(&self) -> Self

Return the least integral decimal greater than or equal to the value.

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

Saturating addition.

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

Saturating subtraction.

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

Checked remainder; returns None on division by zero.

pub const fn checked_abs(&self) -> Option<Self>

Checked absolute value; returns None for the one i128::MIN mantissa case that cannot be represented as positive i128.

pub fn powu(&self, exp: u64) -> Self

Integer exponentiation.

pub fn checked_powu(&self, exp: u64) -> Option<Self>

Checked integer exponentiation using the same exponentiation-by-squaring shape as powu, but failing instead of saturating on intermediate multiplication overflow.

impl Decimal

pub const ZERO: Self

pub const fn max_supported_scale() -> u32

Returns the maximum supported decimal scale.

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

Construct a decimal from mantissa and scale.

Panics

Panics when scale exceeds the supported range.

pub const fn try_new(num: i64, scale: u32) -> Option<Self>

Fallible constructor from mantissa and scale.

pub fn from_num<N: NumericValue>(n: N) -> Option<Self>

Fallible conversion from common numeric types.

This path is lossy for float inputs and may lose precision for large values. Prefer exact integer constructors (from_i64, from_u64) or explicit float constructors (from_f32_lossy, from_f64_lossy) when possible.

pub const fn from_i64(n: i64) -> Option<Self>

Exact conversion from i64.

pub const fn from_u64(n: u64) -> Option<Self>

Exact conversion from u64.

pub const fn from_i128(n: i128) -> Option<Self>

Exact conversion from i128.

pub fn from_u128(n: u128) -> Option<Self>

Exact conversion from u128.

pub fn from_f32_lossy(n: f32) -> Option<Self>

Explicit lossy conversion from f32.

Uses decimal text round-tripping from the binary float representation. This is intentionally lossy and should be used only when float input is required.

pub fn from_f64_lossy(n: f64) -> Option<Self>

Explicit lossy conversion from f64.

Uses decimal text round-tripping from the binary float representation. This is intentionally lossy and should be used only when float input is required.

pub const fn parts(&self) -> DecimalParts

PARTS

Decompose into mantissa and scale.

pub const fn is_integer(&self) -> bool

Returns true if the decimal has no fractional component.

pub fn scale_to_integer(&self, target_scale: u32) -> Option<i128>

Scale by 10^target_scale and require an integer result.

Returns None if:

• fractional precision would be lost
• integer overflow occurs

pub fn to_i32(&self) -> Option<i32>

Convert to i32 when the decimal is integral and in range.

pub fn to_i64(&self) -> Option<i64>

Convert to i64 when the decimal is integral and in range.

pub fn to_i128(&self) -> Option<i128>

Convert to i128 when the decimal is integral.

pub fn to_u64(&self) -> Option<u64>

Convert to u64 when the decimal is integral and in range.

pub fn to_u128(&self) -> Option<u128>

Convert to u128 when the decimal is integral and in range.

pub fn to_f32(&self) -> Option<f32>

Convert to f32 when the decimal is finite in f32.

pub fn to_f64(&self) -> Option<f64>

Convert to f64 when the decimal is finite in f64.

pub const fn try_from_i128_with_scale(num: i128, scale: u32) -> Option<Self>

Fallibly build from a raw mantissa and scale.

pub const fn from_i128_with_scale(num: i128, scale: u32) -> Self

Build from a raw mantissa and scale.

Panics

Panics when the mantissa and scale cannot be represented without violating the decimal scale invariant.

pub const fn normalize(&self) -> Self

Normalize trailing zeros.

pub const fn is_sign_negative(&self) -> bool

Returns true if the value is negative.

pub const fn scale(&self) -> u32

Returns the number of fractional decimal places.

pub const fn mantissa(&self) -> i128

Returns the mantissa component.

pub const fn is_zero(&self) -> bool

Returns true if the value is zero.

Trait Implementations

impl Add for Decimal

type Output = Decimal

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign for Decimal

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl CandidType for Decimal

fn _ty() -> Type

fn idl_serialize<S>(&self, serializer: S) -> Result<(), S::Error>

where S: Serializer,

fn ty() -> Type

fn id() -> TypeId

fn _ty_doc() -> TypeDoc

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

fn default() -> Decimal

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, rhs: Self) -> Self::Output

Performs the / operation.

impl DivAssign for Decimal

fn div_assign(&mut self, rhs: Self)

Performs the /= operation.

impl Eq for Decimal

impl From<f32> for Decimal

fn from(n: f32) -> Self

Converts to this type from the input type.

impl From<f64> for Decimal

fn from(n: f64) -> 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<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<i128> for Decimal

fn from(n: i128) -> 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 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<u128> for Decimal

fn from(n: u128) -> Self

Converts to this type from the input type.

impl FromStr for Decimal

type Err = ParseDecimalError

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, rhs: Self) -> Self::Output

Performs the * operation.

impl MulAssign for Decimal

fn mul_assign(&mut self, rhs: Self)

Performs the *= operation.

impl NumericValue for Decimal

fn try_to_decimal(&self) -> Option<Self>

Convert this value into Decimal for generic numeric handling.

fn try_from_decimal(value: Decimal) -> Option<Self>

Rebuild the value from Decimal after generic numeric handling.

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: &Self) -> 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 Rem for Decimal

type Output = Decimal

The resulting type after applying the % operator.

fn rem(self, rhs: Self) -> Self::Output

Performs the % operation.

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, rhs: Self) -> Self::Output

Performs the - operation.

impl SubAssign for Decimal

fn sub_assign(&mut self, rhs: Self)

Performs the -= operation.

impl Sum for Decimal

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

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