[Python-checkins] r58154 - python/trunk/Doc/library/decimal.rst
facundo.batista
python-checkins at python.org
Fri Sep 14 20:58:35 CEST 2007
Author: facundo.batista
Date: Fri Sep 14 20:58:34 2007
New Revision: 58154
Modified:
python/trunk/Doc/library/decimal.rst
Log:
Included the new functions, and new descriptions.
Modified: python/trunk/Doc/library/decimal.rst
==============================================================================
--- python/trunk/Doc/library/decimal.rst (original)
+++ python/trunk/Doc/library/decimal.rst Fri Sep 14 20:58:34 2007
@@ -19,7 +19,7 @@
.. versionadded:: 2.4
The :mod:`decimal` module provides support for decimal floating point
-arithmetic. It offers several advantages over the :class:`float()` datatype:
+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
@@ -27,7 +27,7 @@
: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
+ + 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 would be preferred in accounting applications which have strict
@@ -41,7 +41,7 @@
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
+ alterable precision (defaulting to 28 places) which can be as large as needed for
a given problem::
>>> getcontext().prec = 6
@@ -61,7 +61,7 @@
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
+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`.
@@ -70,7 +70,7 @@
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`.
+: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,
@@ -87,11 +87,11 @@
.. seealso::
- IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic
- Specification <http://www2.hursley.ibm.com/decimal/decarith.html>`_.
+ * 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>`_.
+ * IEEE standard 854-1987, `Unofficial IEEE 854 Text
+ <http://www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html>`_.
.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -290,7 +290,7 @@
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
+ ``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
@@ -300,7 +300,7 @@
Once constructed, :class:`Decimal` objects are immutable.
-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
operations and special methods apply. Likewise, decimal objects can be copied,
pickled, printed, used as dictionary keys, used as set elements, compared,
@@ -320,50 +320,351 @@
.. method:: Decimal.as_tuple()
- Returns a tuple representation of the number: ``(sign, digittuple, exponent)``.
+ Return a tuple representation of the number: ``(sign, digit_tuple, exponent)``.
+.. method:: Decimal.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])
- Compares like :meth:`__cmp__` but returns a decimal instance::
+ 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:: Decimal.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:: Decimal.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:: Decimal.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:: Decimal.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:: Decimal.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:: Decimal.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:: Decimal.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.
+
+ .. versionadded:: 2.6
+
+.. method:: Decimal.fma(other, third[, context])
+
+ Fused multiply-add. Return self*other+third with no rounding of
+ the intermediate product self*other.
+
+ .. versionadded:: 2.6
+
+.. method:: Decimal.is_canonical()
+
+ Return ``Decimal(1)`` if the argument is canonical and
+ ``Decimal(0)`` otherwise. Currently, a :class:`Decimal` instance
+ is always canonical, so this operation always returns
+ ``Decimal(1)``.
+
+ .. versionadded:: 2.6
+
+.. method:: is_finite()
+
+ Return ``Decimal(1)`` if the argument is a finite number, and
+ ``Decimal(0)`` if the argument is an infinity or a NaN.
+
+ .. versionadded:: 2.6
+
+.. method:: is_infinite()
+
+ Return ``Decimal(1)`` if the argument is either positive or
+ negative infinity and ``Decimal(0)`` otherwise.
+
+ .. versionadded:: 2.6
+
+.. method:: is_nan()
+
+ Return ``Decimal(1)`` if the argument is a (quiet or signaling)
+ NaN and ``Decimal(0)`` otherwise.
+
+ .. versionadded:: 2.6
+
+.. method:: is_normal()
+
+ Return ``Decimal(1)`` if the argument is a *normal* finite number.
+ Return ``Decimal(0)`` if the argument is zero, subnormal, infinite
+ or a NaN.
+
+ .. versionadded:: 2.6
+
+.. method:: is_qnan()
+
+ Return ``Decimal(1)`` if the argument is a quiet NaN, and ``Decimal(0)`` otherwise.
+
+ .. versionadded:: 2.6
+
+.. method:: is_signed()
+
+ Return ``Decimal(1)`` if the argument has a negative sign and
+ ``Decimal(0)`` otherwise. Note that zeros and NaNs can both carry
+ signs.
+
+ .. versionadded:: 2.6
+
+.. method:: is_snan()
+
+ Return ``Decimal(1)`` if the argument is a signaling NaN and
+ ``Decimal(0)`` otherwise.
+
+ .. versionadded:: 2.6
+
+.. method:: is_subnormal()
+
+ Return ``Decimal(1)`` if the argument is subnormal, and
+ ``Decimal(0)`` otherwise.
+
+ .. versionadded:: 2.6
+
+.. method:: is_zero()
+
+ Return ``Decimal(1)`` if the argument is a (positive or negative)
+ zero and ``Decimal(0)`` otherwise.
+
+ .. versionadded:: 2.6
+
+.. method:: Decimal.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:: Decimal.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: Decimal.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:: Decimal.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:: Decimal.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:: Decimal.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:: Decimal.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])
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 ignored
(depending on the context and whether they are signaling or quiet).
+.. method:: Decimal.max_mag(other[, context])
+
+ 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])
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 ignored
(depending on the context and whether they are signaling or quiet).
+.. method:: Decimal.min_mag(other[, context])
+
+ Similar to the :meth:`min` method, but the comparison is done using
+ the absolute values of the operands.
+
+ .. versionadded:: 2.6
+
+.. method:: Decimal.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:: Decimal.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:: Decimal.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])
- Normalize the number by stripping the rightmost trailing zeroes and converting
+ Normalize the number by stripping the rightmost trailing zeros 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.number_class([context])
-.. 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.
+ Return a string describing the *class* of the operand. The
+ returned value is one of the following ten strings.
- If *watchexp* is set (default), then an error is returned whenever the resulting
- exponent is greater than :attr:`Emax` or less than :attr:`Etiny`.
+ * ``"-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]]])
+
+ Returns a value equal to the first operand after rounding and
+ having the exponent of the second operand.
+
+ 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 exponent is greater than Emax or less than Etiny.
+
+.. method:: Decimal.radix()
+
+ 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])
@@ -373,16 +674,49 @@
If both are equally close, the one chosen will have the same sign as *self*.
+.. method:: Decimal.rotate(other[, context])
+
+ 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])
Test whether self and other have the same exponent or whether both are
:const:`NaN`.
+.. method:: Decimal.scaleb(other[, context])
+
+ 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:: Decimal.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])
- Return the square root to full precision.
+ Return the square root of the argument to full precision.
.. method:: Decimal.to_eng_string([context])
@@ -393,13 +727,53 @@
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]])
+ Identical to the :meth:`to_integral_value` method. The ``to_integral``
+ name has been kept for compatibility with older versions.
+
+.. method:: Decimal.to_integral_exact([rounding[, context]])
+
+ Round the argument 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:: Decimal.to_integral_value([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.
+ .. versionchanged:: 2.6
+ renamed from ``to_integral`` to ``to_integral_value``. The old name
+ remains valid for compatibility.
+
+.. method:: Decimal.trim()
+
+ Returns its argument with *insignificant* trailing zeros removed.
+ Here, a trailing zero is considered insignificant either if it
+ follows the decimal point, or if the exponent of the argument (that
+ is, the last element of the :meth:`as_tuple` representation) is
+ positive.
+
+ .. versionadded:: 2.6
+
+.. _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`.
+
.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -516,6 +890,8 @@
* :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).
+ * :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.
@@ -527,9 +903,16 @@
: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.
+ .. versionchanged:: 2.6
+ The :const:`ROUND_05UP` rounding mode was added.
+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. 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)``.
.. method:: Context.clear_flags()
@@ -540,6 +923,9 @@
Return a duplicate of the context.
+.. method:: Context.copy_decimal(num)
+
+ Return a copy of the Decimal instance num.
.. method:: Context.create_decimal(num)
@@ -588,42 +974,19 @@
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.divide_int(x, y)
+ Return *x* divided by *y*, truncated to an integer.
-.. method:: Context.min(x, y)
- Compare two values numerically and return the minimum.
+.. method:: Context.divmod(x, y)
- If they are numerically equal then the left-hand operand is chosen as the
- result.
+ Divides two numbers and returns the integer part of the result.
.. method:: Context.minus(x)
@@ -636,14 +999,6 @@
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
@@ -653,33 +1008,31 @@
.. 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.
-
+ Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if
+ given.
-.. 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.
+ With two arguments, compute ``x**y``. If ``x`` is negative then
+ ``y`` must be integral. The result will be inexact unless ``y`` is
+ integral and the result is finite and can be expressed exactly in
+ 'precision' digits. The result should always be correctly rounded,
+ using the rounding mode of the current thread's context.
+
+ With three arguments, compute ``(x**y) % modulo``. For the three
+ argument form, the following restrictions on the arguments hold:
+
+ - all three arguments must be integral
+ - ``y`` must be nonnegative
+ - at least one of ``x`` or ``y`` must be nonzero
+ - ``modulo`` must be nonzero and have at most 'precision' digits
+
+ 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.
+
+ .. versionchanged:: 2.6
+ ``y`` may now be nonintegral in ``x**y``.
+ Stricter requirements for the three-argument version.
.. method:: Context.remainder(x, y)
@@ -689,47 +1042,10 @@
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.
@@ -762,7 +1078,7 @@
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.
+ fit by adding zeros to the coefficient.
.. class:: DecimalException
@@ -915,7 +1231,7 @@
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`.
+and two zeros, :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
More information about the Python-checkins
mailing list