Move the 3k reST doc tree in place.
diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
new file mode 100644
index 0000000..1d17109
--- /dev/null
+++ b/Doc/library/decimal.rst
@@ -0,0 +1,1289 @@
+
+:mod:`decimal` --- Decimal 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
+
+The :mod:`decimal` module provides support for decimal floating point
+arithmetic. It offers several advantages over the :class:`float()` datatype:
+
+* 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, result
+ is :const:`5.5511151231257827e-017`. While near to zero, the differences
+ prevent reliable equality testing and differences can accumulate. For this
+ reason, decimal would be 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
+ settable 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.
+
+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 zeroes. 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`, and :const:`ROUND_UP`.
+
+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 incremented from zero and, 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://www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html>`_.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _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, InvalidOperation,
+ DivisionByZero])
+
+ >>> 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`. ::
+
+ >>> 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("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. ::
+
+ >>> 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::
+
+ >>> 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")
+
+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::
+
+ >>> 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=[Inexact, Rounded], 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::
+
+ >>> 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]])
+
+ Constructs 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::
+
+ 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 zeroes 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.
+
+Decimal floating point objects share many properties with the other builtin
+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:: Decimal.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:: Decimal.as_tuple()
+
+ Returns a tuple representation of the number: ``(sign, digittuple, exponent)``.
+
+
+.. method:: Decimal.compare(other[, context])
+
+ Compares like :meth:`__cmp__` but returns a decimal instance::
+
+ a or b is a NaN ==> Decimal("NaN")
+ a < b ==> Decimal("-1")
+ a == b ==> Decimal("0")
+ a > b ==> Decimal("1")
+
+
+.. method:: Decimal.max(other[, context])
+
+ Like ``max(self, other)`` except that the context rounding rule is applied
+ before returning and that :const:`NaN` values are either signalled or ignored
+ (depending on the context and whether they are signaling or quiet).
+
+
+.. method:: Decimal.min(other[, context])
+
+ Like ``min(self, other)`` except that the context rounding rule is applied
+ before returning and that :const:`NaN` values are either signalled or ignored
+ (depending on the context and whether they are signaling or quiet).
+
+
+.. method:: Decimal.normalize([context])
+
+ Normalize the number by stripping the rightmost trailing zeroes and converting
+ any result equal to :const:`Decimal("0")` to :const:`Decimal("0e0")`. Used for
+ producing canonical 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")``.
+
+
+.. method:: Decimal.quantize(exp [, rounding[, context[, watchexp]]])
+
+ Quantize makes the exponent the same as *exp*. Searches for a rounding method
+ in *rounding*, then in *context*, and then in the current context.
+
+ If *watchexp* is set (default), then an error is returned whenever the resulting
+ exponent is greater than :attr:`Emax` or less than :attr:`Etiny`.
+
+
+.. method:: Decimal.remainder_near(other[, context])
+
+ Computes the modulo as either a positive or negative value depending on which is
+ closest to zero. For instance, ``Decimal(10).remainder_near(6)`` returns
+ ``Decimal("-2")`` which is closer to zero than ``Decimal("4")``.
+
+ If both are equally close, the one chosen will have the same sign as *self*.
+
+
+.. method:: Decimal.same_quantum(other[, context])
+
+ Test whether self and other have the same exponent or whether both are
+ :const:`NaN`.
+
+
+.. method:: Decimal.sqrt([context])
+
+ Return the square root to full precision.
+
+
+.. method:: Decimal.to_eng_string([context])
+
+ Convert to an engineering-type string.
+
+ 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")``
+
+
+.. method:: Decimal.to_integral([rounding[, context]])
+
+ Rounds to the nearest integer without signaling :const:`Inexact` or
+ :const:`Rounded`. If given, applies *rounding*; otherwise, uses the rounding
+ method in either the supplied *context* or the current context.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _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.
+
+Each thread has its own current context which is accessed or changed using the
+:func:`getcontext` and :func:`setcontext` functions:
+
+
+.. function:: getcontext()
+
+ Return the current context for the active thread.
+
+
+.. function:: setcontext(c)
+
+ Set the current context for the active thread to *c*.
+
+Beginning with Python 2.5, you can also use the :keyword:`with` statement and
+the :func:`localcontext` function to temporarily change the active context.
+
+
+.. function:: localcontext([c])
+
+ Return a context manager that will set the current context for the active thread
+ to a copy of *c* on entry to the with-statement and restore the previous context
+ when exiting the with-statement. If no context is specified, a copy of the
+ current context is used.
+
+ .. versionadded:: 2.5
+
+ For example, the following code sets the current decimal precision to 42 places,
+ performs a calculation, and then automatically restores the previous context::
+
+ from __future__ import with_statement
+ from decimal import localcontext
+
+ with localcontext() as ctx:
+ ctx.prec = 42 # Perform a high precision calculation
+ s = calculate_something()
+ s = +s # Round the final result back to the default precision
+
+New contexts can also be created using the :class:`Context` constructor
+described below. In addition, the module provides three pre-made contexts:
+
+
+.. class:: BasicContext
+
+ This is a standard context defined by the General Decimal Arithmetic
+ Specification. Precision is set to nine. Rounding is set to
+ :const:`ROUND_HALF_UP`. All flags are cleared. All traps are enabled (treated
+ as exceptions) except :const:`Inexact`, :const:`Rounded`, and
+ :const:`Subnormal`.
+
+ Because many of the traps are enabled, this context is useful for debugging.
+
+
+.. class:: ExtendedContext
+
+ This is a standard context defined by the General Decimal Arithmetic
+ Specification. Precision is set to nine. Rounding is set to
+ :const:`ROUND_HALF_EVEN`. All flags are cleared. No traps are enabled (so that
+ exceptions are not raised during computations).
+
+ Because the trapped are disabled, this context is useful for applications that
+ prefer to have result value of :const:`NaN` or :const:`Infinity` instead of
+ raising exceptions. This allows an application to complete a run in the
+ presence of conditions that would otherwise halt the program.
+
+
+.. class:: DefaultContext
+
+ This context is used by the :class:`Context` constructor as a prototype for new
+ contexts. Changing a field (such a precision) has the effect of changing the
+ default for new contexts creating by the :class:`Context` constructor.
+
+ This context is most useful in multi-threaded environments. Changing one of the
+ fields before threads are started has the effect of setting system-wide
+ defaults. Changing the fields after threads have started is not recommended as
+ it would require thread synchronization to prevent race conditions.
+
+ In single threaded environments, it is preferable to not use this context at
+ all. Instead, simply create contexts explicitly as described below.
+
+ The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled traps
+ for Overflow, InvalidOperation, and DivisionByZero.
+
+In addition to the three supplied contexts, new contexts can be created with the
+:class:`Context` constructor.
+
+
+.. class:: Context(prec=None, rounding=None, traps=None, flags=None, Emin=None, Emax=None, capitals=1)
+
+ Creates a new context. If a field is not specified or is :const:`None`, the
+ 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:
+
+ * :const:`ROUND_CEILING` (towards :const:`Infinity`),
+ * :const:`ROUND_DOWN` (towards zero),
+ * :const:`ROUND_FLOOR` (towards :const:`-Infinity`),
+ * :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_UP` (to nearest with ties going away from zero), or
+ * :const:`ROUND_UP` (away from 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')`.
+
+The :class:`Context` class defines several general purpose methods as well as a
+large number of methods for doing arithmetic directly in a given context.
+
+
+.. method:: Context.clear_flags()
+
+ Resets all of the flags to :const:`0`.
+
+
+.. method:: Context.copy()
+
+ Return a duplicate of the context.
+
+
+.. method:: Context.create_decimal(num)
+
+ Creates a new Decimal instance from *num* but using *self* as context. Unlike
+ the :class:`Decimal` constructor, the context precision, rounding method, flags,
+ and traps are applied to the conversion.
+
+ This is useful because constants are often given to a greater precision than is
+ needed by the application. Another benefit is that rounding immediately
+ eliminates unintended effects from digits beyond the current precision. In the
+ following example, using unrounded inputs means that adding zero to a sum can
+ change the result::
+
+ >>> getcontext().prec = 3
+ >>> Decimal("3.4445") + Decimal("1.0023")
+ Decimal("4.45")
+ >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023")
+ Decimal("4.44")
+
+
+.. method:: Context.Etiny()
+
+ Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent value
+ for subnormal results. When underflow occurs, the exponent is set to
+ :const:`Etiny`.
+
+
+.. method:: Context.Etop()
+
+ Returns a value equal to ``Emax - prec + 1``.
+
+The usual approach to working with decimals is to create :class:`Decimal`
+instances and then apply arithmetic operations which take place within the
+current context for the active thread. An alternate approach is to use context
+methods for calculating within a specific context. The methods are similar to
+those for the :class:`Decimal` class and are only briefly recounted here.
+
+
+.. method:: Context.abs(x)
+
+ Returns the absolute value of *x*.
+
+
+.. method:: Context.add(x, y)
+
+ Return the sum of *x* and *y*.
+
+
+.. method:: Context.compare(x, y)
+
+ Compares values numerically.
+
+ Like :meth:`__cmp__` but returns a decimal instance::
+
+ a or b is a NaN ==> Decimal("NaN")
+ a < b ==> Decimal("-1")
+ a == b ==> Decimal("0")
+ a > b ==> Decimal("1")
+
+
+.. method:: Context.divide(x, y)
+
+ Return *x* divided by *y*.
+
+
+.. method:: Context.divmod(x, y)
+
+ Divides two numbers and returns the integer part of the result.
+
+
+.. method:: Context.max(x, y)
+
+ Compare two values numerically and return the maximum.
+
+ If they are numerically equal then the left-hand operand is chosen as the
+ result.
+
+
+.. method:: Context.min(x, y)
+
+ Compare two values numerically and return the minimum.
+
+ If they are numerically equal then the left-hand operand is chosen as the
+ result.
+
+
+.. method:: Context.minus(x)
+
+ Minus corresponds to the unary prefix minus operator in Python.
+
+
+.. method:: Context.multiply(x, y)
+
+ Return the product of *x* and *y*.
+
+
+.. method:: Context.normalize(x)
+
+ Normalize reduces an operand to its simplest form.
+
+ Essentially a :meth:`plus` operation with all trailing zeros removed from the
+ result.
+
+
+.. method:: Context.plus(x)
+
+ Plus corresponds to the unary prefix plus operator in Python. This operation
+ applies the context precision and rounding, so it is *not* an identity
+ operation.
+
+
+.. method:: Context.power(x, y[, modulo])
+
+ Return ``x ** y`` to the *modulo* if given.
+
+ The right-hand operand must be a whole number whose integer part (after any
+ exponent has been applied) has no more than 9 digits and whose fractional part
+ (if any) is all zeros before any rounding. The operand may be positive,
+ negative, or zero; if negative, the absolute value of the power is used, and the
+ left-hand operand is inverted (divided into 1) before use.
+
+ If the increased precision needed for the intermediate calculations exceeds the
+ capabilities of the implementation then an :const:`InvalidOperation` condition
+ is signaled.
+
+ If, when raising to a negative power, an underflow occurs during the division
+ into 1, the operation is not halted at that point but continues.
+
+
+.. method:: Context.quantize(x, y)
+
+ Returns a value equal to *x* after rounding and having the exponent of *y*.
+
+ 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.
+
+
+.. method:: Context.remainder(x, y)
+
+ Returns the remainder from integer division.
+
+ The sign of the result, if non-zero, is the same as that of the original
+ dividend.
+
+
+.. method:: Context.remainder_near(x, y)
+
+ Computed the modulo as either a positive or negative value depending on which is
+ closest to zero. For instance, ``Decimal(10).remainder_near(6)`` returns
+ ``Decimal("-2")`` which is closer to zero than ``Decimal("4")``.
+
+ If both are equally close, the one chosen will have the same sign as *self*.
+
+
+.. method:: Context.same_quantum(x, y)
+
+ Test whether *x* and *y* have the same exponent or whether both are
+ :const:`NaN`.
+
+
+.. method:: Context.sqrt(x)
+
+ Return the square root of *x* to full precision.
+
+
+.. method:: Context.subtract(x, y)
+
+ Return the difference between *x* and *y*.
+
+
+.. method:: Context.to_eng_string()
+
+ Convert to engineering-type string.
+
+ 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")``
+
+
+.. method:: Context.to_integral(x)
+
+ Rounds to the nearest integer without signaling :const:`Inexact` or
+ :const:`Rounded`.
+
+
+.. method:: Context.to_sci_string(x)
+
+ Converts a number to a string using scientific notation.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-signals:
+
+Signals
+-------
+
+Signals represent conditions that arise during computation. Each corresponds to
+one context flag and one context trap enabler.
+
+The context flag is incremented 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
+ fit by adding zeroes to the coefficient.
+
+
+.. class:: DecimalException
+
+ Base class for other signals and a subclass of :exc:`ArithmeticError`.
+
+
+.. class:: DivisionByZero
+
+ Signals the division of a non-infinite number by zero.
+
+ Can occur with division, modulo division, or when raising a number to a negative
+ power. If this signal is not trapped, returns :const:`Infinity` or
+ :const:`-Infinity` with the sign determined by the inputs to the calculation.
+
+
+.. class:: Inexact
+
+ Indicates that rounding occurred and the result is not exact.
+
+ Signals when non-zero digits were discarded during rounding. The rounded result
+ is returned. The signal flag or trap is used to detect when results are
+ inexact.
+
+
+.. class:: InvalidOperation
+
+ An invalid operation was performed.
+
+ Indicates that an operation was requested that does not make sense. If not
+ trapped, returns :const:`NaN`. Possible causes include::
+
+ Infinity - Infinity
+ 0 * Infinity
+ Infinity / Infinity
+ x % 0
+ Infinity % x
+ x._rescale( non-integer )
+ sqrt(-x) and x > 0
+ 0 ** 0
+ x ** (non-integer)
+ x ** Infinity
+
+
+.. class:: Overflow
+
+ Numerical overflow.
+
+ Indicates the exponent is larger than :attr:`Emax` after rounding has occurred.
+ If not trapped, the result depends on the rounding mode, either pulling inward
+ to the largest representable finite number or rounding outward to
+ :const:`Infinity`. In either case, :class:`Inexact` and :class:`Rounded` are
+ also signaled.
+
+
+.. class:: Rounded
+
+ Rounding occurred though possibly no information was lost.
+
+ Signaled whenever rounding discards digits; even if those digits are zero (such
+ as rounding :const:`5.00` to :const:`5.0`). If not trapped, returns the result
+ unchanged. This signal is used to detect loss of significant digits.
+
+
+.. class:: Subnormal
+
+ Exponent was lower than :attr:`Emin` prior to rounding.
+
+ Occurs when an operation result is subnormal (the exponent is too small). If not
+ trapped, returns the result unchanged.
+
+
+.. class:: Underflow
+
+ Numerical underflow with result rounded to zero.
+
+ Occurs when a subnormal result is pushed to zero by rounding. :class:`Inexact`
+ and :class:`Subnormal` are also signaled.
+
+The following table summarizes the hierarchy of signals::
+
+ exceptions.ArithmeticError(exceptions.Exception)
+ DecimalException
+ Clamped
+ DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
+ Inexact
+ Overflow(Inexact, Rounded)
+ Underflow(Inexact, Rounded, Subnormal)
+ InvalidOperation
+ Rounded
+ Subnormal
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-notes:
+
+Floating Point Notes
+--------------------
+
+
+Mitigating round-off error with increased precision
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The use of decimal floating point eliminates decimal representation error
+(making it possible to represent :const:`0.1` exactly); however, some operations
+can still incur round-off error when non-zero digits exceed the fixed precision.
+
+The effects of round-off error can be amplified by the addition or subtraction
+of nearly offsetting quantities resulting in loss of significance. Knuth
+provides two instructive examples where rounded floating point arithmetic with
+insufficient precision causes the breakdown of the associative and distributive
+properties of addition::
+
+ # Examples from Seminumerical Algorithms, Section 4.2.2.
+ >>> from decimal import Decimal, getcontext
+ >>> getcontext().prec = 8
+
+ >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
+ >>> (u + v) + w
+ Decimal("9.5111111")
+ >>> u + (v + w)
+ Decimal("10")
+
+ >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
+ >>> (u*v) + (u*w)
+ Decimal("0.01")
+ >>> u * (v+w)
+ Decimal("0.0060000")
+
+The :mod:`decimal` module makes it possible to restore the identities by
+expanding the precision sufficiently to avoid loss of significance::
+
+ >>> getcontext().prec = 20
+ >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
+ >>> (u + v) + w
+ Decimal("9.51111111")
+ >>> u + (v + w)
+ Decimal("9.51111111")
+ >>>
+ >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
+ >>> (u*v) + (u*w)
+ Decimal("0.0060000")
+ >>> u * (v+w)
+ Decimal("0.0060000")
+
+
+Special values
+^^^^^^^^^^^^^^
+
+The number system for the :mod:`decimal` module provides special values
+including :const:`NaN`, :const:`sNaN`, :const:`-Infinity`, :const:`Infinity`,
+and two zeroes, :const:`+0` and :const:`-0`.
+
+Infinities can be constructed directly with: ``Decimal('Infinity')``. Also,
+they can arise from dividing by zero when the :exc:`DivisionByZero` signal is
+not trapped. Likewise, when the :exc:`Overflow` signal is not trapped, infinity
+can result from rounding beyond the limits of the largest representable number.
+
+The infinities are signed (affine) and can be used in arithmetic operations
+where they get treated as very large, indeterminate numbers. For instance,
+adding a constant to infinity gives another infinite result.
+
+Some operations are indeterminate and return :const:`NaN`, or if the
+:exc:`InvalidOperation` signal is trapped, raise an exception. For example,
+``0/0`` returns :const:`NaN` which means "not a number". This variety of
+:const:`NaN` is quiet and, once created, will flow through other computations
+always resulting in another :const:`NaN`. This behavior can be useful for a
+series of computations that occasionally have missing inputs --- it allows the
+calculation to proceed while flagging specific results as invalid.
+
+A variant is :const:`sNaN` which signals rather than remaining quiet after every
+operation. This is a useful return value when an invalid result needs to
+interrupt a calculation for special handling.
+
+The signed zeros can result from calculations that underflow. They keep the sign
+that would have resulted if the calculation had been carried out to greater
+precision. Since their magnitude is zero, both positive and negative zeros are
+treated as equal and their sign is informational.
+
+In addition to the two signed zeros which are distinct yet equal, there are
+various representations of zero with differing precisions yet equivalent in
+value. This takes a bit of getting used to. For an eye accustomed to
+normalized floating point representations, it is not immediately obvious that
+the following calculation returns a value equal to zero::
+
+ >>> 1 / Decimal('Infinity')
+ Decimal("0E-1000000026")
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-threads:
+
+Working with threads
+--------------------
+
+The :func:`getcontext` function accesses a different :class:`Context` object for
+each thread. Having separate thread contexts means that threads may make
+changes (such as ``getcontext.prec=10``) without interfering with other threads.
+
+Likewise, the :func:`setcontext` function automatically assigns its target to
+the current thread.
+
+If :func:`setcontext` has not been called before :func:`getcontext`, then
+:func:`getcontext` will automatically create a new context for use in the
+current thread.
+
+The new context is copied from a prototype context called *DefaultContext*. To
+control the defaults so that each thread will use the same values throughout the
+application, directly modify the *DefaultContext* object. This should be done
+*before* any threads are started so that there won't be a race condition between
+threads calling :func:`getcontext`. For example::
+
+ # Set applicationwide defaults for all threads about to be launched
+ DefaultContext.prec = 12
+ DefaultContext.rounding = ROUND_DOWN
+ DefaultContext.traps = ExtendedContext.traps.copy()
+ DefaultContext.traps[InvalidOperation] = 1
+ setcontext(DefaultContext)
+
+ # Afterwards, the threads can be started
+ t1.start()
+ t2.start()
+ t3.start()
+ . . .
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-recipes:
+
+Recipes
+-------
+
+Here are a few recipes that serve as utility functions and that demonstrate ways
+to work with the :class:`Decimal` class::
+
+ def moneyfmt(value, places=2, curr='', sep=',', dp='.',
+ pos='', neg='-', trailneg=''):
+ """Convert Decimal to a money formatted string.
+
+ places: required number of places after the decimal point
+ curr: optional currency symbol before the sign (may be blank)
+ sep: optional grouping separator (comma, period, space, or blank)
+ dp: decimal point indicator (comma or period)
+ only specify as blank when places is zero
+ pos: optional sign for positive numbers: '+', space or blank
+ neg: optional sign for negative numbers: '-', '(', space or blank
+ trailneg:optional trailing minus indicator: '-', ')', space or blank
+
+ >>> d = Decimal('-1234567.8901')
+ >>> moneyfmt(d, curr='$')
+ '-$1,234,567.89'
+ >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
+ '1.234.568-'
+ >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
+ '($1,234,567.89)'
+ >>> moneyfmt(Decimal(123456789), sep=' ')
+ '123 456 789.00'
+ >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
+ '<.02>'
+
+ """
+ q = Decimal((0, (1,), -places)) # 2 places --> '0.01'
+ sign, digits, exp = value.quantize(q).as_tuple()
+ assert exp == -places
+ result = []
+ digits = map(str, digits)
+ build, next = result.append, digits.pop
+ if sign:
+ build(trailneg)
+ for i in range(places):
+ if digits:
+ build(next())
+ else:
+ build('0')
+ build(dp)
+ i = 0
+ while digits:
+ build(next())
+ i += 1
+ if i == 3 and digits:
+ i = 0
+ build(sep)
+ build(curr)
+ if sign:
+ build(neg)
+ else:
+ build(pos)
+ result.reverse()
+ return ''.join(result)
+
+ def pi():
+ """Compute Pi to the current precision.
+
+ >>> print pi()
+ 3.141592653589793238462643383
+
+ """
+ getcontext().prec += 2 # extra digits for intermediate steps
+ three = Decimal(3) # substitute "three=3.0" for regular floats
+ lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
+ while s != lasts:
+ lasts = s
+ n, na = n+na, na+8
+ d, da = d+da, da+32
+ t = (t * n) / d
+ s += t
+ getcontext().prec -= 2
+ return +s # unary plus applies the new precision
+
+ def exp(x):
+ """Return e raised to the power of x. Result type matches input type.
+
+ >>> print exp(Decimal(1))
+ 2.718281828459045235360287471
+ >>> print exp(Decimal(2))
+ 7.389056098930650227230427461
+ >>> print exp(2.0)
+ 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:
+ lasts = s
+ i += 1
+ fact *= i
+ num *= x
+ s += num / fact
+ 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:
+ lasts = s
+ i += 2
+ fact *= i * (i-1)
+ num *= x * x
+ sign *= -1
+ s += num / fact * sign
+ 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:
+ lasts = s
+ i += 2
+ fact *= i * (i-1)
+ num *= x * x
+ sign *= -1
+ s += num / fact * sign
+ getcontext().prec -= 2
+ return +s
+
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-faq:
+
+Decimal FAQ
+-----------
+
+Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to
+minimize typing when using the interactive interpreter?
+
+\A. Some users abbreviate the constructor to just a single letter::
+
+ >>> D = decimal.Decimal
+ >>> D('1.23') + D('3.45')
+ Decimal("4.68")
+
+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?
+
+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::
+
+ >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01')
+
+ >>> # Round to two places
+ >>> Decimal("3.214").quantize(TWOPLACES)
+ Decimal("3.21")
+
+ >>> # Validate that a number does not exceed two places
+ >>> Decimal("3.21").quantize(TWOPLACES, context=Context(traps=[Inexact]))
+ Decimal("3.21")
+
+ >>> Decimal("3.214").quantize(TWOPLACES, context=Context(traps=[Inexact]))
+ Traceback (most recent call last):
+ ...
+ Inexact: Changed in rounding
+
+Q. Once I have valid two place inputs, how do I maintain that invariant
+throughout an application?
+
+A. Some operations like addition and subtraction automatically preserve fixed
+point. Others, like multiplication and division, change the number of decimal
+places and need to be followed-up with a :meth:`quantize` step.
+
+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?
+
+A. The :meth:`normalize` method maps all equivalent values to a single
+representative::
+
+ >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
+ >>> [v.normalize() for v in values]
+ [Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")]
+
+Q. Some decimal values always print with exponential notation. Is there a way
+to get a non-exponential representation?
+
+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.
+
+Q. Is there a way to convert a regular float to a :class:`Decimal`?
+
+A. Yes, all binary floating point numbers can be exactly expressed as a
+Decimal. An exact conversion may take more precision than intuition would
+suggest, so trapping :const:`Inexact` will signal a need for more precision::
+
+ def floatToDecimal(f):
+ "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
+ # exponent. Double the mantissa until it is an integer. Use the integer
+ # mantissa and exponent to compute an equivalent Decimal. If this cannot
+ # be done exactly, then retry with more precision.
+
+ mantissa, exponent = math.frexp(f)
+ while mantissa != int(mantissa):
+ mantissa *= 2.0
+ exponent -= 1
+ mantissa = int(mantissa)
+
+ oldcontext = getcontext()
+ setcontext(Context(traps=[Inexact]))
+ try:
+ while True:
+ try:
+ return mantissa * Decimal(2) ** exponent
+ except Inexact:
+ getcontext().prec += 1
+ finally:
+ setcontext(oldcontext)
+
+Q. Why isn't the :func:`floatToDecimal` routine included in the module?
+
+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
+representation issues associated with binary floating point::
+
+ >>> floatToDecimal(1.1)
+ Decimal("1.100000000000000088817841970012523233890533447265625")
+
+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.
+
+A. The decimal module makes it easy to test results. A best practice is to
+re-run calculations using greater precision and with various rounding modes.
+Widely differing results indicate insufficient precision, rounding mode issues,
+ill-conditioned inputs, or a numerically unstable algorithm.
+
+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?
+
+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
+results can look odd if you forget that the inputs haven't been rounded::
+
+ >>> getcontext().prec = 3
+ >>> Decimal('3.104') + D('2.104')
+ Decimal("5.21")
+ >>> Decimal('3.104') + D('0.000') + D('2.104')
+ Decimal("5.20")
+
+The solution is either to increase precision or to force rounding of inputs
+using the unary plus operation::
+
+ >>> getcontext().prec = 3
+ >>> +Decimal('1.23456789') # unary plus triggers rounding
+ Decimal("1.23")
+
+Alternatively, inputs can be rounded upon creation using the
+:meth:`Context.create_decimal` method::
+
+ >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
+ Decimal("1.2345")
+