Lines Matching full:decimal
2 :mod:`decimal` --- Decimal fixed point and floating point arithmetic
5 .. module:: decimal
6 :synopsis: Implementation of the General Decimal Arithmetic Specification.
23 import decimal
25 from decimal import *
29 The :mod:`decimal` module provides support for decimal floating point
32 * Decimal "is based on a floating-point model which was designed with people
35 people learn at school." -- excerpt from the decimal arithmetic specification.
37 * Decimal numbers can be represented exactly. In contrast, numbers like
42 * The exactness carries over into arithmetic. In decimal floating point, ``0.1
46 reason, decimal is preferred in accounting applications which have strict
49 * The decimal module incorporates a notion of significant places so that ``1.30
56 * Unlike hardware based binary floating point, the decimal module has a user
60 >>> from decimal import *
62 >>> Decimal(1) / Decimal(7)
63 Decimal('0.142857')
65 >>> Decimal(1) / Decimal(7)
66 Decimal('0.1428571428571428571428571429')
68 * Both binary and decimal floating point are implemented in terms of published
70 capabilities, the decimal module exposes all required parts of the standard.
75 * The decimal module was designed to support "without prejudice, both exact
76 unrounded decimal arithmetic (sometimes called fixed-point arithmetic)
77 and rounded floating-point arithmetic." -- excerpt from the decimal
80 The module design is centered around three concepts: the decimal number, the
83 A decimal number is immutable. It has a sign, coefficient digits, and an
99 decimal module are: :const:`Clamped`, :const:`InvalidOperation`,
111 * IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic
112 Specification <http://speleotrove.com/decimal/>`_.
126 >>> from decimal import *
134 Decimal instances can be constructed from integers, strings, floats, or tuples.
136 value of that integer or float. Decimal numbers include special values such as
141 >>> Decimal(10)
142 Decimal('10')
143 >>> Decimal('3.14')
144 Decimal('3.14')
145 >>> Decimal(3.14)
146 Decimal('3.140000000000000124344978758017532527446746826171875')
147 >>> Decimal((0, (3, 1, 4), -2))
148 Decimal('3.14')
149 >>> Decimal(str(2.0 ** 0.5))
150 Decimal('1.41421356237')
151 >>> Decimal(2) ** Decimal('0.5')
152 Decimal('1.414213562373095048801688724')
153 >>> Decimal('NaN')
154 Decimal('NaN')
155 >>> Decimal('-Infinity')
156 Decimal('-Infinity')
158 The significance of a new Decimal is determined solely by the number of digits
165 >>> Decimal('3.0')
166 Decimal('3.0')
167 >>> Decimal('3.1415926535')
168 Decimal('3.1415926535')
169 >>> Decimal('3.1415926535') + Decimal('2.7182818285')
170 Decimal('5.85987')
172 >>> Decimal('3.1415926535') + Decimal('2.7182818285')
173 Decimal('5.85988')
175 Decimals interact well with much of the rest of Python. Here is a small decimal
181 >>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())
183 Decimal('9.25')
185 Decimal('0.03')
187 [Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),
188 Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]
190 Decimal('19.29')
201 Decimal('6.70')
203 Decimal('2.5058')
205 Decimal('0.77')
207 And some mathematical functions are also available to Decimal:
210 >>> Decimal(2).sqrt()
211 Decimal('1.414213562373095048801688724')
212 >>> Decimal(1).exp()
213 Decimal('2.718281828459045235360287471')
214 >>> Decimal('10').ln()
215 Decimal('2.302585092994045684017991455')
216 >>> Decimal('10').log10()
217 Decimal('1')
223 >>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
224 Decimal('7.32')
225 >>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
226 Decimal('8')
236 In accordance with the standard, the :mod:`decimal` module provides two ready to
246 >>> Decimal(1) / Decimal(7)
247 Decimal('0.142857142857142857142857142857142857142857142857142857142857')
253 >>> Decimal(1) / Decimal(7)
254 Decimal('0.142857143')
255 >>> Decimal(42) / Decimal(0)
256 Decimal('Infinity')
259 >>> Decimal(42) / Decimal(0)
262 Decimal(42) / Decimal(0)
272 >>> Decimal(355) / Decimal(113)
273 Decimal('3.14159292')
288 >>> Decimal(1) / Decimal(0)
289 Decimal('Infinity')
291 >>> Decimal(1) / Decimal(0)
294 Decimal(1) / Decimal(0)
298 program. And, in many applications, data is converted to :class:`Decimal` with
306 .. _decimal-decimal:
308 Decimal objects
312 .. class:: Decimal([value [, context]])
314 Construct a new :class:`Decimal` object based from *value*.
316 *value* can be an integer, string, tuple, :class:`float`, or another :class:`Decimal`
317 object. If no *value* is given, returns ``Decimal('0')``. If *value* is a
318 string, it should conform to the decimal numeric string syntax after leading
325 decimal-part ::= digits '.' [digits] | ['.'] digits
329 numeric-value ::= decimal-part [exponent-part] | infinity
332 If *value* is a unicode string then other Unicode decimal digits
334 decimal digits from various other alphabets (for example,
340 digits, and an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))``
341 returns ``Decimal('1.414')``.
344 converted to its exact decimal equivalent. This conversion can often require
345 53 or more digits of precision. For example, ``Decimal(float('1.1'))``
347 ``Decimal('1.100000000000000088817841970012523233890533447265625')``.
351 ``Decimal('3.00000')`` records all five zeros even if the context precision is
356 is raised; otherwise, the constructor returns a new Decimal with the value of
359 Once constructed, :class:`Decimal` objects are immutable.
363 creating a Decimal instance from a string.
368 Decimal floating point objects share many properties with the other built-in
370 operations and special methods apply. Likewise, decimal objects can be
375 There are some small differences between arithmetic on Decimal objects and
377 applied to Decimal objects, the sign of the result is the sign of the
382 >>> Decimal(-7) % Decimal(4)
383 Decimal('-3')
391 >>> Decimal(-7) // Decimal(4)
392 Decimal('-1')
398 Decimal objects cannot generally be combined with floats in
399 arithmetic operations: an attempt to add a :class:`Decimal` to a
403 with a :class:`Decimal` instance ``y``. Without this exception,
404 comparisons between :class:`Decimal` and :class:`float` instances
411 :class:`Decimal` instance ``y`` now returns a result based on
413 returned the same (arbitrary) result for any :class:`Decimal`
416 In addition to the standard numeric properties, decimal floating point
424 ``Decimal('321e+5').adjusted()`` returns seven. Used for determining the
425 position of the most significant digit with respect to the decimal point.
440 a :class:`Decimal` instance is always canonical, so this operation returns
447 Compare the values of two Decimal instances. This operation behaves in
449 :meth:`compare` returns a Decimal instance rather than an integer, and if
452 a or b is a NaN ==> Decimal('NaN')
453 a < b ==> Decimal('-1')
454 a == b ==> Decimal('0')
455 a > b ==> Decimal('1')
469 gives a total ordering on :class:`Decimal` instances. Two
470 :class:`Decimal` instances with the same numeric value but different
473 >>> Decimal('12.0').compare_total(Decimal('12'))
474 Decimal('-1')
477 result of this function is ``Decimal('0')`` if both operands have the same
478 representation, ``Decimal('-1')`` if the first operand is lower in the
479 total order than the second, and ``Decimal('1')`` if the first operand is
496 Just returns self, this method is only to comply with the Decimal
521 >>> Decimal('2.3').copy_sign(Decimal('-1.5'))
522 Decimal('-2.3')
535 >>> Decimal(1).exp()
536 Decimal('2.718281828459045235360287471')
537 >>> Decimal(321).exp()
538 Decimal('2.561702493119680037517373933E+139')
544 Classmethod that converts a float to a decimal number, exactly.
546 Note `Decimal.from_float(0.1)` is not the same as `Decimal('0.1')`.
549 `0x1.999999999999ap-4`. That equivalent value in decimal is
552 .. note:: From Python 2.7 onwards, a :class:`Decimal` instance
557 >>> Decimal.from_float(0.1)
558 Decimal('0.1000000000000000055511151231257827021181583404541015625')
559 >>> Decimal.from_float(float('nan'))
560 Decimal('NaN')
561 >>> Decimal.from_float(float('inf'))
562 Decimal('Infinity')
563 >>> Decimal.from_float(float('-inf'))
564 Decimal('-Infinity')
573 >>> Decimal(2).fma(3, 5)
574 Decimal('11')
581 otherwise. Currently, a :class:`Decimal` instance is always canonical, so
670 :class:`Decimal` instance. If the operand is a zero then
671 ``Decimal('-Infinity')`` is returned and the :const:`DivisionByZero` flag
672 is raised. If the operand is an infinity then ``Decimal('Infinity')`` is
764 converting any result equal to :const:`Decimal('0')` to
765 :const:`Decimal('0e0')`. Used for producing canonical values for attributes
766 of an equivalence class. For example, ``Decimal('32.100')`` and
767 ``Decimal('0.321000e+2')`` both normalize to the equivalent value
768 ``Decimal('32.1')``.
793 >>> Decimal('1.41421356').quantize(Decimal('1.000'))
794 Decimal('1.414')
817 Return ``Decimal(10)``, the radix (base) in which the :class:`Decimal`
834 >>> Decimal(18).remainder_near(Decimal(10))
835 Decimal('-2')
836 >>> Decimal(25).remainder_near(Decimal(10))
837 Decimal('5')
838 >>> Decimal(35).remainder_near(Decimal(10))
839 Decimal('-5')
889 can leave up to 3 digits to the left of the decimal place and may
892 For example, this converts ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``.
926 operands*. A *logical operand* is a :class:`Decimal` instance whose
968 For example, the following code sets the current decimal precision to 42 places,
971 from decimal import localcontext
979 print Decimal(1) / Decimal(7)
980 print Decimal(355) / Decimal(113)
988 This is a standard context defined by the General Decimal Arithmetic
999 This is a standard context defined by the General Decimal Arithmetic
1060 lowercase :const:`e` is used: :const:`Decimal('6.02e+23')`.
1067 In addition, for each of the :class:`Decimal` methods described above (with
1070 instance ``C`` and :class:`Decimal` instance ``x``, ``C.exp(x)`` is
1073 Decimal instance is accepted.
1086 Return a copy of the Decimal instance num.
1090 Creates a new Decimal instance from *num* but using *self* as
1091 context. Unlike the :class:`Decimal` constructor, the context precision,
1103 >>> Decimal('3.4445') + Decimal('1.0023')
1104 Decimal('4.45')
1105 >>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
1106 Decimal('4.44')
1114 Creates a new Decimal instance from a float *f* but rounding using *self*
1115 as the context. Unlike the :meth:`Decimal.from_float` class method,
1123 Decimal('3.1415')
1143 The usual approach to working with decimals is to create :class:`Decimal`
1147 similar to those for the :class:`Decimal` class and are only briefly
1163 Returns the same Decimal object *x*.
1410 Just returns 10, as this is Decimal, :)
1461 can leave up to 3 digits to the left of the decimal place and may
1608 The use of decimal floating point eliminates decimal representation error
1621 >>> from decimal import Decimal, getcontext
1624 >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
1626 Decimal('9.5111111')
1628 Decimal('10')
1630 >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
1632 Decimal('0.01')
1634 Decimal('0.0060000')
1636 The :mod:`decimal` module makes it possible to restore the identities by
1642 >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
1644 Decimal('9.51111111')
1646 Decimal('9.51111111')
1648 >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
1650 Decimal('0.0060000')
1652 Decimal('0.0060000')
1658 The number system for the :mod:`decimal` module provides special values
1662 Infinities can be constructed directly with: ``Decimal('Infinity')``. Also,
1686 ``Decimal('NaN')==Decimal('NaN')``), while a test for inequality always returns
1690 not trapped. Note that the General Decimal Arithmetic specification does not
1707 >>> 1 / Decimal('Infinity')
1708 Decimal('0E-1000000026')
1757 to work with the :class:`Decimal` class::
1761 """Convert Decimal to a money formatted string.
1763 places: required number of places after the decimal point
1766 dp: decimal point indicator (comma or period)
1772 >>> d = Decimal('-1234567.8901')
1779 >>> moneyfmt(Decimal(123456789), sep=' ')
1781 >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
1785 q = Decimal(10) ** -places # 2 places --> '0.01'
1816 three = Decimal(3) # substitute "three=3.0" for regular floats
1830 >>> print exp(Decimal(1))
1832 >>> print exp(Decimal(2))
1854 >>> print cos(Decimal('0.5'))
1877 >>> print sin(Decimal('0.5'))
1903 Decimal FAQ
1906 Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to
1911 >>> D = decimal.Decimal
1913 Decimal('4.68')
1915 Q. In a fixed-point application with two decimal places, some inputs have many
1919 A. The :meth:`quantize` method rounds to a fixed number of decimal places. If
1922 >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01')
1925 >>> Decimal('3.214').quantize(TWOPLACES)
1926 Decimal('3.21')
1929 >>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact]))
1930 Decimal('3.21')
1932 >>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact]))
1942 non-integer multiplication, will change the number of decimal places and need to
1945 >>> a = Decimal('102.72') # Initial fixed-point values
1946 >>> b = Decimal('3.17')
1948 Decimal('105.89')
1950 Decimal('99.55')
1952 Decimal('4314.24')
1954 Decimal('325.62')
1956 Decimal('0.03')
1967 Decimal('325.62')
1969 Decimal('0.03')
1979 >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
1981 [Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]
1983 Q. Some decimal values always print with exponential notation. Is there a way
1998 >>> remove_exponent(Decimal('5E+3'))
1999 Decimal('5000')
2002 return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()
2004 Q. Is there a way to convert a regular float to a :class:`Decimal`?
2007 Decimal though an exact conversion may take more precision than intuition would
2012 >>> Decimal(math.pi)
2013 Decimal('3.141592653589793115997963468544185161590576171875')
2018 A. The decimal module makes it easy to test results. A best practice is to
2035 >>> Decimal('3.104') + Decimal('2.104')
2036 Decimal('5.21')
2037 >>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')
2038 Decimal('5.20')
2046 >>> +Decimal('1.23456789') # unary plus triggers rounding
2047 Decimal('1.23')
2053 Decimal('1.2345')