diff -r da65e1dcdda9 Doc/library/decimal.rst --- a/Doc/library/decimal.rst Thu May 26 17:06:47 2011 +0200 +++ b/Doc/library/decimal.rst Fri Jun 03 10:54:04 2011 -0400 @@ -404,8 +404,8 @@ .. method:: compare(other[, context]) Compare the values of two Decimal instances. :meth:`compare` returns a - Decimal instance, and if either operand is a NaN then the result is a - NaN:: + Decimal instance, and if either *self* or *other* is a NaN then the result + is a NaN:: a or b is a NaN ==> Decimal('NaN') a < b ==> Decimal('-1') @@ -415,14 +415,14 @@ .. 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. + NaNs signal. That is, if neither *self* nor *other* is a signaling NaN + then any quiet NaN operand is treated as though it were a signaling NaN. .. 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 + Compare *self* to *other* 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: @@ -430,16 +430,17 @@ 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. + result of this function is ``Decimal('0')`` if both *self* and *other* + have the same representation, ``Decimal('-1')`` if *self* is lower in the + total order than *other*, and ``Decimal('1')`` if *self* is higher in the + total order than *other*. See the specification for details of the total + order. .. 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. + Compare *self* to *other* 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())``. @@ -461,8 +462,8 @@ .. 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: + Return a copy of *self* with the sign set to be the same as the + sign of *other*. For example: >>> Decimal('2.3').copy_sign(Decimal('-1.5')) Decimal('-2.3') @@ -568,44 +569,44 @@ .. method:: ln([context]) - Return the natural (base e) logarithm of the operand. The result is + Return the natural (base e) logarithm of *self*. The result is correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode. .. method:: log10([context]) - Return the base ten logarithm of the operand. The result is correctly + Return the base ten logarithm of *self*. The result is correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode. .. method:: logb([context]) - For a nonzero number, return the adjusted exponent of its operand as a - :class:`Decimal` instance. If the operand is a zero then + For a nonzero number, return the adjusted exponent of *self* as a + :class:`Decimal` instance. If *self* 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 + is raised. If *self* is an infinity then ``Decimal('Infinity')`` is returned. .. method:: logical_and(other[, context]) :meth:`logical_and` is a logical operation which takes two *logical operands* (see :ref:`logical_operands_label`). The result is the - digit-wise ``and`` of the two operands. + digit-wise ``and`` of *self* and *other*. .. method:: logical_invert([context]) :meth:`logical_invert` is a logical operation. The - result is the digit-wise inversion of the operand. + result is the digit-wise inversion of *self*. .. method:: logical_or(other[, context]) :meth:`logical_or` is a logical operation which takes two *logical operands* (see :ref:`logical_operands_label`). The result is the - digit-wise ``or`` of the two operands. + digit-wise ``or`` of *self* and *other*. .. method:: logical_xor(other[, context]) :meth:`logical_xor` is a logical operation which takes two *logical operands* (see :ref:`logical_operands_label`). The result is the - digit-wise exclusive or of the two operands. + digit-wise exclusive or of *self* and *other*. .. method:: max(other[, context]) @@ -617,7 +618,7 @@ .. method:: max_mag(other[, context]) Similar to the :meth:`.max` method, but the comparison is done using the - absolute values of the operands. + absolute values of *self* and *other*. .. method:: min(other[, context]) @@ -629,26 +630,26 @@ .. method:: min_mag(other[, context]) Similar to the :meth:`.min` method, but the comparison is done using the - absolute values of the operands. + absolute values of *self* and *other*. .. method:: next_minus([context]) Return the largest number representable in the given context (or in the - current thread's context if no context is given) that is smaller than the - given operand. + current thread's context if no context is given) that is smaller than + *self*. .. method:: next_plus([context]) Return the smallest number representable in the given context (or in the - current thread's context if no context is given) that is larger than the - given operand. + current thread's context if no context is given) that is larger than + *self*. .. method:: next_toward(other[, context]) - If the two operands are unequal, return the number closest to the first - operand in the direction of the second operand. If both operands are - numerically equal, return a copy of the first operand with the sign set to - be the same as the sign of the second operand. + If *self* and *other* are unequal, return the number closest to *self* in + the direction of *other*. If both *self* and *other* are numerically + equal, return a copy of *self* with the sign set to be the same as the + sign of *other*. .. method:: normalize([context]) @@ -661,24 +662,24 @@ .. method:: number_class([context]) - Return a string describing the *class* of the operand. The returned value + Return a string describing the *class* of *self*. The returned value is one of the following ten strings. - * ``"-Infinity"``, indicating that the operand is negative infinity. - * ``"-Normal"``, indicating that the operand is a negative normal number. - * ``"-Subnormal"``, indicating that the operand is negative and subnormal. - * ``"-Zero"``, indicating that the operand is a negative zero. - * ``"+Zero"``, indicating that the operand is a positive zero. - * ``"+Subnormal"``, indicating that the operand is positive and subnormal. - * ``"+Normal"``, indicating that the operand is a positive normal number. - * ``"+Infinity"``, indicating that the operand is positive infinity. - * ``"NaN"``, indicating that the operand is a quiet NaN (Not a Number). - * ``"sNaN"``, indicating that the operand is a signaling NaN. + * ``"-Infinity"``, indicating that *self* is negative infinity. + * ``"-Normal"``, indicating that *self* is a negative normal number. + * ``"-Subnormal"``, indicating that *self* is negative and subnormal. + * ``"-Zero"``, indicating that *self* is a negative zero. + * ``"+Zero"``, indicating that *self* is a positive zero. + * ``"+Subnormal"``, indicating that *self* is positive and subnormal. + * ``"+Normal"``, indicating that *self* is a positive normal number. + * ``"+Infinity"``, indicating that *self* is positive infinity. + * ``"NaN"``, indicating that *self* is a quiet NaN (Not a Number). + * ``"sNaN"``, indicating that *self* is a signaling NaN. .. method:: quantize(exp[, rounding[, context[, watchexp]]]) - Return a value equal to the first operand after rounding and having the - exponent of the second operand. + Return a value equal to *self* after rounding and having the + exponent of *exp*. >>> Decimal('1.41421356').quantize(Decimal('1.000')) Decimal('1.414') @@ -687,12 +688,12 @@ 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. + *exp*. 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 + If the exponent of *exp* is larger than that of *self* 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 @@ -719,14 +720,13 @@ .. method:: 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. + Return the result of rotating the digits of *self* by an amount + specified by *other*. *other* must be an integer in + the range -precision through precision. The absolute value of *other* + gives the number of places to rotate. If *other* is positive then + rotation is to the left; otherwise rotation is to the right. The + coefficient of *self* is padded on the left with zeros to length precision + if necessary. The sign and exponent of *self* are unchanged. .. method:: same_quantum(other[, context]) @@ -735,19 +735,18 @@ .. method:: 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. + Return *self* with exponent adjusted by *other*. + Equivalently, return *self* multiplied by ``10**other``. + *other* must be an integer. .. method:: shift(other[, context]) - Return the result of shifting the digits of the first operand by an amount - specified by the second operand. The second operand must be an integer in - the range -precision through precision. The absolute value of the second - operand gives the number of places to shift. If the second operand is - positive then the shift is to the left; otherwise the shift is to the - right. Digits shifted into the coefficient are zeros. The sign and - exponent of the first operand are unchanged. + Return the result of shifting the digits of *self* by an amount specified + by *other*. *other* must be an integer in the range -precision through + precision. The absolute value of *other* gives the number of places to + shift. If *other* 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 *self* are unchanged. .. method:: sqrt([context]) @@ -1305,7 +1304,7 @@ .. method:: scaleb (x, y) - Returns the first operand after adding the second value its exp. + Returns *self* after adding the second value its exp. .. method:: shift(x, y)