Decimal class
Exact constructors
-
class
Decimal
-
Decimal
() Default constructor. The value is initialized to a signaling NaN.
-
Decimal
(const Decimal &other) Exact construction by copying the argument.
-
Decimal
(const Decimal &&other) Exact construction by moving the argument. The argument is reset to a signaling NaN, so it is still in a valid state.
-
Decimal
(const T &other) Exact integer conversions. T is one of:
int8_t uint8_t int16_t uint16_t int32_t uint32_t int64_t uint64_t signed char unsigned char short unsigned short int unsigned int long unsigned long long long unsigned long long Since construction is always exact, it is safe to allow implicit conversions.
-
explicit
Decimal
(const char *const s) Exact conversion from a C string. If an internal limit is exceeded (e.g. the exponent exceeds MAX_EMAX), InvalidOperation is set and the result is NaN.
Raises ValueError if the argument is NULL.
-
explicit
Decimal
(const std::string &s) Exact conversion from a std::string. If an internal limit is exceeded (e.g. the exponent exceeds MAX_EMAX), InvalidOperation is set and the result is NaN.
-
Inexact constructors
- explicit
Decimal
(const T &other, Context &c)Inexact integer conversions according to the context. T is one of:
int8_t uint8_t int16_t uint16_t int32_t uint32_t int64_t uint64_t signed char unsigned char short unsigned short int unsigned int long unsigned long long long unsigned long long
- explicit
Decimal
(const char *const s, Context &c)Inexact conversion from a C string according to the context. If an internal limit is exceeded (e.g. the exponent exceeds MAX_EMAX), InvalidOperation is set and the result is NaN.
Raises ValueError if the argument is NULL.
- explicit
Decimal
(const std::string &s, Context &c)Inexact conversion from a std::string according to the context. If an internal limit is exceeded (e.g. the exponent exceeds MAX_EMAX), InvalidOperation is set and the result is NaN.
Accessors
- mpd_t *
get
()Return a pointer to the private mpd_t. This should only be used for passing a Decimal’s internal value to libmpdec functions, where the Decimal is in the output position.
This is an advanced function that is not necessary for normal use.
- const mpd_t *
getconst
() constReturn a const pointer to the private mpd_t. This should only be used for passing a Decimal’s internal value to libmpdec functions, where the Decimal is in the input position.
This is an advanced function that is not necessary for normal use.
- int
sign
() constReturn the arithmetic sign of the Decimal: 1 for positive values, -1 for negative values.
- Decimal
coeff
() constReturn the coefficient of the Decimal. If the Decimal is a special value, raise ValueError.
- int64_t
exponent
() constReturn the exponent of the Decimal. If the Decimal is a special value, raise ValueError.
- Decimal
payload
() constReturn the NaN payload of the Decimal. The default value for NaNs without a payload is 0.
If the Decimal is not a NaN, raise ValueError.
Exact assignment operators
- Decimal &
operator=
(const Decimal &other)Make an exact copy of the argument. This function can raise MallocError if self is an arbitrary precision Decimal with a very large coefficient. In practice this does not occur with regular context precisions from 9 to 38 digits.
Copying has a strong exception guarantee, so the lvalue is unchanged in case of MallocError.
Inexact assignment operators
Exact comparison operators
- bool
operator==
(const Decimal &other) constDetermine if the values are exactly equal. Infinities compare equal if the signs are equal. Quiet NaNs are not equal to anything else (including quiet NaNs).
Signaling NaNs set InvalidOperation, using the thread local context.
- bool
operator!=
(const Decimal &other) constDetermine if the values are not equal. The above rules apply (adapted for !=).
- bool
operator<
(const Decimal &other) constDetermine if self < other. In the case of ordering comparisons quiet NaNs also set InvalidOperation.
- bool
operator<=
(const Decimal &other) constDetermine if self <= other. In the case of ordering comparisons quiet NaNs also set InvalidOperation.
- bool
operator>=
(const Decimal &other) constDetermine if self >= other. In the case of ordering comparisons quiet NaNs also set InvalidOperation.
- bool
operator>
(const Decimal &other) constDetermine if self > other. In the case of ordering comparisons quiet NaNs also set InvalidOperation.
Exact reverse comparison operators
Reverse comparison operators. T is one of:
int8_t uint8_t int16_t uint16_t int32_t uint32_t int64_t uint64_t signed char unsigned char short unsigned short int unsigned int long unsigned long long long unsigned long long
- bool
operator==
(const T &other, const Decimal &self)
- bool
operator!=
(const T &other, const Decimal &self)
- bool
operator<
(const T &other, const Decimal &self)
- bool
operator<=
(const T &other, const Decimal &self)
- bool
operator>=
(const T &other, const Decimal &self)
- bool
operator>
(const T &other, const Decimal &self)
Unary arithmetic operators
- Decimal
operator-
() constNegate the input operand. This function is equivalent to Decimal.minus and applies the thread local context. Note that positive zeros keep their sign, unless the rounding is set to ROUND_FLOOR.
- Decimal
operator+
() constReturn the input operand after applying the thread local context. This function is equivalent to Decimal.plus. Note that negative zeros lose their sign, unless the rounding is set to ROUND_FLOOR.
Binary arithmetic operators
- Decimal
operator+
(const Decimal &other) constReturn self + other. The operation is performed on the unrounded input operands and has a single final rounding step. The thread local context is used.
Same as self.add(other, context).
- Decimal
operator-
(const Decimal &other) constReturn self - other. The operation is performed on the unrounded input operands and has a single final rounding step. The thread local context is used.
Same as self.sub(other, context).
- Decimal
operator*
(const Decimal &other) constReturn self * other. The operation is performed on the unrounded input operands and has a single final rounding step. The thread local context is used.
Same as self.mul(other, context).
Reverse binary arithmetic operators
Reverse binary arithmetic operators. T is one of:
int8_t uint8_t int16_t uint16_t int32_t uint32_t int64_t uint64_t signed char unsigned char short unsigned short int unsigned int long unsigned long long long unsigned long long
Predicates
- bool
isfinite
() constReturn true if self is a finite number, and false if self is infinite or a quiet or signaling NaN.
- bool
isinfinite
() constReturn true if self is either a positive or negative infinity and false otherwise.
- bool
isspecial
() constReturn true if self is a quiet or signaling NaN or infinite, false otherwise.
- bool
isnan
() constReturn true if self is a quiet or signaling NaN and false otherwise.
- bool
isqnan
() constReturn true if self is a quiet NaN, and false otherwise.
- bool
issnan
() constReturn true if self is a signaling NaN and false otherwise.
- bool
issigned
() constReturn true if self has a negative sign and false otherwise. Note that both zeros and NaNs can carry signs.
- bool
iszero
() constReturn true if self is a positive or negative zero, false otherwise.
- bool
isinteger
() constDetermine whether self is an integer. The exponent of an integer is not necessarily zero and may be negative if the coefficient has trailing zeros.
Predicates with an optional context argument
- bool
isnormal
(const Context &c = context)Return true if self is a normal finite non-zero number with an adjusted exponent greater than or equal to emin. Return false if self is zero, subnormal, infinite or a quiet or signaling NaN.
- bool
issubnormal
(const Context &c = context)Return true if self is subnormal, and false otherwise. A number is subnormal if it is non-zero, finite, and has an adjusted exponent less than emin.
Unary functions, no context argument
- int64_t
adjexp
() constReturn the adjusted exponent of self. Defined as exp + digits - 1. Raises ValueError for special values.
- Decimal
copy_abs
() constReturn an exact copy of the absolute value of self. In contrast to Decimal.abs, this function does not use the thread local context.
- Decimal
copy_negate
() constReturn an exact copy of the negation of self. In contrast to -self, this function does not use the thread local context.
Unary functions, optional context argument
- std::string
number_class
(Context &c = context)Return a string describing the class of the operand. The returned value is one of the following ten strings:
- “-Infinity”, indicating that the operand is negative infinity.
- “-Normal”, indicating that the operand is a negative normal number.
- “-Subnormal”, indicating that the operand is negative and subnormal.
- “-Zero”, indicating that the operand is a negative zero.
- “+Zero”, indicating that the operand is a positive zero.
- “+Subnormal”, indicating that the operand is positive and subnormal.
- “+Normal”, indicating that the operand is a positive normal number.
- “+Infinity”, indicating that the operand is positive infinity.
- “NaN”, indicating that the operand is a quiet NaN (Not a Number).
- “sNaN”, indicating that the operand is a signaling NaN`.
- Decimal
exp
(Context &c = context) constReturn the value of the exponential function e**x at the given number. The function always uses the ROUND_HALF_EVEN mode.
If c.allcr() == 1, the result is always correctly rounded.
- Decimal
invroot
(Context &c = context) constReturn the reciprocal of the square root of self. The function always uses the ROUND_HALF_EVEN mode. Results are not correctly rounded, even if the allcr context field is set to 1. This might change in a future release.
- Decimal
ln
(Context &c = context) constReturn the natural (base e) logarithm of the operand. The function always uses the ROUND_HALF_EVEN mode.
If c.allcr() == 1, the result is always correctly rounded.
- Decimal
log10
(Context &c = context) constReturn the base ten logarithm of the operand. The function always uses the ROUND_HALF_EVEN mode.
If c.allcr() == 1, the result is always correctly rounded.
- Decimal
logb
(Context &c = context) constFor a non-zero number, return the adjusted exponent of the operand as a Decimal instance. If the operand is a zero, then Decimal(“-Infinity”) is returned and the DivisionByZero condition is raised. If the operand is an infinity then Decimal(“Infinity”) is returned.
- Decimal
minus
(Context &c = context) constNegate the input operand and apply the context. Note that positive zeros keep their sign, unless the rounding is set to ROUND_FLOOR.
- Decimal
next_minus
(Context &c = context) constReturn the largest number representable in the given context that is smaller than the given operand.
- Decimal
next_plus
(Context &c = context) constReturn the smallest number representable in the given context that is larger than the given operand.
- Decimal
plus
(Context &c = context) constCopy the input operand and apply the context. Note that negative zeros lose their sign, unless the rounding is set to ROUND_FLOOR.
- Decimal
reduce
(Context &c = context) constNormalize the number by stripping the rightmost trailing zeros and converting any result equal to Decimal(“0”) to Decimal(“0e0”).
Used for producing representative values for members of an equivalence class. For example, Decimal(“32.100”) and Decimal(“0.321000e+2”) both normalize to the equivalent value Decimal(“32.1”).
- Decimal
to_integral
(Context &c = context) constRound to the nearest integer without signaling Inexact or Rounded. The rounding mode is determined by the by the given context.
- Decimal
to_integral_exact
(Context &c = context) constRound to the nearest integer, signaling Inexact or Rounded as appropriate if rounding occurs. The rounding mode is determined by the rounding parameter if given, else by the given context. If neither parameter is given, then the rounding mode of the current default context is used.
Note that the use of exact in this name is determined by the specification and differs from the terminology in libmpdec++.
Binary functions, no context argument
- Decimal
compare_total
(const Decimal &other) constCompare two operands using their abstract representation rather than their numerical value. Similar to Decimal.compare, but the result gives a total ordering on Decimal instances. Two Decimal instances with the same numeric value but different representations compare unequal in this ordering:
Decimal("12.0").compare_total(Decimal("12")) == Decimal("-1")Quiet and signaling NaNs are also included in the total ordering. The result of this function is Decimal(“0”) if both operands have the same representation, Decimal(“-1”) if the first operand is lower in the total order than the second, and Decimal(“1”) if the first operand is higher in the total order than the second operand. See the specification for details of the total order.
This operation is unaffected by context and is quiet: no flags are changed and no rounding is performed.
- Decimal
compare_total_mag
(const Decimal &other) constCompare two operands using their abstract representation rather than their value as in Decimal.compare_total, but ignoring the sign of each operand.
x.compare_total_mag(y) == x.copy_abs().compare_total(y.copy_abs())This operation is unaffected by context and is quiet: no flags are changed and no rounding is performed.
Binary functions, optional context argument
- Decimal
divint
(const Decimal &other, Context &c = context) constReturn self divided by other, truncated to an integer.
- Decimal
compare
(const Decimal &other, Context &c = context) constCompare self to other. Return a decimal value:
a.issnan() || b.issnan() => InvalidOperation a.isqnan() || b.isqnan() => Decimal("NaN") a < b => Decimal("-1") a == b => Decimal("0") a > b => Decimal("1")
- Decimal
compare_signal
(const Decimal &other, Context &c = context) constCompare self to other. Return a decimal value:
a.issnan() || b.issnan() => InvalidOperation a.isqnan() || b.isqnan() => InvalidOperation a < b => Decimal("-1") a == b => Decimal("0") a > b => Decimal("1")
- Decimal
max
(const Decimal &other, Context &c = context) constMaximum of self and other. NOTE: If one operand is a quiet NaN and the other is numeric, the numeric operand is returned.
- Decimal
max_mag
(const Decimal &other, Context &c = context) constSimilar to Decimal.max, but the comparison is done using the absolute values of the operands.
- Decimal
min
(const Decimal &other, Context &c = context) constMinimum of self and other. NOTE: If one operand is a quiet NaN and the other is numeric, the numeric operand is returned.
- Decimal
min_mag
(const Decimal &other, Context &c = context) constSimilar to Decimal.min, but the comparison is done using the absolute values of the operands.
- Decimal
next_toward
(const Decimal &other, Context &c = context) constIf the two operands are unequal, return the number closest to the first operand in the direction of the second operand. If both operands are numerically equal, return a copy of the first operand with the sign set to be the same as the sign of the second operand.
- Decimal
pow
(const Decimal &other, Context &c = context) constCompute self raised to the power of other. If self is negative, then other must be integral. The result will be inexact unless self is integral and the result is finite and can be expressed exactly in prec digits.
The result is almost always correctly rounded, but correct rounding is not guaranteed even if c.allcr() is set.
- Decimal
quantize
(const Decimal &other, Context &c = context) constReturn a value equal to self after rounding and having the exponent of the second operand.
Decimal("1.41421356").quantize(Decimal("1.000")) == Decimal("1.414")Unlike other operations, if the length of the coefficient after the quantize operation would be greater than precision, then InvalidOperation is set.
This guarantees that, unless there is an error condition, the quantized exponent is always equal to that of the right-hand operand.
Also unlike other operations, quantize never sets Underflow, even if the result is subnormal and inexact.
If the exponent of the second operand is larger than that of the first, then rounding may be necessary. In this case, the rounding mode is determined by the the given context argument.
- Decimal
rem
(const Decimal &other, Context &c = context) constThe remainder from the division by Decimal.divint. Fails under the same conditions as Decimal.divint.
- Decimal
rem_near
(const Decimal &other, Context &c = context) constReturn self - other * n, where n is the integer nearest the exact value of self / other. If the result is 0 then its sign will be the sign of self.
Binary functions, two return values
Ternary functions
- Decimal
fma
(const Decimal &other, const Decimal &third, Context &c = context) constFused multiply-add. Return self * other + third with no rounding of the intermediate product self * other.
Decimal(2).fma(3, 5) == Decimal(11)
- Decimal
powmod
(const Decimal &other, const Decimal &third, Context &c = context) constself ** other % third. The following restrictions hold:
- All three arguments must be integral.
- other must be nonnegative.
- At least one of self or other must be nonzero.
- third must be nonzero and less than 10 ** prec in absolute value.
Irregular functions
- Decimal
apply
(Context &c = context) constReturn a copy of self with the given context applied. This directly wraps
mpd_finalize
. It is very similar to Decimal.plus, but does not have special rules for zeros.
- int
cmp
(const Decimal &other) constSame as Decimal.compare_signal, but with an integer return value. Return INT_MAX if any operand is NaN. Not part of the specification.
- int
cmp_total
(const Decimal &other) constSame as Decimal.compare_total, but with an integer return value. Not part of the specification.
- int
cmp_total_mag
(const Decimal &other) constSame as Decimal.compare_total_mag, but with an integer return value. Not part of the specification.
- Decimal
copy_sign
(const Decimal &other) constReturn a copy of the first operand with the sign set to be the same as the sign of the second operand. For example:
Decimal("2.3").copy_sign(Decimal("-1.5")) == Decimal("-2.3")
- Decimal
rescale
(const int64_t exp, Context &c = context) constReturn the number that is equal in value to self, but has the exponent exp. Special numbers are copied without signaling. This function is not part of the standard. It is also not equivalent to the rescale function that was removed from the standard.
- bool
same_quantum
(const Decimal &other) constTest whether self and other have the same exponent or whether both are NaN.
This operation is unaffected by context and is quiet: no flags are changed and no rounding is performed.
- Decimal
shiftl
(const int64_t n, Context &c = context) constReturn a copy of self, with its coefficient shifted by n places to the left. self must not be a special number. Digits are never discarded, so the coefficient of the result might exceed prec.
This function is not part of the specification.
- Decimal
shiftr
(const int64_t n, Context &c = context) constReturn a copy of self, with its coefficient shifted by n places to the right.
This function is not part of the specification.
Exact integer conversion
- int64_t
i64
() constConvert a Decimal that is exactly representable as an int64_t. In case of failure, raise ValueError.
- int32_t
i32
() constConvert a Decimal that is exactly representable as an int32_t. In case of failure, raise ValueError.
- uint64_t
u64
() constConvert a Decimal that is exactly representable as a uint64_t. In case of failure, raise ValueError.
- uint32_t
u32
() constConvert a Decimal that is exactly representable as a uint32_t. In case of failure, raise ValueError.
Exact string conversion
- std::string
repr
(bool capitals = true) constSame as Decimal.to_sci, but wrap the string in a constructor.
Decimal("1.234E+100").repr() == "Decimal(\"1.234E+100\")"
- std::string
to_sci
(bool capitals = true) constReturn the scientific string representation of a Decimal. This operation is not context sensitive. If capitals is false, the exponent character is lower case, otherwise it is upper case.
- std::string
to_eng
(bool capitals = true) constReturn the engineering string representation of a Decimal. This operation is not context sensitive. If capitals is false, the exponent character is lower case, otherwise it is upper case.
Inexact string conversion
- std::string
format
(const char *fmt, const Context &c = context) constReturn the string representation of a decimal according to format string fmt. The format string syntax is the same as in Python PEP 3101 (See Standard Format Specifiers) and is quite similar to the syntax used for floating point numbers the C
fprintf
function. The fill character may be a UTF-8 character, the rest of the format string must be ASCII.The function raises ValueError for an invalid format string or MallocError in case of an allocation failure.
- std::string
format
(const std::string &s, const Context &c = context) constSame as above, using a string argument.
Streams
- friend std::ostream &
operator<<
(std::ostream &os, const Decimal &self)The conversion uses Decimal.to_sci.
Required by the specification
- bool
iscanonical
() constReturn true. This function is required by the specification, and the representation of Decimals is always canonical.
- Decimal
canonical
() constReturn an exact copy of self. No context is used. Identical to the assignment operator.
- Decimal
copy
() constReturn an exact copy of self. No context is used. Identical to the assignment operator.
- Decimal
logical_and
(const Decimal &other, Context &c = context) constDigit-wise and of self and other. All digits must be 0 or 1.
- Decimal
logical_invert
(Context &c = context) constInvert the digits of self. All digits must be 0 or 1.
- Decimal
logical_or
(const Decimal &other, Context &c = context) constDigit-wise or of self and other. All digits must be 0 or 1.
- Decimal
logical_xor
(const Decimal &other, Context &c = context) constDigit-wise xor of self and other. All digits must be 0 or 1.
- static int32_t
radix
()Return 10.
- Decimal
rotate
(const Decimal &other, Context &c = context) constReturn the result of rotating the digits of the first operand by an amount specified by the second operand. The second operand must be an integer in the range -precision through precision. The absolute value of the second operand gives the number of places to rotate. If the second operand is positive then rotation is to the left; otherwise rotation is to the right The coefficient of the first operand is padded on the left with zeros to length precision if necessary. The sign and exponent of the first operand are unchanged.
- Decimal
shift
(const Decimal &other, Context &c = context) constReturn the result of shifting the digits of the self by an amount specified by the other. other must be an integer in the range -prec through prec. The absolute value of the second operand gives the number of places to shift. If self is positive, then the shift is to the left; otherwise the shift is to the right. Digits shifted into the coefficient are zeros. The sign and exponent are unchanged.