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

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

Returns the context’s rounding algorithm.

Set’s the context’s rounding algorithm.

Returns the context’s status.

Sets the context’s status.

Clears the context’s status.

Returns the context’s precision.

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

Sets the context’s precision.

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

Reports whether the context has exponent clamping enabled.

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

Sets whether the context has exponent clamping enabled.

Returns the context’s maximum exponent.

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

Sets the context’s maximum exponent.

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

Returns the context’s minimum exponent.

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

Sets the context’s minimum exponent.

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

Parses a number from its string representation.

Classifies the number.

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.

Adds lhs and rhs, storing the result in lhs.

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

Divides lhs by rhs, storing the result in lhs.

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

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

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.

Constructs a number from an i32.

Constructs a number from an i32.

Constructs a number from an i64.

Constructs a number from a u64.

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.

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());

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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

Places whichever of lhs and rhs is larger in lhs.

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

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

Places whichever of lhs and rhs is smaller in lhs.

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

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

Subtracts n from zero, storing the result in n.

Multiples lhs by rhs, storing the result in lhs.

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

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.

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.

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.

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

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.

Adds n to zero, storing the result in n.

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

Takes product of elements in iter.

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

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

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

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

Rescales lhs to have an exponent of rhs.

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

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.

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

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.

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.

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

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

Subtracts rhs from lhs, storing the result in lhs.

Sums all elements of iter.

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.

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

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.

Parses a number from its string representation.

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.

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.

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());

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.

Adds lhs and rhs.

Carries out the digitwise logical and of lhs and rhs.

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

Divides lhs by rhs.

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.

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.

Carries out the digitwise logical inversion of n.

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

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

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

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

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

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

Subtracts n from zero.

Multiplies lhs by rhs.

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

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

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

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

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

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

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.

Adds n to zero.

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

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.

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

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

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.

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

Multiplies x by 10y.

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

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.

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");

Subtracts rhs from lhs.

Carries out the digitwise logical or of lhs and rhs.

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

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

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

Parses a number from its string representation.

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.

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.

Parses a number from its string representation.

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.

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.

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.

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.

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.

Adds lhs and rhs.

Carries out the digitwise logical and of lhs and rhs.

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

Divides lhs by rhs.

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.

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.

Carries out the digitwise logical inversion of n.

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

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

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

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

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

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

Subtracts n from zero.

Multiplies lhs by rhs.

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

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

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

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

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

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

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.

Adds n to zero.

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

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.

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

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

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.

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

Multiplies x by 10y.

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

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.

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");

Subtracts rhs from lhs.

Carries out the digitwise logical or of lhs and rhs.

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

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

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more
Returns the “default value” for a type. Read more
Returns the “default value” for a type. Read more
Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.