1 :mod:`decimal` --- Decimal fixed point and floating point arithmetic 2 ==================================================================== 3 4 .. module:: decimal 5 :synopsis: Implementation of the General Decimal Arithmetic Specification. 6 7 .. moduleauthor:: Eric Price <eprice at tjhsst.edu> 8 .. moduleauthor:: Facundo Batista <facundo at taniquetil.com.ar> 9 .. moduleauthor:: Raymond Hettinger <python at rcn.com> 10 .. moduleauthor:: Aahz <aahz at pobox.com> 11 .. moduleauthor:: Tim Peters <tim.one at comcast.net> 12 .. moduleauthor:: Stefan Krah <skrah at bytereef.org> 13 .. sectionauthor:: Raymond D. Hettinger <python at rcn.com> 14 15 **Source code:** :source:`Lib/decimal.py` 16 17 .. import modules for testing inline doctests with the Sphinx doctest builder 18 .. testsetup:: * 19 20 import decimal 21 import math 22 from decimal import * 23 # make sure each group gets a fresh context 24 setcontext(Context()) 25 26 -------------- 27 28 The :mod:`decimal` module provides support for fast correctly-rounded 29 decimal floating point arithmetic. It offers several advantages over the 30 :class:`float` datatype: 31 32 * Decimal "is based on a floating-point model which was designed with people 33 in mind, and necessarily has a paramount guiding principle -- computers must 34 provide an arithmetic that works in the same way as the arithmetic that 35 people learn at school." -- excerpt from the decimal arithmetic specification. 36 37 * Decimal numbers can be represented exactly. In contrast, numbers like 38 :const:`1.1` and :const:`2.2` do not have exact representations in binary 39 floating point. End users typically would not expect ``1.1 + 2.2`` to display 40 as :const:`3.3000000000000003` as it does with binary floating point. 41 42 * The exactness carries over into arithmetic. In decimal floating point, ``0.1 43 + 0.1 + 0.1 - 0.3`` is exactly equal to zero. In binary floating point, the result 44 is :const:`5.5511151231257827e-017`. While near to zero, the differences 45 prevent reliable equality testing and differences can accumulate. For this 46 reason, decimal is preferred in accounting applications which have strict 47 equality invariants. 48 49 * The decimal module incorporates a notion of significant places so that ``1.30 50 + 1.20`` is :const:`2.50`. The trailing zero is kept to indicate significance. 51 This is the customary presentation for monetary applications. For 52 multiplication, the "schoolbook" approach uses all the figures in the 53 multiplicands. For instance, ``1.3 * 1.2`` gives :const:`1.56` while ``1.30 * 54 1.20`` gives :const:`1.5600`. 55 56 * Unlike hardware based binary floating point, the decimal module has a user 57 alterable precision (defaulting to 28 places) which can be as large as needed for 58 a given problem: 59 60 >>> from decimal import * 61 >>> getcontext().prec = 6 62 >>> Decimal(1) / Decimal(7) 63 Decimal('0.142857') 64 >>> getcontext().prec = 28 65 >>> Decimal(1) / Decimal(7) 66 Decimal('0.1428571428571428571428571429') 67 68 * Both binary and decimal floating point are implemented in terms of published 69 standards. While the built-in float type exposes only a modest portion of its 70 capabilities, the decimal module exposes all required parts of the standard. 71 When needed, the programmer has full control over rounding and signal handling. 72 This includes an option to enforce exact arithmetic by using exceptions 73 to block any inexact operations. 74 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 78 arithmetic specification. 79 80 The module design is centered around three concepts: the decimal number, the 81 context for arithmetic, and signals. 82 83 A decimal number is immutable. It has a sign, coefficient digits, and an 84 exponent. To preserve significance, the coefficient digits do not truncate 85 trailing zeros. Decimals also include special values such as 86 :const:`Infinity`, :const:`-Infinity`, and :const:`NaN`. The standard also 87 differentiates :const:`-0` from :const:`+0`. 88 89 The context for arithmetic is an environment specifying precision, rounding 90 rules, limits on exponents, flags indicating the results of operations, and trap 91 enablers which determine whether signals are treated as exceptions. Rounding 92 options include :const:`ROUND_CEILING`, :const:`ROUND_DOWN`, 93 :const:`ROUND_FLOOR`, :const:`ROUND_HALF_DOWN`, :const:`ROUND_HALF_EVEN`, 94 :const:`ROUND_HALF_UP`, :const:`ROUND_UP`, and :const:`ROUND_05UP`. 95 96 Signals are groups of exceptional conditions arising during the course of 97 computation. Depending on the needs of the application, signals may be ignored, 98 considered as informational, or treated as exceptions. The signals in the 99 decimal module are: :const:`Clamped`, :const:`InvalidOperation`, 100 :const:`DivisionByZero`, :const:`Inexact`, :const:`Rounded`, :const:`Subnormal`, 101 :const:`Overflow`, :const:`Underflow` and :const:`FloatOperation`. 102 103 For each signal there is a flag and a trap enabler. When a signal is 104 encountered, its flag is set to one, then, if the trap enabler is 105 set to one, an exception is raised. Flags are sticky, so the user needs to 106 reset them before monitoring a calculation. 107 108 109 .. seealso:: 110 111 * IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic 112 Specification <http://speleotrove.com/decimal/decarith.html>`_. 113 114 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 115 116 117 .. _decimal-tutorial: 118 119 Quick-start Tutorial 120 -------------------- 121 122 The usual start to using decimals is importing the module, viewing the current 123 context with :func:`getcontext` and, if necessary, setting new values for 124 precision, rounding, or enabled traps:: 125 126 >>> from decimal import * 127 >>> getcontext() 128 Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999, 129 capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero, 130 InvalidOperation]) 131 132 >>> getcontext().prec = 7 # Set a new precision 133 134 Decimal instances can be constructed from integers, strings, floats, or tuples. 135 Construction from an integer or a float performs an exact conversion of the 136 value of that integer or float. Decimal numbers include special values such as 137 :const:`NaN` which stands for "Not a number", positive and negative 138 :const:`Infinity`, and :const:`-0`:: 139 140 >>> getcontext().prec = 28 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.4142135623730951') 151 >>> Decimal(2) ** Decimal('0.5') 152 Decimal('1.414213562373095048801688724') 153 >>> Decimal('NaN') 154 Decimal('NaN') 155 >>> Decimal('-Infinity') 156 Decimal('-Infinity') 157 158 If the :exc:`FloatOperation` signal is trapped, accidental mixing of 159 decimals and floats in constructors or ordering comparisons raises 160 an exception:: 161 162 >>> c = getcontext() 163 >>> c.traps[FloatOperation] = True 164 >>> Decimal(3.14) 165 Traceback (most recent call last): 166 File "<stdin>", line 1, in <module> 167 decimal.FloatOperation: [<class 'decimal.FloatOperation'>] 168 >>> Decimal('3.5') < 3.7 169 Traceback (most recent call last): 170 File "<stdin>", line 1, in <module> 171 decimal.FloatOperation: [<class 'decimal.FloatOperation'>] 172 >>> Decimal('3.5') == 3.5 173 True 174 175 .. versionadded:: 3.3 176 177 The significance of a new Decimal is determined solely by the number of digits 178 input. Context precision and rounding only come into play during arithmetic 179 operations. 180 181 .. doctest:: newcontext 182 183 >>> getcontext().prec = 6 184 >>> Decimal('3.0') 185 Decimal('3.0') 186 >>> Decimal('3.1415926535') 187 Decimal('3.1415926535') 188 >>> Decimal('3.1415926535') + Decimal('2.7182818285') 189 Decimal('5.85987') 190 >>> getcontext().rounding = ROUND_UP 191 >>> Decimal('3.1415926535') + Decimal('2.7182818285') 192 Decimal('5.85988') 193 194 If the internal limits of the C version are exceeded, constructing 195 a decimal raises :class:`InvalidOperation`:: 196 197 >>> Decimal("1e9999999999999999999") 198 Traceback (most recent call last): 199 File "<stdin>", line 1, in <module> 200 decimal.InvalidOperation: [<class 'decimal.InvalidOperation'>] 201 202 .. versionchanged:: 3.3 203 204 Decimals interact well with much of the rest of Python. Here is a small decimal 205 floating point flying circus: 206 207 .. doctest:: 208 :options: +NORMALIZE_WHITESPACE 209 210 >>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())) 211 >>> max(data) 212 Decimal('9.25') 213 >>> min(data) 214 Decimal('0.03') 215 >>> sorted(data) 216 [Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'), 217 Decimal('2.35'), Decimal('3.45'), Decimal('9.25')] 218 >>> sum(data) 219 Decimal('19.29') 220 >>> a,b,c = data[:3] 221 >>> str(a) 222 '1.34' 223 >>> float(a) 224 1.34 225 >>> round(a, 1) 226 Decimal('1.3') 227 >>> int(a) 228 1 229 >>> a * 5 230 Decimal('6.70') 231 >>> a * b 232 Decimal('2.5058') 233 >>> c % a 234 Decimal('0.77') 235 236 And some mathematical functions are also available to Decimal: 237 238 >>> getcontext().prec = 28 239 >>> Decimal(2).sqrt() 240 Decimal('1.414213562373095048801688724') 241 >>> Decimal(1).exp() 242 Decimal('2.718281828459045235360287471') 243 >>> Decimal('10').ln() 244 Decimal('2.302585092994045684017991455') 245 >>> Decimal('10').log10() 246 Decimal('1') 247 248 The :meth:`quantize` method rounds a number to a fixed exponent. This method is 249 useful for monetary applications that often round results to a fixed number of 250 places: 251 252 >>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN) 253 Decimal('7.32') 254 >>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP) 255 Decimal('8') 256 257 As shown above, the :func:`getcontext` function accesses the current context and 258 allows the settings to be changed. This approach meets the needs of most 259 applications. 260 261 For more advanced work, it may be useful to create alternate contexts using the 262 Context() constructor. To make an alternate active, use the :func:`setcontext` 263 function. 264 265 In accordance with the standard, the :mod:`decimal` module provides two ready to 266 use standard contexts, :const:`BasicContext` and :const:`ExtendedContext`. The 267 former is especially useful for debugging because many of the traps are 268 enabled: 269 270 .. doctest:: newcontext 271 :options: +NORMALIZE_WHITESPACE 272 273 >>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN) 274 >>> setcontext(myothercontext) 275 >>> Decimal(1) / Decimal(7) 276 Decimal('0.142857142857142857142857142857142857142857142857142857142857') 277 278 >>> ExtendedContext 279 Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999, 280 capitals=1, clamp=0, flags=[], traps=[]) 281 >>> setcontext(ExtendedContext) 282 >>> Decimal(1) / Decimal(7) 283 Decimal('0.142857143') 284 >>> Decimal(42) / Decimal(0) 285 Decimal('Infinity') 286 287 >>> setcontext(BasicContext) 288 >>> Decimal(42) / Decimal(0) 289 Traceback (most recent call last): 290 File "<pyshell#143>", line 1, in -toplevel- 291 Decimal(42) / Decimal(0) 292 DivisionByZero: x / 0 293 294 Contexts also have signal flags for monitoring exceptional conditions 295 encountered during computations. The flags remain set until explicitly cleared, 296 so it is best to clear the flags before each set of monitored computations by 297 using the :meth:`clear_flags` method. :: 298 299 >>> setcontext(ExtendedContext) 300 >>> getcontext().clear_flags() 301 >>> Decimal(355) / Decimal(113) 302 Decimal('3.14159292') 303 >>> getcontext() 304 Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999, 305 capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[]) 306 307 The *flags* entry shows that the rational approximation to :const:`Pi` was 308 rounded (digits beyond the context precision were thrown away) and that the 309 result is inexact (some of the discarded digits were non-zero). 310 311 Individual traps are set using the dictionary in the :attr:`traps` field of a 312 context: 313 314 .. doctest:: newcontext 315 316 >>> setcontext(ExtendedContext) 317 >>> Decimal(1) / Decimal(0) 318 Decimal('Infinity') 319 >>> getcontext().traps[DivisionByZero] = 1 320 >>> Decimal(1) / Decimal(0) 321 Traceback (most recent call last): 322 File "<pyshell#112>", line 1, in -toplevel- 323 Decimal(1) / Decimal(0) 324 DivisionByZero: x / 0 325 326 Most programs adjust the current context only once, at the beginning of the 327 program. And, in many applications, data is converted to :class:`Decimal` with 328 a single cast inside a loop. With context set and decimals created, the bulk of 329 the program manipulates the data no differently than with other Python numeric 330 types. 331 332 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 333 334 335 .. _decimal-decimal: 336 337 Decimal objects 338 --------------- 339 340 341 .. class:: Decimal(value="0", context=None) 342 343 Construct a new :class:`Decimal` object based from *value*. 344 345 *value* can be an integer, string, tuple, :class:`float`, or another :class:`Decimal` 346 object. If no *value* is given, returns ``Decimal('0')``. If *value* is a 347 string, it should conform to the decimal numeric string syntax after leading 348 and trailing whitespace characters, as well as underscores throughout, are removed:: 349 350 sign ::= '+' | '-' 351 digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' 352 indicator ::= 'e' | 'E' 353 digits ::= digit [digit]... 354 decimal-part ::= digits '.' [digits] | ['.'] digits 355 exponent-part ::= indicator [sign] digits 356 infinity ::= 'Infinity' | 'Inf' 357 nan ::= 'NaN' [digits] | 'sNaN' [digits] 358 numeric-value ::= decimal-part [exponent-part] | infinity 359 numeric-string ::= [sign] numeric-value | [sign] nan 360 361 Other Unicode decimal digits are also permitted where ``digit`` 362 appears above. These include decimal digits from various other 363 alphabets (for example, Arabic-Indic and Devangar digits) along 364 with the fullwidth digits ``'\uff10'`` through ``'\uff19'``. 365 366 If *value* is a :class:`tuple`, it should have three components, a sign 367 (:const:`0` for positive or :const:`1` for negative), a :class:`tuple` of 368 digits, and an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))`` 369 returns ``Decimal('1.414')``. 370 371 If *value* is a :class:`float`, the binary floating point value is losslessly 372 converted to its exact decimal equivalent. This conversion can often require 373 53 or more digits of precision. For example, ``Decimal(float('1.1'))`` 374 converts to 375 ``Decimal('1.100000000000000088817841970012523233890533447265625')``. 376 377 The *context* precision does not affect how many digits are stored. That is 378 determined exclusively by the number of digits in *value*. For example, 379 ``Decimal('3.00000')`` records all five zeros even if the context precision is 380 only three. 381 382 The purpose of the *context* argument is determining what to do if *value* is a 383 malformed string. If the context traps :const:`InvalidOperation`, an exception 384 is raised; otherwise, the constructor returns a new Decimal with the value of 385 :const:`NaN`. 386 387 Once constructed, :class:`Decimal` objects are immutable. 388 389 .. versionchanged:: 3.2 390 The argument to the constructor is now permitted to be a :class:`float` 391 instance. 392 393 .. versionchanged:: 3.3 394 :class:`float` arguments raise an exception if the :exc:`FloatOperation` 395 trap is set. By default the trap is off. 396 397 .. versionchanged:: 3.6 398 Underscores are allowed for grouping, as with integral and floating-point 399 literals in code. 400 401 Decimal floating point objects share many properties with the other built-in 402 numeric types such as :class:`float` and :class:`int`. All of the usual math 403 operations and special methods apply. Likewise, decimal objects can be 404 copied, pickled, printed, used as dictionary keys, used as set elements, 405 compared, sorted, and coerced to another type (such as :class:`float` or 406 :class:`int`). 407 408 There are some small differences between arithmetic on Decimal objects and 409 arithmetic on integers and floats. When the remainder operator ``%`` is 410 applied to Decimal objects, the sign of the result is the sign of the 411 *dividend* rather than the sign of the divisor:: 412 413 >>> (-7) % 4 414 1 415 >>> Decimal(-7) % Decimal(4) 416 Decimal('-3') 417 418 The integer division operator ``//`` behaves analogously, returning the 419 integer part of the true quotient (truncating towards zero) rather than its 420 floor, so as to preserve the usual identity ``x == (x // y) * y + x % y``:: 421 422 >>> -7 // 4 423 -2 424 >>> Decimal(-7) // Decimal(4) 425 Decimal('-1') 426 427 The ``%`` and ``//`` operators implement the ``remainder`` and 428 ``divide-integer`` operations (respectively) as described in the 429 specification. 430 431 Decimal objects cannot generally be combined with floats or 432 instances of :class:`fractions.Fraction` in arithmetic operations: 433 an attempt to add a :class:`Decimal` to a :class:`float`, for 434 example, will raise a :exc:`TypeError`. However, it is possible to 435 use Python's comparison operators to compare a :class:`Decimal` 436 instance ``x`` with another number ``y``. This avoids confusing results 437 when doing equality comparisons between numbers of different types. 438 439 .. versionchanged:: 3.2 440 Mixed-type comparisons between :class:`Decimal` instances and other 441 numeric types are now fully supported. 442 443 In addition to the standard numeric properties, decimal floating point 444 objects also have a number of specialized methods: 445 446 447 .. method:: adjusted() 448 449 Return the adjusted exponent after shifting out the coefficient's 450 rightmost digits until only the lead digit remains: 451 ``Decimal('321e+5').adjusted()`` returns seven. Used for determining the 452 position of the most significant digit with respect to the decimal point. 453 454 .. method:: as_integer_ratio() 455 456 Return a pair ``(n, d)`` of integers that represent the given 457 :class:`Decimal` instance as a fraction, in lowest terms and 458 with a positive denominator:: 459 460 >>> Decimal('-3.14').as_integer_ratio() 461 (-157, 50) 462 463 The conversion is exact. Raise OverflowError on infinities and ValueError 464 on NaNs. 465 466 .. versionadded:: 3.6 467 468 .. method:: as_tuple() 469 470 Return a :term:`named tuple` representation of the number: 471 ``DecimalTuple(sign, digits, exponent)``. 472 473 474 .. method:: canonical() 475 476 Return the canonical encoding of the argument. Currently, the encoding of 477 a :class:`Decimal` instance is always canonical, so this operation returns 478 its argument unchanged. 479 480 .. method:: compare(other, context=None) 481 482 Compare the values of two Decimal instances. :meth:`compare` returns a 483 Decimal instance, and if either operand is a NaN then the result is a 484 NaN:: 485 486 a or b is a NaN ==> Decimal('NaN') 487 a < b ==> Decimal('-1') 488 a == b ==> Decimal('0') 489 a > b ==> Decimal('1') 490 491 .. method:: compare_signal(other, context=None) 492 493 This operation is identical to the :meth:`compare` method, except that all 494 NaNs signal. That is, if neither operand is a signaling NaN then any 495 quiet NaN operand is treated as though it were a signaling NaN. 496 497 .. method:: compare_total(other, context=None) 498 499 Compare two operands using their abstract representation rather than their 500 numerical value. Similar to the :meth:`compare` method, but the result 501 gives a total ordering on :class:`Decimal` instances. Two 502 :class:`Decimal` instances with the same numeric value but different 503 representations compare unequal in this ordering: 504 505 >>> Decimal('12.0').compare_total(Decimal('12')) 506 Decimal('-1') 507 508 Quiet and signaling NaNs are also included in the total ordering. The 509 result of this function is ``Decimal('0')`` if both operands have the same 510 representation, ``Decimal('-1')`` if the first operand is lower in the 511 total order than the second, and ``Decimal('1')`` if the first operand is 512 higher in the total order than the second operand. See the specification 513 for details of the total order. 514 515 This operation is unaffected by context and is quiet: no flags are changed 516 and no rounding is performed. As an exception, the C version may raise 517 InvalidOperation if the second operand cannot be converted exactly. 518 519 .. method:: compare_total_mag(other, context=None) 520 521 Compare two operands using their abstract representation rather than their 522 value as in :meth:`compare_total`, but ignoring the sign of each operand. 523 ``x.compare_total_mag(y)`` is equivalent to 524 ``x.copy_abs().compare_total(y.copy_abs())``. 525 526 This operation is unaffected by context and is quiet: no flags are changed 527 and no rounding is performed. As an exception, the C version may raise 528 InvalidOperation if the second operand cannot be converted exactly. 529 530 .. method:: conjugate() 531 532 Just returns self, this method is only to comply with the Decimal 533 Specification. 534 535 .. method:: copy_abs() 536 537 Return the absolute value of the argument. This operation is unaffected 538 by the context and is quiet: no flags are changed and no rounding is 539 performed. 540 541 .. method:: copy_negate() 542 543 Return the negation of the argument. This operation is unaffected by the 544 context and is quiet: no flags are changed and no rounding is performed. 545 546 .. method:: copy_sign(other, context=None) 547 548 Return a copy of the first operand with the sign set to be the same as the 549 sign of the second operand. For example: 550 551 >>> Decimal('2.3').copy_sign(Decimal('-1.5')) 552 Decimal('-2.3') 553 554 This operation is unaffected by context and is quiet: no flags are changed 555 and no rounding is performed. As an exception, the C version may raise 556 InvalidOperation if the second operand cannot be converted exactly. 557 558 .. method:: exp(context=None) 559 560 Return the value of the (natural) exponential function ``e**x`` at the 561 given number. The result is correctly rounded using the 562 :const:`ROUND_HALF_EVEN` rounding mode. 563 564 >>> Decimal(1).exp() 565 Decimal('2.718281828459045235360287471') 566 >>> Decimal(321).exp() 567 Decimal('2.561702493119680037517373933E+139') 568 569 .. method:: from_float(f) 570 571 Classmethod that converts a float to a decimal number, exactly. 572 573 Note `Decimal.from_float(0.1)` is not the same as `Decimal('0.1')`. 574 Since 0.1 is not exactly representable in binary floating point, the 575 value is stored as the nearest representable value which is 576 `0x1.999999999999ap-4`. That equivalent value in decimal is 577 `0.1000000000000000055511151231257827021181583404541015625`. 578 579 .. note:: From Python 3.2 onwards, a :class:`Decimal` instance 580 can also be constructed directly from a :class:`float`. 581 582 .. doctest:: 583 584 >>> Decimal.from_float(0.1) 585 Decimal('0.1000000000000000055511151231257827021181583404541015625') 586 >>> Decimal.from_float(float('nan')) 587 Decimal('NaN') 588 >>> Decimal.from_float(float('inf')) 589 Decimal('Infinity') 590 >>> Decimal.from_float(float('-inf')) 591 Decimal('-Infinity') 592 593 .. versionadded:: 3.1 594 595 .. method:: fma(other, third, context=None) 596 597 Fused multiply-add. Return self*other+third with no rounding of the 598 intermediate product self*other. 599 600 >>> Decimal(2).fma(3, 5) 601 Decimal('11') 602 603 .. method:: is_canonical() 604 605 Return :const:`True` if the argument is canonical and :const:`False` 606 otherwise. Currently, a :class:`Decimal` instance is always canonical, so 607 this operation always returns :const:`True`. 608 609 .. method:: is_finite() 610 611 Return :const:`True` if the argument is a finite number, and 612 :const:`False` if the argument is an infinity or a NaN. 613 614 .. method:: is_infinite() 615 616 Return :const:`True` if the argument is either positive or negative 617 infinity and :const:`False` otherwise. 618 619 .. method:: is_nan() 620 621 Return :const:`True` if the argument is a (quiet or signaling) NaN and 622 :const:`False` otherwise. 623 624 .. method:: is_normal(context=None) 625 626 Return :const:`True` if the argument is a *normal* finite number. Return 627 :const:`False` if the argument is zero, subnormal, infinite or a NaN. 628 629 .. method:: is_qnan() 630 631 Return :const:`True` if the argument is a quiet NaN, and 632 :const:`False` otherwise. 633 634 .. method:: is_signed() 635 636 Return :const:`True` if the argument has a negative sign and 637 :const:`False` otherwise. Note that zeros and NaNs can both carry signs. 638 639 .. method:: is_snan() 640 641 Return :const:`True` if the argument is a signaling NaN and :const:`False` 642 otherwise. 643 644 .. method:: is_subnormal(context=None) 645 646 Return :const:`True` if the argument is subnormal, and :const:`False` 647 otherwise. 648 649 .. method:: is_zero() 650 651 Return :const:`True` if the argument is a (positive or negative) zero and 652 :const:`False` otherwise. 653 654 .. method:: ln(context=None) 655 656 Return the natural (base e) logarithm of the operand. The result is 657 correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode. 658 659 .. method:: log10(context=None) 660 661 Return the base ten logarithm of the operand. The result is correctly 662 rounded using the :const:`ROUND_HALF_EVEN` rounding mode. 663 664 .. method:: logb(context=None) 665 666 For a nonzero number, return the adjusted exponent of its operand as a 667 :class:`Decimal` instance. If the operand is a zero then 668 ``Decimal('-Infinity')`` is returned and the :const:`DivisionByZero` flag 669 is raised. If the operand is an infinity then ``Decimal('Infinity')`` is 670 returned. 671 672 .. method:: logical_and(other, context=None) 673 674 :meth:`logical_and` is a logical operation which takes two *logical 675 operands* (see :ref:`logical_operands_label`). The result is the 676 digit-wise ``and`` of the two operands. 677 678 .. method:: logical_invert(context=None) 679 680 :meth:`logical_invert` is a logical operation. The 681 result is the digit-wise inversion of the operand. 682 683 .. method:: logical_or(other, context=None) 684 685 :meth:`logical_or` is a logical operation which takes two *logical 686 operands* (see :ref:`logical_operands_label`). The result is the 687 digit-wise ``or`` of the two operands. 688 689 .. method:: logical_xor(other, context=None) 690 691 :meth:`logical_xor` is a logical operation which takes two *logical 692 operands* (see :ref:`logical_operands_label`). The result is the 693 digit-wise exclusive or of the two operands. 694 695 .. method:: max(other, context=None) 696 697 Like ``max(self, other)`` except that the context rounding rule is applied 698 before returning and that :const:`NaN` values are either signaled or 699 ignored (depending on the context and whether they are signaling or 700 quiet). 701 702 .. method:: max_mag(other, context=None) 703 704 Similar to the :meth:`.max` method, but the comparison is done using the 705 absolute values of the operands. 706 707 .. method:: min(other, context=None) 708 709 Like ``min(self, other)`` except that the context rounding rule is applied 710 before returning and that :const:`NaN` values are either signaled or 711 ignored (depending on the context and whether they are signaling or 712 quiet). 713 714 .. method:: min_mag(other, context=None) 715 716 Similar to the :meth:`.min` method, but the comparison is done using the 717 absolute values of the operands. 718 719 .. method:: next_minus(context=None) 720 721 Return the largest number representable in the given context (or in the 722 current thread's context if no context is given) that is smaller than the 723 given operand. 724 725 .. method:: next_plus(context=None) 726 727 Return the smallest number representable in the given context (or in the 728 current thread's context if no context is given) that is larger than the 729 given operand. 730 731 .. method:: next_toward(other, context=None) 732 733 If the two operands are unequal, return the number closest to the first 734 operand in the direction of the second operand. If both operands are 735 numerically equal, return a copy of the first operand with the sign set to 736 be the same as the sign of the second operand. 737 738 .. method:: normalize(context=None) 739 740 Normalize the number by stripping the rightmost trailing zeros and 741 converting any result equal to :const:`Decimal('0')` to 742 :const:`Decimal('0e0')`. Used for producing canonical values for attributes 743 of an equivalence class. For example, ``Decimal('32.100')`` and 744 ``Decimal('0.321000e+2')`` both normalize to the equivalent value 745 ``Decimal('32.1')``. 746 747 .. method:: number_class(context=None) 748 749 Return a string describing the *class* of the operand. The returned value 750 is one of the following ten strings. 751 752 * ``"-Infinity"``, indicating that the operand is negative infinity. 753 * ``"-Normal"``, indicating that the operand is a negative normal number. 754 * ``"-Subnormal"``, indicating that the operand is negative and subnormal. 755 * ``"-Zero"``, indicating that the operand is a negative zero. 756 * ``"+Zero"``, indicating that the operand is a positive zero. 757 * ``"+Subnormal"``, indicating that the operand is positive and subnormal. 758 * ``"+Normal"``, indicating that the operand is a positive normal number. 759 * ``"+Infinity"``, indicating that the operand is positive infinity. 760 * ``"NaN"``, indicating that the operand is a quiet NaN (Not a Number). 761 * ``"sNaN"``, indicating that the operand is a signaling NaN. 762 763 .. method:: quantize(exp, rounding=None, context=None) 764 765 Return a value equal to the first operand after rounding and having the 766 exponent of the second operand. 767 768 >>> Decimal('1.41421356').quantize(Decimal('1.000')) 769 Decimal('1.414') 770 771 Unlike other operations, if the length of the coefficient after the 772 quantize operation would be greater than precision, then an 773 :const:`InvalidOperation` is signaled. This guarantees that, unless there 774 is an error condition, the quantized exponent is always equal to that of 775 the right-hand operand. 776 777 Also unlike other operations, quantize never signals Underflow, even if 778 the result is subnormal and inexact. 779 780 If the exponent of the second operand is larger than that of the first 781 then rounding may be necessary. In this case, the rounding mode is 782 determined by the ``rounding`` argument if given, else by the given 783 ``context`` argument; if neither argument is given the rounding mode of 784 the current thread's context is used. 785 786 An error is returned whenever the resulting exponent is greater than 787 :attr:`Emax` or less than :attr:`Etiny`. 788 789 .. method:: radix() 790 791 Return ``Decimal(10)``, the radix (base) in which the :class:`Decimal` 792 class does all its arithmetic. Included for compatibility with the 793 specification. 794 795 .. method:: remainder_near(other, context=None) 796 797 Return the remainder from dividing *self* by *other*. This differs from 798 ``self % other`` in that the sign of the remainder is chosen so as to 799 minimize its absolute value. More precisely, the return value is 800 ``self - n * other`` where ``n`` is the integer nearest to the exact 801 value of ``self / other``, and if two integers are equally near then the 802 even one is chosen. 803 804 If the result is zero then its sign will be the sign of *self*. 805 806 >>> Decimal(18).remainder_near(Decimal(10)) 807 Decimal('-2') 808 >>> Decimal(25).remainder_near(Decimal(10)) 809 Decimal('5') 810 >>> Decimal(35).remainder_near(Decimal(10)) 811 Decimal('-5') 812 813 .. method:: rotate(other, context=None) 814 815 Return the result of rotating the digits of the first operand by an amount 816 specified by the second operand. The second operand must be an integer in 817 the range -precision through precision. The absolute value of the second 818 operand gives the number of places to rotate. If the second operand is 819 positive then rotation is to the left; otherwise rotation is to the right. 820 The coefficient of the first operand is padded on the left with zeros to 821 length precision if necessary. The sign and exponent of the first operand 822 are unchanged. 823 824 .. method:: same_quantum(other, context=None) 825 826 Test whether self and other have the same exponent or whether both are 827 :const:`NaN`. 828 829 This operation is unaffected by context and is quiet: no flags are changed 830 and no rounding is performed. As an exception, the C version may raise 831 InvalidOperation if the second operand cannot be converted exactly. 832 833 .. method:: scaleb(other, context=None) 834 835 Return the first operand with exponent adjusted by the second. 836 Equivalently, return the first operand multiplied by ``10**other``. The 837 second operand must be an integer. 838 839 .. method:: shift(other, context=None) 840 841 Return the result of shifting the digits of the first operand by an amount 842 specified by the second operand. The second operand must be an integer in 843 the range -precision through precision. The absolute value of the second 844 operand gives the number of places to shift. If the second operand is 845 positive then the shift is to the left; otherwise the shift is to the 846 right. Digits shifted into the coefficient are zeros. The sign and 847 exponent of the first operand are unchanged. 848 849 .. method:: sqrt(context=None) 850 851 Return the square root of the argument to full precision. 852 853 854 .. method:: to_eng_string(context=None) 855 856 Convert to a string, using engineering notation if an exponent is needed. 857 858 Engineering notation has an exponent which is a multiple of 3. This 859 can leave up to 3 digits to the left of the decimal place and may 860 require the addition of either one or two trailing zeros. 861 862 For example, this converts ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``. 863 864 .. method:: to_integral(rounding=None, context=None) 865 866 Identical to the :meth:`to_integral_value` method. The ``to_integral`` 867 name has been kept for compatibility with older versions. 868 869 .. method:: to_integral_exact(rounding=None, context=None) 870 871 Round to the nearest integer, signaling :const:`Inexact` or 872 :const:`Rounded` as appropriate if rounding occurs. The rounding mode is 873 determined by the ``rounding`` parameter if given, else by the given 874 ``context``. If neither parameter is given then the rounding mode of the 875 current context is used. 876 877 .. method:: to_integral_value(rounding=None, context=None) 878 879 Round to the nearest integer without signaling :const:`Inexact` or 880 :const:`Rounded`. If given, applies *rounding*; otherwise, uses the 881 rounding method in either the supplied *context* or the current context. 882 883 884 .. _logical_operands_label: 885 886 Logical operands 887 ^^^^^^^^^^^^^^^^ 888 889 The :meth:`logical_and`, :meth:`logical_invert`, :meth:`logical_or`, 890 and :meth:`logical_xor` methods expect their arguments to be *logical 891 operands*. A *logical operand* is a :class:`Decimal` instance whose 892 exponent and sign are both zero, and whose digits are all either 893 :const:`0` or :const:`1`. 894 895 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 896 897 898 .. _decimal-context: 899 900 Context objects 901 --------------- 902 903 Contexts are environments for arithmetic operations. They govern precision, set 904 rules for rounding, determine which signals are treated as exceptions, and limit 905 the range for exponents. 906 907 Each thread has its own current context which is accessed or changed using the 908 :func:`getcontext` and :func:`setcontext` functions: 909 910 911 .. function:: getcontext() 912 913 Return the current context for the active thread. 914 915 916 .. function:: setcontext(c) 917 918 Set the current context for the active thread to *c*. 919 920 You can also use the :keyword:`with` statement and the :func:`localcontext` 921 function to temporarily change the active context. 922 923 .. function:: localcontext(ctx=None) 924 925 Return a context manager that will set the current context for the active thread 926 to a copy of *ctx* on entry to the with-statement and restore the previous context 927 when exiting the with-statement. If no context is specified, a copy of the 928 current context is used. 929 930 For example, the following code sets the current decimal precision to 42 places, 931 performs a calculation, and then automatically restores the previous context:: 932 933 from decimal import localcontext 934 935 with localcontext() as ctx: 936 ctx.prec = 42 # Perform a high precision calculation 937 s = calculate_something() 938 s = +s # Round the final result back to the default precision 939 940 New contexts can also be created using the :class:`Context` constructor 941 described below. In addition, the module provides three pre-made contexts: 942 943 944 .. class:: BasicContext 945 946 This is a standard context defined by the General Decimal Arithmetic 947 Specification. Precision is set to nine. Rounding is set to 948 :const:`ROUND_HALF_UP`. All flags are cleared. All traps are enabled (treated 949 as exceptions) except :const:`Inexact`, :const:`Rounded`, and 950 :const:`Subnormal`. 951 952 Because many of the traps are enabled, this context is useful for debugging. 953 954 955 .. class:: ExtendedContext 956 957 This is a standard context defined by the General Decimal Arithmetic 958 Specification. Precision is set to nine. Rounding is set to 959 :const:`ROUND_HALF_EVEN`. All flags are cleared. No traps are enabled (so that 960 exceptions are not raised during computations). 961 962 Because the traps are disabled, this context is useful for applications that 963 prefer to have result value of :const:`NaN` or :const:`Infinity` instead of 964 raising exceptions. This allows an application to complete a run in the 965 presence of conditions that would otherwise halt the program. 966 967 968 .. class:: DefaultContext 969 970 This context is used by the :class:`Context` constructor as a prototype for new 971 contexts. Changing a field (such a precision) has the effect of changing the 972 default for new contexts created by the :class:`Context` constructor. 973 974 This context is most useful in multi-threaded environments. Changing one of the 975 fields before threads are started has the effect of setting system-wide 976 defaults. Changing the fields after threads have started is not recommended as 977 it would require thread synchronization to prevent race conditions. 978 979 In single threaded environments, it is preferable to not use this context at 980 all. Instead, simply create contexts explicitly as described below. 981 982 The default values are :attr:`prec`\ =\ :const:`28`, 983 :attr:`rounding`\ =\ :const:`ROUND_HALF_EVEN`, 984 and enabled traps for :class:`Overflow`, :class:`InvalidOperation`, and 985 :class:`DivisionByZero`. 986 987 In addition to the three supplied contexts, new contexts can be created with the 988 :class:`Context` constructor. 989 990 991 .. class:: Context(prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=None, flags=None, traps=None) 992 993 Creates a new context. If a field is not specified or is :const:`None`, the 994 default values are copied from the :const:`DefaultContext`. If the *flags* 995 field is not specified or is :const:`None`, all flags are cleared. 996 997 *prec* is an integer in the range [:const:`1`, :const:`MAX_PREC`] that sets 998 the precision for arithmetic operations in the context. 999 1000 The *rounding* option is one of the constants listed in the section 1001 `Rounding Modes`_. 1002 1003 The *traps* and *flags* fields list any signals to be set. Generally, new 1004 contexts should only set traps and leave the flags clear. 1005 1006 The *Emin* and *Emax* fields are integers specifying the outer limits allowable 1007 for exponents. *Emin* must be in the range [:const:`MIN_EMIN`, :const:`0`], 1008 *Emax* in the range [:const:`0`, :const:`MAX_EMAX`]. 1009 1010 The *capitals* field is either :const:`0` or :const:`1` (the default). If set to 1011 :const:`1`, exponents are printed with a capital :const:`E`; otherwise, a 1012 lowercase :const:`e` is used: :const:`Decimal('6.02e+23')`. 1013 1014 The *clamp* field is either :const:`0` (the default) or :const:`1`. 1015 If set to :const:`1`, the exponent ``e`` of a :class:`Decimal` 1016 instance representable in this context is strictly limited to the 1017 range ``Emin - prec + 1 <= e <= Emax - prec + 1``. If *clamp* is 1018 :const:`0` then a weaker condition holds: the adjusted exponent of 1019 the :class:`Decimal` instance is at most ``Emax``. When *clamp* is 1020 :const:`1`, a large normal number will, where possible, have its 1021 exponent reduced and a corresponding number of zeros added to its 1022 coefficient, in order to fit the exponent constraints; this 1023 preserves the value of the number but loses information about 1024 significant trailing zeros. For example:: 1025 1026 >>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999') 1027 Decimal('1.23000E+999') 1028 1029 A *clamp* value of :const:`1` allows compatibility with the 1030 fixed-width decimal interchange formats specified in IEEE 754. 1031 1032 The :class:`Context` class defines several general purpose methods as well as 1033 a large number of methods for doing arithmetic directly in a given context. 1034 In addition, for each of the :class:`Decimal` methods described above (with 1035 the exception of the :meth:`adjusted` and :meth:`as_tuple` methods) there is 1036 a corresponding :class:`Context` method. For example, for a :class:`Context` 1037 instance ``C`` and :class:`Decimal` instance ``x``, ``C.exp(x)`` is 1038 equivalent to ``x.exp(context=C)``. Each :class:`Context` method accepts a 1039 Python integer (an instance of :class:`int`) anywhere that a 1040 Decimal instance is accepted. 1041 1042 1043 .. method:: clear_flags() 1044 1045 Resets all of the flags to :const:`0`. 1046 1047 .. method:: clear_traps() 1048 1049 Resets all of the traps to :const:`0`. 1050 1051 .. versionadded:: 3.3 1052 1053 .. method:: copy() 1054 1055 Return a duplicate of the context. 1056 1057 .. method:: copy_decimal(num) 1058 1059 Return a copy of the Decimal instance num. 1060 1061 .. method:: create_decimal(num) 1062 1063 Creates a new Decimal instance from *num* but using *self* as 1064 context. Unlike the :class:`Decimal` constructor, the context precision, 1065 rounding method, flags, and traps are applied to the conversion. 1066 1067 This is useful because constants are often given to a greater precision 1068 than is needed by the application. Another benefit is that rounding 1069 immediately eliminates unintended effects from digits beyond the current 1070 precision. In the following example, using unrounded inputs means that 1071 adding zero to a sum can change the result: 1072 1073 .. doctest:: newcontext 1074 1075 >>> getcontext().prec = 3 1076 >>> Decimal('3.4445') + Decimal('1.0023') 1077 Decimal('4.45') 1078 >>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023') 1079 Decimal('4.44') 1080 1081 This method implements the to-number operation of the IBM specification. 1082 If the argument is a string, no leading or trailing whitespace or 1083 underscores are permitted. 1084 1085 .. method:: create_decimal_from_float(f) 1086 1087 Creates a new Decimal instance from a float *f* but rounding using *self* 1088 as the context. Unlike the :meth:`Decimal.from_float` class method, 1089 the context precision, rounding method, flags, and traps are applied to 1090 the conversion. 1091 1092 .. doctest:: 1093 1094 >>> context = Context(prec=5, rounding=ROUND_DOWN) 1095 >>> context.create_decimal_from_float(math.pi) 1096 Decimal('3.1415') 1097 >>> context = Context(prec=5, traps=[Inexact]) 1098 >>> context.create_decimal_from_float(math.pi) 1099 Traceback (most recent call last): 1100 ... 1101 decimal.Inexact: None 1102 1103 .. versionadded:: 3.1 1104 1105 .. method:: Etiny() 1106 1107 Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent 1108 value for subnormal results. When underflow occurs, the exponent is set 1109 to :const:`Etiny`. 1110 1111 .. method:: Etop() 1112 1113 Returns a value equal to ``Emax - prec + 1``. 1114 1115 The usual approach to working with decimals is to create :class:`Decimal` 1116 instances and then apply arithmetic operations which take place within the 1117 current context for the active thread. An alternative approach is to use 1118 context methods for calculating within a specific context. The methods are 1119 similar to those for the :class:`Decimal` class and are only briefly 1120 recounted here. 1121 1122 1123 .. method:: abs(x) 1124 1125 Returns the absolute value of *x*. 1126 1127 1128 .. method:: add(x, y) 1129 1130 Return the sum of *x* and *y*. 1131 1132 1133 .. method:: canonical(x) 1134 1135 Returns the same Decimal object *x*. 1136 1137 1138 .. method:: compare(x, y) 1139 1140 Compares *x* and *y* numerically. 1141 1142 1143 .. method:: compare_signal(x, y) 1144 1145 Compares the values of the two operands numerically. 1146 1147 1148 .. method:: compare_total(x, y) 1149 1150 Compares two operands using their abstract representation. 1151 1152 1153 .. method:: compare_total_mag(x, y) 1154 1155 Compares two operands using their abstract representation, ignoring sign. 1156 1157 1158 .. method:: copy_abs(x) 1159 1160 Returns a copy of *x* with the sign set to 0. 1161 1162 1163 .. method:: copy_negate(x) 1164 1165 Returns a copy of *x* with the sign inverted. 1166 1167 1168 .. method:: copy_sign(x, y) 1169 1170 Copies the sign from *y* to *x*. 1171 1172 1173 .. method:: divide(x, y) 1174 1175 Return *x* divided by *y*. 1176 1177 1178 .. method:: divide_int(x, y) 1179 1180 Return *x* divided by *y*, truncated to an integer. 1181 1182 1183 .. method:: divmod(x, y) 1184 1185 Divides two numbers and returns the integer part of the result. 1186 1187 1188 .. method:: exp(x) 1189 1190 Returns `e ** x`. 1191 1192 1193 .. method:: fma(x, y, z) 1194 1195 Returns *x* multiplied by *y*, plus *z*. 1196 1197 1198 .. method:: is_canonical(x) 1199 1200 Returns ``True`` if *x* is canonical; otherwise returns ``False``. 1201 1202 1203 .. method:: is_finite(x) 1204 1205 Returns ``True`` if *x* is finite; otherwise returns ``False``. 1206 1207 1208 .. method:: is_infinite(x) 1209 1210 Returns ``True`` if *x* is infinite; otherwise returns ``False``. 1211 1212 1213 .. method:: is_nan(x) 1214 1215 Returns ``True`` if *x* is a qNaN or sNaN; otherwise returns ``False``. 1216 1217 1218 .. method:: is_normal(x) 1219 1220 Returns ``True`` if *x* is a normal number; otherwise returns ``False``. 1221 1222 1223 .. method:: is_qnan(x) 1224 1225 Returns ``True`` if *x* is a quiet NaN; otherwise returns ``False``. 1226 1227 1228 .. method:: is_signed(x) 1229 1230 Returns ``True`` if *x* is negative; otherwise returns ``False``. 1231 1232 1233 .. method:: is_snan(x) 1234 1235 Returns ``True`` if *x* is a signaling NaN; otherwise returns ``False``. 1236 1237 1238 .. method:: is_subnormal(x) 1239 1240 Returns ``True`` if *x* is subnormal; otherwise returns ``False``. 1241 1242 1243 .. method:: is_zero(x) 1244 1245 Returns ``True`` if *x* is a zero; otherwise returns ``False``. 1246 1247 1248 .. method:: ln(x) 1249 1250 Returns the natural (base e) logarithm of *x*. 1251 1252 1253 .. method:: log10(x) 1254 1255 Returns the base 10 logarithm of *x*. 1256 1257 1258 .. method:: logb(x) 1259 1260 Returns the exponent of the magnitude of the operand's MSD. 1261 1262 1263 .. method:: logical_and(x, y) 1264 1265 Applies the logical operation *and* between each operand's digits. 1266 1267 1268 .. method:: logical_invert(x) 1269 1270 Invert all the digits in *x*. 1271 1272 1273 .. method:: logical_or(x, y) 1274 1275 Applies the logical operation *or* between each operand's digits. 1276 1277 1278 .. method:: logical_xor(x, y) 1279 1280 Applies the logical operation *xor* between each operand's digits. 1281 1282 1283 .. method:: max(x, y) 1284 1285 Compares two values numerically and returns the maximum. 1286 1287 1288 .. method:: max_mag(x, y) 1289 1290 Compares the values numerically with their sign ignored. 1291 1292 1293 .. method:: min(x, y) 1294 1295 Compares two values numerically and returns the minimum. 1296 1297 1298 .. method:: min_mag(x, y) 1299 1300 Compares the values numerically with their sign ignored. 1301 1302 1303 .. method:: minus(x) 1304 1305 Minus corresponds to the unary prefix minus operator in Python. 1306 1307 1308 .. method:: multiply(x, y) 1309 1310 Return the product of *x* and *y*. 1311 1312 1313 .. method:: next_minus(x) 1314 1315 Returns the largest representable number smaller than *x*. 1316 1317 1318 .. method:: next_plus(x) 1319 1320 Returns the smallest representable number larger than *x*. 1321 1322 1323 .. method:: next_toward(x, y) 1324 1325 Returns the number closest to *x*, in direction towards *y*. 1326 1327 1328 .. method:: normalize(x) 1329 1330 Reduces *x* to its simplest form. 1331 1332 1333 .. method:: number_class(x) 1334 1335 Returns an indication of the class of *x*. 1336 1337 1338 .. method:: plus(x) 1339 1340 Plus corresponds to the unary prefix plus operator in Python. This 1341 operation applies the context precision and rounding, so it is *not* an 1342 identity operation. 1343 1344 1345 .. method:: power(x, y, modulo=None) 1346 1347 Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if given. 1348 1349 With two arguments, compute ``x**y``. If ``x`` is negative then ``y`` 1350 must be integral. The result will be inexact unless ``y`` is integral and 1351 the result is finite and can be expressed exactly in 'precision' digits. 1352 The rounding mode of the context is used. Results are always correctly-rounded 1353 in the Python version. 1354 1355 .. versionchanged:: 3.3 1356 The C module computes :meth:`power` in terms of the correctly-rounded 1357 :meth:`exp` and :meth:`ln` functions. The result is well-defined but 1358 only "almost always correctly-rounded". 1359 1360 With three arguments, compute ``(x**y) % modulo``. For the three argument 1361 form, the following restrictions on the arguments hold: 1362 1363 - all three arguments must be integral 1364 - ``y`` must be nonnegative 1365 - at least one of ``x`` or ``y`` must be nonzero 1366 - ``modulo`` must be nonzero and have at most 'precision' digits 1367 1368 The value resulting from ``Context.power(x, y, modulo)`` is 1369 equal to the value that would be obtained by computing ``(x**y) 1370 % modulo`` with unbounded precision, but is computed more 1371 efficiently. The exponent of the result is zero, regardless of 1372 the exponents of ``x``, ``y`` and ``modulo``. The result is 1373 always exact. 1374 1375 1376 .. method:: quantize(x, y) 1377 1378 Returns a value equal to *x* (rounded), having the exponent of *y*. 1379 1380 1381 .. method:: radix() 1382 1383 Just returns 10, as this is Decimal, :) 1384 1385 1386 .. method:: remainder(x, y) 1387 1388 Returns the remainder from integer division. 1389 1390 The sign of the result, if non-zero, is the same as that of the original 1391 dividend. 1392 1393 1394 .. method:: remainder_near(x, y) 1395 1396 Returns ``x - y * n``, where *n* is the integer nearest the exact value 1397 of ``x / y`` (if the result is 0 then its sign will be the sign of *x*). 1398 1399 1400 .. method:: rotate(x, y) 1401 1402 Returns a rotated copy of *x*, *y* times. 1403 1404 1405 .. method:: same_quantum(x, y) 1406 1407 Returns ``True`` if the two operands have the same exponent. 1408 1409 1410 .. method:: scaleb (x, y) 1411 1412 Returns the first operand after adding the second value its exp. 1413 1414 1415 .. method:: shift(x, y) 1416 1417 Returns a shifted copy of *x*, *y* times. 1418 1419 1420 .. method:: sqrt(x) 1421 1422 Square root of a non-negative number to context precision. 1423 1424 1425 .. method:: subtract(x, y) 1426 1427 Return the difference between *x* and *y*. 1428 1429 1430 .. method:: to_eng_string(x) 1431 1432 Convert to a string, using engineering notation if an exponent is needed. 1433 1434 Engineering notation has an exponent which is a multiple of 3. This 1435 can leave up to 3 digits to the left of the decimal place and may 1436 require the addition of either one or two trailing zeros. 1437 1438 1439 .. method:: to_integral_exact(x) 1440 1441 Rounds to an integer. 1442 1443 1444 .. method:: to_sci_string(x) 1445 1446 Converts a number to a string using scientific notation. 1447 1448 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1449 1450 .. _decimal-rounding-modes: 1451 1452 Constants 1453 --------- 1454 1455 The constants in this section are only relevant for the C module. They 1456 are also included in the pure Python version for compatibility. 1457 1458 +---------------------+---------------------+-------------------------------+ 1459 | | 32-bit | 64-bit | 1460 +=====================+=====================+===============================+ 1461 | .. data:: MAX_PREC | :const:`425000000` | :const:`999999999999999999` | 1462 +---------------------+---------------------+-------------------------------+ 1463 | .. data:: MAX_EMAX | :const:`425000000` | :const:`999999999999999999` | 1464 +---------------------+---------------------+-------------------------------+ 1465 | .. data:: MIN_EMIN | :const:`-425000000` | :const:`-999999999999999999` | 1466 +---------------------+---------------------+-------------------------------+ 1467 | .. data:: MIN_ETINY | :const:`-849999999` | :const:`-1999999999999999997` | 1468 +---------------------+---------------------+-------------------------------+ 1469 1470 1471 .. data:: HAVE_THREADS 1472 1473 The default value is ``True``. If Python is compiled without threads, the 1474 C version automatically disables the expensive thread local context 1475 machinery. In this case, the value is ``False``. 1476 1477 Rounding modes 1478 -------------- 1479 1480 .. data:: ROUND_CEILING 1481 1482 Round towards :const:`Infinity`. 1483 1484 .. data:: ROUND_DOWN 1485 1486 Round towards zero. 1487 1488 .. data:: ROUND_FLOOR 1489 1490 Round towards :const:`-Infinity`. 1491 1492 .. data:: ROUND_HALF_DOWN 1493 1494 Round to nearest with ties going towards zero. 1495 1496 .. data:: ROUND_HALF_EVEN 1497 1498 Round to nearest with ties going to nearest even integer. 1499 1500 .. data:: ROUND_HALF_UP 1501 1502 Round to nearest with ties going away from zero. 1503 1504 .. data:: ROUND_UP 1505 1506 Round away from zero. 1507 1508 .. data:: ROUND_05UP 1509 1510 Round away from zero if last digit after rounding towards zero would have 1511 been 0 or 5; otherwise round towards zero. 1512 1513 1514 .. _decimal-signals: 1515 1516 Signals 1517 ------- 1518 1519 Signals represent conditions that arise during computation. Each corresponds to 1520 one context flag and one context trap enabler. 1521 1522 The context flag is set whenever the condition is encountered. After the 1523 computation, flags may be checked for informational purposes (for instance, to 1524 determine whether a computation was exact). After checking the flags, be sure to 1525 clear all flags before starting the next computation. 1526 1527 If the context's trap enabler is set for the signal, then the condition causes a 1528 Python exception to be raised. For example, if the :class:`DivisionByZero` trap 1529 is set, then a :exc:`DivisionByZero` exception is raised upon encountering the 1530 condition. 1531 1532 1533 .. class:: Clamped 1534 1535 Altered an exponent to fit representation constraints. 1536 1537 Typically, clamping occurs when an exponent falls outside the context's 1538 :attr:`Emin` and :attr:`Emax` limits. If possible, the exponent is reduced to 1539 fit by adding zeros to the coefficient. 1540 1541 1542 .. class:: DecimalException 1543 1544 Base class for other signals and a subclass of :exc:`ArithmeticError`. 1545 1546 1547 .. class:: DivisionByZero 1548 1549 Signals the division of a non-infinite number by zero. 1550 1551 Can occur with division, modulo division, or when raising a number to a negative 1552 power. If this signal is not trapped, returns :const:`Infinity` or 1553 :const:`-Infinity` with the sign determined by the inputs to the calculation. 1554 1555 1556 .. class:: Inexact 1557 1558 Indicates that rounding occurred and the result is not exact. 1559 1560 Signals when non-zero digits were discarded during rounding. The rounded result 1561 is returned. The signal flag or trap is used to detect when results are 1562 inexact. 1563 1564 1565 .. class:: InvalidOperation 1566 1567 An invalid operation was performed. 1568 1569 Indicates that an operation was requested that does not make sense. If not 1570 trapped, returns :const:`NaN`. Possible causes include:: 1571 1572 Infinity - Infinity 1573 0 * Infinity 1574 Infinity / Infinity 1575 x % 0 1576 Infinity % x 1577 sqrt(-x) and x > 0 1578 0 ** 0 1579 x ** (non-integer) 1580 x ** Infinity 1581 1582 1583 .. class:: Overflow 1584 1585 Numerical overflow. 1586 1587 Indicates the exponent is larger than :attr:`Emax` after rounding has 1588 occurred. If not trapped, the result depends on the rounding mode, either 1589 pulling inward to the largest representable finite number or rounding outward 1590 to :const:`Infinity`. In either case, :class:`Inexact` and :class:`Rounded` 1591 are also signaled. 1592 1593 1594 .. class:: Rounded 1595 1596 Rounding occurred though possibly no information was lost. 1597 1598 Signaled whenever rounding discards digits; even if those digits are zero 1599 (such as rounding :const:`5.00` to :const:`5.0`). If not trapped, returns 1600 the result unchanged. This signal is used to detect loss of significant 1601 digits. 1602 1603 1604 .. class:: Subnormal 1605 1606 Exponent was lower than :attr:`Emin` prior to rounding. 1607 1608 Occurs when an operation result is subnormal (the exponent is too small). If 1609 not trapped, returns the result unchanged. 1610 1611 1612 .. class:: Underflow 1613 1614 Numerical underflow with result rounded to zero. 1615 1616 Occurs when a subnormal result is pushed to zero by rounding. :class:`Inexact` 1617 and :class:`Subnormal` are also signaled. 1618 1619 1620 .. class:: FloatOperation 1621 1622 Enable stricter semantics for mixing floats and Decimals. 1623 1624 If the signal is not trapped (default), mixing floats and Decimals is 1625 permitted in the :class:`~decimal.Decimal` constructor, 1626 :meth:`~decimal.Context.create_decimal` and all comparison operators. 1627 Both conversion and comparisons are exact. Any occurrence of a mixed 1628 operation is silently recorded by setting :exc:`FloatOperation` in the 1629 context flags. Explicit conversions with :meth:`~decimal.Decimal.from_float` 1630 or :meth:`~decimal.Context.create_decimal_from_float` do not set the flag. 1631 1632 Otherwise (the signal is trapped), only equality comparisons and explicit 1633 conversions are silent. All other mixed operations raise :exc:`FloatOperation`. 1634 1635 1636 The following table summarizes the hierarchy of signals:: 1637 1638 exceptions.ArithmeticError(exceptions.Exception) 1639 DecimalException 1640 Clamped 1641 DivisionByZero(DecimalException, exceptions.ZeroDivisionError) 1642 Inexact 1643 Overflow(Inexact, Rounded) 1644 Underflow(Inexact, Rounded, Subnormal) 1645 InvalidOperation 1646 Rounded 1647 Subnormal 1648 FloatOperation(DecimalException, exceptions.TypeError) 1649 1650 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1651 1652 1653 1654 .. _decimal-notes: 1655 1656 Floating Point Notes 1657 -------------------- 1658 1659 1660 Mitigating round-off error with increased precision 1661 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1662 1663 The use of decimal floating point eliminates decimal representation error 1664 (making it possible to represent :const:`0.1` exactly); however, some operations 1665 can still incur round-off error when non-zero digits exceed the fixed precision. 1666 1667 The effects of round-off error can be amplified by the addition or subtraction 1668 of nearly offsetting quantities resulting in loss of significance. Knuth 1669 provides two instructive examples where rounded floating point arithmetic with 1670 insufficient precision causes the breakdown of the associative and distributive 1671 properties of addition: 1672 1673 .. doctest:: newcontext 1674 1675 # Examples from Seminumerical Algorithms, Section 4.2.2. 1676 >>> from decimal import Decimal, getcontext 1677 >>> getcontext().prec = 8 1678 1679 >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111') 1680 >>> (u + v) + w 1681 Decimal('9.5111111') 1682 >>> u + (v + w) 1683 Decimal('10') 1684 1685 >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003') 1686 >>> (u*v) + (u*w) 1687 Decimal('0.01') 1688 >>> u * (v+w) 1689 Decimal('0.0060000') 1690 1691 The :mod:`decimal` module makes it possible to restore the identities by 1692 expanding the precision sufficiently to avoid loss of significance: 1693 1694 .. doctest:: newcontext 1695 1696 >>> getcontext().prec = 20 1697 >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111') 1698 >>> (u + v) + w 1699 Decimal('9.51111111') 1700 >>> u + (v + w) 1701 Decimal('9.51111111') 1702 >>> 1703 >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003') 1704 >>> (u*v) + (u*w) 1705 Decimal('0.0060000') 1706 >>> u * (v+w) 1707 Decimal('0.0060000') 1708 1709 1710 Special values 1711 ^^^^^^^^^^^^^^ 1712 1713 The number system for the :mod:`decimal` module provides special values 1714 including :const:`NaN`, :const:`sNaN`, :const:`-Infinity`, :const:`Infinity`, 1715 and two zeros, :const:`+0` and :const:`-0`. 1716 1717 Infinities can be constructed directly with: ``Decimal('Infinity')``. Also, 1718 they can arise from dividing by zero when the :exc:`DivisionByZero` signal is 1719 not trapped. Likewise, when the :exc:`Overflow` signal is not trapped, infinity 1720 can result from rounding beyond the limits of the largest representable number. 1721 1722 The infinities are signed (affine) and can be used in arithmetic operations 1723 where they get treated as very large, indeterminate numbers. For instance, 1724 adding a constant to infinity gives another infinite result. 1725 1726 Some operations are indeterminate and return :const:`NaN`, or if the 1727 :exc:`InvalidOperation` signal is trapped, raise an exception. For example, 1728 ``0/0`` returns :const:`NaN` which means "not a number". This variety of 1729 :const:`NaN` is quiet and, once created, will flow through other computations 1730 always resulting in another :const:`NaN`. This behavior can be useful for a 1731 series of computations that occasionally have missing inputs --- it allows the 1732 calculation to proceed while flagging specific results as invalid. 1733 1734 A variant is :const:`sNaN` which signals rather than remaining quiet after every 1735 operation. This is a useful return value when an invalid result needs to 1736 interrupt a calculation for special handling. 1737 1738 The behavior of Python's comparison operators can be a little surprising where a 1739 :const:`NaN` is involved. A test for equality where one of the operands is a 1740 quiet or signaling :const:`NaN` always returns :const:`False` (even when doing 1741 ``Decimal('NaN')==Decimal('NaN')``), while a test for inequality always returns 1742 :const:`True`. An attempt to compare two Decimals using any of the ``<``, 1743 ``<=``, ``>`` or ``>=`` operators will raise the :exc:`InvalidOperation` signal 1744 if either operand is a :const:`NaN`, and return :const:`False` if this signal is 1745 not trapped. Note that the General Decimal Arithmetic specification does not 1746 specify the behavior of direct comparisons; these rules for comparisons 1747 involving a :const:`NaN` were taken from the IEEE 854 standard (see Table 3 in 1748 section 5.7). To ensure strict standards-compliance, use the :meth:`compare` 1749 and :meth:`compare-signal` methods instead. 1750 1751 The signed zeros can result from calculations that underflow. They keep the sign 1752 that would have resulted if the calculation had been carried out to greater 1753 precision. Since their magnitude is zero, both positive and negative zeros are 1754 treated as equal and their sign is informational. 1755 1756 In addition to the two signed zeros which are distinct yet equal, there are 1757 various representations of zero with differing precisions yet equivalent in 1758 value. This takes a bit of getting used to. For an eye accustomed to 1759 normalized floating point representations, it is not immediately obvious that 1760 the following calculation returns a value equal to zero: 1761 1762 >>> 1 / Decimal('Infinity') 1763 Decimal('0E-1000026') 1764 1765 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1766 1767 1768 .. _decimal-threads: 1769 1770 Working with threads 1771 -------------------- 1772 1773 The :func:`getcontext` function accesses a different :class:`Context` object for 1774 each thread. Having separate thread contexts means that threads may make 1775 changes (such as ``getcontext().prec=10``) without interfering with other threads. 1776 1777 Likewise, the :func:`setcontext` function automatically assigns its target to 1778 the current thread. 1779 1780 If :func:`setcontext` has not been called before :func:`getcontext`, then 1781 :func:`getcontext` will automatically create a new context for use in the 1782 current thread. 1783 1784 The new context is copied from a prototype context called *DefaultContext*. To 1785 control the defaults so that each thread will use the same values throughout the 1786 application, directly modify the *DefaultContext* object. This should be done 1787 *before* any threads are started so that there won't be a race condition between 1788 threads calling :func:`getcontext`. For example:: 1789 1790 # Set applicationwide defaults for all threads about to be launched 1791 DefaultContext.prec = 12 1792 DefaultContext.rounding = ROUND_DOWN 1793 DefaultContext.traps = ExtendedContext.traps.copy() 1794 DefaultContext.traps[InvalidOperation] = 1 1795 setcontext(DefaultContext) 1796 1797 # Afterwards, the threads can be started 1798 t1.start() 1799 t2.start() 1800 t3.start() 1801 . . . 1802 1803 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1804 1805 1806 .. _decimal-recipes: 1807 1808 Recipes 1809 ------- 1810 1811 Here are a few recipes that serve as utility functions and that demonstrate ways 1812 to work with the :class:`Decimal` class:: 1813 1814 def moneyfmt(value, places=2, curr='', sep=',', dp='.', 1815 pos='', neg='-', trailneg=''): 1816 """Convert Decimal to a money formatted string. 1817 1818 places: required number of places after the decimal point 1819 curr: optional currency symbol before the sign (may be blank) 1820 sep: optional grouping separator (comma, period, space, or blank) 1821 dp: decimal point indicator (comma or period) 1822 only specify as blank when places is zero 1823 pos: optional sign for positive numbers: '+', space or blank 1824 neg: optional sign for negative numbers: '-', '(', space or blank 1825 trailneg:optional trailing minus indicator: '-', ')', space or blank 1826 1827 >>> d = Decimal('-1234567.8901') 1828 >>> moneyfmt(d, curr='$') 1829 '-$1,234,567.89' 1830 >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-') 1831 '1.234.568-' 1832 >>> moneyfmt(d, curr='$', neg='(', trailneg=')') 1833 '($1,234,567.89)' 1834 >>> moneyfmt(Decimal(123456789), sep=' ') 1835 '123 456 789.00' 1836 >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>') 1837 '<0.02>' 1838 1839 """ 1840 q = Decimal(10) ** -places # 2 places --> '0.01' 1841 sign, digits, exp = value.quantize(q).as_tuple() 1842 result = [] 1843 digits = list(map(str, digits)) 1844 build, next = result.append, digits.pop 1845 if sign: 1846 build(trailneg) 1847 for i in range(places): 1848 build(next() if digits else '0') 1849 if places: 1850 build(dp) 1851 if not digits: 1852 build('0') 1853 i = 0 1854 while digits: 1855 build(next()) 1856 i += 1 1857 if i == 3 and digits: 1858 i = 0 1859 build(sep) 1860 build(curr) 1861 build(neg if sign else pos) 1862 return ''.join(reversed(result)) 1863 1864 def pi(): 1865 """Compute Pi to the current precision. 1866 1867 >>> print(pi()) 1868 3.141592653589793238462643383 1869 1870 """ 1871 getcontext().prec += 2 # extra digits for intermediate steps 1872 three = Decimal(3) # substitute "three=3.0" for regular floats 1873 lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24 1874 while s != lasts: 1875 lasts = s 1876 n, na = n+na, na+8 1877 d, da = d+da, da+32 1878 t = (t * n) / d 1879 s += t 1880 getcontext().prec -= 2 1881 return +s # unary plus applies the new precision 1882 1883 def exp(x): 1884 """Return e raised to the power of x. Result type matches input type. 1885 1886 >>> print(exp(Decimal(1))) 1887 2.718281828459045235360287471 1888 >>> print(exp(Decimal(2))) 1889 7.389056098930650227230427461 1890 >>> print(exp(2.0)) 1891 7.38905609893 1892 >>> print(exp(2+0j)) 1893 (7.38905609893+0j) 1894 1895 """ 1896 getcontext().prec += 2 1897 i, lasts, s, fact, num = 0, 0, 1, 1, 1 1898 while s != lasts: 1899 lasts = s 1900 i += 1 1901 fact *= i 1902 num *= x 1903 s += num / fact 1904 getcontext().prec -= 2 1905 return +s 1906 1907 def cos(x): 1908 """Return the cosine of x as measured in radians. 1909 1910 The Taylor series approximation works best for a small value of x. 1911 For larger values, first compute x = x % (2 * pi). 1912 1913 >>> print(cos(Decimal('0.5'))) 1914 0.8775825618903727161162815826 1915 >>> print(cos(0.5)) 1916 0.87758256189 1917 >>> print(cos(0.5+0j)) 1918 (0.87758256189+0j) 1919 1920 """ 1921 getcontext().prec += 2 1922 i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1 1923 while s != lasts: 1924 lasts = s 1925 i += 2 1926 fact *= i * (i-1) 1927 num *= x * x 1928 sign *= -1 1929 s += num / fact * sign 1930 getcontext().prec -= 2 1931 return +s 1932 1933 def sin(x): 1934 """Return the sine of x as measured in radians. 1935 1936 The Taylor series approximation works best for a small value of x. 1937 For larger values, first compute x = x % (2 * pi). 1938 1939 >>> print(sin(Decimal('0.5'))) 1940 0.4794255386042030002732879352 1941 >>> print(sin(0.5)) 1942 0.479425538604 1943 >>> print(sin(0.5+0j)) 1944 (0.479425538604+0j) 1945 1946 """ 1947 getcontext().prec += 2 1948 i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1 1949 while s != lasts: 1950 lasts = s 1951 i += 2 1952 fact *= i * (i-1) 1953 num *= x * x 1954 sign *= -1 1955 s += num / fact * sign 1956 getcontext().prec -= 2 1957 return +s 1958 1959 1960 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1961 1962 1963 .. _decimal-faq: 1964 1965 Decimal FAQ 1966 ----------- 1967 1968 Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to 1969 minimize typing when using the interactive interpreter? 1970 1971 A. Some users abbreviate the constructor to just a single letter: 1972 1973 >>> D = decimal.Decimal 1974 >>> D('1.23') + D('3.45') 1975 Decimal('4.68') 1976 1977 Q. In a fixed-point application with two decimal places, some inputs have many 1978 places and need to be rounded. Others are not supposed to have excess digits 1979 and need to be validated. What methods should be used? 1980 1981 A. The :meth:`quantize` method rounds to a fixed number of decimal places. If 1982 the :const:`Inexact` trap is set, it is also useful for validation: 1983 1984 >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01') 1985 1986 >>> # Round to two places 1987 >>> Decimal('3.214').quantize(TWOPLACES) 1988 Decimal('3.21') 1989 1990 >>> # Validate that a number does not exceed two places 1991 >>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact])) 1992 Decimal('3.21') 1993 1994 >>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact])) 1995 Traceback (most recent call last): 1996 ... 1997 Inexact: None 1998 1999 Q. Once I have valid two place inputs, how do I maintain that invariant 2000 throughout an application? 2001 2002 A. Some operations like addition, subtraction, and multiplication by an integer 2003 will automatically preserve fixed point. Others operations, like division and 2004 non-integer multiplication, will change the number of decimal places and need to 2005 be followed-up with a :meth:`quantize` step: 2006 2007 >>> a = Decimal('102.72') # Initial fixed-point values 2008 >>> b = Decimal('3.17') 2009 >>> a + b # Addition preserves fixed-point 2010 Decimal('105.89') 2011 >>> a - b 2012 Decimal('99.55') 2013 >>> a * 42 # So does integer multiplication 2014 Decimal('4314.24') 2015 >>> (a * b).quantize(TWOPLACES) # Must quantize non-integer multiplication 2016 Decimal('325.62') 2017 >>> (b / a).quantize(TWOPLACES) # And quantize division 2018 Decimal('0.03') 2019 2020 In developing fixed-point applications, it is convenient to define functions 2021 to handle the :meth:`quantize` step: 2022 2023 >>> def mul(x, y, fp=TWOPLACES): 2024 ... return (x * y).quantize(fp) 2025 >>> def div(x, y, fp=TWOPLACES): 2026 ... return (x / y).quantize(fp) 2027 2028 >>> mul(a, b) # Automatically preserve fixed-point 2029 Decimal('325.62') 2030 >>> div(b, a) 2031 Decimal('0.03') 2032 2033 Q. There are many ways to express the same value. The numbers :const:`200`, 2034 :const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at 2035 various precisions. Is there a way to transform them to a single recognizable 2036 canonical value? 2037 2038 A. The :meth:`normalize` method maps all equivalent values to a single 2039 representative: 2040 2041 >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split()) 2042 >>> [v.normalize() for v in values] 2043 [Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')] 2044 2045 Q. Some decimal values always print with exponential notation. Is there a way 2046 to get a non-exponential representation? 2047 2048 A. For some values, exponential notation is the only way to express the number 2049 of significant places in the coefficient. For example, expressing 2050 :const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the 2051 original's two-place significance. 2052 2053 If an application does not care about tracking significance, it is easy to 2054 remove the exponent and trailing zeroes, losing significance, but keeping the 2055 value unchanged: 2056 2057 >>> def remove_exponent(d): 2058 ... return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize() 2059 2060 >>> remove_exponent(Decimal('5E+3')) 2061 Decimal('5000') 2062 2063 Q. Is there a way to convert a regular float to a :class:`Decimal`? 2064 2065 A. Yes, any binary floating point number can be exactly expressed as a 2066 Decimal though an exact conversion may take more precision than intuition would 2067 suggest: 2068 2069 .. doctest:: 2070 2071 >>> Decimal(math.pi) 2072 Decimal('3.141592653589793115997963468544185161590576171875') 2073 2074 Q. Within a complex calculation, how can I make sure that I haven't gotten a 2075 spurious result because of insufficient precision or rounding anomalies. 2076 2077 A. The decimal module makes it easy to test results. A best practice is to 2078 re-run calculations using greater precision and with various rounding modes. 2079 Widely differing results indicate insufficient precision, rounding mode issues, 2080 ill-conditioned inputs, or a numerically unstable algorithm. 2081 2082 Q. I noticed that context precision is applied to the results of operations but 2083 not to the inputs. Is there anything to watch out for when mixing values of 2084 different precisions? 2085 2086 A. Yes. The principle is that all values are considered to be exact and so is 2087 the arithmetic on those values. Only the results are rounded. The advantage 2088 for inputs is that "what you type is what you get". A disadvantage is that the 2089 results can look odd if you forget that the inputs haven't been rounded: 2090 2091 .. doctest:: newcontext 2092 2093 >>> getcontext().prec = 3 2094 >>> Decimal('3.104') + Decimal('2.104') 2095 Decimal('5.21') 2096 >>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104') 2097 Decimal('5.20') 2098 2099 The solution is either to increase precision or to force rounding of inputs 2100 using the unary plus operation: 2101 2102 .. doctest:: newcontext 2103 2104 >>> getcontext().prec = 3 2105 >>> +Decimal('1.23456789') # unary plus triggers rounding 2106 Decimal('1.23') 2107 2108 Alternatively, inputs can be rounded upon creation using the 2109 :meth:`Context.create_decimal` method: 2110 2111 >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678') 2112 Decimal('1.2345') 2113