: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>

.. versionadded:: 2.4

.. 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

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

  + 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

  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

  alterable precision (defaulting to 28 places) which can be as large as needed for

  a given problem:

     >>> getcontext().prec = 6

     >>> Decimal(1) / Decimal(7)

     Decimal('0.142857')

     >>> getcontext().prec = 28

     >>> Decimal(1) / Decimal(7)

     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.

  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

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`,

: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

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::

   * IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic

     Specification <http://www2.hursley.ibm.com/decimal/decarith.html>`_.

   * IEEE standard 854-1987, `Unofficial IEEE 854 Text

     <http://754r.ucbtest.org/standards/854.pdf>`_.

.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

.. _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,

           capitals=1, flags=[], traps=[Overflow, 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

:const:`Infinity`, and :const:`-0`.

   >>> getcontext().prec = 28

   >>> Decimal(10)

   Decimal('10')

   >>> Decimal('3.14')

   Decimal('3.14')

   >>> Decimal((0, (3, 1, 4), -2))

   Decimal('3.14')

   >>> Decimal(str(2.0 ** 0.5))

   Decimal('1.41421356237')

   >>> Decimal(2) ** Decimal('0.5')

   Decimal('1.414213562373095048801688724')

   >>> Decimal('NaN')

   Decimal('NaN')

   >>> 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

operations.

.. doctest:: newcontext

   >>> getcontext().prec = 6

   >>> Decimal('3.0')

   Decimal('3.0')

   >>> Decimal('3.1415926535')

   Decimal('3.1415926535')

   >>> Decimal('3.1415926535') + Decimal('2.7182818285')

   Decimal('5.85987')

   >>> getcontext().rounding = ROUND_UP

   >>> Decimal('3.1415926535') + Decimal('2.7182818285')

   Decimal('5.85988')

Decimals interact well with much of the rest of Python.  Here is a small decimal

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)

   Decimal('9.25')

   >>> min(data)

   Decimal('0.03')

   >>> sorted(data)

   [Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),

    Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]

   >>> sum(data)

   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

   Decimal('6.70')

   >>> a * b

   Decimal('2.5058')

   >>> c % a

   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

places:

   >>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)

   Decimal('7.32')

   >>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)

   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

enabled:

.. doctest:: newcontext

   :options: +NORMALIZE_WHITESPACE

   >>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)

   >>> setcontext(myothercontext)

   >>> Decimal(1) / Decimal(7)

   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)

   Decimal('0.142857143')

   >>> Decimal(42) / Decimal(0)

   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)

   Decimal('3.14159292')

   >>> getcontext()

   Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,

           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

context:

.. doctest:: newcontext

   >>> setcontext(ExtendedContext)

   >>> Decimal(1) / Decimal(0)

   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.

.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

.. _decimal-decimal:

Decimal objects

---------------

.. class:: Decimal([value [, context]])

   Construct a new :class:`Decimal` object based from *value*.

   *value* can be an integer, string, tuple, or another :class:`Decimal`

   object. If no *value* is given, returns ``Decimal('0')``.  If *value* is a

   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

      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))``

   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,

   ``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.

   .. 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 built-in

   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, pickled, printed, used as dictionary keys, used as set elements,

   compared, sorted, and coerced to another type (such as :class:`float` or

   :class:`long`).

   In addition to the standard numeric properties, decimal floating point

   objects also have a number of specialized methods:

   .. method:: adjusted()

      Return the adjusted exponent after shifting out the coefficient's

      rightmost digits until only the lead digit remains:

      ``Decimal('321e+5').adjusted()`` returns seven.  Used for determining the

      position of the most significant digit with respect to the decimal point.

   .. method:: as_tuple()

      Return a :term:`named tuple` representation of the number:

      ``DecimalTuple(sign, digits, exponent)``.

      .. versionchanged:: 2.6

         Use a named tuple.

   .. 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:: compare(other[, context])

      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::

         a or b is a NaN ==> Decimal('NaN')

         a < b           ==> Decimal('-1')

         a == b          ==> Decimal('0')

         a > b           ==> Decimal('1')

   .. method:: compare_signal(other[, context])

      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