f | |
n | :mod:`decimal` --- Decimal floating point arithmetic |
n | :mod:`decimal` --- Decimal fixed point and floating point arithmetic |
| ==================================================== |
| ==================================================================== |
| |
| .. module:: decimal |
| :synopsis: Implementation of the General Decimal Arithmetic Specification. |
| |
| |
| .. moduleauthor:: Eric Price <eprice at tjhsst.edu> |
| .. moduleauthor:: Facundo Batista <facundo at taniquetil.com.ar> |
| .. moduleauthor:: Raymond Hettinger <python at rcn.com> |
| .. moduleauthor:: Aahz <aahz at pobox.com> |
| .. moduleauthor:: Tim Peters <tim.one at comcast.net> |
| |
| |
| .. sectionauthor:: Raymond D. Hettinger <python at rcn.com> |
| |
n | |
| .. versionadded:: 2.4 |
| |
n | .. import modules for testing inline doctests with the Sphinx doctest builder |
| .. testsetup:: * |
| |
| import decimal |
| import math |
| from decimal import * |
| # make sure each group gets a fresh context |
| setcontext(Context()) |
| |
| The :mod:`decimal` module provides support for decimal floating point |
n | arithmetic. It offers several advantages over the :class:`float()` datatype: |
n | arithmetic. It offers several advantages over the :class:`float` datatype: |
| |
| * Decimal "is based on a floating-point model which was designed with people |
| in mind, and necessarily has a paramount guiding principle -- computers must |
| provide an arithmetic that works in the same way as the arithmetic that |
| people learn at school." -- excerpt from the decimal arithmetic specification. |
| |
| * Decimal numbers can be represented exactly. In contrast, numbers like |
| :const:`1.1` do not have an exact representation in binary floating point. End |
| users typically would not expect :const:`1.1` to display as |
| :const:`1.1000000000000001` as it does with binary floating point. |
| |
| * The exactness carries over into arithmetic. In decimal floating point, ``0.1 |
n | + 0.1 + 0.1 - 0.3`` is exactly equal to zero. In binary floating point, result |
n | + 0.1 + 0.1 - 0.3`` is exactly equal to zero. In binary floating point, the result |
| is :const:`5.5511151231257827e-017`. While near to zero, the differences |
| prevent reliable equality testing and differences can accumulate. For this |
n | reason, decimal would be preferred in accounting applications which have strict |
n | reason, decimal is preferred in accounting applications which have strict |
| equality invariants. |
| |
| * The decimal module incorporates a notion of significant places so that ``1.30 |
| + 1.20`` is :const:`2.50`. The trailing zero is kept to indicate significance. |
| This is the customary presentation for monetary applications. For |
| multiplication, the "schoolbook" approach uses all the figures in the |
| multiplicands. For instance, ``1.3 * 1.2`` gives :const:`1.56` while ``1.30 * |
| 1.20`` gives :const:`1.5600`. |
| |
| * Unlike hardware based binary floating point, the decimal module has a user |
n | settable precision (defaulting to 28 places) which can be as large as needed for |
n | alterable precision (defaulting to 28 places) which can be as large as needed for |
| a given problem:: |
| a given problem: |
| |
| >>> getcontext().prec = 6 |
| >>> Decimal(1) / Decimal(7) |
n | Decimal("0.142857") |
n | Decimal('0.142857') |
| >>> getcontext().prec = 28 |
| >>> Decimal(1) / Decimal(7) |
n | Decimal("0.1428571428571428571428571429") |
n | Decimal('0.1428571428571428571428571429') |
| |
| * Both binary and decimal floating point are implemented in terms of published |
| standards. While the built-in float type exposes only a modest portion of its |
| capabilities, the decimal module exposes all required parts of the standard. |
| When needed, the programmer has full control over rounding and signal handling. |
n | This includes an option to enforce exact arithmetic by using exceptions |
| to block any inexact operations. |
| |
| * The decimal module was designed to support "without prejudice, both exact |
| unrounded decimal arithmetic (sometimes called fixed-point arithmetic) |
| and rounded floating-point arithmetic." -- excerpt from the decimal |
| arithmetic specification. |
| |
| The module design is centered around three concepts: the decimal number, the |
| context for arithmetic, and signals. |
| |
| A decimal number is immutable. It has a sign, coefficient digits, and an |
| exponent. To preserve significance, the coefficient digits do not truncate |
n | trailing zeroes. Decimals also include special values such as |
n | trailing zeros. Decimals also include special values such as |
| :const:`Infinity`, :const:`-Infinity`, and :const:`NaN`. The standard also |
| differentiates :const:`-0` from :const:`+0`. |
| |
| The context for arithmetic is an environment specifying precision, rounding |
| rules, limits on exponents, flags indicating the results of operations, and trap |
| enablers which determine whether signals are treated as exceptions. Rounding |
| options include :const:`ROUND_CEILING`, :const:`ROUND_DOWN`, |
| :const:`ROUND_FLOOR`, :const:`ROUND_HALF_DOWN`, :const:`ROUND_HALF_EVEN`, |
n | :const:`ROUND_HALF_UP`, and :const:`ROUND_UP`. |
n | :const:`ROUND_HALF_UP`, :const:`ROUND_UP`, and :const:`ROUND_05UP`. |
| |
| Signals are groups of exceptional conditions arising during the course of |
| computation. Depending on the needs of the application, signals may be ignored, |
| considered as informational, or treated as exceptions. The signals in the |
| decimal module are: :const:`Clamped`, :const:`InvalidOperation`, |
| :const:`DivisionByZero`, :const:`Inexact`, :const:`Rounded`, :const:`Subnormal`, |
| :const:`Overflow`, and :const:`Underflow`. |
| |
| For each signal there is a flag and a trap enabler. When a signal is |
n | encountered, its flag is incremented from zero and, then, if the trap enabler is |
n | encountered, its flag is set to one, then, if the trap enabler is |
| set to one, an exception is raised. Flags are sticky, so the user needs to |
| reset them before monitoring a calculation. |
| |
| |
| .. seealso:: |
| |
n | IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic |
n | * IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic |
| Specification <http://www2.hursley.ibm.com/decimal/decarith.html>`_. |
| Specification <http://www2.hursley.ibm.com/decimal/decarith.html>`_. |
| |
n | IEEE standard 854-1987, `Unofficial IEEE 854 Text |
n | * IEEE standard 854-1987, `Unofficial IEEE 854 Text |
| <http://www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html>`_. |
| <http://754r.ucbtest.org/standards/854.pdf>`_. |
| |
n | .. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
n | .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| |
| |
| .. _decimal-tutorial: |
| |
| Quick-start Tutorial |
| -------------------- |
| |
| The usual start to using decimals is importing the module, viewing the current |
| context with :func:`getcontext` and, if necessary, setting new values for |
| precision, rounding, or enabled traps:: |
| |
| >>> from decimal import * |
| >>> getcontext() |
| Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, |
n | capitals=1, flags=[], traps=[Overflow, InvalidOperation, |
n | capitals=1, flags=[], traps=[Overflow, DivisionByZero, |
| DivisionByZero]) |
| InvalidOperation]) |
| |
| >>> getcontext().prec = 7 # Set a new precision |
| |
| Decimal instances can be constructed from integers, strings, or tuples. To |
| create a Decimal from a :class:`float`, first convert it to a string. This |
| serves as an explicit reminder of the details of the conversion (including |
| representation error). Decimal numbers include special values such as |
| :const:`NaN` which stands for "Not a number", positive and negative |
n | :const:`Infinity`, and :const:`-0`. :: |
n | :const:`Infinity`, and :const:`-0`. |
| |
n | >>> getcontext().prec = 28 |
| >>> Decimal(10) |
n | Decimal("10") |
n | Decimal('10') |
| >>> Decimal("3.14") |
| >>> Decimal('3.14') |
| Decimal("3.14") |
| Decimal('3.14') |
| >>> Decimal((0, (3, 1, 4), -2)) |
n | Decimal("3.14") |
n | Decimal('3.14') |
| >>> Decimal(str(2.0 ** 0.5)) |
n | Decimal("1.41421356237") |
n | Decimal('1.41421356237') |
| >>> Decimal(2) ** Decimal('0.5') |
| Decimal('1.414213562373095048801688724') |
| >>> Decimal("NaN") |
| >>> Decimal('NaN') |
| Decimal("NaN") |
| Decimal('NaN') |
| >>> Decimal("-Infinity") |
| >>> Decimal('-Infinity') |
| Decimal("-Infinity") |
| Decimal('-Infinity') |
| |
| The significance of a new Decimal is determined solely by the number of digits |
| input. Context precision and rounding only come into play during arithmetic |
n | operations. :: |
n | operations. |
| |
| .. doctest:: newcontext |
| |
| >>> getcontext().prec = 6 |
| >>> Decimal('3.0') |
n | Decimal("3.0") |
n | Decimal('3.0') |
| >>> Decimal('3.1415926535') |
n | Decimal("3.1415926535") |
n | Decimal('3.1415926535') |
| >>> Decimal('3.1415926535') + Decimal('2.7182818285') |
n | Decimal("5.85987") |
n | Decimal('5.85987') |
| >>> getcontext().rounding = ROUND_UP |
| >>> Decimal('3.1415926535') + Decimal('2.7182818285') |
n | Decimal("5.85988") |
n | Decimal('5.85988') |
| |
| Decimals interact well with much of the rest of Python. Here is a small decimal |
n | floating point flying circus:: |
n | floating point flying circus: |
| |
| .. doctest:: |
| :options: +NORMALIZE_WHITESPACE |
| |
| >>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()) |
| >>> max(data) |
n | Decimal("9.25") |
n | Decimal('9.25') |
| >>> min(data) |
n | Decimal("0.03") |
n | Decimal('0.03') |
| >>> sorted(data) |
n | [Decimal("0.03"), Decimal("1.00"), Decimal("1.34"), Decimal("1.87"), |
n | [Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'), |
| Decimal("2.35"), Decimal("3.45"), Decimal("9.25")] |
| Decimal('2.35'), Decimal('3.45'), Decimal('9.25')] |
| >>> sum(data) |
n | Decimal("19.29") |
n | Decimal('19.29') |
| >>> a,b,c = data[:3] |
| >>> str(a) |
| '1.34' |
| >>> float(a) |
| 1.3400000000000001 |
| >>> round(a, 1) # round() first converts to binary floating point |
| 1.3 |
| >>> int(a) |
| 1 |
| >>> a * 5 |
n | Decimal("6.70") |
n | Decimal('6.70') |
| >>> a * b |
n | Decimal("2.5058") |
n | Decimal('2.5058') |
| >>> c % a |
n | Decimal("0.77") |
n | Decimal('0.77') |
| |
| And some mathematical functions are also available to Decimal: |
| |
| >>> getcontext().prec = 28 |
| >>> Decimal(2).sqrt() |
| Decimal('1.414213562373095048801688724') |
| >>> Decimal(1).exp() |
| Decimal('2.718281828459045235360287471') |
| >>> Decimal('10').ln() |
| Decimal('2.302585092994045684017991455') |
| >>> Decimal('10').log10() |
| Decimal('1') |
| |
| The :meth:`quantize` method rounds a number to a fixed exponent. This method is |
| useful for monetary applications that often round results to a fixed number of |
n | places:: |
n | places: |
| |
| >>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN) |
n | Decimal("7.32") |
n | Decimal('7.32') |
| >>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP) |
n | Decimal("8") |
n | Decimal('8') |
| |
| As shown above, the :func:`getcontext` function accesses the current context and |
| allows the settings to be changed. This approach meets the needs of most |
| applications. |
| |
| For more advanced work, it may be useful to create alternate contexts using the |
| Context() constructor. To make an alternate active, use the :func:`setcontext` |
| function. |
| |
| In accordance with the standard, the :mod:`Decimal` module provides two ready to |
| use standard contexts, :const:`BasicContext` and :const:`ExtendedContext`. The |
| former is especially useful for debugging because many of the traps are |
n | enabled:: |
n | enabled: |
| |
| .. doctest:: newcontext |
| :options: +NORMALIZE_WHITESPACE |
| |
| >>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN) |
| >>> setcontext(myothercontext) |
| >>> Decimal(1) / Decimal(7) |
n | Decimal("0.142857142857142857142857142857142857142857142857142857142857") |
n | Decimal('0.142857142857142857142857142857142857142857142857142857142857') |
| |
| >>> ExtendedContext |
| Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, |
| capitals=1, flags=[], traps=[]) |
| >>> setcontext(ExtendedContext) |
| >>> Decimal(1) / Decimal(7) |
n | Decimal("0.142857143") |
n | Decimal('0.142857143') |
| >>> Decimal(42) / Decimal(0) |
n | Decimal("Infinity") |
n | Decimal('Infinity') |
| |
| >>> setcontext(BasicContext) |
| >>> Decimal(42) / Decimal(0) |
| Traceback (most recent call last): |
| File "<pyshell#143>", line 1, in -toplevel- |
| Decimal(42) / Decimal(0) |
| DivisionByZero: x / 0 |
| |
| Contexts also have signal flags for monitoring exceptional conditions |
| encountered during computations. The flags remain set until explicitly cleared, |
| so it is best to clear the flags before each set of monitored computations by |
| using the :meth:`clear_flags` method. :: |
| |
| >>> setcontext(ExtendedContext) |
| >>> getcontext().clear_flags() |
| >>> Decimal(355) / Decimal(113) |
n | Decimal("3.14159292") |
n | Decimal('3.14159292') |
| >>> getcontext() |
| Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, |
n | capitals=1, flags=[Inexact, Rounded], traps=[]) |
n | capitals=1, flags=[Rounded, Inexact], traps=[]) |
| |
| The *flags* entry shows that the rational approximation to :const:`Pi` was |
| rounded (digits beyond the context precision were thrown away) and that the |
| result is inexact (some of the discarded digits were non-zero). |
| |
| Individual traps are set using the dictionary in the :attr:`traps` field of a |
n | context:: |
n | context: |
| |
n | .. doctest:: newcontext |
| |
| >>> setcontext(ExtendedContext) |
| >>> Decimal(1) / Decimal(0) |
n | Decimal("Infinity") |
n | Decimal('Infinity') |
| >>> getcontext().traps[DivisionByZero] = 1 |
| >>> Decimal(1) / Decimal(0) |
| Traceback (most recent call last): |
| File "<pyshell#112>", line 1, in -toplevel- |
| Decimal(1) / Decimal(0) |
| DivisionByZero: x / 0 |
| |
| Most programs adjust the current context only once, at the beginning of the |
| program. And, in many applications, data is converted to :class:`Decimal` with |
| a single cast inside a loop. With context set and decimals created, the bulk of |
| the program manipulates the data no differently than with other Python numeric |
| types. |
| |
n | .. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
n | .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| |
| |
| .. _decimal-decimal: |
| |
| Decimal objects |
| --------------- |
| |
| |
| .. class:: Decimal([value [, context]]) |
| |
n | Constructs a new :class:`Decimal` object based from *value*. |
n | Construct a new :class:`Decimal` object based from *value*. |
| |
n | *value* can be an integer, string, tuple, or another :class:`Decimal` object. If |
n | *value* can be an integer, string, tuple, or another :class:`Decimal` |
| no *value* is given, returns ``Decimal("0")``. If *value* is a string, it |
| object. If no *value* is given, returns ``Decimal('0')``. If *value* is a |
| should conform to the decimal numeric string syntax:: |
| string, it should conform to the decimal numeric string syntax after leading |
| and trailing whitespace characters are removed:: |
| |
| sign ::= '+' | '-' |
| digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' |
| indicator ::= 'e' | 'E' |
| digits ::= digit [digit]... |
| decimal-part ::= digits '.' [digits] | ['.'] digits |
| exponent-part ::= indicator [sign] digits |
| infinity ::= 'Infinity' | 'Inf' |
| nan ::= 'NaN' [digits] | 'sNaN' [digits] |
| numeric-value ::= decimal-part [exponent-part] | infinity |
n | numeric-string ::= [sign] numeric-value | [sign] nan |
n | numeric-string ::= [sign] numeric-value | [sign] nan |
| |
| If *value* is a :class:`tuple`, it should have three components, a sign |
| (:const:`0` for positive or :const:`1` for negative), a :class:`tuple` of |
| digits, and an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))`` |
n | returns ``Decimal("1.414")``. |
n | returns ``Decimal('1.414')``. |
| |
| The *context* precision does not affect how many digits are stored. That is |
| determined exclusively by the number of digits in *value*. For example, |
n | ``Decimal("3.00000")`` records all five zeroes even if the context precision is |
n | ``Decimal('3.00000')`` records all five zeros even if the context precision is |
| only three. |
| |
| The purpose of the *context* argument is determining what to do if *value* is a |
| malformed string. If the context traps :const:`InvalidOperation`, an exception |
| is raised; otherwise, the constructor returns a new Decimal with the value of |
| :const:`NaN`. |
| |
| Once constructed, :class:`Decimal` objects are immutable. |
| |
n | .. versionchanged:: 2.6 |
| leading and trailing whitespace characters are permitted when |
| creating a Decimal instance from a string. |
| |
| Decimal floating point objects share many properties with the other builtin |
| Decimal floating point objects share many properties with the other built-in |
| numeric types such as :class:`float` and :class:`int`. All of the usual math |
| numeric types such as :class:`float` and :class:`int`. All of the usual math |
| operations and special methods apply. Likewise, decimal objects can be copied, |
| operations and special methods apply. Likewise, decimal objects can be |
| pickled, printed, used as dictionary keys, used as set elements, compared, |
| copied, pickled, printed, used as dictionary keys, used as set elements, |
| sorted, and coerced to another type (such as :class:`float` or :class:`long`). |
| compared, sorted, and coerced to another type (such as :class:`float` or |
| :class:`long`). |
| |
n | In addition to the standard numeric properties, decimal floating point objects |
n | In addition to the standard numeric properties, decimal floating point |
| also have a number of specialized methods: |
| objects also have a number of specialized methods: |
| |
| |
n | .. method:: Decimal.adjusted() |
n | .. method:: adjusted() |
| |
n | Return the adjusted exponent after shifting out the coefficient's rightmost |
n | Return the adjusted exponent after shifting out the coefficient's |
| digits until only the lead digit remains: ``Decimal("321e+5").adjusted()`` |
| rightmost digits until only the lead digit remains: |
| returns seven. Used for determining the position of the most significant digit |
| ``Decimal('321e+5').adjusted()`` returns seven. Used for determining the |
| with respect to the decimal point. |
| position of the most significant digit with respect to the decimal point. |
| |
| |
n | .. method:: Decimal.as_tuple() |
n | .. method:: as_tuple() |
| |
n | Returns a tuple representation of the number: ``(sign, digittuple, exponent)``. |
n | Return a :term:`named tuple` representation of the number: |
| ``DecimalTuple(sign, digits, exponent)``. |
| |
n | .. versionchanged:: 2.6 |
| Use a named tuple. |
| |
n | |
| .. method:: canonical() |
| |
| Return the canonical encoding of the argument. Currently, the encoding of |
| a :class:`Decimal` instance is always canonical, so this operation returns |
| its argument unchanged. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: Decimal.compare(other[, context]) |
| .. method:: compare(other[, context]) |
| |
n | Compares like :meth:`__cmp__` but returns a decimal instance:: |
n | Compare the values of two Decimal instances. This operation behaves in |
| the same way as the usual comparison method :meth:`__cmp__`, except that |
| :meth:`compare` returns a Decimal instance rather than an integer, and if |
| either operand is a NaN then the result is a NaN:: |
| |
n | a or b is a NaN ==> Decimal("NaN") |
n | a or b is a NaN ==> Decimal('NaN') |
| a < b ==> Decimal("-1") |
| a < b ==> Decimal('-1') |
| a == b ==> Decimal("0") |
| a == b ==> Decimal('0') |
| a > b ==> Decimal("1") |
| a > b ==> Decimal('1') |
| |
n | .. method:: compare_signal(other[, context]) |
| |
n | This operation is identical to the :meth:`compare` method, except that all |
| NaNs signal. That is, if neither operand is a signaling NaN then any |
| quiet NaN operand is treated as though it were a signaling NaN. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: compare_total(other) |
| |
| Compare two operands using their abstract representation rather than their |
| numerical value. Similar to the :meth:`compare` method, but the result |
| gives a total ordering on :class:`Decimal` instances. Two |
| :class:`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. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: compare_total_mag(other) |
| |
| Compare two operands using their abstract representation rather than their |
| value as in :meth:`compare_total`, but ignoring the sign of each operand. |
| ``x.compare_total_mag(y)`` is equivalent to |
| ``x.copy_abs().compare_total(y.copy_abs())``. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: conjugate() |
| |
| Just returns self, this method is only to comply with the Decimal |
| Specification. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: copy_abs() |
| |
| Return the absolute value of the argument. This operation is unaffected |
| by the context and is quiet: no flags are changed and no rounding is |
| performed. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: copy_negate() |
| |
| Return the negation of the argument. This operation is unaffected by the |
| context and is quiet: no flags are changed and no rounding is performed. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: copy_sign(other) |
| |
| Return 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') |
| |
| This operation is unaffected by the context and is quiet: no flags are |
| changed and no rounding is performed. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: exp([context]) |
| |
| Return the value of the (natural) exponential function ``e**x`` at the |
| given number. The result is correctly rounded using the |
| :const:`ROUND_HALF_EVEN` rounding mode. |
| |
| >>> Decimal(1).exp() |
| Decimal('2.718281828459045235360287471') |
| >>> Decimal(321).exp() |
| Decimal('2.561702493119680037517373933E+139') |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: fma(other, third[, context]) |
| |
| Fused multiply-add. Return self*other+third with no rounding of the |
| intermediate product self*other. |
| |
| >>> Decimal(2).fma(3, 5) |
| Decimal('11') |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: is_canonical() |
| |
| Return :const:`True` if the argument is canonical and :const:`False` |
| otherwise. Currently, a :class:`Decimal` instance is always canonical, so |
| this operation always returns :const:`True`. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: is_finite() |
| |
| Return :const:`True` if the argument is a finite number, and |
| :const:`False` if the argument is an infinity or a NaN. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: is_infinite() |
| |
| Return :const:`True` if the argument is either positive or negative |
| infinity and :const:`False` otherwise. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: is_nan() |
| |
| Return :const:`True` if the argument is a (quiet or signaling) NaN and |
| :const:`False` otherwise. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: is_normal() |
| |
| Return :const:`True` if the argument is a *normal* finite number. Return |
| :const:`False` if the argument is zero, subnormal, infinite or a NaN. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: is_qnan() |
| |
| Return :const:`True` if the argument is a quiet NaN, and |
| :const:`False` otherwise. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: is_signed() |
| |
| Return :const:`True` if the argument has a negative sign and |
| :const:`False` otherwise. Note that zeros and NaNs can both carry signs. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: is_snan() |
| |
| Return :const:`True` if the argument is a signaling NaN and :const:`False` |
| otherwise. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: is_subnormal() |
| |
| Return :const:`True` if the argument is subnormal, and :const:`False` |
| otherwise. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: is_zero() |
| |
| Return :const:`True` if the argument is a (positive or negative) zero and |
| :const:`False` otherwise. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: ln([context]) |
| |
| Return the natural (base e) logarithm of the operand. The result is |
| correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: log10([context]) |
| |
| Return the base ten logarithm of the operand. The result is correctly |
| rounded using the :const:`ROUND_HALF_EVEN` rounding mode. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: logb([context]) |
| |
| For a nonzero number, return the adjusted exponent of its operand as a |
| :class:`Decimal` instance. If the operand is a zero then |
| ``Decimal('-Infinity')`` is returned and the :const:`DivisionByZero` flag |
| is raised. If the operand is an infinity then ``Decimal('Infinity')`` is |
| returned. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: logical_and(other[, context]) |
| |
| :meth:`logical_and` is a logical operation which takes two *logical |
| operands* (see :ref:`logical_operands_label`). The result is the |
| digit-wise ``and`` of the two operands. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: logical_invert(other[, context]) |
| |
| :meth:`logical_invert` is a logical operation. The argument must |
| be a *logical operand* (see :ref:`logical_operands_label`). The |
| result is the digit-wise inversion of the operand. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: logical_or(other[, context]) |
| |
| :meth:`logical_or` is a logical operation which takes two *logical |
| operands* (see :ref:`logical_operands_label`). The result is the |
| digit-wise ``or`` of the two operands. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: logical_xor(other[, context]) |
| |
| :meth:`logical_xor` is a logical operation which takes two *logical |
| operands* (see :ref:`logical_operands_label`). The result is the |
| digit-wise exclusive or of the two operands. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: Decimal.max(other[, context]) |
| .. method:: max(other[, context]) |
| |
n | Like ``max(self, other)`` except that the context rounding rule is applied |
n | Like ``max(self, other)`` except that the context rounding rule is applied |
| before returning and that :const:`NaN` values are either signalled or ignored |
| before returning and that :const:`NaN` values are either signaled or |
| (depending on the context and whether they are signaling or quiet). |
| ignored (depending on the context and whether they are signaling or |
| quiet). |
| |
n | .. method:: max_mag(other[, context]) |
| |
n | Similar to the :meth:`max` method, but the comparison is done using the |
| absolute values of the operands. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: Decimal.min(other[, context]) |
| .. method:: min(other[, context]) |
| |
n | Like ``min(self, other)`` except that the context rounding rule is applied |
n | Like ``min(self, other)`` except that the context rounding rule is applied |
| before returning and that :const:`NaN` values are either signalled or ignored |
| before returning and that :const:`NaN` values are either signaled or |
| (depending on the context and whether they are signaling or quiet). |
| ignored (depending on the context and whether they are signaling or |
| quiet). |
| |
n | .. method:: min_mag(other[, context]) |
| |
n | Similar to the :meth:`min` method, but the comparison is done using the |
| absolute values of the operands. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: next_minus([context]) |
| |
| Return the largest number representable in the given context (or in the |
| current thread's context if no context is given) that is smaller than the |
| given operand. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: next_plus([context]) |
| |
| Return the smallest number representable in the given context (or in the |
| current thread's context if no context is given) that is larger than the |
| given operand. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: next_toward(other[, context]) |
| |
| If 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. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: Decimal.normalize([context]) |
| .. method:: normalize([context]) |
| |
n | Normalize the number by stripping the rightmost trailing zeroes and converting |
n | Normalize the number by stripping the rightmost trailing zeros and |
| any result equal to :const:`Decimal("0")` to :const:`Decimal("0e0")`. Used for |
| converting any result equal to :const:`Decimal('0')` to |
| producing canonical values for members of an equivalence class. For example, |
| :const:`Decimal('0e0')`. Used for producing canonical values for members |
| ``Decimal("32.100")`` and ``Decimal("0.321000e+2")`` both normalize to the |
| of an equivalence class. For example, ``Decimal('32.100')`` and |
| equivalent value ``Decimal("32.1")``. |
| ``Decimal('0.321000e+2')`` both normalize to the equivalent value |
| ``Decimal('32.1')``. |
| |
n | .. method:: number_class([context]) |
| |
n | 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. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: Decimal.quantize(exp [, rounding[, context[, watchexp]]]) |
| .. method:: quantize(exp[, rounding[, context[, watchexp]]]) |
| |
n | Quantize makes the exponent the same as *exp*. Searches for a rounding method |
n | Return a value equal to the first operand after rounding and having the |
| in *rounding*, then in *context*, and then in the current context. |
| exponent of the second operand. |
| |
n | >>> 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 an |
| :const:`InvalidOperation` is signaled. 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 signals 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 ``rounding`` argument if given, else by the given |
| ``context`` argument; if neither argument is given the rounding mode of |
| the current thread's context is used. |
| |
| If *watchexp* is set (default), then an error is returned whenever the resulting |
| If *watchexp* is set (default), then an error is returned whenever the |
| exponent is greater than :attr:`Emax` or less than :attr:`Etiny`. |
| resulting exponent is greater than :attr:`Emax` or less than |
| :attr:`Etiny`. |
| |
n | .. method:: radix() |
| |
n | Return ``Decimal(10)``, the radix (base) in which the :class:`Decimal` |
| class does all its arithmetic. Included for compatibility with the |
| specification. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: Decimal.remainder_near(other[, context]) |
| .. method:: remainder_near(other[, context]) |
| |
n | Computes the modulo as either a positive or negative value depending on which is |
n | Compute the modulo as either a positive or negative value depending on |
| closest to zero. For instance, ``Decimal(10).remainder_near(6)`` returns |
| which is closest to zero. For instance, ``Decimal(10).remainder_near(6)`` |
| ``Decimal("-2")`` which is closer to zero than ``Decimal("4")``. |
| returns ``Decimal('-2')`` which is closer to zero than ``Decimal('4')``. |
| |
n | If both are equally close, the one chosen will have the same sign as *self*. |
n | If both are equally close, the one chosen will have the same sign as |
| *self*. |
| |
n | .. method:: rotate(other[, context]) |
| |
n | Return 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. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: Decimal.same_quantum(other[, context]) |
| .. method:: same_quantum(other[, context]) |
| |
n | Test whether self and other have the same exponent or whether both are |
n | Test whether self and other have the same exponent or whether both are |
| :const:`NaN`. |
| :const:`NaN`. |
| |
n | .. method:: scaleb(other[, context]) |
| |
n | Return the first operand with exponent adjusted by the second. |
| Equivalently, return the first operand multiplied by ``10**other``. The |
| second operand must be an integer. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: shift(other[, context]) |
| |
| Return the result of shifting 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 shift. If the second operand 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 of the first operand are unchanged. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: Decimal.sqrt([context]) |
| .. method:: sqrt([context]) |
| |
n | Return the square root to full precision. |
n | Return the square root of the argument to full precision. |
| |
| |
n | .. method:: Decimal.to_eng_string([context]) |
n | .. method:: to_eng_string([context]) |
| |
n | Convert to an engineering-type string. |
n | Convert to an engineering-type string. |
| |
n | Engineering notation has an exponent which is a multiple of 3, so there are up |
n | Engineering notation has an exponent which is a multiple of 3, so there |
| to 3 digits left of the decimal place. For example, converts |
| are up to 3 digits left of the decimal place. For example, converts |
| ``Decimal('123E+1')`` to ``Decimal("1.23E+3")`` |
| ``Decimal('123E+1')`` to ``Decimal('1.23E+3')`` |
| |
n | |
| .. method:: Decimal.to_integral([rounding[, context]]) |
| .. method:: to_integral([rounding[, context]]) |
| |
n | Identical to the :meth:`to_integral_value` method. The ``to_integral`` |
| name has been kept for compatibility with older versions. |
| |
| .. method:: to_integral_exact([rounding[, context]]) |
| |
| Round to the nearest integer, signaling :const:`Inexact` or |
| :const:`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 context is used. |
| |
| .. versionadded:: 2.6 |
| |
| .. method:: to_integral_value([rounding[, context]]) |
| |
| Rounds to the nearest integer without signaling :const:`Inexact` or |
| Round to the nearest integer without signaling :const:`Inexact` or |
| :const:`Rounded`. If given, applies *rounding*; otherwise, uses the rounding |
| :const:`Rounded`. If given, applies *rounding*; otherwise, uses the |
| method in either the supplied *context* or the current context. |
| rounding method in either the supplied *context* or the current context. |
| |
n | .. versionchanged:: 2.6 |
| renamed from ``to_integral`` to ``to_integral_value``. The old name |
| remains valid for compatibility. |
| |
| .. _logical_operands_label: |
| |
| Logical operands |
| ^^^^^^^^^^^^^^^^ |
| |
| The :meth:`logical_and`, :meth:`logical_invert`, :meth:`logical_or`, |
| and :meth:`logical_xor` methods expect their arguments to be *logical |
| operands*. A *logical operand* is a :class:`Decimal` instance whose |
| exponent and sign are both zero, and whose digits are all either |
| :const:`0` or :const:`1`. |
| |
| .. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| |
| |
n | .. _decimal-decimal: |
n | .. _decimal-context: |
| |
| Context objects |
| --------------- |
| |
| Contexts are environments for arithmetic operations. They govern precision, set |
| rules for rounding, determine which signals are treated as exceptions, and limit |
| the range for exponents. |
| |
| default values are copied from the :const:`DefaultContext`. If the *flags* |
| field is not specified or is :const:`None`, all flags are cleared. |
| |
| The *prec* field is a positive integer that sets the precision for arithmetic |
| operations in the context. |
| |
| The *rounding* option is one of: |
| |
n | * :const:`ROUND_CEILING` (towards :const:`Infinity`), |
n | * :const:`ROUND_CEILING` (towards :const:`Infinity`), |
| |
| * :const:`ROUND_DOWN` (towards zero), |
| * :const:`ROUND_DOWN` (towards zero), |
| |
| * :const:`ROUND_FLOOR` (towards :const:`-Infinity`), |
| * :const:`ROUND_FLOOR` (towards :const:`-Infinity`), |
| |
| * :const:`ROUND_HALF_DOWN` (to nearest with ties going towards zero), |
| * :const:`ROUND_HALF_DOWN` (to nearest with ties going towards zero), |
| |
| * :const:`ROUND_HALF_EVEN` (to nearest with ties going to nearest even integer), |
| * :const:`ROUND_HALF_EVEN` (to nearest with ties going to nearest even integer), |
| |
| * :const:`ROUND_HALF_UP` (to nearest with ties going away from zero), or |
| * :const:`ROUND_HALF_UP` (to nearest with ties going away from zero), or |
| |
| * :const:`ROUND_UP` (away from zero). |
| * :const:`ROUND_UP` (away from zero). |
| * :const:`ROUND_05UP` (away from zero if last digit after rounding towards zero |
| would have been 0 or 5; otherwise towards zero) |
| |
| The *traps* and *flags* fields list any signals to be set. Generally, new |
| contexts should only set traps and leave the flags clear. |
| |
| The *Emin* and *Emax* fields are integers specifying the outer limits allowable |
| for exponents. |
| |
| The *capitals* field is either :const:`0` or :const:`1` (the default). If set to |
| :const:`1`, exponents are printed with a capital :const:`E`; otherwise, a |
| lowercase :const:`e` is used: :const:`Decimal('6.02e+23')`. |
| |
n | .. versionchanged:: 2.6 |
| The :const:`ROUND_05UP` rounding mode was added. |
| |
| The :class:`Context` class defines several general purpose methods as well as a |
| The :class:`Context` class defines several general purpose methods as well as |
| large number of methods for doing arithmetic directly in a given context. |
| a large number of methods for doing arithmetic directly in a given context. |
| In addition, for each of the :class:`Decimal` methods described above (with |
| the exception of the :meth:`adjusted` and :meth:`as_tuple` methods) there is |
| a corresponding :class:`Context` method. For example, ``C.exp(x)`` is |
| equivalent to ``x.exp(context=C)``. |
| |
| |
n | .. method:: Context.clear_flags() |
n | .. method:: clear_flags() |
| |
n | Resets all of the flags to :const:`0`. |
n | Resets all of the flags to :const:`0`. |
| |
n | |
| .. method:: Context.copy() |
| .. method:: copy() |
| |
n | Return a duplicate of the context. |
n | Return a duplicate of the context. |
| |
n | .. method:: copy_decimal(num) |
| |
n | Return a copy of the Decimal instance num. |
| |
| .. method:: Context.create_decimal(num) |
| .. method:: create_decimal(num) |
| |
n | Creates a new Decimal instance from *num* but using *self* as context. Unlike |
n | Creates a new Decimal instance from *num* but using *self* as |
| the :class:`Decimal` constructor, the context precision, rounding method, flags, |
| context. Unlike the :class:`Decimal` constructor, the context precision, |
| and traps are applied to the conversion. |
| rounding method, flags, and traps are applied to the conversion. |
| |
n | This is useful because constants are often given to a greater precision than is |
n | This is useful because constants are often given to a greater precision |
| needed by the application. Another benefit is that rounding immediately |
| than is needed by the application. Another benefit is that rounding |
| eliminates unintended effects from digits beyond the current precision. In the |
| immediately eliminates unintended effects from digits beyond the current |
| following example, using unrounded inputs means that adding zero to a sum can |
| precision. In the following example, using unrounded inputs means that |
| change the result:: |
| adding zero to a sum can change the result: |
| |
n | .. doctest:: newcontext |
| |
| >>> getcontext().prec = 3 |
| >>> getcontext().prec = 3 |
| >>> Decimal("3.4445") + Decimal("1.0023") |
| >>> Decimal('3.4445') + Decimal('1.0023') |
| Decimal("4.45") |
| Decimal('4.45') |
| >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023") |
| >>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023') |
| Decimal("4.44") |
| Decimal('4.44') |
| |
n | This method implements the to-number operation of the IBM specification. |
| If the argument is a string, no leading or trailing whitespace is |
| permitted. |
| |
n | .. method:: Context.Etiny() |
n | .. method:: Etiny() |
| |
n | Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent value |
n | Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent |
| for subnormal results. When underflow occurs, the exponent is set to |
| value for subnormal results. When underflow occurs, the exponent is set |
| :const:`Etiny`. |
| to :const:`Etiny`. |
| |
| |
n | .. method:: Context.Etop() |
n | .. method:: Etop() |
| |
n | Returns a value equal to ``Emax - prec + 1``. |
n | Returns a value equal to ``Emax - prec + 1``. |
| |
n | The usual approach to working with decimals is to create :class:`Decimal` |
n | The usual approach to working with decimals is to create :class:`Decimal` |
| instances and then apply arithmetic operations which take place within the |
| instances and then apply arithmetic operations which take place within the |
| current context for the active thread. An alternate approach is to use context |
| current context for the active thread. An alternative approach is to use |
| methods for calculating within a specific context. The methods are similar to |
| context methods for calculating within a specific context. The methods are |
| those for the :class:`Decimal` class and are only briefly recounted here. |
| similar to those for the :class:`Decimal` class and are only briefly |
| recounted here. |
| |
| |
n | .. method:: Context.abs(x) |
n | .. method:: abs(x) |
| |
n | Returns the absolute value of *x*. |
n | Returns the absolute value of *x*. |
| |
| |
n | .. method:: Context.add(x, y) |
n | .. method:: add(x, y) |
| |
n | Return the sum of *x* and *y*. |
n | Return the sum of *x* and *y*. |
| |
| |
n | .. method:: canonical(x) |
| |
| Returns the same Decimal object *x*. |
| |
| |
| .. method:: Context.compare(x, y) |
| .. method:: compare(x, y) |
| |
n | Compares values numerically. |
n | Compares *x* and *y* numerically. |
| |
n | Like :meth:`__cmp__` but returns a decimal instance:: |
| |
n | a or b is a NaN ==> Decimal("NaN") |
n | .. method:: compare_signal(x, y) |
| a < b ==> Decimal("-1") |
| a == b ==> Decimal("0") |
| a > b ==> Decimal("1") |
| |
n | Compares the values of the two operands numerically. |
| |
n | |
| .. method:: compare_total(x, y) |
| |
| Compares two operands using their abstract representation. |
| |
| |
| .. method:: compare_total_mag(x, y) |
| |
| Compares two operands using their abstract representation, ignoring sign. |
| |
| |
| .. method:: copy_abs(x) |
| |
| Returns a copy of *x* with the sign set to 0. |
| |
| |
| .. method:: copy_negate(x) |
| |
| Returns a copy of *x* with the sign inverted. |
| |
| |
| .. method:: copy_sign(x, y) |
| |
| Copies the sign from *y* to *x*. |
| |
| |
| .. method:: Context.divide(x, y) |
| .. method:: divide(x, y) |
| |
n | Return *x* divided by *y*. |
n | Return *x* divided by *y*. |
| |
| |
n | .. method:: divide_int(x, y) |
| |
| Return *x* divided by *y*, truncated to an integer. |
| |
| |
| .. method:: Context.divmod(x, y) |
| .. method:: divmod(x, y) |
| |
n | Divides two numbers and returns the integer part of the result. |
n | Divides two numbers and returns the integer part of the result. |
| |
| |
n | .. method:: exp(x) |
| |
| Returns `e ** x`. |
| |
| |
| .. method:: fma(x, y, z) |
| |
| Returns *x* multiplied by *y*, plus *z*. |
| |
| |
| .. method:: is_canonical(x) |
| |
| Returns True if *x* is canonical; otherwise returns False. |
| |
| |
| .. method:: is_finite(x) |
| |
| Returns True if *x* is finite; otherwise returns False. |
| |
| |
| .. method:: is_infinite(x) |
| |
| Returns True if *x* is infinite; otherwise returns False. |
| |
| |
| .. method:: is_nan(x) |
| |
| Returns True if *x* is a qNaN or sNaN; otherwise returns False. |
| |
| |
| .. method:: is_normal(x) |
| |
| Returns True if *x* is a normal number; otherwise returns False. |
| |
| |
| .. method:: is_qnan(x) |
| |
| Returns True if *x* is a quiet NaN; otherwise returns False. |
| |
| |
| .. method:: is_signed(x) |
| |
| Returns True if *x* is negative; otherwise returns False. |
| |
| |
| .. method:: is_snan(x) |
| |
| Returns True if *x* is a signaling NaN; otherwise returns False. |
| |
| |
| .. method:: is_subnormal(x) |
| |
| Returns True if *x* is subnormal; otherwise returns False. |
| |
| |
| .. method:: is_zero(x) |
| |
| Returns True if *x* is a zero; otherwise returns False. |
| |
| |
| .. method:: ln(x) |
| |
| Returns the natural (base e) logarithm of *x*. |
| |
| |
| .. method:: log10(x) |
| |
| Returns the base 10 logarithm of *x*. |
| |
| |
| .. method:: logb(x) |
| |
| Returns the exponent of the magnitude of the operand's MSD. |
| |
| |
| .. method:: logical_and(x, y) |
| |
| Applies the logical operation *and* between each operand's digits. |
| |
| |
| .. method:: logical_invert(x) |
| |
| Invert all the digits in *x*. |
| |
| |
| .. method:: logical_or(x, y) |
| |
| Applies the logical operation *or* between each operand's digits. |
| |
| |
| .. method:: logical_xor(x, y) |
| |
| Applies the logical operation *xor* between each operand's digits. |
| |
| |
| .. method:: Context.max(x, y) |
| .. method:: max(x, y) |
| |
n | Compare two values numerically and return the maximum. |
n | Compares two values numerically and returns the maximum. |
| |
n | If they are numerically equal then the left-hand operand is chosen as the |
| result. |
| |
n | .. method:: max_mag(x, y) |
| |
n | Compares the values numerically with their sign ignored. |
| |
| |
| .. method:: Context.min(x, y) |
| .. method:: min(x, y) |
| |
n | Compare two values numerically and return the minimum. |
n | Compares two values numerically and returns the minimum. |
| |
n | If they are numerically equal then the left-hand operand is chosen as the |
| result. |
| |
n | .. method:: min_mag(x, y) |
| |
n | Compares the values numerically with their sign ignored. |
| |
| |
| .. method:: Context.minus(x) |
| .. method:: minus(x) |
| |
n | Minus corresponds to the unary prefix minus operator in Python. |
n | Minus corresponds to the unary prefix minus operator in Python. |
| |
| |
n | .. method:: Context.multiply(x, y) |
n | .. method:: multiply(x, y) |
| |
n | Return the product of *x* and *y*. |
n | Return the product of *x* and *y*. |
| |
| |
n | .. method:: Context.normalize(x) |
n | .. method:: next_minus(x) |
| |
n | Normalize reduces an operand to its simplest form. |
n | Returns the largest representable number smaller than *x*. |
| |
n | Essentially a :meth:`plus` operation with all trailing zeros removed from the |
| result. |
| |
n | |
| .. method:: Context.plus(x) |
| .. method:: next_plus(x) |
| |
n | Returns the smallest representable number larger than *x*. |
| |
| |
| .. method:: next_toward(x, y) |
| |
| Returns the number closest to *x*, in direction towards *y*. |
| |
| |
| .. method:: normalize(x) |
| |
| Reduces *x* to its simplest form. |
| |
| |
| .. method:: number_class(x) |
| |
| Returns an indication of the class of *x*. |
| |
| |
| .. method:: plus(x) |
| |
| Plus corresponds to the unary prefix plus operator in Python. This operation |
| Plus corresponds to the unary prefix plus operator in Python. This |
| applies the context precision and rounding, so it is *not* an identity |
| operation applies the context precision and rounding, so it is *not* an |
| operation. |
| identity operation. |
| |
| |
n | .. method:: Context.power(x, y[, modulo]) |
n | .. method:: power(x, y[, modulo]) |
| |
n | Return ``x ** y`` to the *modulo* if given. |
n | Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if given. |
| |
n | The right-hand operand must be a whole number whose integer part (after any |
n | With two arguments, compute ``x**y``. If ``x`` is negative then ``y`` |
| exponent has been applied) has no more than 9 digits and whose fractional part |
| must be integral. The result will be inexact unless ``y`` is integral and |
| (if any) is all zeros before any rounding. The operand may be positive, |
| the result is finite and can be expressed exactly in 'precision' digits. |
| negative, or zero; if negative, the absolute value of the power is used, and the |
| The result should always be correctly rounded, using the rounding mode of |
| left-hand operand is inverted (divided into 1) before use. |
| the current thread's context. |
| |
n | If the increased precision needed for the intermediate calculations exceeds the |
n | With three arguments, compute ``(x**y) % modulo``. For the three argument |
| capabilities of the implementation then an :const:`InvalidOperation` condition |
| form, the following restrictions on the arguments hold: |
| is signaled. |
| |
n | If, when raising to a negative power, an underflow occurs during the division |
n | - all three arguments must be integral |
| into 1, the operation is not halted at that point but continues. |
| - ``y`` must be nonnegative |
| - at least one of ``x`` or ``y`` must be nonzero |
| - ``modulo`` must be nonzero and have at most 'precision' digits |
| |
n | The result of ``Context.power(x, y, modulo)`` is identical to the result |
| that would be obtained by computing ``(x**y) % modulo`` with unbounded |
| precision, but is computed more efficiently. It is always exact. |
| |
n | .. versionchanged:: 2.6 |
| ``y`` may now be nonintegral in ``x**y``. |
| Stricter requirements for the three-argument version. |
| |
| |
| .. method:: Context.quantize(x, y) |
| .. method:: quantize(x, y) |
| |
n | Returns a value equal to *x* after rounding and having the exponent of *y*. |
n | Returns a value equal to *x* (rounded), having the exponent of *y*. |
| |
n | Unlike other operations, if the length of the coefficient after the quantize |
| operation would be greater than precision, then an :const:`InvalidOperation` is |
| signaled. This guarantees that, unless there is an error condition, the |
| quantized exponent is always equal to that of the right-hand operand. |
| |
n | Also unlike other operations, quantize never signals Underflow, even if the |
n | .. method:: radix() |
| result is subnormal and inexact. |
| |
n | Just returns 10, as this is Decimal, :) |
| |
n | |
| .. method:: Context.remainder(x, y) |
| .. method:: remainder(x, y) |
| |
n | Returns the remainder from integer division. |
n | Returns the remainder from integer division. |
| |
n | The sign of the result, if non-zero, is the same as that of the original |
n | The sign of the result, if non-zero, is the same as that of the original |
| dividend. |
| dividend. |
| |
n | |
| .. method:: Context.remainder_near(x, y) |
| .. method:: remainder_near(x, y) |
| |
n | Computed the modulo as either a positive or negative value depending on which is |
n | Returns ``x - y * n``, where *n* is the integer nearest the exact value |
| closest to zero. For instance, ``Decimal(10).remainder_near(6)`` returns |
| of ``x / y`` (if the result is 0 then its sign will be the sign of *x*). |
| ``Decimal("-2")`` which is closer to zero than ``Decimal("4")``. |
| |
n | If both are equally close, the one chosen will have the same sign as *self*. |
| |
n | .. method:: rotate(x, y) |
| |
n | Returns a rotated copy of *x*, *y* times. |
| |
| |
| .. method:: Context.same_quantum(x, y) |
| .. method:: same_quantum(x, y) |
| |
n | Test whether *x* and *y* have the same exponent or whether both are |
n | Returns True if the two operands have the same exponent. |
| :const:`NaN`. |
| |
| |
n | .. method:: scaleb (x, y) |
| |
| Returns the first operand after adding the second value its exp. |
| |
| |
| .. method:: shift(x, y) |
| |
| Returns a shifted copy of *x*, *y* times. |
| |
| |
| .. method:: Context.sqrt(x) |
| .. method:: sqrt(x) |
| |
n | Return the square root of *x* to full precision. |
n | Square root of a non-negative number to context precision. |
| |
| |
n | .. method:: Context.subtract(x, y) |
n | .. method:: subtract(x, y) |
| |
n | Return the difference between *x* and *y*. |
n | Return the difference between *x* and *y*. |
| |
| |
n | .. method:: Context.to_eng_string() |
n | .. method:: to_eng_string(x) |
| |
n | Convert to engineering-type string. |
n | Converts a number to a string, using scientific notation. |
| |
n | Engineering notation has an exponent which is a multiple of 3, so there are up |
| to 3 digits left of the decimal place. For example, converts |
| ``Decimal('123E+1')`` to ``Decimal("1.23E+3")`` |
| |
n | |
| .. method:: Context.to_integral(x) |
| .. method:: to_integral_exact(x) |
| |
n | Rounds to the nearest integer without signaling :const:`Inexact` or |
n | Rounds to an integer. |
| :const:`Rounded`. |
| |
| |
n | .. method:: Context.to_sci_string(x) |
n | .. method:: to_sci_string(x) |
| |
n | Converts a number to a string using scientific notation. |
n | Converts a number to a string using scientific notation. |
| |
n | .. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
n | .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| |
| |
| .. _decimal-signals: |
| |
| Signals |
| ------- |
| |
| Signals represent conditions that arise during computation. Each corresponds to |
| one context flag and one context trap enabler. |
| |
n | The context flag is incremented whenever the condition is encountered. After the |
n | The context flag is set whenever the condition is encountered. After the |
| computation, flags may be checked for informational purposes (for instance, to |
| determine whether a computation was exact). After checking the flags, be sure to |
| clear all flags before starting the next computation. |
| |
| If the context's trap enabler is set for the signal, then the condition causes a |
| Python exception to be raised. For example, if the :class:`DivisionByZero` trap |
| is set, then a :exc:`DivisionByZero` exception is raised upon encountering the |
| condition. |
| |
| |
| .. class:: Clamped |
| |
| Altered an exponent to fit representation constraints. |
| |
| Typically, clamping occurs when an exponent falls outside the context's |
| :attr:`Emin` and :attr:`Emax` limits. If possible, the exponent is reduced to |
n | fit by adding zeroes to the coefficient. |
n | fit by adding zeros to the coefficient. |
| |
| |
| .. class:: DecimalException |
| |
| Base class for other signals and a subclass of :exc:`ArithmeticError`. |
| |
| |
| .. class:: DivisionByZero |
| 7.38905609893 |
| >>> print exp(2+0j) |
| (7.38905609893+0j) |
| |
| """ |
| getcontext().prec += 2 |
| i, lasts, s, fact, num = 0, 0, 1, 1, 1 |
| while s != lasts: |
n | lasts = s |
n | lasts = s |
| i += 1 |
| fact *= i |
n | num *= x |
n | num *= x |
| s += num / fact |
| s += num / fact |
| getcontext().prec -= 2 |
| getcontext().prec -= 2 |
| return +s |
| |
| def cos(x): |
| """Return the cosine of x as measured in radians. |
| |
| >>> print cos(Decimal('0.5')) |
| 0.8775825618903727161162815826 |
| >>> print cos(0.5) |
| 0.87758256189 |
| >>> print cos(0.5+0j) |
| (0.87758256189+0j) |
| |
| """ |
| getcontext().prec += 2 |
| i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1 |
| while s != lasts: |
n | lasts = s |
n | lasts = s |
| i += 2 |
| fact *= i * (i-1) |
| num *= x * x |
| sign *= -1 |
n | s += num / fact * sign |
n | s += num / fact * sign |
| getcontext().prec -= 2 |
| getcontext().prec -= 2 |
| return +s |
| |
| def sin(x): |
| """Return the sine of x as measured in radians. |
| |
| >>> print sin(Decimal('0.5')) |
| 0.4794255386042030002732879352 |
| >>> print sin(0.5) |
| 0.479425538604 |
| >>> print sin(0.5+0j) |
| (0.479425538604+0j) |
| |
| """ |
| getcontext().prec += 2 |
| i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1 |
| while s != lasts: |
n | lasts = s |
n | lasts = s |
| i += 2 |
| fact *= i * (i-1) |
| num *= x * x |
| sign *= -1 |
n | s += num / fact * sign |
n | s += num / fact * sign |
| getcontext().prec -= 2 |
| getcontext().prec -= 2 |
| return +s |
| |
| |
n | .. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
n | .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| |
| |
| .. _decimal-faq: |
| |
| Decimal FAQ |
| ----------- |
| |
n | Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to |
n | Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to |
| minimize typing when using the interactive interpreter? |
| |
n | A. Some users abbreviate the constructor to just a single letter:: |
n | A. Some users abbreviate the constructor to just a single letter: |
| |
| >>> D = decimal.Decimal |
| >>> D('1.23') + D('3.45') |
n | Decimal("4.68") |
n | Decimal('4.68') |
| |
n | Q. In a fixed-point application with two decimal places, some inputs have many |
n | Q. In a fixed-point application with two decimal places, some inputs have many |
| places and need to be rounded. Others are not supposed to have excess digits |
| and need to be validated. What methods should be used? |
| |
n | A. The :meth:`quantize` method rounds to a fixed number of decimal places. If |
n | A. The :meth:`quantize` method rounds to a fixed number of decimal places. If |
| the :const:`Inexact` trap is set, it is also useful for validation:: |
| the :const:`Inexact` trap is set, it is also useful for validation: |
| |
| >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01') |
| |
| >>> # Round to two places |
n | >>> Decimal("3.214").quantize(TWOPLACES) |
n | >>> Decimal('3.214').quantize(TWOPLACES) |
| Decimal("3.21") |
| Decimal('3.21') |
| |
n | >>> # Validate that a number does not exceed two places |
n | >>> # Validate that a number does not exceed two places |
| >>> Decimal("3.21").quantize(TWOPLACES, context=Context(traps=[Inexact])) |
| >>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact])) |
| Decimal("3.21") |
| Decimal('3.21') |
| |
n | >>> Decimal("3.214").quantize(TWOPLACES, context=Context(traps=[Inexact])) |
n | >>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact])) |
| Traceback (most recent call last): |
| ... |
n | Inexact: Changed in rounding |
n | Inexact |
| |
n | Q. Once I have valid two place inputs, how do I maintain that invariant |
n | Q. Once I have valid two place inputs, how do I maintain that invariant |
| throughout an application? |
| |
n | A. Some operations like addition and subtraction automatically preserve fixed |
n | A. Some operations like addition, subtraction, and multiplication by an integer |
| point. Others, like multiplication and division, change the number of decimal |
| will automatically preserve fixed point. Others operations, like division and |
| non-integer multiplication, will change the number of decimal places and need to |
| places and need to be followed-up with a :meth:`quantize` step. |
| be followed-up with a :meth:`quantize` step: |
| |
n | >>> a = Decimal('102.72') # Initial fixed-point values |
| >>> b = Decimal('3.17') |
| >>> a + b # Addition preserves fixed-point |
| Decimal('105.89') |
| >>> a - b |
| Decimal('99.55') |
| >>> a * 42 # So does integer multiplication |
| Decimal('4314.24') |
| >>> (a * b).quantize(TWOPLACES) # Must quantize non-integer multiplication |
| Decimal('325.62') |
| >>> (b / a).quantize(TWOPLACES) # And quantize division |
| Decimal('0.03') |
| |
| In developing fixed-point applications, it is convenient to define functions |
| to handle the :meth:`quantize` step: |
| |
| >>> def mul(x, y, fp=TWOPLACES): |
| ... return (x * y).quantize(fp) |
| >>> def div(x, y, fp=TWOPLACES): |
| ... return (x / y).quantize(fp) |
| |
| >>> mul(a, b) # Automatically preserve fixed-point |
| Decimal('325.62') |
| >>> div(b, a) |
| Decimal('0.03') |
| |
| Q. There are many ways to express the same value. The numbers :const:`200`, |
| Q. There are many ways to express the same value. The numbers :const:`200`, |
| :const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at |
| various precisions. Is there a way to transform them to a single recognizable |
| canonical value? |
| |
n | A. The :meth:`normalize` method maps all equivalent values to a single |
n | A. The :meth:`normalize` method maps all equivalent values to a single |
| representative:: |
| representative: |
| |
| >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split()) |
| >>> [v.normalize() for v in values] |
n | [Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")] |
n | [Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')] |
| |
n | Q. Some decimal values always print with exponential notation. Is there a way |
n | Q. Some decimal values always print with exponential notation. Is there a way |
| to get a non-exponential representation? |
| |
n | A. For some values, exponential notation is the only way to express the number |
n | A. For some values, exponential notation is the only way to express the number |
| of significant places in the coefficient. For example, expressing |
| :const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the |
| original's two-place significance. |
| |
n | If an application does not care about tracking significance, it is easy to |
| remove the exponent and trailing zeroes, losing significance, but keeping the |
| value unchanged: |
| |
| >>> def remove_exponent(d): |
| ... return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize() |
| |
| >>> remove_exponent(Decimal('5E+3')) |
| Decimal('5000') |
| |
| Q. Is there a way to convert a regular float to a :class:`Decimal`? |
| Q. Is there a way to convert a regular float to a :class:`Decimal`? |
| |
n | A. Yes, all binary floating point numbers can be exactly expressed as a |
n | A. Yes, all binary floating point numbers can be exactly expressed as a |
| Decimal. An exact conversion may take more precision than intuition would |
n | suggest, so trapping :const:`Inexact` will signal a need for more precision:: |
n | suggest, so we trap :const:`Inexact` to signal a need for more precision: |
| |
n | .. testcode:: |
| |
| def floatToDecimal(f): |
| def float_to_decimal(f): |
| "Convert a floating point number to a Decimal with no loss of information" |
| "Convert a floating point number to a Decimal with no loss of information" |
| # Transform (exactly) a float to a mantissa (0.5 <= abs(m) < 1.0) and an |
| n, d = f.as_integer_ratio() |
| # exponent. Double the mantissa until it is an integer. Use the integer |
| numerator, denominator = Decimal(n), Decimal(d) |
| # mantissa and exponent to compute an equivalent Decimal. If this cannot |
| ctx = Context(prec=60) |
| # be done exactly, then retry with more precision. |
| result = ctx.divide(numerator, denominator) |
| while ctx.flags[Inexact]: |
| ctx.flags[Inexact] = False |
| ctx.prec *= 2 |
| result = ctx.divide(numerator, denominator) |
| return result |
| |
n | mantissa, exponent = math.frexp(f) |
n | .. doctest:: |
| while mantissa != int(mantissa): |
| mantissa *= 2.0 |
| exponent -= 1 |
| mantissa = int(mantissa) |
| |
n | oldcontext = getcontext() |
n | >>> float_to_decimal(math.pi) |
| setcontext(Context(traps=[Inexact])) |
| Decimal('3.141592653589793115997963468544185161590576171875') |
| try: |
| while True: |
| try: |
| return mantissa * Decimal(2) ** exponent |
| except Inexact: |
| getcontext().prec += 1 |
| finally: |
| setcontext(oldcontext) |
| |
n | Q. Why isn't the :func:`floatToDecimal` routine included in the module? |
n | Q. Why isn't the :func:`float_to_decimal` routine included in the module? |
| |
n | A. There is some question about whether it is advisable to mix binary and |
n | A. There is some question about whether it is advisable to mix binary and |
| decimal floating point. Also, its use requires some care to avoid the |
n | representation issues associated with binary floating point:: |
n | representation issues associated with binary floating point: |
| |
n | >>> floatToDecimal(1.1) |
n | >>> float_to_decimal(1.1) |
| Decimal("1.100000000000000088817841970012523233890533447265625") |
| Decimal('1.100000000000000088817841970012523233890533447265625') |
| |
n | Q. Within a complex calculation, how can I make sure that I haven't gotten a |
n | Q. Within a complex calculation, how can I make sure that I haven't gotten a |
| spurious result because of insufficient precision or rounding anomalies. |
| |
n | A. The decimal module makes it easy to test results. A best practice is to re- |
n | A. The decimal module makes it easy to test results. A best practice is to |
| run calculations using greater precision and with various rounding modes. Widely |
| re-run calculations using greater precision and with various rounding modes. |
| differing results indicate insufficient precision, rounding mode issues, ill- |
| Widely differing results indicate insufficient precision, rounding mode issues, |
| conditioned inputs, or a numerically unstable algorithm. |
| ill-conditioned inputs, or a numerically unstable algorithm. |
| |
n | Q. I noticed that context precision is applied to the results of operations but |
n | Q. I noticed that context precision is applied to the results of operations but |
| not to the inputs. Is there anything to watch out for when mixing values of |
| different precisions? |
| |
n | A. Yes. The principle is that all values are considered to be exact and so is |
n | A. Yes. The principle is that all values are considered to be exact and so is |
| the arithmetic on those values. Only the results are rounded. The advantage |
| for inputs is that "what you type is what you get". A disadvantage is that the |
n | results can look odd if you forget that the inputs haven't been rounded:: |
n | results can look odd if you forget that the inputs haven't been rounded: |
| |
| .. doctest:: newcontext |
| |
| >>> getcontext().prec = 3 |
n | >>> Decimal('3.104') + D('2.104') |
n | >>> Decimal('3.104') + Decimal('2.104') |
| Decimal("5.21") |
| Decimal('5.21') |
| >>> Decimal('3.104') + D('0.000') + D('2.104') |
| >>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104') |
| Decimal("5.20") |
| Decimal('5.20') |
| |
| The solution is either to increase precision or to force rounding of inputs |
n | using the unary plus operation:: |
n | using the unary plus operation: |
| |
| .. doctest:: newcontext |
| |
| >>> getcontext().prec = 3 |
| >>> +Decimal('1.23456789') # unary plus triggers rounding |
n | Decimal("1.23") |
n | Decimal('1.23') |
| |
| Alternatively, inputs can be rounded upon creation using the |
n | :meth:`Context.create_decimal` method:: |
n | :meth:`Context.create_decimal` method: |
| |
| >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678') |
t | Decimal("1.2345") |
t | Decimal('1.2345') |
| |