Lines Matching +full:sign +full:- +full:compare
1 :mod:`decimal` --- Decimal fixed point and floating point arithmetic
31 --------------
33 The :mod:`decimal` module provides support for fast correctly-rounded
37 * Decimal "is based on a floating-point model which was designed with people
38 in mind, and necessarily has a paramount guiding principle -- computers must
40 people learn at school." -- excerpt from the decimal arithmetic specification.
48 + 0.1 + 0.1 - 0.3`` is exactly equal to zero. In binary floating point, the result
49 is :const:`5.5511151231257827e-017`. While near to zero, the differences
74 standards. While the built-in float type exposes only a modest portion of its
81 unrounded decimal arithmetic (sometimes called fixed-point arithmetic)
82 and rounded floating-point arithmetic." -- excerpt from the decimal
88 A decimal number is immutable. It has a sign, coefficient digits, and an
91 :const:`Infinity`, :const:`-Infinity`, and :const:`NaN`. The standard also
92 differentiates :const:`-0` from :const:`+0`.
122 .. _decimal-tutorial:
124 Quick-start Tutorial
125 --------------------
133 Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
143 :const:`Infinity`, and :const:`-0`::
152 >>> Decimal((0, (3, 1, 4), -2))
160 >>> Decimal('-Infinity')
161 Decimal('-Infinity')
284 Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
295 File "<pyshell#143>", line 1, in -toplevel-
309 Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
314 result is inexact (some of the discarded digits were non-zero).
327 File "<pyshell#112>", line 1, in -toplevel-
340 .. _decimal-decimal:
343 ---------------
355 sign ::= '+' | '-'
359 decimal-part ::= digits '.' [digits] | ['.'] digits
360 exponent-part ::= indicator [sign] digits
363 numeric-value ::= decimal-part [exponent-part] | infinity
364 numeric-string ::= [sign] numeric-value | [sign] nan
368 alphabets (for example, Arabic-Indic and Devanāgarī digits) along
371 If *value* is a :class:`tuple`, it should have three components, a sign
373 digits, and an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))``
403 Underscores are allowed for grouping, as with integral and floating-point
406 Decimal floating point objects share many properties with the other built-in
415 applied to Decimal objects, the sign of the result is the sign of the
416 *dividend* rather than the sign of the divisor::
418 >>> (-7) % 4
420 >>> Decimal(-7) % Decimal(4)
421 Decimal('-3')
427 >>> -7 // 4
428 -2
429 >>> Decimal(-7) // Decimal(4)
430 Decimal('-1')
433 ``divide-integer`` operations (respectively) as described in the
440 use Python's comparison operators to compare a :class:`Decimal`
445 Mixed-type comparisons between :class:`Decimal` instances and other
465 >>> Decimal('-3.14').as_integer_ratio()
466 (-157, 50)
476 ``DecimalTuple(sign, digits, exponent)``.
485 .. method:: compare(other, context=None)
487 Compare the values of two Decimal instances. :meth:`compare` returns a
492 a < b ==> Decimal('-1')
498 This operation is identical to the :meth:`compare` method, except that all
504 Compare two operands using their abstract representation rather than their
505 numerical value. Similar to the :meth:`compare` method, but the result
508 representations compare unequal in this ordering:
511 Decimal('-1')
515 representation, ``Decimal('-1')`` if the first operand is lower in the
526 Compare two operands using their abstract representation rather than their
527 value as in :meth:`compare_total`, but ignoring the sign of each operand.
553 Return a copy of the first operand with the sign set to be the same as the
554 sign of the second operand. For example:
556 >>> Decimal('2.3').copy_sign(Decimal('-1.5'))
557 Decimal('-2.3')
581 `0x1.999999999999ap-4`. That equivalent value in decimal is
595 >>> Decimal.from_float(float('-inf'))
596 Decimal('-Infinity')
602 Fused multiply-add. Return self*other+third with no rounding of the
641 Return :const:`True` if the argument has a negative sign and
673 ``Decimal('-Infinity')`` is returned and the :const:`DivisionByZero` flag
681 digit-wise ``and`` of the two operands.
686 result is the digit-wise inversion of the operand.
692 digit-wise ``or`` of the two operands.
698 digit-wise exclusive or of the two operands.
740 numerically equal, return a copy of the first operand with the sign set to
741 be the same as the sign of the second operand.
757 * ``"-Infinity"``, indicating that the operand is negative infinity.
758 * ``"-Normal"``, indicating that the operand is a negative normal number.
759 * ``"-Subnormal"``, indicating that the operand is negative and subnormal.
760 * ``"-Zero"``, indicating that the operand is a negative zero.
780 the right-hand operand.
803 ``self % other`` in that the sign of the remainder is chosen so as to
805 ``self - n * other`` where ``n`` is the integer nearest to the exact
809 If the result is zero then its sign will be the sign of *self*.
812 Decimal('-2')
816 Decimal('-5')
822 the range -precision through precision. The absolute value of the second
826 length precision if necessary. The sign and exponent of the first operand
848 the range -precision through precision. The absolute value of the second
851 right. Digits shifted into the coefficient are zeros. The sign and
897 exponent and sign are both zero, and whose digits are all either
903 .. _decimal-context:
906 ---------------
931 to a copy of *ctx* on entry to the with-statement and restore the previous context
932 when exiting the with-statement. If no context is specified, a copy of the
946 described below. In addition, the module provides three pre-made contexts:
979 This context is most useful in multi-threaded environments. Changing one of the
980 fields before threads are started has the effect of setting system-wide
1022 range ``Emin - prec + 1 <= e <= Emax - prec + 1``. If *clamp* is
1035 fixed-width decimal interchange formats specified in IEEE 754.
1086 This method implements the to-number operation of the IBM specification.
1112 Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent
1118 Returns a value equal to ``Emax - prec + 1``.
1143 .. method:: compare(x, y)
1160 Compares two operands using their abstract representation, ignoring sign.
1165 Returns a copy of *x* with the sign set to 0.
1170 Returns a copy of *x* with the sign inverted.
1175 Copies the sign from *y* to *x*.
1295 Compares the values numerically with their sign ignored.
1305 Compares the values numerically with their sign ignored.
1357 The rounding mode of the context is used. Results are always correctly-rounded
1364 The C module computes :meth:`power` in terms of the correctly-rounded
1365 :meth:`exp` and :meth:`ln` functions. The result is well-defined but
1366 only "almost always correctly-rounded".
1371 - all three arguments must be integral
1372 - ``y`` must be nonnegative
1373 - at least one of ``x`` or ``y`` must be nonzero
1374 - ``modulo`` must be nonzero and have at most 'precision' digits
1398 The sign of the result, if non-zero, is the same as that of the original
1404 Returns ``x - y * n``, where *n* is the integer nearest the exact value
1405 of ``x / y`` (if the result is 0 then its sign will be the sign of *x*).
1430 Square root of a non-negative number to context precision.
1458 .. _decimal-rounding-modes:
1461 ---------
1466 +---------------------+---------------------+-------------------------------+
1467 | | 32-bit | 64-bit |
1470 +---------------------+---------------------+-------------------------------+
1472 +---------------------+---------------------+-------------------------------+
1473 | .. data:: MIN_EMIN | :const:`-425000000` | :const:`-999999999999999999` |
1474 +---------------------+---------------------+-------------------------------+
1475 | .. data:: MIN_ETINY | :const:`-849999999` | :const:`-1999999999999999997` |
1476 +---------------------+---------------------+-------------------------------+
1488 the --without-decimal-contextvar option <--without-decimal-contextvar>`,
1489 the C version uses a thread-local rather than a coroutine-local context and the value
1496 --------------
1508 Round towards :const:`-Infinity`.
1532 .. _decimal-signals:
1535 -------
1567 Signals the division of a non-infinite number by zero.
1571 :const:`-Infinity` with the sign determined by the inputs to the calculation.
1578 Signals when non-zero digits were discarded during rounding. The rounded result
1590 Infinity - Infinity
1595 sqrt(-x) and x > 0
1597 x ** (non-integer)
1672 .. _decimal-notes:
1675 --------------------
1678 Mitigating round-off error with increased precision
1683 can still incur round-off error when non-zero digits exceed the fixed precision.
1685 The effects of round-off error can be amplified by the addition or subtraction
1697 >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
1703 >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
1715 >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
1721 >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
1732 including :const:`NaN`, :const:`sNaN`, :const:`-Infinity`, :const:`Infinity`,
1733 and two zeros, :const:`+0` and :const:`-0`.
1749 series of computations that occasionally have missing inputs --- it allows the
1760 :const:`True`. An attempt to compare two Decimals using any of the ``<``,
1766 section 5.7). To ensure strict standards-compliance, use the :meth:`compare`
1767 and :meth:`compare-signal` methods instead.
1769 The signed zeros can result from calculations that underflow. They keep the sign
1772 treated as equal and their sign is informational.
1781 Decimal('0E-1000026')
1786 .. _decimal-threads:
1789 --------------------
1824 .. _decimal-recipes:
1827 -------
1833 pos='', neg='-', trailneg=''):
1837 curr: optional currency symbol before the sign (may be blank)
1841 pos: optional sign for positive numbers: '+', space or blank
1842 neg: optional sign for negative numbers: '-', '(', space or blank
1843 trailneg:optional trailing minus indicator: '-', ')', space or blank
1845 >>> d = Decimal('-1234567.8901')
1847 '-$1,234,567.89'
1848 >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
1849 '1.234.568-'
1854 >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
1858 q = Decimal(10) ** -places # 2 places --> '0.01'
1859 sign, digits, exp = value.quantize(q).as_tuple()
1863 if sign:
1879 build(neg if sign else pos)
1898 getcontext().prec -= 2
1922 getcontext().prec -= 2
1940 i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
1944 fact *= i * (i-1)
1946 sign *= -1
1947 s += num / fact * sign
1948 getcontext().prec -= 2
1966 i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
1970 fact *= i * (i-1)
1972 sign *= -1
1973 s += num / fact * sign
1974 getcontext().prec -= 2
1981 .. _decimal-faq:
1984 -----------
1995 Q. In a fixed-point application with two decimal places, some inputs have many
2002 >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01')
2022 non-integer multiplication, will change the number of decimal places and need to
2023 be followed-up with a :meth:`quantize` step:
2025 >>> a = Decimal('102.72') # Initial fixed-point values
2027 >>> a + b # Addition preserves fixed-point
2029 >>> a - b
2033 >>> (a * b).quantize(TWOPLACES) # Must quantize non-integer multiplication
2038 In developing fixed-point applications, it is convenient to define functions
2046 >>> mul(a, b) # Automatically preserve fixed-point
2064 to get a non-exponential representation?
2069 original's two-place significance.
2096 re-run calculations using greater precision and with various rounding modes.
2098 ill-conditioned inputs, or a numerically unstable algorithm.
2137 arbitrary precision correctly-rounded decimal floating point arithmetic [#]_.
2140 for medium-sized numbers and the `Number Theoretic Transform
2141 <https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general)#Number-theoretic_transform>`_
2157 For inexact results, :attr:`MAX_PREC` is far too large on 64-bit platforms and
2171 >>> # Maximum number of digits for a single operand using 500MB in 8-byte words
2172 >>> # with 19 digits per word (4-byte and 9 digits for the 32-bit build):
2199 This approach now works for all exact results except for non-integer powers.