Struct Decimal 

pub struct Decimal { /* private fields */ }

Decimal

Owned fixed-point decimal with an explicit i128 mantissa and base-10 scale. Candid and Serde encode and decode decimal text in every format.

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 _ty() -> Type

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

where S: Serializer,

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

type Output = Decimal

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - 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.

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: &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 Product for Decimal

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

Takes an iterator and generates Self from the elements by multiplying the items.

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

fn rem_assign(&mut self, rhs: Self)

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.