Struct dec::Context

pub struct Context<D> { /* private fields */ }

A context for performing decimal operations.

Contexts serve two purposes:

• They configure various properties of decimal arithmetic, like the rounding algorithm to use.

• They accumulate any informational and exceptional conditions raised by decimal operations. Multiple operations can be performed on a context and the status need only be checked once at the end. This can improve performance when performing many decimal operations.

A given context is only valid for use with one decimal type, specified by the D type parameter.

Not all context types support all operations. For example, only the context for the arbitrary-precision decimal type Decimal supports configuring precision.

Implementations

impl<D> Context<D>

pub fn rounding(&self) -> Rounding

Returns the context’s rounding algorithm.

pub fn set_rounding(&mut self, rounding: Rounding)

Set’s the context’s rounding algorithm.

pub fn status(&self) -> Status

Returns the context’s status.

pub fn set_status(&mut self, status: Status)

Sets the context’s status.

pub fn clear_status(&mut self)

Clears the context’s status.

impl<const N: usize> Context<Decimal<N>>

pub fn precision(&self) -> usize

Returns the context’s precision.

Operations that use this context will be rounded to this length if necessary.

pub fn set_precision( &mut self, precision: usize, ) -> Result<(), InvalidPrecisionError>

Sets the context’s precision.

The precision must be at least one and no greater than N * 3.

pub fn clamp(&self) -> bool

Reports whether the context has exponent clamping enabled.

See the clamp field in the documentation of libdecnumber’s decContext module for details.

pub fn set_clamp(&mut self, clamp: bool)

Sets whether the context has exponent clamping enabled.

pub fn max_exponent(&self) -> isize

Returns the context’s maximum exponent.

See the emax field in the documentation of libdecnumber’s decContext module for details.

pub fn set_max_exponent(&mut self, e: isize) -> Result<(), InvalidExponentError>

Sets the context’s maximum exponent.

The maximum exponent must not be negative and no greater than 999,999,999.

pub fn min_exponent(&self) -> isize

Returns the context’s minimum exponent.

See the emin field in the documentation of libdecnumber’s decContext module for details.

pub fn set_min_exponent(&mut self, e: isize) -> Result<(), InvalidExponentError>

Sets the context’s minimum exponent.

The minimum exponent must not be positive and no smaller than -999,999,999.

pub fn parse<S>(&mut self, s: S) -> Result<Decimal<N>, ParseDecimalError>

where S: Into<Vec<u8>>,

Parses a number from its string representation.

pub fn class(&mut self, n: &Decimal<N>) -> Class

Classifies the number.

pub fn abs(&mut self, n: &mut Decimal<N>)

Computes the absolute value of n, storing the result in n.

This has the same effect as Context::<Decimal<N>>::plus unless n is negative, in which case it has the same effect as Context::<Decimal<N>>::minus.

pub fn add<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Adds lhs and rhs, storing the result in lhs.

pub fn and<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Carries out the digitwise logical and of lhs and rhs, storing the result in lhs.

pub fn div<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Divides lhs by rhs, storing the result in lhs.

pub fn div_integer<const M: usize>( &mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>, )

Divides lhs by rhs, storing the integer part of the result in lhs.

pub fn exp(&mut self, n: &mut Decimal<N>)

Raises e to the power of n, storing the result in n.

pub fn fma<const L: usize, const M: usize>( &mut self, x: &mut Decimal<N>, y: &Decimal<L>, z: &Decimal<M>, )

Calculates the fused multiply-add (x * y) + z and stores the result in x.

The multiplication is carried out first and is exact, so this operation only has the one, final rounding.

pub fn from_i32(&mut self, n: i32) -> Decimal<N>

Constructs a number from an i32.

pub fn from_u32(&mut self, n: u32) -> Decimal<N>

Constructs a number from an i32.

pub fn from_i64(&mut self, n: i64) -> Decimal<N>

Constructs a number from an i64.

pub fn from_u64(&mut self, n: u64) -> Decimal<N>

Constructs a number from a u64.

pub fn from_i128(&mut self, n: i128) -> Decimal<N>

Constructs a number from an i128.

Note that this function can return inexact results for numbers with more than N * 3 places of precision, e.g. where N is 12, 9_999_999_999_999_999_999_999_999_999_999_999_999i128, -9_999_999_999_999_999_999_999_999_999_999_999_999i128, i128::MAX, i128::MIN, etc.

However, some numbers more than N * 3 places of precision retain their exactness, e.g. 1_000_000_000_000_000_000_000_000_000_000_000_000i128.

const N: usize = 12;
use dec::Decimal;
let mut ctx = dec::Context::<Decimal::<N>>::default();
let d = ctx.from_i128(i128::MAX);
// Inexact result
assert!(ctx.status().inexact());

let mut ctx = dec::Context::<Decimal::<N>>::default();
let d = ctx.from_i128(1_000_000_000_000_000_000_000_000_000_000_000_000i128);
// Exact result
assert!(!ctx.status().inexact());

To avoid inexact results when converting from large i64, use crate::Decimal128 instead.

pub fn from_u128(&mut self, n: u128) -> Decimal<N>

Constructs a number from an u128.

Note that this function can return inexact results for numbers with more than N * 3 places of precision, e.g. where N is 12, 10_000_000_000_000_000_000_000_000_000_000_001u128 and u128::MAX.

However, some numbers more than N * 3 places of precision retain their exactness, e.g. 10_000_000_000_000_000_000_000_000_000_000_000u128.

const N: usize = 12;
use dec::Decimal;
let mut ctx = dec::Context::<Decimal::<N>>::default();
let d = ctx.from_u128(u128::MAX);
// Inexact result
assert!(ctx.status().inexact());

let mut ctx = dec::Context::<Decimal::<N>>::default();
let d = ctx.from_u128(1_000_000_000_000_000_000_000_000_000_000_000_000u128);
// Exact result
assert!(!ctx.status().inexact());

pub fn try_into_u8(&mut self, d: Decimal<N>) -> Result<u8, TryFromDecimalError>

Attempts to convert d to u8 or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_i8(&mut self, d: Decimal<N>) -> Result<i8, TryFromDecimalError>

Attempts to convert d to i8 or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_u16( &mut self, d: Decimal<N>, ) -> Result<u16, TryFromDecimalError>

Attempts to convert d to u16 or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_i16( &mut self, d: Decimal<N>, ) -> Result<i16, TryFromDecimalError>

Attempts to convert d to i16 or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_i32( &mut self, d: Decimal<N>, ) -> Result<i32, TryFromDecimalError>

Attempts to convert d to i32 or fails if not possible. Note that when returning an error, self’s [context::Status] is set to invalid_operation in addition to using Rust’s Err return value.

Note that this function:

• Accepts any value that can be rescaled to an exponent of 0 without becoming inexact. For example, 123.000 and 123E2 are valid Decimal values.

  The corollary is that values that cannot be rescaled to an exponent of 0 error.

• Errors if self.status() is set to invalid_operation irrespective of whether or not this specific invocation of the function set that status.

pub fn try_into_u32( &mut self, d: Decimal<N>, ) -> Result<u32, TryFromDecimalError>

Attempts to convert d to u32 or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_isize( &mut self, d: Decimal<N>, ) -> Result<isize, TryFromDecimalError>

Attempts to convert d to isize or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_i64( &mut self, d: Decimal<N>, ) -> Result<i64, TryFromDecimalError>

Attempts to convert d to i64 or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_i128( &mut self, d: Decimal<N>, ) -> Result<i128, TryFromDecimalError>

Attempts to convert d to i128 or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_usize( &mut self, d: Decimal<N>, ) -> Result<usize, TryFromDecimalError>

Attempts to convert d to usize or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_u64( &mut self, d: Decimal<N>, ) -> Result<u64, TryFromDecimalError>

Attempts to convert d to u64 or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_u128( &mut self, d: Decimal<N>, ) -> Result<u128, TryFromDecimalError>

Attempts to convert d to u128 or fails if not possible.

Refer to the comments on Self::try_into_i32(), which also apply to this function.

pub fn try_into_f32( &mut self, d: Decimal<N>, ) -> Result<f32, TryFromDecimalError>

Attempts to convert d to f32 or fails if not possible.

Note that this function:

• Errors for values that over- or underflow f32, rather than returning infinity or 0.0, respectively.
• Returns a primitive infinity or NaN if d is an equivalent value.

pub fn try_into_f64( &mut self, d: Decimal<N>, ) -> Result<f64, TryFromDecimalError>

Attempts to convert d to f32 or fails if not possible.

Refer to the comments on Self::try_into_f32(), which also apply to this function.

pub fn from_f32(&mut self, n: f32) -> Decimal<N>

Converts an f32 to a Decimal<N>.

Note that this conversion is infallible because f32’s:

• Maximum precision is ~8
• Min/max exponent is ~ -37, 37

Both of these are guaranteed to fit comfortably within Decimal’s constraints.

pub fn from_f64(&mut self, n: f64) -> Decimal<N>

Converts an f64 to a Decimal<N>.

Note that this conversion is infallible because f64’s:

• Maximum precision is ~18
• Min/max exponent is ~ -305, 305

Both of these are guaranteed to fit comfortably within Decimal’s constraints.

pub fn invert(&mut self, n: &mut Decimal<N>)

Computes the digitwise logical inversion of n, storing the result in n.

pub fn ln(&mut self, n: &mut Decimal<N>)

Computes the natural logarithm of n, storing the result in n.

pub fn log10(&mut self, n: &mut Decimal<N>)

Computes the base-10 logarithm of n, storing the result in n.

pub fn logb(&mut self, n: &mut Decimal<N>)

Computes the adjusted exponent of the number, according to IEEE 754 rules.

pub fn max<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Places whichever of lhs and rhs is larger in lhs.

The comparison is performed using the same rules as for total_cmp.

pub fn max_abs<const M: usize>( &mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>, )

Places whichever of lhs and rhs has the larger absolute value in lhs.

pub fn min<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Places whichever of lhs and rhs is smaller in lhs.

The comparison is performed using the same rules as for total_cmp.

pub fn min_abs<const M: usize>( &mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>, )

Places whichever of lhs and rhs has the smaller absolute value in lhs.

pub fn minus(&mut self, n: &mut Decimal<N>)

Subtracts n from zero, storing the result in n.

pub fn mul<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Multiples lhs by rhs, storing the result in lhs.

pub fn neg(&mut self, n: &mut Decimal<N>)

Negates the sign of n, storing the result in n. Note that unlike minus, no exception or error can occur.

pub fn next_minus(&mut self, n: &mut Decimal<N>)

Computes the next number to n in the direction of negative infinity, storing the result in n.

This operation is a generalization of the IEEE 754 nextDown operation.

pub fn next_plus(&mut self, n: &mut Decimal<N>)

Computes the next number to n in the direction of positive infinity, storing the result in n.

This operation is a generalization of the IEEE 754 nextUp operation.

pub fn next_toward<const M: usize>( &mut self, x: &mut Decimal<N>, y: &Decimal<M>, )

Computes the next number to x in the direction of y, storing the result in x.

This operation is a generalization of the IEEE 754 nextAfter operation.

pub fn or<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Carries out the digitwise logical or of lhs and rhs, storing the result in lhs.

pub fn partial_cmp<const L: usize, const M: usize>( &mut self, lhs: &Decimal<L>, rhs: &Decimal<M>, ) -> Option<Ordering>

Determines the ordering of lhs relative to rhs, using a partial order.

If either lhs or rhs is a NaN, returns None. To force an ordering upon NaNs, use total_cmp.

pub fn plus(&mut self, n: &mut Decimal<N>)

Adds n to zero, storing the result in n.

pub fn pow<const M: usize>(&mut self, x: &mut Decimal<N>, y: &Decimal<M>)

Raises x to the power of y, storing the result in x.

pub fn product<'a, I, const M: usize>(&mut self, iter: I) -> Decimal<N>

where I: Iterator<Item = &'a Decimal<M>>,

Takes product of elements in iter.

pub fn quantize<const M: usize>( &mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>, )

Rounds or pads lhs so that it has the same exponent as rhs, storing the result in lhs.

pub fn reduce(&mut self, n: &mut Decimal<N>)

Reduces n’s coefficient to its shortest possible form without changing the value of the result, storing the result in n.

pub fn rem<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Integer-divides lhs by rhs, storing the remainder in lhs.

pub fn rem_near<const M: usize>( &mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>, )

Like rem, but uses the IEEE 754 rules for remainder operations.

pub fn rescale<const M: usize>( &mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>, )

Rescales lhs to have an exponent of rhs.

pub fn round(&mut self, n: &mut Decimal<N>)

Rounds the number to an integral value using the rounding mode in the context.

pub fn round_to_place( &mut self, n: &mut Decimal<N>, place: usize, ) -> Result<(), InvalidPrecisionError>

Rounds n at a given “place from the left” in the number, akin to a shift right, round, and shift left.

Note that this rounding will not drop integral digits (i.e those representing values at least 1), but can round off fractional values.

place must be at least one and no greater than N * 3, i.e. a valid precision.

pub fn round_reduce_to_place( &mut self, n: &mut Decimal<N>, place: usize, ) -> Result<(), InvalidPrecisionError>

Identical to [round_to_place] but simultaneously performs a [reduce] operation, as well.

pub fn shift<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Shifts the digits of lhs by rhs, storing the result in lhs.

If rhs is positive, shifts to the left. If rhs is negative, shifts to the right. Any digits “shifted in” will be zero.

rhs specifies the number of positions to shift, and must be a finite integer.

pub fn rotate<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Rotates the digits of lhs by rhs, storing the result in lhs.

If rhs is positive, rotates to the left. If rhs is negative, rotates to the right.

rhs specifies the number of positions to rotate, and must be a finite integer.

pub fn scaleb<const M: usize>(&mut self, x: &mut Decimal<N>, y: &Decimal<M>)

Multiplies x by 10^y, storing the result in x.

pub fn sqrt<const M: usize>(&mut self, n: &mut Decimal<M>)

Computes the square root of n, storing the result in n.

pub fn sub<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Subtracts rhs from lhs, storing the result in lhs.

pub fn sum<'a, I, const M: usize>(&mut self, iter: I) -> Decimal<N>

where I: Iterator<Item = &'a Decimal<M>>,

Sums all elements of iter.

pub fn total_cmp<const L: usize, const M: usize>( &mut self, lhs: &Decimal<L>, rhs: &Decimal<M>, ) -> Ordering

Determines the ordering of lhs relative to rhs, using the total order predicate defined in IEEE 754-2008.

For a brief description of the ordering, consult f32::total_cmp.

pub fn xor<const M: usize>(&mut self, lhs: &mut Decimal<N>, rhs: &Decimal<M>)

Carries out the digitwise logical xor of lhs and rhs, storing the result in lhs.

pub fn to_width<const M: usize>(&mut self, m: Decimal<M>) -> Decimal<N>

Returns m cast as a Decimal::<N>.

Context uses similar statuses to arithmetic to express under- and overflow for values whose total precisions exceeds this context’s.

impl Context<Decimal128>

pub fn parse<S>(&mut self, s: S) -> Result<Decimal128, ParseDecimalError>

where S: Into<Vec<u8>>,

Parses a number from its string representation.

pub fn from_decimal<const N: usize>(&mut self, d: &Decimal<N>) -> Decimal128

Constructs a number from an arbitrary-precision decimal.

The result may be inexact. The status fields on the context will be set appropriately if so.

pub fn from_i128(&mut self, n: i128) -> Decimal128

Constructs a number from an i128.

Note that this function can return inexact results for numbers with 35 or more places of precision, e.g. 99_999_999_999_999_999_999_999_999_999_999_999i128, -99_999_999_999_999_999_999_999_999_999_999_999i128, i128::MAX, i128::MIN, etc.

However, some numbers with 35 or more places of precision retain their exactness, e.g. 10_000_000_000_000_000_000_000_000_000_000_000i128.

use dec::Decimal128;
let mut ctx = dec::Context::<Decimal128>::default();
let d = ctx.from_i128(-99_999_999_999_999_999_999_999_999_999_999_999i128);
// Inexact result
assert!(ctx.status().inexact());

let mut ctx = dec::Context::<Decimal128>::default();
let d = ctx.from_i128(10_000_000_000_000_000_000_000_000_000_000_000i128);
// Exact result
assert!(!ctx.status().inexact());

To avoid inexact results when converting from large i64, use crate::Decimal128 instead.

pub fn from_u128(&mut self, n: u128) -> Decimal128

Constructs a number from an u128.

Note that this function can return inexact results for numbers with 35 or more places of precision, e.g., 10_000_000_000_000_000_000_000_000_000_000_001u128 and u128::MAX.

However, some numbers with 15 or more places of precision retain their exactness, e.g. 10_000_000_000_000_000_000_000_000_000_000_000u128.

use dec::Decimal128;
let mut ctx = dec::Context::<Decimal128>::default();
let d = ctx.from_i128(10_000_000_000_000_000_000_000_000_000_000_001i128);
// Inexact result
assert!(ctx.status().inexact());

let mut ctx = dec::Context::<Decimal128>::default();
let d = ctx.from_i128(10_000_000_000_000_000_000_000_000_000_000_000i128);
// Exact result
assert!(!ctx.status().inexact());

pub fn abs(&mut self, n: Decimal128) -> Decimal128

Computes the absolute value of n.

This has the same effect as Context::<Decimal128>::plus unless n is negative, in which case it has the same effect as Context::<Decimal128>::minus.

The returned result will be canonical.

pub fn add(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Adds lhs and rhs.

pub fn and(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Carries out the digitwise logical and of lhs and rhs.

The operands must be valid for logical operations. See Decimal128::is_logical.

pub fn div(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Divides lhs by rhs.

pub fn div_integer(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Divides lhs by rhs and returns the integer part of the result (rounded towards zero) with an exponent of 0.

If the result would overflow, then Status::division_impossible is set.

pub fn fma(&mut self, x: Decimal128, y: Decimal128, z: Decimal128) -> Decimal128

Calculates the fused multiply-add (x * y) + z.

The multiplication is carried out first and is exact, so this operation only has the one, final rounding.

pub fn invert(&mut self, n: Decimal128) -> Decimal128

Carries out the digitwise logical inversion of n.

The operand must be valid for logical operation. See Decimal128::is_logical.

pub fn logb(&mut self, n: Decimal128) -> Decimal128

Computes the adjusted exponent of the number, according to IEEE 754 rules.

pub fn max(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Returns whichever of lhs and rhs is larger. The comparison is performed using the same rules as for Decimal128::total_cmp.

pub fn max_abs(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Returns whichever of lhs and rhs has the largest absolute value.

pub fn min(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Returns whichever of lhs and rhs is smaller. The comparison is performed using the same rules as for Decimal128::total_cmp.

pub fn min_abs(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Returns whichever of lhs and rhs has the largest absolute value.

pub fn minus(&mut self, n: Decimal128) -> Decimal128

Subtracts n from zero.

pub fn mul(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Multiplies lhs by rhs.

pub fn next_minus(&mut self, n: Decimal128) -> Decimal128

Returns the next number to n in the direction of negative infinity.

This operation follows the IEEE 754 rules for the nextDown operation.

pub fn next_plus(&mut self, n: Decimal128) -> Decimal128

Returns the next number to n in the direction of positive infinity.

This operation follows the IEEE 754 rules for the nextUp operation.

pub fn next_toward(&mut self, x: Decimal128, y: Decimal128) -> Decimal128

Returns the next number to x in the direction of y.

This operation follows the IEEE 754 rules for the nextAfter operation.

pub fn partial_cmp( &mut self, lhs: Decimal128, rhs: Decimal128, ) -> Option<Ordering>

Determines the ordering of lhs relative to rhs, using a partial order.

If either lhs or rhs is a NaN, returns None. To force an ordering upon NaNs, use Decimal128::total_cmp.

pub fn plus(&mut self, n: Decimal128) -> Decimal128

Adds n to zero.

pub fn quantize(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Rounds or pads lhs so that it has the same exponent as rhs.

pub fn reduce(&mut self, n: Decimal128) -> Decimal128

Reduces the number’s coefficient to its shortest possible form without changing the value of the result.

This removes all possible trailing zeros; some may remain when the number is very close to the most positive or most negative number.

pub fn rem(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Integer-divides lhs by rhs and returns the remainder from the division.

pub fn rem_near(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Like rem, but uses the IEEE 754 rules for remainder operations.

pub fn rotate(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Rotates the digits of lhs by rhs.

If rhs is positive, rotates to the left. If rhs is negative, rotates to the right.

rhs specifies the number of positions to rotate, and must be a finite integer. NaNs are propagated as usual.

If lhs is infinity, the result is infinity of the same sign.

pub fn round(&mut self, n: Decimal128) -> Decimal128

Rounds the number to an integral value using the rounding mode in the context.

pub fn scaleb(&mut self, x: Decimal128, y: Decimal128) -> Decimal128

Multiplies x by 10^y.

pub fn set_exponent(&mut self, d: &mut Decimal128, e: i32)

Sets d’s exponent to e without modifying the coefficient.

pub fn shift(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Shifts the digits of lhs by rhs.

If rhs is positive, shifts to the left. If rhs is negative, shifts to the right. Any digits “shifted in” will be zero.

rhs specifies the number of positions to shift, and must be a finite integer. NaNs are propagated as usual.

If lhs is infinity, the result is infinity of the same sign.

pub fn rescale(&mut self, x: &mut Decimal128, s: i32)

Adjust x’s exponent to equal s, while retaining as many of the same significant digits of the coefficient as permitted with the current and new exponents.

• When increasing the exponent’s value, irrevocably truncates the least significant digits. Use caution in this context.
• When reducing the exponent’s value, appends 0s as less significant digits.

use dec::{Context, Decimal128};
let mut cx = Context::<Decimal128>::default();
let mut d = cx.div(Decimal128::from(5), Decimal128::from(4));

assert_eq!(d.exponent(), -2);
assert_eq!(d.to_string(), "1.25");

cx.rescale(&mut d, -3);
assert_eq!(d.exponent(), -3);
assert_eq!(d.to_string(), "1.250");

cx.rescale(&mut d, -1);
assert_eq!(d.exponent(), -1);
assert_eq!(d.to_string(), "1.2");

cx.rescale(&mut d, 0);
assert_eq!(d.exponent(), 0);
assert_eq!(d.to_string(), "1");

pub fn sub(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Subtracts rhs from lhs.

pub fn or(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Carries out the digitwise logical or of lhs and rhs.

The operands must be valid for logical operations. See Decimal128::is_logical.

pub fn xor(&mut self, lhs: Decimal128, rhs: Decimal128) -> Decimal128

Carries out the digitwise logical exclusive or of lhs and rhs.

The operands must be valid for logical operations. See Decimal128::is_logical.

impl Context<Decimal32>

pub fn parse<S>(&mut self, s: S) -> Result<Decimal32, ParseDecimalError>

where S: Into<Vec<u8>>,

Parses a number from its string representation.

pub fn from_decimal64(&mut self, d64: Decimal64) -> Decimal32

Constructs a number from a 64-bit decimal float.

The result may be inexact. The status fields on the context will be set appropriately if so.

pub fn from_decimal<const N: usize>(&mut self, d: &Decimal<N>) -> Decimal32

Constructs a number from an arbitrary-precision decimal.

The result may be inexact. The status fields on the context will be set appropriately if so.

impl Context<Decimal64>

pub fn parse<S>(&mut self, s: S) -> Result<Decimal64, ParseDecimalError>

where S: Into<Vec<u8>>,

Parses a number from its string representation.

pub fn from_decimal128(&mut self, d128: Decimal128) -> Decimal64

Constructs a number from a 128-bit decimal float.

The result may be inexact. The status fields on the context will be set appropriately if so.

pub fn from_decimal<const N: usize>(&mut self, d: &Decimal<N>) -> Decimal64

Constructs a number from an arbitrary-precision decimal.

The result may be inexact. The status fields on the context will be set appropriately if so.

pub fn from_i64(&mut self, n: i64) -> Decimal64

Constructs a number from an i64.

Note that this function can return inexact results for numbers with 15 or more places of precision, e.g. 99_999_999_999_999_999i64, -99_999_999_999_999_999i64, i64::MAX, i64::MIN, etc.

However, some numbers with 15 or more places of precision retain their exactness, e.g. 1_000_000_000_000_000i64.

use dec::Decimal64;
let mut ctx = dec::Context::<Decimal64>::default();
let d = ctx.from_i64(-99_999_999_999_999_999i64);
// Inexact result
assert!(ctx.status().inexact());

let mut ctx = dec::Context::<Decimal64>::default();
let d = ctx.from_i64(1_000_000_000_000_000i64);
// Exact result
assert!(!ctx.status().inexact());

To avoid inexact results when converting from large i64, use crate::Decimal128 instead.

pub fn from_u64(&mut self, n: u64) -> Decimal64

Constructs a number from an u64.

Note that this function can return inexact results for numbers with 16 or more places of precision, e.g., 1_000_000_000_000_0001u64 and u64::MAX.

However, some numbers with 15 or more places of precision retain their exactness, e.g. 1_000_000_000_000_000u64.

use dec::Decimal64;
let mut ctx = dec::Context::<Decimal64>::default();
let d = ctx.from_i64(1_000_000_000_000_0001i64);
// Inexact result
assert!(ctx.status().inexact());

let mut ctx = dec::Context::<Decimal64>::default();
let d = ctx.from_i64(1_000_000_000_000_000i64);
// Exact result
assert!(!ctx.status().inexact());

To avoid inexact results when converting from large u64, use crate::Decimal128 instead.

pub fn abs(&mut self, n: Decimal64) -> Decimal64

Computes the absolute value of n.

This has the same effect as Context::<Decimal64>::plus unless n is negative, in which case it has the same effect as Context::<Decimal64>::minus.

The returned result will be canonical.

pub fn add(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Adds lhs and rhs.

pub fn and(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Carries out the digitwise logical and of lhs and rhs.

The operands must be valid for logical operations. See Decimal64::is_logical.

pub fn div(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Divides lhs by rhs.

pub fn div_integer(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Divides lhs by rhs and returns the integer part of the result (rounded towards zero) with an exponent of 0.

If the result would overflow, then Status::division_impossible is set.

pub fn fma(&mut self, x: Decimal64, y: Decimal64, z: Decimal64) -> Decimal64

Calculates the fused multiply-add (x * y) + z.

The multiplication is carried out first and is exact, so this operation only has the one, final rounding.

pub fn invert(&mut self, n: Decimal64) -> Decimal64

Carries out the digitwise logical inversion of n.

The operand must be valid for logical operation. See Decimal64::is_logical.

pub fn logb(&mut self, n: Decimal64) -> Decimal64

Computes the adjusted exponent of the number, according to IEEE 754 rules.

pub fn max(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Returns whichever of lhs and rhs is larger. The comparison is performed using the same rules as for Decimal64::total_cmp.

pub fn max_abs(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Returns whichever of lhs and rhs has the largest absolute value.

pub fn min(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Returns whichever of lhs and rhs is smaller. The comparison is performed using the same rules as for Decimal64::total_cmp.

pub fn min_abs(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Returns whichever of lhs and rhs has the largest absolute value.

pub fn minus(&mut self, n: Decimal64) -> Decimal64

Subtracts n from zero.

pub fn mul(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Multiplies lhs by rhs.

pub fn next_minus(&mut self, n: Decimal64) -> Decimal64

Returns the next number to n in the direction of negative infinity.

This operation follows the IEEE 754 rules for the nextDown operation.

pub fn next_plus(&mut self, n: Decimal64) -> Decimal64

Returns the next number to n in the direction of positive infinity.

This operation follows the IEEE 754 rules for the nextUp operation.

pub fn next_toward(&mut self, x: Decimal64, y: Decimal64) -> Decimal64

Returns the next number to x in the direction of y.

This operation follows the IEEE 754 rules for the nextAfter operation.

pub fn partial_cmp( &mut self, lhs: Decimal64, rhs: Decimal64, ) -> Option<Ordering>

Determines the ordering of lhs relative to rhs, using a partial order.

If either lhs or rhs is a NaN, returns None. To force an ordering upon NaNs, use Decimal64::total_cmp or OrderedDecimal.

pub fn plus(&mut self, n: Decimal64) -> Decimal64

Adds n to zero.

pub fn quantize(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Rounds or pads lhs so that it has the same exponent as rhs.

pub fn reduce(&mut self, n: Decimal64) -> Decimal64

Reduces the number’s coefficient to its shortest possible form without changing the value of the result.

This removes all possible trailing zeros; some may remain when the number is very close to the most positive or most negative number.

pub fn rem(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Integer-divides lhs by rhs and returns the remainder from the division.

pub fn rem_near(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Like rem, but uses the IEEE 754 rules for remainder operations.

pub fn rotate(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Rotates the digits of lhs by rhs.

If rhs is positive, rotates to the left. If rhs is negative, rotates to the right.

rhs specifies the number of positions to rotate, and must be a finite integer. NaNs are propagated as usual.

If lhs is infinity, the result is infinity of the same sign.

pub fn round(&mut self, n: Decimal64) -> Decimal64

Rounds the number to an integral value using the rounding mode in the context.

pub fn scaleb(&mut self, x: Decimal64, y: Decimal64) -> Decimal64

Multiplies x by 10^y.

pub fn set_exponent(&mut self, d: &mut Decimal64, e: i32)

Sets d’s exponent to e without modifying the coefficient.

pub fn shift(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Shifts the digits of lhs by rhs.

If rhs is positive, shifts to the left. If rhs is negative, shifts to the right. Any digits “shifted in” will be zero.

rhs specifies the number of positions to shift, and must be a finite integer. NaNs are propagated as usual.

If lhs is infinity, the result is infinity of the same sign.

pub fn rescale(&mut self, x: &mut Decimal64, s: i32)

Adjust x’s exponent to equal s, while retaining as many of the same significant digits of the coefficient as permitted with the current and new exponents.

• When increasing the exponent’s value, irrevocably truncates the least significant digits. Use caution in this context.
• When reducing the exponent’s value, appends 0s as less significant digits.

use dec::{Context, Decimal64};
let mut cx = Context::<Decimal64>::default();
let mut d = cx.div(Decimal64::from(5), Decimal64::from(4));

assert_eq!(d.exponent(), -2);
assert_eq!(d.to_string(), "1.25");

cx.rescale(&mut d, -3);
assert_eq!(d.exponent(), -3);
assert_eq!(d.to_string(), "1.250");

cx.rescale(&mut d, -1);
assert_eq!(d.exponent(), -1);
assert_eq!(d.to_string(), "1.2");

cx.rescale(&mut d, 0);
assert_eq!(d.exponent(), 0);
assert_eq!(d.to_string(), "1");

pub fn sub(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Subtracts rhs from lhs.

pub fn or(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Carries out the digitwise logical or of lhs and rhs.

The operands must be valid for logical operations. See Decimal64::is_logical.

pub fn xor(&mut self, lhs: Decimal64, rhs: Decimal64) -> Decimal64

Carries out the digitwise logical exclusive or of lhs and rhs.

The operands must be valid for logical operations. See Decimal64::is_logical.

Trait Implementations

impl<D: Clone> Clone for Context<D>

fn clone(&self) -> Context<D>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<D> Debug for Context<D>

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

Formats the value using the given formatter.

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

fn default() -> Context<Decimal<N>>

Returns the “default value” for a type.

impl Default for Context<Decimal128>

fn default() -> Context<Decimal128>

Returns the “default value” for a type.

impl Default for Context<Decimal32>

fn default() -> Context<Decimal32>

Returns the “default value” for a type.

impl Default for Context<Decimal64>

fn default() -> Context<Decimal64>

Returns the “default value” for a type.