[Python-checkins] cpython (3.2): Issue #12005: clarify behaviour of % and // for Decimal objects.

[mark.dickinson]

http://hg.python.org/cpython/rev/0ec314f26791
changeset:   80488:0ec314f26791
branch:      3.2
parent:      80482:d51d95c9ea81
user:        Mark Dickinson <mdickinson at enthought.com>
date:        Sun Nov 18 10:22:05 2012 +0000
summary:
  Issue #12005: clarify behaviour of % and // for Decimal objects.

files:
  Doc/library/decimal.rst |  23 +++++++++++++++++++++++
  1 files changed, 23 insertions(+), 0 deletions(-)


diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -365,6 +365,29 @@
    compared, sorted, and coerced to another type (such as :class:`float` or
    :class:`int`).
 
+   There are some small differences between arithmetic on Decimal objects and
+   arithmetic on integers and floats.  When the remainder operator ``%`` is
+   applied to Decimal objects, the sign of the result is the sign of the
+   *dividend* rather than the sign of the divisor::
+
+      >>> (-7) % 4
+      1
+      >>> Decimal(-7) % Decimal(4)
+      Decimal('-3')
+
+   The integer division operator ``//`` behaves analogously, returning the
+   integer part of the true quotient (truncating towards zero) rather than its
+   floor, so as to preseve the usual identity ``x == (x // y) * y + x % y``::
+
+      >>> -7 // 4
+      -2
+      >>> Decimal(-7) // Decimal(4)
+      Decimal('-1')
+
+   The ``%`` and ``//`` operators implement the ``remainder`` and
+   ``divide-integer`` operations (respectively) as described in the
+   specification.
+
    Decimal objects cannot generally be combined with floats or
    instances of :class:`fractions.Fraction` in arithmetic operations:
    an attempt to add a :class:`Decimal` to a :class:`float`, for

-- 
Repository URL: http://hg.python.org/cpython