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
Set’s the context’s rounding algorithm.
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.
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
.
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 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
and123E2
are validDecimal
values.The corollary is that values that cannot be rescaled to an exponent of 0 error.
-
Errors if
self.status()
is set toinvalid_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 or0.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
.
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
.
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.
pub fn round_to_place(
&mut self,
n: &mut Decimal<N>,
place: usize
) -> Result<(), InvalidPrecisionError>
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>
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.
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
.
pub fn parse<S>(&mut self, s: S) -> Result<Decimal128, ParseDecimalError> where
S: Into<Vec<u8>>,
pub fn parse<S>(&mut self, s: S) -> Result<Decimal128, ParseDecimalError> where
S: Into<Vec<u8>>,
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
0
s 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.
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
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.
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
.
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.
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
0
s 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");
Carries out the digitwise logical or of lhs
and rhs
.
The operands must be valid for logical operations.
See Decimal64::is_logical
.
Trait Implementations
Auto Trait Implementations
impl<D> RefUnwindSafe for Context<D> where
D: RefUnwindSafe,
impl<D> UnwindSafe for Context<D> where
D: UnwindSafe,
Blanket Implementations
Mutably borrows from an owned value. Read more