diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/decimal.rst | 253 |
1 files changed, 243 insertions, 10 deletions
diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 7052c7b..aea1c01 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -135,6 +135,7 @@ 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') @@ -173,7 +174,7 @@ 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()) + >>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())) >>> max(data) Decimal('9.25') >>> min(data) @@ -201,6 +202,7 @@ floating point flying circus: And some mathematical functions are also available to Decimal: + >>> getcontext().prec = 28 >>> Decimal(2).sqrt() Decimal('1.414213562373095048801688724') >>> Decimal(1).exp() @@ -267,7 +269,7 @@ using the :meth:`clear_flags` method. :: Decimal('3.14159292') >>> getcontext() Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, - capitals=1, flags=[Rounded, Inexact], traps=[]) + 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 @@ -414,6 +416,11 @@ Decimal objects ``x.compare_total_mag(y)`` is equivalent to ``x.copy_abs().compare_total(y.copy_abs())``. + .. method:: conjugate() + + Just returns itself, this method is only to comply with the Decimal + Specification. + .. method:: copy_abs() Return the absolute value of the argument. This operation is unaffected @@ -722,13 +729,6 @@ Decimal objects :const:`Rounded`. If given, applies *rounding*; otherwise, uses the rounding method in either the supplied *context* or the current context. - .. method:: trim() - - Return the decimal 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. - .. _logical_operands_label: @@ -940,6 +940,46 @@ In addition to the three supplied contexts, new contexts can be created with the Return the sum of *x* and *y*. + .. method:: canonical(x) + + Returns the same Decimal object *x*. + + + .. method:: compare(x, y) + + Compares *x* and *y* numerically. + + + .. method:: compare_signal(x, y) + + Compares the values of the two operands numerically. + + + .. method:: compare_total(x, y) + + Compares two operands using their abstract representation. + + + .. method:: compare_total_mag(x, y) + + Compares two operands using their abstract representation, ignoring sign. + + + .. method:: copy_abs(x) + + Returns a copy of *x* with the sign set to 0. + + + .. method:: copy_negate(x) + + Returns a copy of *x* with the sign inverted. + + + .. method:: copy_sign(x, y) + + Copies the sign from *y* to *x*. + + .. method:: divide(x, y) Return *x* divided by *y*. @@ -955,6 +995,121 @@ In addition to the three supplied contexts, new contexts can be created with the Divides two numbers and returns the integer part of the result. + .. method:: exp(x) + + Returns `e ** x`. + + + .. method:: fma(x, y, z) + + Returns *x* multiplied by *y*, plus *z*. + + + .. method:: is_canonical(x) + + Returns True if *x* is canonical; otherwise returns False. + + + .. method:: is_finite(x) + + Returns True if *x* is finite; otherwise returns False. + + + .. method:: is_infinite(x) + + Returns True if *x* is infinite; otherwise returns False. + + + .. method:: is_nan(x) + + Returns True if *x* is a qNaN or sNaN; otherwise returns False. + + + .. method:: is_normal(x) + + Returns True if *x* is a normal number; otherwise returns False. + + + .. method:: is_qnan(x) + + Returns True if *x* is a quiet NaN; otherwise returns False. + + + .. method:: is_signed(x) + + Returns True if *x* is negative; otherwise returns False. + + + .. method:: is_snan(x) + + Returns True if *x* is a signaling NaN; otherwise returns False. + + + .. method:: is_subnormal(x) + + Returns True if *x* is subnormal; otherwise returns False. + + + .. method:: is_zero(x) + + Returns True if *x* is a zero; otherwise returns False. + + + .. method:: ln(x) + + Returns the natural (base e) logarithm of *x*. + + + .. method:: log10(x) + + Returns the base 10 logarithm of *x*. + + + .. method:: logb(x) + + Returns the exponent of the magnitude of the operand's MSD. + + + .. method:: logical_and(x, y) + + Applies the logical operation `and` between each operand's digits. + + + .. method:: logical_invert(x) + + Invert all the digits in *x*. + + + .. method:: logical_or(x, y) + + Applies the logical operation `or` between each operand's digits. + + + .. method:: logical_xor(x, y) + + Applies the logical operation `xor` between each operand's digits. + + + .. method:: max(x, y) + + Compares two values numerically and returns the maximum. + + + .. method:: max_mag(x, y) + + Compares the values numerically with their sign ignored. + + + .. method:: min(x, y) + + Compares two values numerically and returns the minimum. + + + .. method:: min_mag(x, y) + + Compares the values numerically with their sign ignored. + + .. method:: minus(x) Minus corresponds to the unary prefix minus operator in Python. @@ -965,6 +1120,31 @@ In addition to the three supplied contexts, new contexts can be created with the Return the product of *x* and *y*. + .. method:: next_minus(x) + + Returns the largest representable number smaller than *x*. + + + .. method:: next_plus(x) + + Returns the smallest representable number larger than *x*. + + + .. method:: next_toward(x, y) + + Returns the number closest to *x*, in direction towards *y*. + + + .. method:: normalize(x) + + Reduces *x* to its simplest form. + + + .. method:: number_class(x) + + Returns an indication of the class of *x*. + + .. method:: plus(x) Plus corresponds to the unary prefix plus operator in Python. This @@ -994,6 +1174,17 @@ In addition to the three supplied contexts, new contexts can be created with the that would be obtained by computing ``(x**y) % modulo`` with unbounded precision, but is computed more efficiently. It is always exact. + + .. method:: quantize(x, y) + + Returns a value equal to *x* (rounded), having the exponent of *y*. + + + .. method:: radix() + + Just returns 10, as this is Decimal, :) + + .. method:: remainder(x, y) Returns the remainder from integer division. @@ -1001,10 +1192,52 @@ In addition to the three supplied contexts, new contexts can be created with the The sign of the result, if non-zero, is the same as that of the original dividend. + .. method:: remainder_near(x, y) + + Returns `x - y * n`, where *n* is the integer nearest the exact value + of `x / y` (if the result is `0` then its sign will be the sign of *x*). + + + .. method:: rotate(x, y) + + Returns a rotated copy of *x*, *y* times. + + + .. method:: same_quantum(x, y) + + Returns True if the two operands have the same exponent. + + + .. method:: scaleb (x, y) + + Returns the first operand after adding the second value its exp. + + + .. method:: shift(x, y) + + Returns a shifted copy of *x*, *y* times. + + + .. method:: sqrt(x) + + Square root of a non-negative number to context precision. + + .. method:: subtract(x, y) Return the difference between *x* and *y*. + + .. method:: to_eng_string(x) + + Converts a number to a string, using scientific notation. + + + .. method:: to_integral_exact(x) + + Rounds to an integer. + + .. method:: to_sci_string(x) Converts a number to a string using scientific notation. @@ -1323,7 +1556,7 @@ to work with the :class:`Decimal` class:: q = Decimal(10) ** -places # 2 places --> '0.01' sign, digits, exp = value.quantize(q).as_tuple() result = [] - digits = map(str, digits) + digits = list(map(str, digits)) build, next = result.append, digits.pop if sign: build(trailneg) |