Struct dec::Decimal

#[repr(C)]
pub struct Decimal<const N: usize> { /* private fields */ }

An arbitrary-precision decimal number.

The maximum number of digits that can be stored in the number is specified by N * 3. For example, a value of type Decimal<3> has space for nine decimal digits. This somewhat odd design is due to limitations of constant generic parameters in Rust. The intention is to someday make N correspond directly to the number of digits of precision.

N must be at least 12 and no greater than 999,999,999, though typically the stack size implies a smaller maximum for N. Due to limitations with constant generics it is not yet possible to enforce these restrictions at compile time, so they are checked at runtime.

For more details about e.g. the struct’s fields, see the upstream documentation.

Implementations

impl<const N: usize> Decimal<N>

pub fn zero() -> Decimal<N>

Constructs a decimal number with N / 3 digits of precision representing the number 0.

pub fn infinity() -> Decimal<N>

Constructs a decimal number representing positive infinity.

pub fn nan() -> Decimal<N>

Constructs a decimal number representing a non-signaling NaN.

pub fn digits(&self) -> u32

Computes the number of significant digits in the number.

If the number is zero or infinite, returns 1. If the number is a NaN, returns the number of digits in the payload.

pub fn coefficient_digits(&self) -> Vec<u8>

Returns the individual digits of the coefficient in 8-bit, unpacked binary-coded decimal format.

pub fn coefficient_units(&self) -> &[u16]

Returns the digits of the coefficient in [decNumberUnit][dnu] format, which is a vector of u16, with element number representing decnumber_sys::DECDPUN digits of the coefficient.

The result is ordered with the least significant digits at index 0.

pub fn coefficient<T>(&mut self) -> Result<T, InvalidCoefficientError> where
    T: TryFrom<Decimal<N>>, 

Returns the value’s coefficient as T or errors if not possible.

All primitive ints are valid for T.

pub fn digits_to_lsu_elements_len(digits: u32) -> usize

Returns the number of elements required in the lsu to represent some number of digits.

This function is public and accepts a u32 instead of a Decimal to aid in recomposing (Self::from_raw_parts) values.

pub fn exponent(&self) -> i32

Computes the exponent of the number.

pub fn set_exponent(&mut self, exponent: i32)

Sets self’s exponent to the provided value.

pub fn is_finite(&self) -> bool

Reports whether the number is finite.

A finite number is one that is neither infinite nor a NaN.

pub fn is_infinite(&self) -> bool

Reports whether the number is positive or negative infinity.

pub fn is_nan(&self) -> bool

Reports whether the number is a NaN.

pub fn is_negative(&self) -> bool

Reports whether the number is negative.

A negative number is either negative zero, less than zero, or NaN with a sign of one. This corresponds to Decimal128::is_signed, not Decimal128::is_negative.

pub fn is_quiet_nan(&self) -> bool

Reports whether the number is a quiet NaN.

pub fn is_signaling_nan(&self) -> bool

Reports whether the number is a signaling NaN.

pub fn is_special(&self) -> bool

Reports whether the number has a special value.

A special value is either infinity or NaN. This is the inverse of Decimal::is_finite.

pub fn is_zero(&self) -> bool

Reports whether the number is positive or negative zero.

pub fn quantum_matches(&self, rhs: &Decimal<N>) -> bool

Reports whether the quantum of the number matches the quantum of rhs.

Quantums are considered to match if the numbers have the same exponent, are both NaNs, or both infinite.

pub fn to_decimal32(&self) -> Decimal32

Converts this decimal to a 32-bit decimal float.

The result may be inexact. Use Context::<Decimal32>::from_decimal to observe exceptional conditions.

pub fn to_decimal64(&self) -> Decimal64

Converts this decimal to a 64-bit decimal float.

The result may be inexact. Use Context::<Decimal64>::from_decimal to observe exceptional conditions.

pub fn to_decimal128(&self) -> Decimal128

Converts this decimal to a 128-bit decimal float.

The result may be inexact. Use Context::<Decimal128>::from_decimal to observe exceptional conditions.

pub fn to_raw_parts(&self) -> (u32, i32, u8, &[u16])

Returns the raw parts of this decimal, with the u16 elements of lsu converted to u8.

The meaning of these parts are unspecified and subject to change.

pub fn from_raw_parts(
    digits: u32,
    exponent: i32,
    bits: u8,
    lsu_in: &[u16]
) -> Self

Returns a Decimal::<N> with the supplied raw parts, which should be generated using Decimal::to_raw_parts on a machine with compatible architecture.

Panics

If lsu_in is not a slice with the number of digits implicitly specified by the digits parameter, i.e. essentially ceil(digits / decnumber_sys::DECDPUN).

pub fn to_packed_bcd(&mut self) -> Option<(Vec<u8>, i32)>

Returns self as a Packed Decimal number, including its scale (i.e. its negated exponent) or None for special values.

pub fn from_packed_bcd(
    bcd: &[u8],
    scale: i32
) -> Result<Decimal<N>, FromBcdError>

Takes Packed Decimal values and their scales (generated by Self::to_packed_bcd) and returns a Decimal.

Errors

• bcd contains more digits than the coefficient permits
• The adjusted exponent is out of range
• No sign nibble was found
• A sign nibble was found before the final nibble

pub fn to_standard_notation_string(&self) -> String

Returns a string of the number in standard notation, i.e. guaranteed to not be scientific notation.

pub fn trim(&mut self)

Removes insignificant trailing zeros from a number, unconditionally, and stores the modified value in self.

Trait Implementations

impl<const M: usize, const N: usize> Add<Decimal<M>> for Decimal<N>

fn add(self, rhs: Decimal<M>) -> Self

Note that this clones self to generate the output. For a non-cloning method, use Context::<N>::add.

type Output = Self

The resulting type after applying the + operator.

impl<const M: usize, const N: usize> AddAssign<Decimal<M>> for Decimal<N>

fn add_assign(&mut self, rhs: Decimal<M>)

Performs the += operation.

impl<const N: usize> Clone for Decimal<N>

fn clone(&self) -> Decimal<N>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<const N: usize> Debug for Decimal<N>

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

Formats the value using the given formatter.

impl<const N: usize> Default for Decimal<N>

fn default() -> Decimal<N>

Returns the “default value” for a type.

impl<'de, const N: usize> Deserialize<'de> for Decimal<N>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<const N: usize> Display for Decimal<N>

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

Formats the value using the given formatter.

impl<const M: usize, const N: usize> Div<Decimal<M>> for Decimal<N>

fn div(self, rhs: Decimal<M>) -> Self

Note that this clones self to generate the output. For a non-cloning method, use Context::<N>::div.

type Output = Self

The resulting type after applying the / operator.

impl<const M: usize, const N: usize> DivAssign<Decimal<M>> for Decimal<N>

fn div_assign(&mut self, rhs: Decimal<M>)

Performs the /= operation.

impl<const N: usize> From<Decimal128> for Decimal<N>

fn from(n: Decimal128) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<Decimal32> for Decimal<N>

fn from(n: Decimal32) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<Decimal64> for Decimal<N>

fn from(n: Decimal64) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<f32> for Decimal<N>

fn from(n: f32) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<f64> for Decimal<N>

fn from(n: f64) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<i16> for Decimal<N>

fn from(n: i16) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<i32> for Decimal<N>

fn from(n: i32) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<i64> for Decimal<N>

fn from(n: i64) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<i8> for Decimal<N>

fn from(n: i8) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<isize> for Decimal<N>

fn from(n: isize) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<u16> for Decimal<N>

fn from(n: u16) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<u32> for Decimal<N>

fn from(n: u32) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<u64> for Decimal<N>

fn from(n: u64) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<u8> for Decimal<N>

fn from(n: u8) -> Decimal<N>

Performs the conversion.

impl<const N: usize> From<usize> for Decimal<N>

fn from(n: usize) -> Decimal<N>

Performs the conversion.

impl<const N: usize> FromStr for Decimal<N>

type Err = ParseDecimalError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Decimal<N>, ParseDecimalError>

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

impl<const M: usize, const N: usize> Mul<Decimal<M>> for Decimal<N>

fn mul(self, rhs: Decimal<M>) -> Self

Note that this clones self to generate the output. For a non-cloning method, use Context::<N>::mul.

type Output = Self

The resulting type after applying the * operator.

impl<const M: usize, const N: usize> MulAssign<Decimal<M>> for Decimal<N>

fn mul_assign(&mut self, rhs: Decimal<M>)

Performs the *= operation.

impl<const N: usize> Neg for Decimal<N>

fn neg(self) -> Decimal<N>

Note that this clones self to generate the negative value. For a non-cloning method, use Context::<N>::neg.

type Output = Decimal<N>

The resulting type after applying the - operator.

impl<const N: usize> PartialEq<Decimal<N>> for Decimal<N>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<const N: usize> PartialOrd<Decimal<N>> for Decimal<N>

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<'a, const M: usize, const N: usize> Product<&'a Decimal<M>> for Decimal<N>

fn product<I>(iter: I) -> Self where
    I: Iterator<Item = &'a Decimal<M>>, 

Method which takes an iterator and generates Self from the elements by multiplying the items.

impl<const M: usize, const N: usize> Product<Decimal<M>> for Decimal<N>

fn product<I>(iter: I) -> Self where
    I: Iterator<Item = Decimal<M>>, 

Method which takes an iterator and generates Self from the elements by multiplying the items.

impl<const M: usize, const N: usize> Rem<Decimal<M>> for Decimal<N>

fn rem(self, rhs: Decimal<M>) -> Self

Note that this clones self to generate the output. For a non-cloning method, use Context::<N>::rem.

type Output = Self

The resulting type after applying the % operator.

impl<const M: usize, const N: usize> RemAssign<Decimal<M>> for Decimal<N>

fn rem_assign(&mut self, rhs: Decimal<M>)

Performs the %= operation.

impl<const N: usize> Serialize for Decimal<N>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl<const M: usize, const N: usize> Sub<Decimal<M>> for Decimal<N>

fn sub(self, rhs: Decimal<M>) -> Self

Note that this clones self to generate the output. For a non-cloning method, use Context::<N>::sub.

type Output = Self

The resulting type after applying the - operator.

impl<const M: usize, const N: usize> SubAssign<Decimal<M>> for Decimal<N>

fn sub_assign(&mut self, rhs: Decimal<M>)

Performs the -= operation.

impl<'a, const M: usize, const N: usize> Sum<&'a Decimal<M>> for Decimal<N>

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

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl<const M: usize, const N: usize> Sum<Decimal<M>> for Decimal<N>

fn sum<I>(iter: I) -> Self where
    I: Iterator<Item = Decimal<M>>, 

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl<const N: usize> TryFrom<Decimal<N>> for i8

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<i8, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for u8

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<u8, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for usize

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<usize, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for isize

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<isize, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for f32

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<f32, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for f64

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<f64, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for i16

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<i16, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for u16

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<u16, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for i32

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<i32, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for u32

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<u32, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for i64

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<i64, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for u64

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<u64, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for i128

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<i128, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Decimal<N>> for u128

Refer to the comments on Context<Decimal<N>>::try_into_i32(), which also apply to this trait.

type Error = TryFromDecimalError

The type returned in the event of a conversion error.

fn try_from(n: Decimal<N>) -> Result<u128, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<i128> for Decimal<N>

Generates a Decimal from an i128 or fails if the result would be imprecise, e.g. has more than N*3 digits of precision.

For an infallible version of this function, see Context<Decimal<N>>::from_i128.

type Error = TryIntoDecimalError

The type returned in the event of a conversion error.

fn try_from(n: i128) -> Result<Decimal<N>, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<u128> for Decimal<N>

Generates a Decimal from a u128 or fails if the result would be imprecise, e.g. has more than N*3 digits of precision.

For an infallible version of this function, see Context<Decimal<N>>::from_u128.

type Error = TryIntoDecimalError

The type returned in the event of a conversion error.

fn try_from(n: u128) -> Result<Decimal<N>, Self::Error>

Performs the conversion.

impl<const N: usize> Copy for Decimal<N>