1 # Copyright (c) 2004 Python Software Foundation.
4 # Written by Eric Price <eprice at tjhsst.edu>
5 # and Facundo Batista <facundo at taniquetil.com.ar>
6 # and Raymond Hettinger <python at rcn.com>
7 # and Aahz <aahz at pobox.com>
10 # This module should be kept in sync with the latest updates of the
11 # IBM specification as it evolves. Those updates will be treated
12 # as bug fixes (deviation from the spec is a compatibility, usability
13 # bug) and will be backported. At this point the spec is stabilizing
14 # and the updates are becoming fewer, smaller, and less significant.
17 This is an implementation of decimal floating point arithmetic based on
18 the General Decimal Arithmetic Specification:
20 http://speleotrove.com/decimal/decarith.html
22 and IEEE standard 854-1987:
24 www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html
26 Decimal floating point has finite precision with arbitrarily large bounds.
28 The purpose of this module is to support arithmetic using familiar
29 "schoolhouse" rules and to avoid some of the tricky representation
30 issues associated with binary floating point. The package is especially
31 useful for financial applications or for contexts where users have
32 expectations that are at odds with binary floating point (for instance,
33 in binary floating point, 1.00 % 0.1 gives 0.09999999999999995 instead
34 of the expected Decimal('0.00') returned by decimal floating point).
36 Here are some examples of using the decimal module:
38 >>> from decimal import *
39 >>> setcontext(ExtendedContext)
48 >>> Decimal('123.45e12345678901234567890')
49 Decimal('1.2345E+12345678901234567892')
50 >>> Decimal('1.33') + Decimal('1.27')
52 >>> Decimal('12.34') + Decimal('3.87') - Decimal('18.41')
55 >>> print(dig / Decimal(3))
57 >>> getcontext().prec = 18
58 >>> print(dig / Decimal(3))
62 >>> print(Decimal(3).sqrt())
64 >>> print(Decimal(3) ** 123)
65 4.85192780976896427E+58
66 >>> inf = Decimal(1) / Decimal(0)
69 >>> neginf = Decimal(-1) / Decimal(0)
72 >>> print(neginf + inf)
74 >>> print(neginf * inf)
78 >>> getcontext().traps[DivisionByZero] = 1
80 Traceback (most recent call last):
84 decimal.DivisionByZero: x / 0
86 >>> c.traps[InvalidOperation] = 0
87 >>> print(c.flags[InvalidOperation])
89 >>> c.divide(Decimal(0), Decimal(0))
91 >>> c.traps[InvalidOperation] = 1
92 >>> print(c.flags[InvalidOperation])
94 >>> c.flags[InvalidOperation] = 0
95 >>> print(c.flags[InvalidOperation])
97 >>> print(c.divide(Decimal(0), Decimal(0)))
98 Traceback (most recent call last):
102 decimal.InvalidOperation: 0 / 0
103 >>> print(c.flags[InvalidOperation])
105 >>> c.flags[InvalidOperation] = 0
106 >>> c.traps[InvalidOperation] = 0
107 >>> print(c.divide(Decimal(0), Decimal(0)))
109 >>> print(c.flags[InvalidOperation])
116 'Decimal', 'Context',
119 'DefaultContext', 'BasicContext', 'ExtendedContext',
122 'DecimalException', 'Clamped', 'InvalidOperation', 'DivisionByZero',
123 'Inexact', 'Rounded', 'Subnormal', 'Overflow', 'Underflow',
125 # Constants for use in setting up contexts
126 'ROUND_DOWN', 'ROUND_HALF_UP', 'ROUND_HALF_EVEN', 'ROUND_CEILING',
127 'ROUND_FLOOR', 'ROUND_UP', 'ROUND_HALF_DOWN', 'ROUND_05UP',
129 # Functions for manipulating contexts
130 'setcontext', 'getcontext', 'localcontext'
133 __version__
= '1.70' # Highest version of the spec this complies with
137 import numbers
as _numbers
140 from collections
import namedtuple
as _namedtuple
141 DecimalTuple
= _namedtuple('DecimalTuple', 'sign digits exponent')
143 DecimalTuple
= lambda *args
: args
146 ROUND_DOWN
= 'ROUND_DOWN'
147 ROUND_HALF_UP
= 'ROUND_HALF_UP'
148 ROUND_HALF_EVEN
= 'ROUND_HALF_EVEN'
149 ROUND_CEILING
= 'ROUND_CEILING'
150 ROUND_FLOOR
= 'ROUND_FLOOR'
151 ROUND_UP
= 'ROUND_UP'
152 ROUND_HALF_DOWN
= 'ROUND_HALF_DOWN'
153 ROUND_05UP
= 'ROUND_05UP'
157 class DecimalException(ArithmeticError):
158 """Base exception class.
160 Used exceptions derive from this.
161 If an exception derives from another exception besides this (such as
162 Underflow (Inexact, Rounded, Subnormal) that indicates that it is only
163 called if the others are present. This isn't actually used for
166 handle -- Called when context._raise_error is called and the
167 trap_enabler is set. First argument is self, second is the
168 context. More arguments can be given, those being after
169 the explanation in _raise_error (For example,
170 context._raise_error(NewError, '(-x)!', self._sign) would
171 call NewError().handle(context, self._sign).)
173 To define a new exception, it should be sufficient to have it derive
174 from DecimalException.
176 def handle(self
, context
, *args
):
180 class Clamped(DecimalException
):
181 """Exponent of a 0 changed to fit bounds.
183 This occurs and signals clamped if the exponent of a result has been
184 altered in order to fit the constraints of a specific concrete
185 representation. This may occur when the exponent of a zero result would
186 be outside the bounds of a representation, or when a large normal
187 number would have an encoded exponent that cannot be represented. In
188 this latter case, the exponent is reduced to fit and the corresponding
189 number of zero digits are appended to the coefficient ("fold-down").
192 class InvalidOperation(DecimalException
):
193 """An invalid operation was performed.
195 Various bad things cause this:
197 Something creates a signaling NaN
203 x._rescale( non-integer )
208 An operand is invalid
210 The result of the operation after these is a quiet positive NaN,
211 except when the cause is a signaling NaN, in which case the result is
212 also a quiet NaN, but with the original sign, and an optional
213 diagnostic information.
215 def handle(self
, context
, *args
):
217 ans
= _dec_from_triple(args
[0]._sign
, args
[0]._int
, 'n', True)
218 return ans
._fix
_nan
(context
)
221 class ConversionSyntax(InvalidOperation
):
222 """Trying to convert badly formed string.
224 This occurs and signals invalid-operation if an string is being
225 converted to a number and it does not conform to the numeric string
226 syntax. The result is [0,qNaN].
228 def handle(self
, context
, *args
):
231 class DivisionByZero(DecimalException
, ZeroDivisionError):
234 This occurs and signals division-by-zero if division of a finite number
235 by zero was attempted (during a divide-integer or divide operation, or a
236 power operation with negative right-hand operand), and the dividend was
239 The result of the operation is [sign,inf], where sign is the exclusive
240 or of the signs of the operands for divide, or is 1 for an odd power of
244 def handle(self
, context
, sign
, *args
):
245 return _SignedInfinity
[sign
]
247 class DivisionImpossible(InvalidOperation
):
248 """Cannot perform the division adequately.
250 This occurs and signals invalid-operation if the integer result of a
251 divide-integer or remainder operation had too many digits (would be
252 longer than precision). The result is [0,qNaN].
255 def handle(self
, context
, *args
):
258 class DivisionUndefined(InvalidOperation
, ZeroDivisionError):
259 """Undefined result of division.
261 This occurs and signals invalid-operation if division by zero was
262 attempted (during a divide-integer, divide, or remainder operation), and
263 the dividend is also zero. The result is [0,qNaN].
266 def handle(self
, context
, *args
):
269 class Inexact(DecimalException
):
270 """Had to round, losing information.
272 This occurs and signals inexact whenever the result of an operation is
273 not exact (that is, it needed to be rounded and any discarded digits
274 were non-zero), or if an overflow or underflow condition occurs. The
275 result in all cases is unchanged.
277 The inexact signal may be tested (or trapped) to determine if a given
278 operation (or sequence of operations) was inexact.
281 class InvalidContext(InvalidOperation
):
282 """Invalid context. Unknown rounding, for example.
284 This occurs and signals invalid-operation if an invalid context was
285 detected during an operation. This can occur if contexts are not checked
286 on creation and either the precision exceeds the capability of the
287 underlying concrete representation or an unknown or unsupported rounding
288 was specified. These aspects of the context need only be checked when
289 the values are required to be used. The result is [0,qNaN].
292 def handle(self
, context
, *args
):
295 class Rounded(DecimalException
):
296 """Number got rounded (not necessarily changed during rounding).
298 This occurs and signals rounded whenever the result of an operation is
299 rounded (that is, some zero or non-zero digits were discarded from the
300 coefficient), or if an overflow or underflow condition occurs. The
301 result in all cases is unchanged.
303 The rounded signal may be tested (or trapped) to determine if a given
304 operation (or sequence of operations) caused a loss of precision.
307 class Subnormal(DecimalException
):
308 """Exponent < Emin before rounding.
310 This occurs and signals subnormal whenever the result of a conversion or
311 operation is subnormal (that is, its adjusted exponent is less than
312 Emin, before any rounding). The result in all cases is unchanged.
314 The subnormal signal may be tested (or trapped) to determine if a given
315 or operation (or sequence of operations) yielded a subnormal result.
318 class Overflow(Inexact
, Rounded
):
319 """Numerical overflow.
321 This occurs and signals overflow if the adjusted exponent of a result
322 (from a conversion or from an operation that is not an attempt to divide
323 by zero), after rounding, would be greater than the largest value that
324 can be handled by the implementation (the value Emax).
326 The result depends on the rounding mode:
328 For round-half-up and round-half-even (and for round-half-down and
329 round-up, if implemented), the result of the operation is [sign,inf],
330 where sign is the sign of the intermediate result. For round-down, the
331 result is the largest finite number that can be represented in the
332 current precision, with the sign of the intermediate result. For
333 round-ceiling, the result is the same as for round-down if the sign of
334 the intermediate result is 1, or is [0,inf] otherwise. For round-floor,
335 the result is the same as for round-down if the sign of the intermediate
336 result is 0, or is [1,inf] otherwise. In all cases, Inexact and Rounded
340 def handle(self
, context
, sign
, *args
):
341 if context
.rounding
in (ROUND_HALF_UP
, ROUND_HALF_EVEN
,
342 ROUND_HALF_DOWN
, ROUND_UP
):
343 return _SignedInfinity
[sign
]
345 if context
.rounding
== ROUND_CEILING
:
346 return _SignedInfinity
[sign
]
347 return _dec_from_triple(sign
, '9'*context
.prec
,
348 context
.Emax
-context
.prec
+1)
350 if context
.rounding
== ROUND_FLOOR
:
351 return _SignedInfinity
[sign
]
352 return _dec_from_triple(sign
, '9'*context
.prec
,
353 context
.Emax
-context
.prec
+1)
356 class Underflow(Inexact
, Rounded
, Subnormal
):
357 """Numerical underflow with result rounded to 0.
359 This occurs and signals underflow if a result is inexact and the
360 adjusted exponent of the result would be smaller (more negative) than
361 the smallest value that can be handled by the implementation (the value
362 Emin). That is, the result is both inexact and subnormal.
364 The result after an underflow will be a subnormal number rounded, if
365 necessary, so that its exponent is not less than Etiny. This may result
366 in 0 with the sign of the intermediate result and an exponent of Etiny.
368 In all cases, Inexact, Rounded, and Subnormal will also be raised.
371 # List of public traps and flags
372 _signals
= [Clamped
, DivisionByZero
, Inexact
, Overflow
, Rounded
,
373 Underflow
, InvalidOperation
, Subnormal
]
375 # Map conditions (per the spec) to signals
376 _condition_map
= {ConversionSyntax
:InvalidOperation
,
377 DivisionImpossible
:InvalidOperation
,
378 DivisionUndefined
:InvalidOperation
,
379 InvalidContext
:InvalidOperation
}
381 ##### Context Functions ##################################################
383 # The getcontext() and setcontext() function manage access to a thread-local
384 # current context. Py2.4 offers direct support for thread locals. If that
385 # is not available, use threading.current_thread() which is slower but will
386 # work for older Pythons. If threads are not part of the build, create a
387 # mock threading object with threading.local() returning the module namespace.
392 # Python was compiled without threads; create a mock object instead
394 class MockThreading(object):
395 def local(self
, sys
=sys
):
396 return sys
.modules
[__name__
]
397 threading
= MockThreading()
398 del sys
, MockThreading
403 except AttributeError:
405 # To fix reloading, force it to create a new context
406 # Old contexts have different exceptions in their dicts, making problems.
407 if hasattr(threading
.current_thread(), '__decimal_context__'):
408 del threading
.current_thread().__decimal
_context
__
410 def setcontext(context
):
411 """Set this thread's context to context."""
412 if context
in (DefaultContext
, BasicContext
, ExtendedContext
):
413 context
= context
.copy()
414 context
.clear_flags()
415 threading
.current_thread().__decimal
_context
__ = context
418 """Returns this thread's context.
420 If this thread does not yet have a context, returns
421 a new context and sets this thread's context.
422 New contexts are copies of DefaultContext.
425 return threading
.current_thread().__decimal
_context
__
426 except AttributeError:
428 threading
.current_thread().__decimal
_context
__ = context
433 local
= threading
.local()
434 if hasattr(local
, '__decimal_context__'):
435 del local
.__decimal
_context
__
437 def getcontext(_local
=local
):
438 """Returns this thread's context.
440 If this thread does not yet have a context, returns
441 a new context and sets this thread's context.
442 New contexts are copies of DefaultContext.
445 return _local
.__decimal
_context
__
446 except AttributeError:
448 _local
.__decimal
_context
__ = context
451 def setcontext(context
, _local
=local
):
452 """Set this thread's context to context."""
453 if context
in (DefaultContext
, BasicContext
, ExtendedContext
):
454 context
= context
.copy()
455 context
.clear_flags()
456 _local
.__decimal
_context
__ = context
458 del threading
, local
# Don't contaminate the namespace
460 def localcontext(ctx
=None):
461 """Return a context manager for a copy of the supplied context
463 Uses a copy of the current context if no context is specified
464 The returned context manager creates a local decimal context
467 with localcontext() as ctx:
469 # Rest of sin calculation algorithm
470 # uses a precision 2 greater than normal
471 return +s # Convert result to normal precision
474 with localcontext(ExtendedContext):
475 # Rest of sin calculation algorithm
476 # uses the Extended Context from the
477 # General Decimal Arithmetic Specification
478 return +s # Convert result to normal context
480 >>> setcontext(DefaultContext)
481 >>> print(getcontext().prec)
483 >>> with localcontext():
484 ... ctx = getcontext()
489 >>> with localcontext(ExtendedContext):
490 ... print(getcontext().prec)
493 >>> print(getcontext().prec)
496 if ctx
is None: ctx
= getcontext()
497 return _ContextManager(ctx
)
500 ##### Decimal class #######################################################
502 # Do not subclass Decimal from numbers.Real and do not register it as such
503 # (because Decimals are not interoperable with floats). See the notes in
504 # numbers.py for more detail.
506 class Decimal(object):
507 """Floating point class for decimal arithmetic."""
509 __slots__
= ('_exp','_int','_sign', '_is_special')
510 # Generally, the value of the Decimal instance is given by
511 # (-1)**_sign * _int * 10**_exp
512 # Special values are signified by _is_special == True
514 # We're immutable, so use __new__ not __init__
515 def __new__(cls
, value
="0", context
=None):
516 """Create a decimal point instance.
518 >>> Decimal('3.14') # string input
520 >>> Decimal((0, (3, 1, 4), -2)) # tuple (sign, digit_tuple, exponent)
522 >>> Decimal(314) # int
524 >>> Decimal(Decimal(314)) # another decimal instance
526 >>> Decimal(' 3.14 \\n') # leading and trailing whitespace okay
530 # Note that the coefficient, self._int, is actually stored as
531 # a string rather than as a tuple of digits. This speeds up
532 # the "digits to integer" and "integer to digits" conversions
533 # that are used in almost every arithmetic operation on
534 # Decimals. This is an internal detail: the as_tuple function
535 # and the Decimal constructor still deal with tuples of
538 self
= object.__new
__(cls
)
541 # REs insist on real strings, so we can too.
542 if isinstance(value
, str):
543 m
= _parser(value
.strip())
546 context
= getcontext()
547 return context
._raise
_error
(ConversionSyntax
,
548 "Invalid literal for Decimal: %r" % value
)
550 if m
.group('sign') == "-":
554 intpart
= m
.group('int')
555 if intpart
is not None:
557 fracpart
= m
.group('frac') or ''
558 exp
= int(m
.group('exp') or '0')
559 self
._int
= str(int(intpart
+fracpart
))
560 self
._exp
= exp
- len(fracpart
)
561 self
._is
_special
= False
563 diag
= m
.group('diag')
566 self
._int
= str(int(diag
or '0')).lstrip('0')
567 if m
.group('signal'):
575 self
._is
_special
= True
579 if isinstance(value
, int):
585 self
._int
= str(abs(value
))
586 self
._is
_special
= False
589 # From another decimal
590 if isinstance(value
, Decimal
):
591 self
._exp
= value
._exp
592 self
._sign
= value
._sign
593 self
._int
= value
._int
594 self
._is
_special
= value
._is
_special
597 # From an internal working value
598 if isinstance(value
, _WorkRep
):
599 self
._sign
= value
.sign
600 self
._int
= str(value
.int)
601 self
._exp
= int(value
.exp
)
602 self
._is
_special
= False
605 # tuple/list conversion (possibly from as_tuple())
606 if isinstance(value
, (list,tuple)):
608 raise ValueError('Invalid tuple size in creation of Decimal '
609 'from list or tuple. The list or tuple '
610 'should have exactly three elements.')
611 # process sign. The isinstance test rejects floats
612 if not (isinstance(value
[0], int) and value
[0] in (0,1)):
613 raise ValueError("Invalid sign. The first value in the tuple "
614 "should be an integer; either 0 for a "
615 "positive number or 1 for a negative number.")
616 self
._sign
= value
[0]
618 # infinity: value[1] is ignored
621 self
._is
_special
= True
623 # process and validate the digits in value[1]
625 for digit
in value
[1]:
626 if isinstance(digit
, int) and 0 <= digit
<= 9:
628 if digits
or digit
!= 0:
631 raise ValueError("The second value in the tuple must "
632 "be composed of integers in the range "
634 if value
[2] in ('n', 'N'):
635 # NaN: digits form the diagnostic
636 self
._int
= ''.join(map(str, digits
))
638 self
._is
_special
= True
639 elif isinstance(value
[2], int):
640 # finite number: digits give the coefficient
641 self
._int
= ''.join(map(str, digits
or [0]))
643 self
._is
_special
= False
645 raise ValueError("The third value in the tuple must "
646 "be an integer, or one of the "
647 "strings 'F', 'n', 'N'.")
650 if isinstance(value
, float):
651 raise TypeError("Cannot convert float in Decimal constructor. "
652 "Use from_float class method.")
654 raise TypeError("Cannot convert %r to Decimal" % value
)
656 # @classmethod, but @decorator is not valid Python 2.3 syntax, so
657 # don't use it (see notes on Py2.3 compatibility at top of file)
658 def from_float(cls
, f
):
659 """Converts a float to a decimal number, exactly.
661 Note that Decimal.from_float(0.1) is not the same as Decimal('0.1').
662 Since 0.1 is not exactly representable in binary floating point, the
663 value is stored as the nearest representable value which is
664 0x1.999999999999ap-4. The exact equivalent of the value in decimal
665 is 0.1000000000000000055511151231257827021181583404541015625.
667 >>> Decimal.from_float(0.1)
668 Decimal('0.1000000000000000055511151231257827021181583404541015625')
669 >>> Decimal.from_float(float('nan'))
671 >>> Decimal.from_float(float('inf'))
673 >>> Decimal.from_float(-float('inf'))
675 >>> Decimal.from_float(-0.0)
679 if isinstance(f
, int): # handle integer inputs
681 if _math
.isinf(f
) or _math
.isnan(f
): # raises TypeError if not a float
683 if _math
.copysign(1.0, f
) == 1.0:
687 n
, d
= abs(f
).as_integer_ratio()
688 k
= d
.bit_length() - 1
689 result
= _dec_from_triple(sign
, str(n
*5**k
), -k
)
694 from_float
= classmethod(from_float
)
697 """Returns whether the number is not actually one.
711 def _isinfinity(self
):
712 """Returns whether the number is infinite
714 0 if finite or not a number
724 def _check_nans(self
, other
=None, context
=None):
725 """Returns whether the number is not actually one.
727 if self, other are sNaN, signal
728 if self, other are NaN return nan
731 Done before operations.
734 self_is_nan
= self
._isnan
()
738 other_is_nan
= other
._isnan
()
740 if self_is_nan
or other_is_nan
:
742 context
= getcontext()
745 return context
._raise
_error
(InvalidOperation
, 'sNaN',
747 if other_is_nan
== 2:
748 return context
._raise
_error
(InvalidOperation
, 'sNaN',
751 return self
._fix
_nan
(context
)
753 return other
._fix
_nan
(context
)
756 def _compare_check_nans(self
, other
, context
):
757 """Version of _check_nans used for the signaling comparisons
758 compare_signal, __le__, __lt__, __ge__, __gt__.
760 Signal InvalidOperation if either self or other is a (quiet
761 or signaling) NaN. Signaling NaNs take precedence over quiet
764 Return 0 if neither operand is a NaN.
768 context
= getcontext()
770 if self
._is
_special
or other
._is
_special
:
772 return context
._raise
_error
(InvalidOperation
,
773 'comparison involving sNaN',
775 elif other
.is_snan():
776 return context
._raise
_error
(InvalidOperation
,
777 'comparison involving sNaN',
780 return context
._raise
_error
(InvalidOperation
,
781 'comparison involving NaN',
783 elif other
.is_qnan():
784 return context
._raise
_error
(InvalidOperation
,
785 'comparison involving NaN',
790 """Return True if self is nonzero; otherwise return False.
792 NaNs and infinities are considered nonzero.
794 return self
._is
_special
or self
._int
!= '0'
796 def _cmp(self
, other
):
797 """Compare the two non-NaN decimal instances self and other.
799 Returns -1 if self < other, 0 if self == other and 1
800 if self > other. This routine is for internal use only."""
802 if self
._is
_special
or other
._is
_special
:
803 self_inf
= self
._isinfinity
()
804 other_inf
= other
._isinfinity
()
805 if self_inf
== other_inf
:
807 elif self_inf
< other_inf
:
812 # check for zeros; Decimal('0') == Decimal('-0')
817 return -((-1)**other
._sign
)
819 return (-1)**self
._sign
821 # If different signs, neg one is less
822 if other
._sign
< self
._sign
:
824 if self
._sign
< other
._sign
:
827 self_adjusted
= self
.adjusted()
828 other_adjusted
= other
.adjusted()
829 if self_adjusted
== other_adjusted
:
830 self_padded
= self
._int
+ '0'*(self
._exp
- other
._exp
)
831 other_padded
= other
._int
+ '0'*(other
._exp
- self
._exp
)
832 if self_padded
== other_padded
:
834 elif self_padded
< other_padded
:
835 return -(-1)**self
._sign
837 return (-1)**self
._sign
838 elif self_adjusted
> other_adjusted
:
839 return (-1)**self
._sign
840 else: # self_adjusted < other_adjusted
841 return -((-1)**self
._sign
)
843 # Note: The Decimal standard doesn't cover rich comparisons for
844 # Decimals. In particular, the specification is silent on the
845 # subject of what should happen for a comparison involving a NaN.
846 # We take the following approach:
848 # == comparisons involving a NaN always return False
849 # != comparisons involving a NaN always return True
850 # <, >, <= and >= comparisons involving a (quiet or signaling)
851 # NaN signal InvalidOperation, and return False if the
852 # InvalidOperation is not trapped.
854 # This behavior is designed to conform as closely as possible to
855 # that specified by IEEE 754.
857 def __eq__(self
, other
):
858 other
= _convert_other(other
)
859 if other
is NotImplemented:
861 if self
.is_nan() or other
.is_nan():
863 return self
._cmp
(other
) == 0
865 def __ne__(self
, other
):
866 other
= _convert_other(other
)
867 if other
is NotImplemented:
869 if self
.is_nan() or other
.is_nan():
871 return self
._cmp
(other
) != 0
874 def __lt__(self
, other
, context
=None):
875 other
= _convert_other(other
)
876 if other
is NotImplemented:
878 ans
= self
._compare
_check
_nans
(other
, context
)
881 return self
._cmp
(other
) < 0
883 def __le__(self
, other
, context
=None):
884 other
= _convert_other(other
)
885 if other
is NotImplemented:
887 ans
= self
._compare
_check
_nans
(other
, context
)
890 return self
._cmp
(other
) <= 0
892 def __gt__(self
, other
, context
=None):
893 other
= _convert_other(other
)
894 if other
is NotImplemented:
896 ans
= self
._compare
_check
_nans
(other
, context
)
899 return self
._cmp
(other
) > 0
901 def __ge__(self
, other
, context
=None):
902 other
= _convert_other(other
)
903 if other
is NotImplemented:
905 ans
= self
._compare
_check
_nans
(other
, context
)
908 return self
._cmp
(other
) >= 0
910 def compare(self
, other
, context
=None):
911 """Compares one to another.
917 Like __cmp__, but returns Decimal instances.
919 other
= _convert_other(other
, raiseit
=True)
921 # Compare(NaN, NaN) = NaN
922 if (self
._is
_special
or other
and other
._is
_special
):
923 ans
= self
._check
_nans
(other
, context
)
927 return Decimal(self
._cmp
(other
))
930 """x.__hash__() <==> hash(x)"""
931 # Decimal integers must hash the same as the ints
933 # The hash of a nonspecial noninteger Decimal must depend only
934 # on the value of that Decimal, and not on its representation.
935 # For example: hash(Decimal('100E-1')) == hash(Decimal('10')).
938 raise TypeError('Cannot hash a NaN value.')
939 return hash(str(self
))
942 if self
._isinteger
():
943 op
= _WorkRep(self
.to_integral_value())
944 # to make computation feasible for Decimals with large
945 # exponent, we use the fact that hash(n) == hash(m) for
946 # any two nonzero integers n and m such that (i) n and m
947 # have the same sign, and (ii) n is congruent to m modulo
948 # 2**64-1. So we can replace hash((-1)**s*c*10**e) with
949 # hash((-1)**s*c*pow(10, e, 2**64-1).
950 return hash((-1)**op
.sign
*op
.int*pow(10, op
.exp
, 2**64-1))
951 # The value of a nonzero nonspecial Decimal instance is
952 # faithfully represented by the triple consisting of its sign,
953 # its adjusted exponent, and its coefficient with trailing
955 return hash((self
._sign
,
956 self
._exp
+len(self
._int
),
957 self
._int
.rstrip('0')))
960 """Represents the number as a triple tuple.
962 To show the internals exactly as they are.
964 return DecimalTuple(self
._sign
, tuple(map(int, self
._int
)), self
._exp
)
967 """Represents the number as an instance of Decimal."""
968 # Invariant: eval(repr(d)) == d
969 return "Decimal('%s')" % str(self
)
971 def __str__(self
, eng
=False, context
=None):
972 """Return string representation of the number in scientific notation.
974 Captures all of the information in the underlying representation.
977 sign
= ['', '-'][self
._sign
]
980 return sign
+ 'Infinity'
981 elif self
._exp
== 'n':
982 return sign
+ 'NaN' + self
._int
983 else: # self._exp == 'N'
984 return sign
+ 'sNaN' + self
._int
986 # number of digits of self._int to left of decimal point
987 leftdigits
= self
._exp
+ len(self
._int
)
989 # dotplace is number of digits of self._int to the left of the
990 # decimal point in the mantissa of the output string (that is,
991 # after adjusting the exponent)
992 if self
._exp
<= 0 and leftdigits
> -6:
993 # no exponent required
994 dotplace
= leftdigits
996 # usual scientific notation: 1 digit on left of the point
998 elif self
._int
== '0':
999 # engineering notation, zero
1000 dotplace
= (leftdigits
+ 1) % 3 - 1
1002 # engineering notation, nonzero
1003 dotplace
= (leftdigits
- 1) % 3 + 1
1007 fracpart
= '.' + '0'*(-dotplace
) + self
._int
1008 elif dotplace
>= len(self
._int
):
1009 intpart
= self
._int
+'0'*(dotplace
-len(self
._int
))
1012 intpart
= self
._int
[:dotplace
]
1013 fracpart
= '.' + self
._int
[dotplace
:]
1014 if leftdigits
== dotplace
:
1018 context
= getcontext()
1019 exp
= ['e', 'E'][context
.capitals
] + "%+d" % (leftdigits
-dotplace
)
1021 return sign
+ intpart
+ fracpart
+ exp
1023 def to_eng_string(self
, context
=None):
1024 """Convert to engineering-type string.
1026 Engineering notation has an exponent which is a multiple of 3, so there
1027 are up to 3 digits left of the decimal place.
1029 Same rules for when in exponential and when as a value as in __str__.
1031 return self
.__str
__(eng
=True, context
=context
)
1033 def __neg__(self
, context
=None):
1034 """Returns a copy with the sign switched.
1036 Rounds, if it has reason.
1038 if self
._is
_special
:
1039 ans
= self
._check
_nans
(context
=context
)
1044 # -Decimal('0') is Decimal('0'), not Decimal('-0')
1045 ans
= self
.copy_abs()
1047 ans
= self
.copy_negate()
1050 context
= getcontext()
1051 return ans
._fix
(context
)
1053 def __pos__(self
, context
=None):
1054 """Returns a copy, unless it is a sNaN.
1056 Rounds the number (if more then precision digits)
1058 if self
._is
_special
:
1059 ans
= self
._check
_nans
(context
=context
)
1065 ans
= self
.copy_abs()
1070 context
= getcontext()
1071 return ans
._fix
(context
)
1073 def __abs__(self
, round=True, context
=None):
1074 """Returns the absolute value of self.
1076 If the keyword argument 'round' is false, do not round. The
1077 expression self.__abs__(round=False) is equivalent to
1081 return self
.copy_abs()
1083 if self
._is
_special
:
1084 ans
= self
._check
_nans
(context
=context
)
1089 ans
= self
.__neg
__(context
=context
)
1091 ans
= self
.__pos
__(context
=context
)
1095 def __add__(self
, other
, context
=None):
1096 """Returns self + other.
1098 -INF + INF (or the reverse) cause InvalidOperation errors.
1100 other
= _convert_other(other
)
1101 if other
is NotImplemented:
1105 context
= getcontext()
1107 if self
._is
_special
or other
._is
_special
:
1108 ans
= self
._check
_nans
(other
, context
)
1112 if self
._isinfinity
():
1113 # If both INF, same sign => same as both, opposite => error.
1114 if self
._sign
!= other
._sign
and other
._isinfinity
():
1115 return context
._raise
_error
(InvalidOperation
, '-INF + INF')
1116 return Decimal(self
)
1117 if other
._isinfinity
():
1118 return Decimal(other
) # Can't both be infinity here
1120 exp
= min(self
._exp
, other
._exp
)
1122 if context
.rounding
== ROUND_FLOOR
and self
._sign
!= other
._sign
:
1123 # If the answer is 0, the sign should be negative, in this case.
1126 if not self
and not other
:
1127 sign
= min(self
._sign
, other
._sign
)
1130 ans
= _dec_from_triple(sign
, '0', exp
)
1131 ans
= ans
._fix
(context
)
1134 exp
= max(exp
, other
._exp
- context
.prec
-1)
1135 ans
= other
._rescale
(exp
, context
.rounding
)
1136 ans
= ans
._fix
(context
)
1139 exp
= max(exp
, self
._exp
- context
.prec
-1)
1140 ans
= self
._rescale
(exp
, context
.rounding
)
1141 ans
= ans
._fix
(context
)
1144 op1
= _WorkRep(self
)
1145 op2
= _WorkRep(other
)
1146 op1
, op2
= _normalize(op1
, op2
, context
.prec
)
1149 if op1
.sign
!= op2
.sign
:
1150 # Equal and opposite
1151 if op1
.int == op2
.int:
1152 ans
= _dec_from_triple(negativezero
, '0', exp
)
1153 ans
= ans
._fix
(context
)
1155 if op1
.int < op2
.int:
1157 # OK, now abs(op1) > abs(op2)
1160 op1
.sign
, op2
.sign
= op2
.sign
, op1
.sign
1163 # So we know the sign, and op1 > 0.
1166 op1
.sign
, op2
.sign
= (0, 0)
1169 # Now, op1 > abs(op2) > 0
1172 result
.int = op1
.int + op2
.int
1174 result
.int = op1
.int - op2
.int
1176 result
.exp
= op1
.exp
1177 ans
= Decimal(result
)
1178 ans
= ans
._fix
(context
)
1183 def __sub__(self
, other
, context
=None):
1184 """Return self - other"""
1185 other
= _convert_other(other
)
1186 if other
is NotImplemented:
1189 if self
._is
_special
or other
._is
_special
:
1190 ans
= self
._check
_nans
(other
, context
=context
)
1194 # self - other is computed as self + other.copy_negate()
1195 return self
.__add
__(other
.copy_negate(), context
=context
)
1197 def __rsub__(self
, other
, context
=None):
1198 """Return other - self"""
1199 other
= _convert_other(other
)
1200 if other
is NotImplemented:
1203 return other
.__sub
__(self
, context
=context
)
1205 def __mul__(self
, other
, context
=None):
1206 """Return self * other.
1208 (+-) INF * 0 (or its reverse) raise InvalidOperation.
1210 other
= _convert_other(other
)
1211 if other
is NotImplemented:
1215 context
= getcontext()
1217 resultsign
= self
._sign ^ other
._sign
1219 if self
._is
_special
or other
._is
_special
:
1220 ans
= self
._check
_nans
(other
, context
)
1224 if self
._isinfinity
():
1226 return context
._raise
_error
(InvalidOperation
, '(+-)INF * 0')
1227 return _SignedInfinity
[resultsign
]
1229 if other
._isinfinity
():
1231 return context
._raise
_error
(InvalidOperation
, '0 * (+-)INF')
1232 return _SignedInfinity
[resultsign
]
1234 resultexp
= self
._exp
+ other
._exp
1236 # Special case for multiplying by zero
1237 if not self
or not other
:
1238 ans
= _dec_from_triple(resultsign
, '0', resultexp
)
1239 # Fixing in case the exponent is out of bounds
1240 ans
= ans
._fix
(context
)
1243 # Special case for multiplying by power of 10
1244 if self
._int
== '1':
1245 ans
= _dec_from_triple(resultsign
, other
._int
, resultexp
)
1246 ans
= ans
._fix
(context
)
1248 if other
._int
== '1':
1249 ans
= _dec_from_triple(resultsign
, self
._int
, resultexp
)
1250 ans
= ans
._fix
(context
)
1253 op1
= _WorkRep(self
)
1254 op2
= _WorkRep(other
)
1256 ans
= _dec_from_triple(resultsign
, str(op1
.int * op2
.int), resultexp
)
1257 ans
= ans
._fix
(context
)
1262 def __truediv__(self
, other
, context
=None):
1263 """Return self / other."""
1264 other
= _convert_other(other
)
1265 if other
is NotImplemented:
1266 return NotImplemented
1269 context
= getcontext()
1271 sign
= self
._sign ^ other
._sign
1273 if self
._is
_special
or other
._is
_special
:
1274 ans
= self
._check
_nans
(other
, context
)
1278 if self
._isinfinity
() and other
._isinfinity
():
1279 return context
._raise
_error
(InvalidOperation
, '(+-)INF/(+-)INF')
1281 if self
._isinfinity
():
1282 return _SignedInfinity
[sign
]
1284 if other
._isinfinity
():
1285 context
._raise
_error
(Clamped
, 'Division by infinity')
1286 return _dec_from_triple(sign
, '0', context
.Etiny())
1288 # Special cases for zeroes
1291 return context
._raise
_error
(DivisionUndefined
, '0 / 0')
1292 return context
._raise
_error
(DivisionByZero
, 'x / 0', sign
)
1295 exp
= self
._exp
- other
._exp
1298 # OK, so neither = 0, INF or NaN
1299 shift
= len(other
._int
) - len(self
._int
) + context
.prec
+ 1
1300 exp
= self
._exp
- other
._exp
- shift
1301 op1
= _WorkRep(self
)
1302 op2
= _WorkRep(other
)
1304 coeff
, remainder
= divmod(op1
.int * 10**shift
, op2
.int)
1306 coeff
, remainder
= divmod(op1
.int, op2
.int * 10**-shift
)
1308 # result is not exact; adjust to ensure correct rounding
1312 # result is exact; get as close to ideal exponent as possible
1313 ideal_exp
= self
._exp
- other
._exp
1314 while exp
< ideal_exp
and coeff
% 10 == 0:
1318 ans
= _dec_from_triple(sign
, str(coeff
), exp
)
1319 return ans
._fix
(context
)
1321 def _divide(self
, other
, context
):
1322 """Return (self // other, self % other), to context.prec precision.
1324 Assumes that neither self nor other is a NaN, that self is not
1325 infinite and that other is nonzero.
1327 sign
= self
._sign ^ other
._sign
1328 if other
._isinfinity
():
1329 ideal_exp
= self
._exp
1331 ideal_exp
= min(self
._exp
, other
._exp
)
1333 expdiff
= self
.adjusted() - other
.adjusted()
1334 if not self
or other
._isinfinity
() or expdiff
<= -2:
1335 return (_dec_from_triple(sign
, '0', 0),
1336 self
._rescale
(ideal_exp
, context
.rounding
))
1337 if expdiff
<= context
.prec
:
1338 op1
= _WorkRep(self
)
1339 op2
= _WorkRep(other
)
1340 if op1
.exp
>= op2
.exp
:
1341 op1
.int *= 10**(op1
.exp
- op2
.exp
)
1343 op2
.int *= 10**(op2
.exp
- op1
.exp
)
1344 q
, r
= divmod(op1
.int, op2
.int)
1345 if q
< 10**context
.prec
:
1346 return (_dec_from_triple(sign
, str(q
), 0),
1347 _dec_from_triple(self
._sign
, str(r
), ideal_exp
))
1349 # Here the quotient is too large to be representable
1350 ans
= context
._raise
_error
(DivisionImpossible
,
1351 'quotient too large in //, % or divmod')
1354 def __rtruediv__(self
, other
, context
=None):
1355 """Swaps self/other and returns __truediv__."""
1356 other
= _convert_other(other
)
1357 if other
is NotImplemented:
1359 return other
.__truediv
__(self
, context
=context
)
1361 def __divmod__(self
, other
, context
=None):
1363 Return (self // other, self % other)
1365 other
= _convert_other(other
)
1366 if other
is NotImplemented:
1370 context
= getcontext()
1372 ans
= self
._check
_nans
(other
, context
)
1376 sign
= self
._sign ^ other
._sign
1377 if self
._isinfinity
():
1378 if other
._isinfinity
():
1379 ans
= context
._raise
_error
(InvalidOperation
, 'divmod(INF, INF)')
1382 return (_SignedInfinity
[sign
],
1383 context
._raise
_error
(InvalidOperation
, 'INF % x'))
1387 ans
= context
._raise
_error
(DivisionUndefined
, 'divmod(0, 0)')
1390 return (context
._raise
_error
(DivisionByZero
, 'x // 0', sign
),
1391 context
._raise
_error
(InvalidOperation
, 'x % 0'))
1393 quotient
, remainder
= self
._divide
(other
, context
)
1394 remainder
= remainder
._fix
(context
)
1395 return quotient
, remainder
1397 def __rdivmod__(self
, other
, context
=None):
1398 """Swaps self/other and returns __divmod__."""
1399 other
= _convert_other(other
)
1400 if other
is NotImplemented:
1402 return other
.__divmod
__(self
, context
=context
)
1404 def __mod__(self
, other
, context
=None):
1408 other
= _convert_other(other
)
1409 if other
is NotImplemented:
1413 context
= getcontext()
1415 ans
= self
._check
_nans
(other
, context
)
1419 if self
._isinfinity
():
1420 return context
._raise
_error
(InvalidOperation
, 'INF % x')
1423 return context
._raise
_error
(InvalidOperation
, 'x % 0')
1425 return context
._raise
_error
(DivisionUndefined
, '0 % 0')
1427 remainder
= self
._divide
(other
, context
)[1]
1428 remainder
= remainder
._fix
(context
)
1431 def __rmod__(self
, other
, context
=None):
1432 """Swaps self/other and returns __mod__."""
1433 other
= _convert_other(other
)
1434 if other
is NotImplemented:
1436 return other
.__mod
__(self
, context
=context
)
1438 def remainder_near(self
, other
, context
=None):
1440 Remainder nearest to 0- abs(remainder-near) <= other/2
1443 context
= getcontext()
1445 other
= _convert_other(other
, raiseit
=True)
1447 ans
= self
._check
_nans
(other
, context
)
1451 # self == +/-infinity -> InvalidOperation
1452 if self
._isinfinity
():
1453 return context
._raise
_error
(InvalidOperation
,
1454 'remainder_near(infinity, x)')
1456 # other == 0 -> either InvalidOperation or DivisionUndefined
1459 return context
._raise
_error
(InvalidOperation
,
1460 'remainder_near(x, 0)')
1462 return context
._raise
_error
(DivisionUndefined
,
1463 'remainder_near(0, 0)')
1465 # other = +/-infinity -> remainder = self
1466 if other
._isinfinity
():
1468 return ans
._fix
(context
)
1470 # self = 0 -> remainder = self, with ideal exponent
1471 ideal_exponent
= min(self
._exp
, other
._exp
)
1473 ans
= _dec_from_triple(self
._sign
, '0', ideal_exponent
)
1474 return ans
._fix
(context
)
1476 # catch most cases of large or small quotient
1477 expdiff
= self
.adjusted() - other
.adjusted()
1478 if expdiff
>= context
.prec
+ 1:
1479 # expdiff >= prec+1 => abs(self/other) > 10**prec
1480 return context
._raise
_error
(DivisionImpossible
)
1482 # expdiff <= -2 => abs(self/other) < 0.1
1483 ans
= self
._rescale
(ideal_exponent
, context
.rounding
)
1484 return ans
._fix
(context
)
1486 # adjust both arguments to have the same exponent, then divide
1487 op1
= _WorkRep(self
)
1488 op2
= _WorkRep(other
)
1489 if op1
.exp
>= op2
.exp
:
1490 op1
.int *= 10**(op1
.exp
- op2
.exp
)
1492 op2
.int *= 10**(op2
.exp
- op1
.exp
)
1493 q
, r
= divmod(op1
.int, op2
.int)
1494 # remainder is r*10**ideal_exponent; other is +/-op2.int *
1495 # 10**ideal_exponent. Apply correction to ensure that
1496 # abs(remainder) <= abs(other)/2
1497 if 2*r
+ (q
&1) > op2
.int:
1501 if q
>= 10**context
.prec
:
1502 return context
._raise
_error
(DivisionImpossible
)
1504 # result has same sign as self unless r is negative
1510 ans
= _dec_from_triple(sign
, str(r
), ideal_exponent
)
1511 return ans
._fix
(context
)
1513 def __floordiv__(self
, other
, context
=None):
1515 other
= _convert_other(other
)
1516 if other
is NotImplemented:
1520 context
= getcontext()
1522 ans
= self
._check
_nans
(other
, context
)
1526 if self
._isinfinity
():
1527 if other
._isinfinity
():
1528 return context
._raise
_error
(InvalidOperation
, 'INF // INF')
1530 return _SignedInfinity
[self
._sign ^ other
._sign
]
1534 return context
._raise
_error
(DivisionByZero
, 'x // 0',
1535 self
._sign ^ other
._sign
)
1537 return context
._raise
_error
(DivisionUndefined
, '0 // 0')
1539 return self
._divide
(other
, context
)[0]
1541 def __rfloordiv__(self
, other
, context
=None):
1542 """Swaps self/other and returns __floordiv__."""
1543 other
= _convert_other(other
)
1544 if other
is NotImplemented:
1546 return other
.__floordiv
__(self
, context
=context
)
1548 def __float__(self
):
1549 """Float representation."""
1550 return float(str(self
))
1553 """Converts self to an int, truncating if necessary."""
1554 if self
._is
_special
:
1556 raise ValueError("Cannot convert NaN to integer")
1557 elif self
._isinfinity
():
1558 raise OverflowError("Cannot convert infinity to integer")
1559 s
= (-1)**self
._sign
1561 return s
*int(self
._int
)*10**self
._exp
1563 return s
*int(self
._int
[:self
._exp
] or '0')
1569 real
= property(real
)
1573 imag
= property(imag
)
1575 def conjugate(self
):
1578 def __complex__(self
):
1579 return complex(float(self
))
1581 def _fix_nan(self
, context
):
1582 """Decapitate the payload of a NaN to fit the context"""
1585 # maximum length of payload is precision if _clamp=0,
1586 # precision-1 if _clamp=1.
1587 max_payload_len
= context
.prec
- context
._clamp
1588 if len(payload
) > max_payload_len
:
1589 payload
= payload
[len(payload
)-max_payload_len
:].lstrip('0')
1590 return _dec_from_triple(self
._sign
, payload
, self
._exp
, True)
1591 return Decimal(self
)
1593 def _fix(self
, context
):
1594 """Round if it is necessary to keep self within prec precision.
1596 Rounds and fixes the exponent. Does not raise on a sNaN.
1599 self - Decimal instance
1600 context - context used.
1603 if self
._is
_special
:
1605 # decapitate payload if necessary
1606 return self
._fix
_nan
(context
)
1608 # self is +/-Infinity; return unaltered
1609 return Decimal(self
)
1611 # if self is zero then exponent should be between Etiny and
1612 # Emax if _clamp==0, and between Etiny and Etop if _clamp==1.
1613 Etiny
= context
.Etiny()
1614 Etop
= context
.Etop()
1616 exp_max
= [context
.Emax
, Etop
][context
._clamp
]
1617 new_exp
= min(max(self
._exp
, Etiny
), exp_max
)
1618 if new_exp
!= self
._exp
:
1619 context
._raise
_error
(Clamped
)
1620 return _dec_from_triple(self
._sign
, '0', new_exp
)
1622 return Decimal(self
)
1624 # exp_min is the smallest allowable exponent of the result,
1625 # equal to max(self.adjusted()-context.prec+1, Etiny)
1626 exp_min
= len(self
._int
) + self
._exp
- context
.prec
1628 # overflow: exp_min > Etop iff self.adjusted() > Emax
1629 context
._raise
_error
(Inexact
)
1630 context
._raise
_error
(Rounded
)
1631 return context
._raise
_error
(Overflow
, 'above Emax', self
._sign
)
1632 self_is_subnormal
= exp_min
< Etiny
1633 if self_is_subnormal
:
1634 context
._raise
_error
(Subnormal
)
1637 # round if self has too many digits
1638 if self
._exp
< exp_min
:
1639 context
._raise
_error
(Rounded
)
1640 digits
= len(self
._int
) + self
._exp
- exp_min
1642 self
= _dec_from_triple(self
._sign
, '1', exp_min
-1)
1644 this_function
= getattr(self
, self
._pick
_rounding
_function
[context
.rounding
])
1645 changed
= this_function(digits
)
1646 coeff
= self
._int
[:digits
] or '0'
1648 coeff
= str(int(coeff
)+1)
1649 ans
= _dec_from_triple(self
._sign
, coeff
, exp_min
)
1652 context
._raise
_error
(Inexact
)
1653 if self_is_subnormal
:
1654 context
._raise
_error
(Underflow
)
1656 # raise Clamped on underflow to 0
1657 context
._raise
_error
(Clamped
)
1658 elif len(ans
._int
) == context
.prec
+1:
1659 # we get here only if rescaling rounds the
1660 # cofficient up to exactly 10**context.prec
1662 ans
= _dec_from_triple(ans
._sign
,
1663 ans
._int
[:-1], ans
._exp
+1)
1665 # Inexact and Rounded have already been raised
1666 ans
= context
._raise
_error
(Overflow
, 'above Emax',
1670 # fold down if _clamp == 1 and self has too few digits
1671 if context
._clamp
== 1 and self
._exp
> Etop
:
1672 context
._raise
_error
(Clamped
)
1673 self_padded
= self
._int
+ '0'*(self
._exp
- Etop
)
1674 return _dec_from_triple(self
._sign
, self_padded
, Etop
)
1676 # here self was representable to begin with; return unchanged
1677 return Decimal(self
)
1679 _pick_rounding_function
= {}
1681 # for each of the rounding functions below:
1682 # self is a finite, nonzero Decimal
1683 # prec is an integer satisfying 0 <= prec < len(self._int)
1685 # each function returns either -1, 0, or 1, as follows:
1686 # 1 indicates that self should be rounded up (away from zero)
1687 # 0 indicates that self should be truncated, and that all the
1688 # digits to be truncated are zeros (so the value is unchanged)
1689 # -1 indicates that there are nonzero digits to be truncated
1691 def _round_down(self
, prec
):
1692 """Also known as round-towards-0, truncate."""
1693 if _all_zeros(self
._int
, prec
):
1698 def _round_up(self
, prec
):
1699 """Rounds away from 0."""
1700 return -self
._round
_down
(prec
)
1702 def _round_half_up(self
, prec
):
1703 """Rounds 5 up (away from 0)"""
1704 if self
._int
[prec
] in '56789':
1706 elif _all_zeros(self
._int
, prec
):
1711 def _round_half_down(self
, prec
):
1713 if _exact_half(self
._int
, prec
):
1716 return self
._round
_half
_up
(prec
)
1718 def _round_half_even(self
, prec
):
1719 """Round 5 to even, rest to nearest."""
1720 if _exact_half(self
._int
, prec
) and \
1721 (prec
== 0 or self
._int
[prec
-1] in '02468'):
1724 return self
._round
_half
_up
(prec
)
1726 def _round_ceiling(self
, prec
):
1727 """Rounds up (not away from 0 if negative.)"""
1729 return self
._round
_down
(prec
)
1731 return -self
._round
_down
(prec
)
1733 def _round_floor(self
, prec
):
1734 """Rounds down (not towards 0 if negative)"""
1736 return self
._round
_down
(prec
)
1738 return -self
._round
_down
(prec
)
1740 def _round_05up(self
, prec
):
1741 """Round down unless digit prec-1 is 0 or 5."""
1742 if prec
and self
._int
[prec
-1] not in '05':
1743 return self
._round
_down
(prec
)
1745 return -self
._round
_down
(prec
)
1747 def __round__(self
, n
=None):
1748 """Round self to the nearest integer, or to a given precision.
1750 If only one argument is supplied, round a finite Decimal
1751 instance self to the nearest integer. If self is infinite or
1752 a NaN then a Python exception is raised. If self is finite
1753 and lies exactly halfway between two integers then it is
1754 rounded to the integer with even last digit.
1756 >>> round(Decimal('123.456'))
1758 >>> round(Decimal('-456.789'))
1760 >>> round(Decimal('-3.0'))
1762 >>> round(Decimal('2.5'))
1764 >>> round(Decimal('3.5'))
1766 >>> round(Decimal('Inf'))
1767 Traceback (most recent call last):
1769 OverflowError: cannot round an infinity
1770 >>> round(Decimal('NaN'))
1771 Traceback (most recent call last):
1773 ValueError: cannot round a NaN
1775 If a second argument n is supplied, self is rounded to n
1776 decimal places using the rounding mode for the current
1779 For an integer n, round(self, -n) is exactly equivalent to
1780 self.quantize(Decimal('1En')).
1782 >>> round(Decimal('123.456'), 0)
1784 >>> round(Decimal('123.456'), 2)
1786 >>> round(Decimal('123.456'), -2)
1788 >>> round(Decimal('-Infinity'), 37)
1790 >>> round(Decimal('sNaN123'), 0)
1795 # two-argument form: use the equivalent quantize call
1796 if not isinstance(n
, int):
1797 raise TypeError('Second argument to round should be integral')
1798 exp
= _dec_from_triple(0, '1', -n
)
1799 return self
.quantize(exp
)
1802 if self
._is
_special
:
1804 raise ValueError("cannot round a NaN")
1806 raise OverflowError("cannot round an infinity")
1807 return int(self
._rescale
(0, ROUND_HALF_EVEN
))
1809 def __floor__(self
):
1810 """Return the floor of self, as an integer.
1812 For a finite Decimal instance self, return the greatest
1813 integer n such that n <= self. If self is infinite or a NaN
1814 then a Python exception is raised.
1817 if self
._is
_special
:
1819 raise ValueError("cannot round a NaN")
1821 raise OverflowError("cannot round an infinity")
1822 return int(self
._rescale
(0, ROUND_FLOOR
))
1825 """Return the ceiling of self, as an integer.
1827 For a finite Decimal instance self, return the least integer n
1828 such that n >= self. If self is infinite or a NaN then a
1829 Python exception is raised.
1832 if self
._is
_special
:
1834 raise ValueError("cannot round a NaN")
1836 raise OverflowError("cannot round an infinity")
1837 return int(self
._rescale
(0, ROUND_CEILING
))
1839 def fma(self
, other
, third
, context
=None):
1840 """Fused multiply-add.
1842 Returns self*other+third with no rounding of the intermediate
1845 self and other are multiplied together, with no rounding of
1846 the result. The third operand is then added to the result,
1847 and a single final rounding is performed.
1850 other
= _convert_other(other
, raiseit
=True)
1852 # compute product; raise InvalidOperation if either operand is
1853 # a signaling NaN or if the product is zero times infinity.
1854 if self
._is
_special
or other
._is
_special
:
1856 context
= getcontext()
1857 if self
._exp
== 'N':
1858 return context
._raise
_error
(InvalidOperation
, 'sNaN', self
)
1859 if other
._exp
== 'N':
1860 return context
._raise
_error
(InvalidOperation
, 'sNaN', other
)
1861 if self
._exp
== 'n':
1863 elif other
._exp
== 'n':
1865 elif self
._exp
== 'F':
1867 return context
._raise
_error
(InvalidOperation
,
1869 product
= _SignedInfinity
[self
._sign ^ other
._sign
]
1870 elif other
._exp
== 'F':
1872 return context
._raise
_error
(InvalidOperation
,
1874 product
= _SignedInfinity
[self
._sign ^ other
._sign
]
1876 product
= _dec_from_triple(self
._sign ^ other
._sign
,
1877 str(int(self
._int
) * int(other
._int
)),
1878 self
._exp
+ other
._exp
)
1880 third
= _convert_other(third
, raiseit
=True)
1881 return product
.__add
__(third
, context
)
1883 def _power_modulo(self
, other
, modulo
, context
=None):
1884 """Three argument version of __pow__"""
1886 # if can't convert other and modulo to Decimal, raise
1887 # TypeError; there's no point returning NotImplemented (no
1888 # equivalent of __rpow__ for three argument pow)
1889 other
= _convert_other(other
, raiseit
=True)
1890 modulo
= _convert_other(modulo
, raiseit
=True)
1893 context
= getcontext()
1895 # deal with NaNs: if there are any sNaNs then first one wins,
1896 # (i.e. behaviour for NaNs is identical to that of fma)
1897 self_is_nan
= self
._isnan
()
1898 other_is_nan
= other
._isnan
()
1899 modulo_is_nan
= modulo
._isnan
()
1900 if self_is_nan
or other_is_nan
or modulo_is_nan
:
1901 if self_is_nan
== 2:
1902 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1904 if other_is_nan
== 2:
1905 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1907 if modulo_is_nan
== 2:
1908 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1911 return self
._fix
_nan
(context
)
1913 return other
._fix
_nan
(context
)
1914 return modulo
._fix
_nan
(context
)
1916 # check inputs: we apply same restrictions as Python's pow()
1917 if not (self
._isinteger
() and
1918 other
._isinteger
() and
1919 modulo
._isinteger
()):
1920 return context
._raise
_error
(InvalidOperation
,
1921 'pow() 3rd argument not allowed '
1922 'unless all arguments are integers')
1924 return context
._raise
_error
(InvalidOperation
,
1925 'pow() 2nd argument cannot be '
1926 'negative when 3rd argument specified')
1928 return context
._raise
_error
(InvalidOperation
,
1929 'pow() 3rd argument cannot be 0')
1931 # additional restriction for decimal: the modulus must be less
1932 # than 10**prec in absolute value
1933 if modulo
.adjusted() >= context
.prec
:
1934 return context
._raise
_error
(InvalidOperation
,
1935 'insufficient precision: pow() 3rd '
1936 'argument must not have more than '
1939 # define 0**0 == NaN, for consistency with two-argument pow
1940 # (even though it hurts!)
1941 if not other
and not self
:
1942 return context
._raise
_error
(InvalidOperation
,
1943 'at least one of pow() 1st argument '
1944 'and 2nd argument must be nonzero ;'
1945 '0**0 is not defined')
1947 # compute sign of result
1953 # convert modulo to a Python integer, and self and other to
1954 # Decimal integers (i.e. force their exponents to be >= 0)
1955 modulo
= abs(int(modulo
))
1956 base
= _WorkRep(self
.to_integral_value())
1957 exponent
= _WorkRep(other
.to_integral_value())
1959 # compute result using integer pow()
1960 base
= (base
.int % modulo
* pow(10, base
.exp
, modulo
)) % modulo
1961 for i
in range(exponent
.exp
):
1962 base
= pow(base
, 10, modulo
)
1963 base
= pow(base
, exponent
.int, modulo
)
1965 return _dec_from_triple(sign
, str(base
), 0)
1967 def _power_exact(self
, other
, p
):
1968 """Attempt to compute self**other exactly.
1970 Given Decimals self and other and an integer p, attempt to
1971 compute an exact result for the power self**other, with p
1972 digits of precision. Return None if self**other is not
1973 exactly representable in p digits.
1975 Assumes that elimination of special cases has already been
1976 performed: self and other must both be nonspecial; self must
1977 be positive and not numerically equal to 1; other must be
1978 nonzero. For efficiency, other._exp should not be too large,
1979 so that 10**abs(other._exp) is a feasible calculation."""
1981 # In the comments below, we write x for the value of self and
1982 # y for the value of other. Write x = xc*10**xe and y =
1985 # The main purpose of this method is to identify the *failure*
1986 # of x**y to be exactly representable with as little effort as
1987 # possible. So we look for cheap and easy tests that
1988 # eliminate the possibility of x**y being exact. Only if all
1989 # these tests are passed do we go on to actually compute x**y.
1991 # Here's the main idea. First normalize both x and y. We
1992 # express y as a rational m/n, with m and n relatively prime
1993 # and n>0. Then for x**y to be exactly representable (at
1994 # *any* precision), xc must be the nth power of a positive
1995 # integer and xe must be divisible by n. If m is negative
1996 # then additionally xc must be a power of either 2 or 5, hence
1997 # a power of 2**n or 5**n.
1999 # There's a limit to how small |y| can be: if y=m/n as above
2002 # (1) if xc != 1 then for the result to be representable we
2003 # need xc**(1/n) >= 2, and hence also xc**|y| >= 2. So
2004 # if |y| <= 1/nbits(xc) then xc < 2**nbits(xc) <=
2005 # 2**(1/|y|), hence xc**|y| < 2 and the result is not
2008 # (2) if xe != 0, |xe|*(1/n) >= 1, so |xe|*|y| >= 1. Hence if
2009 # |y| < 1/|xe| then the result is not representable.
2011 # Note that since x is not equal to 1, at least one of (1) and
2012 # (2) must apply. Now |y| < 1/nbits(xc) iff |yc|*nbits(xc) <
2013 # 10**-ye iff len(str(|yc|*nbits(xc)) <= -ye.
2015 # There's also a limit to how large y can be, at least if it's
2016 # positive: the normalized result will have coefficient xc**y,
2017 # so if it's representable then xc**y < 10**p, and y <
2018 # p/log10(xc). Hence if y*log10(xc) >= p then the result is
2019 # not exactly representable.
2021 # if len(str(abs(yc*xe)) <= -ye then abs(yc*xe) < 10**-ye,
2022 # so |y| < 1/xe and the result is not representable.
2023 # Similarly, len(str(abs(yc)*xc_bits)) <= -ye implies |y|
2027 xc
, xe
= x
.int, x
.exp
2033 yc
, ye
= y
.int, y
.exp
2038 # case where xc == 1: result is 10**(xe*y), with xe*y
2039 # required to be an integer
2042 exponent
= xe
*yc
*10**ye
2044 exponent
, remainder
= divmod(xe
*yc
, 10**-ye
)
2048 exponent
= -exponent
2049 # if other is a nonnegative integer, use ideal exponent
2050 if other
._isinteger
() and other
._sign
== 0:
2051 ideal_exponent
= self
._exp
*int(other
)
2052 zeros
= min(exponent
-ideal_exponent
, p
-1)
2055 return _dec_from_triple(0, '1' + '0'*zeros
, exponent
-zeros
)
2057 # case where y is negative: xc must be either a power
2058 # of 2 or a power of 5.
2060 last_digit
= xc
% 10
2061 if last_digit
in (2,4,6,8):
2062 # quick test for power of 2
2065 # now xc is a power of 2; e is its exponent
2067 # find e*y and xe*y; both must be integers
2069 y_as_int
= yc
*10**ye
2074 e
, remainder
= divmod(e
*yc
, ten_pow
)
2077 xe
, remainder
= divmod(xe
*yc
, ten_pow
)
2081 if e
*65 >= p
*93: # 93/65 > log(10)/log(5)
2085 elif last_digit
== 5:
2086 # e >= log_5(xc) if xc is a power of 5; we have
2087 # equality all the way up to xc=5**2658
2088 e
= _nbits(xc
)*28//65
2089 xc
, remainder
= divmod(5**e
, xc
)
2096 y_as_integer
= yc
*10**ye
2098 xe
= xe
*y_as_integer
2101 e
, remainder
= divmod(e
*yc
, ten_pow
)
2104 xe
, remainder
= divmod(xe
*yc
, ten_pow
)
2107 if e
*3 >= p
*10: # 10/3 > log(10)/log(2)
2116 return _dec_from_triple(0, str(xc
), xe
)
2118 # now y is positive; find m and n such that y = m/n
2122 if xe
!= 0 and len(str(abs(yc
*xe
))) <= -ye
:
2124 xc_bits
= _nbits(xc
)
2125 if xc
!= 1 and len(str(abs(yc
)*xc_bits
)) <= -ye
:
2127 m
, n
= yc
, 10**(-ye
)
2128 while m
% 2 == n
% 2 == 0:
2131 while m
% 5 == n
% 5 == 0:
2135 # compute nth root of xc*10**xe
2137 # if 1 < xc < 2**n then xc isn't an nth power
2138 if xc
!= 1 and xc_bits
<= n
:
2141 xe
, rem
= divmod(xe
, n
)
2145 # compute nth root of xc using Newton's method
2146 a
= 1 << -(-_nbits(xc
)//n
) # initial estimate
2148 q
, r
= divmod(xc
, a
**(n
-1))
2152 a
= (a
*(n
-1) + q
)//n
2153 if not (a
== q
and r
== 0):
2157 # now xc*10**xe is the nth root of the original xc*10**xe
2158 # compute mth power of xc*10**xe
2160 # if m > p*100//_log10_lb(xc) then m > p/log10(xc), hence xc**m >
2161 # 10**p and the result is not representable.
2162 if xc
> 1 and m
> p
*100//_log10_lb(xc
):
2169 # by this point the result *is* exactly representable
2170 # adjust the exponent to get as close as possible to the ideal
2171 # exponent, if necessary
2173 if other
._isinteger
() and other
._sign
== 0:
2174 ideal_exponent
= self
._exp
*int(other
)
2175 zeros
= min(xe
-ideal_exponent
, p
-len(str_xc
))
2178 return _dec_from_triple(0, str_xc
+'0'*zeros
, xe
-zeros
)
2180 def __pow__(self
, other
, modulo
=None, context
=None):
2181 """Return self ** other [ % modulo].
2183 With two arguments, compute self**other.
2185 With three arguments, compute (self**other) % modulo. For the
2186 three argument form, the following restrictions on the
2189 - all three arguments must be integral
2190 - other must be nonnegative
2191 - either self or other (or both) must be nonzero
2192 - modulo must be nonzero and must have at most p digits,
2193 where p is the context precision.
2195 If any of these restrictions is violated the InvalidOperation
2198 The result of pow(self, other, modulo) is identical to the
2199 result that would be obtained by computing (self**other) %
2200 modulo with unbounded precision, but is computed more
2201 efficiently. It is always exact.
2204 if modulo
is not None:
2205 return self
._power
_modulo
(other
, modulo
, context
)
2207 other
= _convert_other(other
)
2208 if other
is NotImplemented:
2212 context
= getcontext()
2214 # either argument is a NaN => result is NaN
2215 ans
= self
._check
_nans
(other
, context
)
2219 # 0**0 = NaN (!), x**0 = 1 for nonzero x (including +/-Infinity)
2222 return context
._raise
_error
(InvalidOperation
, '0 ** 0')
2226 # result has sign 1 iff self._sign is 1 and other is an odd integer
2229 if other
._isinteger
():
2230 if not other
._iseven
():
2233 # -ve**noninteger = NaN
2234 # (-0)**noninteger = 0**noninteger
2236 return context
._raise
_error
(InvalidOperation
,
2237 'x ** y with x negative and y not an integer')
2238 # negate self, without doing any unwanted rounding
2239 self
= self
.copy_negate()
2241 # 0**(+ve or Inf)= 0; 0**(-ve or -Inf) = Infinity
2243 if other
._sign
== 0:
2244 return _dec_from_triple(result_sign
, '0', 0)
2246 return _SignedInfinity
[result_sign
]
2248 # Inf**(+ve or Inf) = Inf; Inf**(-ve or -Inf) = 0
2249 if self
._isinfinity
():
2250 if other
._sign
== 0:
2251 return _SignedInfinity
[result_sign
]
2253 return _dec_from_triple(result_sign
, '0', 0)
2255 # 1**other = 1, but the choice of exponent and the flags
2256 # depend on the exponent of self, and on whether other is a
2257 # positive integer, a negative integer, or neither
2259 if other
._isinteger
():
2260 # exp = max(self._exp*max(int(other), 0),
2261 # 1-context.prec) but evaluating int(other) directly
2262 # is dangerous until we know other is small (other
2263 # could be 1e999999999)
2264 if other
._sign
== 1:
2266 elif other
> context
.prec
:
2267 multiplier
= context
.prec
2269 multiplier
= int(other
)
2271 exp
= self
._exp
* multiplier
2272 if exp
< 1-context
.prec
:
2273 exp
= 1-context
.prec
2274 context
._raise
_error
(Rounded
)
2276 context
._raise
_error
(Inexact
)
2277 context
._raise
_error
(Rounded
)
2278 exp
= 1-context
.prec
2280 return _dec_from_triple(result_sign
, '1'+'0'*-exp
, exp
)
2282 # compute adjusted exponent of self
2283 self_adj
= self
.adjusted()
2285 # self ** infinity is infinity if self > 1, 0 if self < 1
2286 # self ** -infinity is infinity if self < 1, 0 if self > 1
2287 if other
._isinfinity
():
2288 if (other
._sign
== 0) == (self_adj
< 0):
2289 return _dec_from_triple(result_sign
, '0', 0)
2291 return _SignedInfinity
[result_sign
]
2293 # from here on, the result always goes through the call
2294 # to _fix at the end of this function.
2297 # crude test to catch cases of extreme overflow/underflow. If
2298 # log10(self)*other >= 10**bound and bound >= len(str(Emax))
2299 # then 10**bound >= 10**len(str(Emax)) >= Emax+1 and hence
2300 # self**other >= 10**(Emax+1), so overflow occurs. The test
2301 # for underflow is similar.
2302 bound
= self
._log
10_exp
_bound
() + other
.adjusted()
2303 if (self_adj
>= 0) == (other
._sign
== 0):
2304 # self > 1 and other +ve, or self < 1 and other -ve
2305 # possibility of overflow
2306 if bound
>= len(str(context
.Emax
)):
2307 ans
= _dec_from_triple(result_sign
, '1', context
.Emax
+1)
2309 # self > 1 and other -ve, or self < 1 and other +ve
2310 # possibility of underflow to 0
2311 Etiny
= context
.Etiny()
2312 if bound
>= len(str(-Etiny
)):
2313 ans
= _dec_from_triple(result_sign
, '1', Etiny
-1)
2315 # try for an exact result with precision +1
2317 ans
= self
._power
_exact
(other
, context
.prec
+ 1)
2318 if ans
is not None and result_sign
== 1:
2319 ans
= _dec_from_triple(1, ans
._int
, ans
._exp
)
2321 # usual case: inexact result, x**y computed directly as exp(y*log(x))
2325 xc
, xe
= x
.int, x
.exp
2327 yc
, ye
= y
.int, y
.exp
2331 # compute correctly rounded result: start with precision +3,
2332 # then increase precision until result is unambiguously roundable
2335 coeff
, exp
= _dpower(xc
, xe
, yc
, ye
, p
+extra
)
2336 if coeff
% (5*10**(len(str(coeff
))-p
-1)):
2340 ans
= _dec_from_triple(result_sign
, str(coeff
), exp
)
2342 # the specification says that for non-integer other we need to
2343 # raise Inexact, even when the result is actually exact. In
2344 # the same way, we need to raise Underflow here if the result
2345 # is subnormal. (The call to _fix will take care of raising
2346 # Rounded and Subnormal, as usual.)
2347 if not other
._isinteger
():
2348 context
._raise
_error
(Inexact
)
2349 # pad with zeros up to length context.prec+1 if necessary
2350 if len(ans
._int
) <= context
.prec
:
2351 expdiff
= context
.prec
+1 - len(ans
._int
)
2352 ans
= _dec_from_triple(ans
._sign
, ans
._int
+'0'*expdiff
,
2354 if ans
.adjusted() < context
.Emin
:
2355 context
._raise
_error
(Underflow
)
2357 # unlike exp, ln and log10, the power function respects the
2358 # rounding mode; no need to use ROUND_HALF_EVEN here
2359 ans
= ans
._fix
(context
)
2362 def __rpow__(self
, other
, context
=None):
2363 """Swaps self/other and returns __pow__."""
2364 other
= _convert_other(other
)
2365 if other
is NotImplemented:
2367 return other
.__pow
__(self
, context
=context
)
2369 def normalize(self
, context
=None):
2370 """Normalize- strip trailing 0s, change anything equal to 0 to 0e0"""
2373 context
= getcontext()
2375 if self
._is
_special
:
2376 ans
= self
._check
_nans
(context
=context
)
2380 dup
= self
._fix
(context
)
2381 if dup
._isinfinity
():
2385 return _dec_from_triple(dup
._sign
, '0', 0)
2386 exp_max
= [context
.Emax
, context
.Etop()][context
._clamp
]
2389 while dup
._int
[end
-1] == '0' and exp
< exp_max
:
2392 return _dec_from_triple(dup
._sign
, dup
._int
[:end
], exp
)
2394 def quantize(self
, exp
, rounding
=None, context
=None, watchexp
=True):
2395 """Quantize self so its exponent is the same as that of exp.
2397 Similar to self._rescale(exp._exp) but with error checking.
2399 exp
= _convert_other(exp
, raiseit
=True)
2402 context
= getcontext()
2403 if rounding
is None:
2404 rounding
= context
.rounding
2406 if self
._is
_special
or exp
._is
_special
:
2407 ans
= self
._check
_nans
(exp
, context
)
2411 if exp
._isinfinity
() or self
._isinfinity
():
2412 if exp
._isinfinity
() and self
._isinfinity
():
2413 return Decimal(self
) # if both are inf, it is OK
2414 return context
._raise
_error
(InvalidOperation
,
2415 'quantize with one INF')
2417 # if we're not watching exponents, do a simple rescale
2419 ans
= self
._rescale
(exp
._exp
, rounding
)
2420 # raise Inexact and Rounded where appropriate
2421 if ans
._exp
> self
._exp
:
2422 context
._raise
_error
(Rounded
)
2424 context
._raise
_error
(Inexact
)
2427 # exp._exp should be between Etiny and Emax
2428 if not (context
.Etiny() <= exp
._exp
<= context
.Emax
):
2429 return context
._raise
_error
(InvalidOperation
,
2430 'target exponent out of bounds in quantize')
2433 ans
= _dec_from_triple(self
._sign
, '0', exp
._exp
)
2434 return ans
._fix
(context
)
2436 self_adjusted
= self
.adjusted()
2437 if self_adjusted
> context
.Emax
:
2438 return context
._raise
_error
(InvalidOperation
,
2439 'exponent of quantize result too large for current context')
2440 if self_adjusted
- exp
._exp
+ 1 > context
.prec
:
2441 return context
._raise
_error
(InvalidOperation
,
2442 'quantize result has too many digits for current context')
2444 ans
= self
._rescale
(exp
._exp
, rounding
)
2445 if ans
.adjusted() > context
.Emax
:
2446 return context
._raise
_error
(InvalidOperation
,
2447 'exponent of quantize result too large for current context')
2448 if len(ans
._int
) > context
.prec
:
2449 return context
._raise
_error
(InvalidOperation
,
2450 'quantize result has too many digits for current context')
2452 # raise appropriate flags
2453 if ans
._exp
> self
._exp
:
2454 context
._raise
_error
(Rounded
)
2456 context
._raise
_error
(Inexact
)
2457 if ans
and ans
.adjusted() < context
.Emin
:
2458 context
._raise
_error
(Subnormal
)
2460 # call to fix takes care of any necessary folddown
2461 ans
= ans
._fix
(context
)
2464 def same_quantum(self
, other
):
2465 """Return True if self and other have the same exponent; otherwise
2468 If either operand is a special value, the following rules are used:
2469 * return True if both operands are infinities
2470 * return True if both operands are NaNs
2471 * otherwise, return False.
2473 other
= _convert_other(other
, raiseit
=True)
2474 if self
._is
_special
or other
._is
_special
:
2475 return (self
.is_nan() and other
.is_nan() or
2476 self
.is_infinite() and other
.is_infinite())
2477 return self
._exp
== other
._exp
2479 def _rescale(self
, exp
, rounding
):
2480 """Rescale self so that the exponent is exp, either by padding with zeros
2481 or by truncating digits, using the given rounding mode.
2483 Specials are returned without change. This operation is
2484 quiet: it raises no flags, and uses no information from the
2487 exp = exp to scale to (an integer)
2488 rounding = rounding mode
2490 if self
._is
_special
:
2491 return Decimal(self
)
2493 return _dec_from_triple(self
._sign
, '0', exp
)
2495 if self
._exp
>= exp
:
2496 # pad answer with zeros if necessary
2497 return _dec_from_triple(self
._sign
,
2498 self
._int
+ '0'*(self
._exp
- exp
), exp
)
2500 # too many digits; round and lose data. If self.adjusted() <
2501 # exp-1, replace self by 10**(exp-1) before rounding
2502 digits
= len(self
._int
) + self
._exp
- exp
2504 self
= _dec_from_triple(self
._sign
, '1', exp
-1)
2506 this_function
= getattr(self
, self
._pick
_rounding
_function
[rounding
])
2507 changed
= this_function(digits
)
2508 coeff
= self
._int
[:digits
] or '0'
2510 coeff
= str(int(coeff
)+1)
2511 return _dec_from_triple(self
._sign
, coeff
, exp
)
2513 def _round(self
, places
, rounding
):
2514 """Round a nonzero, nonspecial Decimal to a fixed number of
2515 significant figures, using the given rounding mode.
2517 Infinities, NaNs and zeros are returned unaltered.
2519 This operation is quiet: it raises no flags, and uses no
2520 information from the context.
2524 raise ValueError("argument should be at least 1 in _round")
2525 if self
._is
_special
or not self
:
2526 return Decimal(self
)
2527 ans
= self
._rescale
(self
.adjusted()+1-places
, rounding
)
2528 # it can happen that the rescale alters the adjusted exponent;
2529 # for example when rounding 99.97 to 3 significant figures.
2530 # When this happens we end up with an extra 0 at the end of
2531 # the number; a second rescale fixes this.
2532 if ans
.adjusted() != self
.adjusted():
2533 ans
= ans
._rescale
(ans
.adjusted()+1-places
, rounding
)
2536 def to_integral_exact(self
, rounding
=None, context
=None):
2537 """Rounds to a nearby integer.
2539 If no rounding mode is specified, take the rounding mode from
2540 the context. This method raises the Rounded and Inexact flags
2543 See also: to_integral_value, which does exactly the same as
2544 this method except that it doesn't raise Inexact or Rounded.
2546 if self
._is
_special
:
2547 ans
= self
._check
_nans
(context
=context
)
2550 return Decimal(self
)
2552 return Decimal(self
)
2554 return _dec_from_triple(self
._sign
, '0', 0)
2556 context
= getcontext()
2557 if rounding
is None:
2558 rounding
= context
.rounding
2559 context
._raise
_error
(Rounded
)
2560 ans
= self
._rescale
(0, rounding
)
2562 context
._raise
_error
(Inexact
)
2565 def to_integral_value(self
, rounding
=None, context
=None):
2566 """Rounds to the nearest integer, without raising inexact, rounded."""
2568 context
= getcontext()
2569 if rounding
is None:
2570 rounding
= context
.rounding
2571 if self
._is
_special
:
2572 ans
= self
._check
_nans
(context
=context
)
2575 return Decimal(self
)
2577 return Decimal(self
)
2579 return self
._rescale
(0, rounding
)
2581 # the method name changed, but we provide also the old one, for compatibility
2582 to_integral
= to_integral_value
2584 def sqrt(self
, context
=None):
2585 """Return the square root of self."""
2587 context
= getcontext()
2589 if self
._is
_special
:
2590 ans
= self
._check
_nans
(context
=context
)
2594 if self
._isinfinity
() and self
._sign
== 0:
2595 return Decimal(self
)
2598 # exponent = self._exp // 2. sqrt(-0) = -0
2599 ans
= _dec_from_triple(self
._sign
, '0', self
._exp
// 2)
2600 return ans
._fix
(context
)
2603 return context
._raise
_error
(InvalidOperation
, 'sqrt(-x), x > 0')
2605 # At this point self represents a positive number. Let p be
2606 # the desired precision and express self in the form c*100**e
2607 # with c a positive real number and e an integer, c and e
2608 # being chosen so that 100**(p-1) <= c < 100**p. Then the
2609 # (exact) square root of self is sqrt(c)*10**e, and 10**(p-1)
2610 # <= sqrt(c) < 10**p, so the closest representable Decimal at
2611 # precision p is n*10**e where n = round_half_even(sqrt(c)),
2612 # the closest integer to sqrt(c) with the even integer chosen
2613 # in the case of a tie.
2615 # To ensure correct rounding in all cases, we use the
2616 # following trick: we compute the square root to an extra
2617 # place (precision p+1 instead of precision p), rounding down.
2618 # Then, if the result is inexact and its last digit is 0 or 5,
2619 # we increase the last digit to 1 or 6 respectively; if it's
2620 # exact we leave the last digit alone. Now the final round to
2621 # p places (or fewer in the case of underflow) will round
2622 # correctly and raise the appropriate flags.
2624 # use an extra digit of precision
2625 prec
= context
.prec
+1
2627 # write argument in the form c*100**e where e = self._exp//2
2628 # is the 'ideal' exponent, to be used if the square root is
2629 # exactly representable. l is the number of 'digits' of c in
2630 # base 100, so that 100**(l-1) <= c < 100**l.
2635 l
= (len(self
._int
) >> 1) + 1
2638 l
= len(self
._int
)+1 >> 1
2640 # rescale so that c has exactly prec base 100 'digits'
2646 c
, remainder
= divmod(c
, 100**-shift
)
2647 exact
= not remainder
2650 # find n = floor(sqrt(c)) using Newton's method
2658 exact
= exact
and n
*n
== c
2661 # result is exact; rescale to use ideal exponent e
2663 # assert n % 10**shift == 0
2669 # result is not exact; fix last digit as described above
2673 ans
= _dec_from_triple(0, str(n
), e
)
2675 # round, and fit to current context
2676 context
= context
._shallow
_copy
()
2677 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
2678 ans
= ans
._fix
(context
)
2679 context
.rounding
= rounding
2683 def max(self
, other
, context
=None):
2684 """Returns the larger value.
2686 Like max(self, other) except if one is not a number, returns
2687 NaN (and signals if one is sNaN). Also rounds.
2689 other
= _convert_other(other
, raiseit
=True)
2692 context
= getcontext()
2694 if self
._is
_special
or other
._is
_special
:
2695 # If one operand is a quiet NaN and the other is number, then the
2696 # number is always returned
2700 if on
== 1 and sn
== 0:
2701 return self
._fix
(context
)
2702 if sn
== 1 and on
== 0:
2703 return other
._fix
(context
)
2704 return self
._check
_nans
(other
, context
)
2706 c
= self
._cmp
(other
)
2708 # If both operands are finite and equal in numerical value
2709 # then an ordering is applied:
2711 # If the signs differ then max returns the operand with the
2712 # positive sign and min returns the operand with the negative sign
2714 # If the signs are the same then the exponent is used to select
2715 # the result. This is exactly the ordering used in compare_total.
2716 c
= self
.compare_total(other
)
2723 return ans
._fix
(context
)
2725 def min(self
, other
, context
=None):
2726 """Returns the smaller value.
2728 Like min(self, other) except if one is not a number, returns
2729 NaN (and signals if one is sNaN). Also rounds.
2731 other
= _convert_other(other
, raiseit
=True)
2734 context
= getcontext()
2736 if self
._is
_special
or other
._is
_special
:
2737 # If one operand is a quiet NaN and the other is number, then the
2738 # number is always returned
2742 if on
== 1 and sn
== 0:
2743 return self
._fix
(context
)
2744 if sn
== 1 and on
== 0:
2745 return other
._fix
(context
)
2746 return self
._check
_nans
(other
, context
)
2748 c
= self
._cmp
(other
)
2750 c
= self
.compare_total(other
)
2757 return ans
._fix
(context
)
2759 def _isinteger(self
):
2760 """Returns whether self is an integer"""
2761 if self
._is
_special
:
2765 rest
= self
._int
[self
._exp
:]
2766 return rest
== '0'*len(rest
)
2769 """Returns True if self is even. Assumes self is an integer."""
2770 if not self
or self
._exp
> 0:
2772 return self
._int
[-1+self
._exp
] in '02468'
2775 """Return the adjusted exponent of self"""
2777 return self
._exp
+ len(self
._int
) - 1
2778 # If NaN or Infinity, self._exp is string
2782 def canonical(self
, context
=None):
2783 """Returns the same Decimal object.
2785 As we do not have different encodings for the same number, the
2786 received object already is in its canonical form.
2790 def compare_signal(self
, other
, context
=None):
2791 """Compares self to the other operand numerically.
2793 It's pretty much like compare(), but all NaNs signal, with signaling
2794 NaNs taking precedence over quiet NaNs.
2796 other
= _convert_other(other
, raiseit
= True)
2797 ans
= self
._compare
_check
_nans
(other
, context
)
2800 return self
.compare(other
, context
=context
)
2802 def compare_total(self
, other
):
2803 """Compares self to other using the abstract representations.
2805 This is not like the standard compare, which use their numerical
2806 value. Note that a total ordering is defined for all possible abstract
2809 other
= _convert_other(other
, raiseit
=True)
2811 # if one is negative and the other is positive, it's easy
2812 if self
._sign
and not other
._sign
:
2814 if not self
._sign
and other
._sign
:
2818 # let's handle both NaN types
2819 self_nan
= self
._isnan
()
2820 other_nan
= other
._isnan
()
2821 if self_nan
or other_nan
:
2822 if self_nan
== other_nan
:
2823 # compare payloads as though they're integers
2824 self_key
= len(self
._int
), self
._int
2825 other_key
= len(other
._int
), other
._int
2826 if self_key
< other_key
:
2831 if self_key
> other_key
:
2862 if self
._exp
< other
._exp
:
2867 if self
._exp
> other
._exp
:
2875 def compare_total_mag(self
, other
):
2876 """Compares self to other using abstract repr., ignoring sign.
2878 Like compare_total, but with operand's sign ignored and assumed to be 0.
2880 other
= _convert_other(other
, raiseit
=True)
2883 o
= other
.copy_abs()
2884 return s
.compare_total(o
)
2887 """Returns a copy with the sign set to 0. """
2888 return _dec_from_triple(0, self
._int
, self
._exp
, self
._is
_special
)
2890 def copy_negate(self
):
2891 """Returns a copy with the sign inverted."""
2893 return _dec_from_triple(0, self
._int
, self
._exp
, self
._is
_special
)
2895 return _dec_from_triple(1, self
._int
, self
._exp
, self
._is
_special
)
2897 def copy_sign(self
, other
):
2898 """Returns self with the sign of other."""
2899 return _dec_from_triple(other
._sign
, self
._int
,
2900 self
._exp
, self
._is
_special
)
2902 def exp(self
, context
=None):
2903 """Returns e ** self."""
2906 context
= getcontext()
2909 ans
= self
._check
_nans
(context
=context
)
2913 # exp(-Infinity) = 0
2914 if self
._isinfinity
() == -1:
2921 # exp(Infinity) = Infinity
2922 if self
._isinfinity
() == 1:
2923 return Decimal(self
)
2925 # the result is now guaranteed to be inexact (the true
2926 # mathematical result is transcendental). There's no need to
2927 # raise Rounded and Inexact here---they'll always be raised as
2928 # a result of the call to _fix.
2930 adj
= self
.adjusted()
2932 # we only need to do any computation for quite a small range
2933 # of adjusted exponents---for example, -29 <= adj <= 10 for
2934 # the default context. For smaller exponent the result is
2935 # indistinguishable from 1 at the given precision, while for
2936 # larger exponent the result either overflows or underflows.
2937 if self
._sign
== 0 and adj
> len(str((context
.Emax
+1)*3)):
2939 ans
= _dec_from_triple(0, '1', context
.Emax
+1)
2940 elif self
._sign
== 1 and adj
> len(str((-context
.Etiny()+1)*3)):
2942 ans
= _dec_from_triple(0, '1', context
.Etiny()-1)
2943 elif self
._sign
== 0 and adj
< -p
:
2944 # p+1 digits; final round will raise correct flags
2945 ans
= _dec_from_triple(0, '1' + '0'*(p
-1) + '1', -p
)
2946 elif self
._sign
== 1 and adj
< -p
-1:
2947 # p+1 digits; final round will raise correct flags
2948 ans
= _dec_from_triple(0, '9'*(p
+1), -p
-1)
2952 c
, e
= op
.int, op
.exp
2956 # compute correctly rounded result: increase precision by
2957 # 3 digits at a time until we get an unambiguously
2961 coeff
, exp
= _dexp(c
, e
, p
+extra
)
2962 if coeff
% (5*10**(len(str(coeff
))-p
-1)):
2966 ans
= _dec_from_triple(0, str(coeff
), exp
)
2968 # at this stage, ans should round correctly with *any*
2969 # rounding mode, not just with ROUND_HALF_EVEN
2970 context
= context
._shallow
_copy
()
2971 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
2972 ans
= ans
._fix
(context
)
2973 context
.rounding
= rounding
2977 def is_canonical(self
):
2978 """Return True if self is canonical; otherwise return False.
2980 Currently, the encoding of a Decimal instance is always
2981 canonical, so this method returns True for any Decimal.
2985 def is_finite(self
):
2986 """Return True if self is finite; otherwise return False.
2988 A Decimal instance is considered finite if it is neither
2991 return not self
._is
_special
2993 def is_infinite(self
):
2994 """Return True if self is infinite; otherwise return False."""
2995 return self
._exp
== 'F'
2998 """Return True if self is a qNaN or sNaN; otherwise return False."""
2999 return self
._exp
in ('n', 'N')
3001 def is_normal(self
, context
=None):
3002 """Return True if self is a normal number; otherwise return False."""
3003 if self
._is
_special
or not self
:
3006 context
= getcontext()
3007 return context
.Emin
<= self
.adjusted()
3010 """Return True if self is a quiet NaN; otherwise return False."""
3011 return self
._exp
== 'n'
3013 def is_signed(self
):
3014 """Return True if self is negative; otherwise return False."""
3015 return self
._sign
== 1
3018 """Return True if self is a signaling NaN; otherwise return False."""
3019 return self
._exp
== 'N'
3021 def is_subnormal(self
, context
=None):
3022 """Return True if self is subnormal; otherwise return False."""
3023 if self
._is
_special
or not self
:
3026 context
= getcontext()
3027 return self
.adjusted() < context
.Emin
3030 """Return True if self is a zero; otherwise return False."""
3031 return not self
._is
_special
and self
._int
== '0'
3033 def _ln_exp_bound(self
):
3034 """Compute a lower bound for the adjusted exponent of self.ln().
3035 In other words, compute r such that self.ln() >= 10**r. Assumes
3036 that self is finite and positive and that self != 1.
3039 # for 0.1 <= x <= 10 we use the inequalities 1-1/x <= ln(x) <= x-1
3040 adj
= self
._exp
+ len(self
._int
) - 1
3042 # argument >= 10; we use 23/10 = 2.3 as a lower bound for ln(10)
3043 return len(str(adj
*23//10)) - 1
3046 return len(str((-1-adj
)*23//10)) - 1
3048 c
, e
= op
.int, op
.exp
3053 return len(num
) - len(den
) - (num
< den
)
3054 # adj == -1, 0.1 <= self < 1
3055 return e
+ len(str(10**-e
- c
)) - 1
3058 def ln(self
, context
=None):
3059 """Returns the natural (base e) logarithm of self."""
3062 context
= getcontext()
3065 ans
= self
._check
_nans
(context
=context
)
3069 # ln(0.0) == -Infinity
3071 return _NegativeInfinity
3073 # ln(Infinity) = Infinity
3074 if self
._isinfinity
() == 1:
3081 # ln(negative) raises InvalidOperation
3083 return context
._raise
_error
(InvalidOperation
,
3084 'ln of a negative value')
3086 # result is irrational, so necessarily inexact
3088 c
, e
= op
.int, op
.exp
3091 # correctly rounded result: repeatedly increase precision by 3
3092 # until we get an unambiguously roundable result
3093 places
= p
- self
._ln
_exp
_bound
() + 2 # at least p+3 places
3095 coeff
= _dlog(c
, e
, places
)
3096 # assert len(str(abs(coeff)))-p >= 1
3097 if coeff
% (5*10**(len(str(abs(coeff
)))-p
-1)):
3100 ans
= _dec_from_triple(int(coeff
<0), str(abs(coeff
)), -places
)
3102 context
= context
._shallow
_copy
()
3103 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
3104 ans
= ans
._fix
(context
)
3105 context
.rounding
= rounding
3108 def _log10_exp_bound(self
):
3109 """Compute a lower bound for the adjusted exponent of self.log10().
3110 In other words, find r such that self.log10() >= 10**r.
3111 Assumes that self is finite and positive and that self != 1.
3114 # For x >= 10 or x < 0.1 we only need a bound on the integer
3115 # part of log10(self), and this comes directly from the
3116 # exponent of x. For 0.1 <= x <= 10 we use the inequalities
3117 # 1-1/x <= log(x) <= x-1. If x > 1 we have |log10(x)| >
3118 # (1-1/x)/2.31 > 0. If x < 1 then |log10(x)| > (1-x)/2.31 > 0
3120 adj
= self
._exp
+ len(self
._int
) - 1
3123 return len(str(adj
))-1
3126 return len(str(-1-adj
))-1
3128 c
, e
= op
.int, op
.exp
3133 return len(num
) - len(den
) - (num
< den
) + 2
3134 # adj == -1, 0.1 <= self < 1
3136 return len(num
) + e
- (num
< "231") - 1
3138 def log10(self
, context
=None):
3139 """Returns the base 10 logarithm of self."""
3142 context
= getcontext()
3145 ans
= self
._check
_nans
(context
=context
)
3149 # log10(0.0) == -Infinity
3151 return _NegativeInfinity
3153 # log10(Infinity) = Infinity
3154 if self
._isinfinity
() == 1:
3157 # log10(negative or -Infinity) raises InvalidOperation
3159 return context
._raise
_error
(InvalidOperation
,
3160 'log10 of a negative value')
3163 if self
._int
[0] == '1' and self
._int
[1:] == '0'*(len(self
._int
) - 1):
3164 # answer may need rounding
3165 ans
= Decimal(self
._exp
+ len(self
._int
) - 1)
3167 # result is irrational, so necessarily inexact
3169 c
, e
= op
.int, op
.exp
3172 # correctly rounded result: repeatedly increase precision
3173 # until result is unambiguously roundable
3174 places
= p
-self
._log
10_exp
_bound
()+2
3176 coeff
= _dlog10(c
, e
, places
)
3177 # assert len(str(abs(coeff)))-p >= 1
3178 if coeff
% (5*10**(len(str(abs(coeff
)))-p
-1)):
3181 ans
= _dec_from_triple(int(coeff
<0), str(abs(coeff
)), -places
)
3183 context
= context
._shallow
_copy
()
3184 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
3185 ans
= ans
._fix
(context
)
3186 context
.rounding
= rounding
3189 def logb(self
, context
=None):
3190 """ Returns the exponent of the magnitude of self's MSD.
3192 The result is the integer which is the exponent of the magnitude
3193 of the most significant digit of self (as though it were truncated
3194 to a single digit while maintaining the value of that digit and
3195 without limiting the resulting exponent).
3198 ans
= self
._check
_nans
(context
=context
)
3203 context
= getcontext()
3205 # logb(+/-Inf) = +Inf
3206 if self
._isinfinity
():
3209 # logb(0) = -Inf, DivisionByZero
3211 return context
._raise
_error
(DivisionByZero
, 'logb(0)', 1)
3213 # otherwise, simply return the adjusted exponent of self, as a
3214 # Decimal. Note that no attempt is made to fit the result
3215 # into the current context.
3216 ans
= Decimal(self
.adjusted())
3217 return ans
._fix
(context
)
3219 def _islogical(self
):
3220 """Return True if self is a logical operand.
3222 For being logical, it must be a finite number with a sign of 0,
3223 an exponent of 0, and a coefficient whose digits must all be
3226 if self
._sign
!= 0 or self
._exp
!= 0:
3228 for dig
in self
._int
:
3233 def _fill_logical(self
, context
, opa
, opb
):
3234 dif
= context
.prec
- len(opa
)
3238 opa
= opa
[-context
.prec
:]
3239 dif
= context
.prec
- len(opb
)
3243 opb
= opb
[-context
.prec
:]
3246 def logical_and(self
, other
, context
=None):
3247 """Applies an 'and' operation between self and other's digits."""
3249 context
= getcontext()
3251 other
= _convert_other(other
, raiseit
=True)
3253 if not self
._islogical
() or not other
._islogical
():
3254 return context
._raise
_error
(InvalidOperation
)
3256 # fill to context.prec
3257 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3259 # make the operation, and clean starting zeroes
3260 result
= "".join([str(int(a
)&int(b
)) for a
,b
in zip(opa
,opb
)])
3261 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3263 def logical_invert(self
, context
=None):
3264 """Invert all its digits."""
3266 context
= getcontext()
3267 return self
.logical_xor(_dec_from_triple(0,'1'*context
.prec
,0),
3270 def logical_or(self
, other
, context
=None):
3271 """Applies an 'or' operation between self and other's digits."""
3273 context
= getcontext()
3275 other
= _convert_other(other
, raiseit
=True)
3277 if not self
._islogical
() or not other
._islogical
():
3278 return context
._raise
_error
(InvalidOperation
)
3280 # fill to context.prec
3281 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3283 # make the operation, and clean starting zeroes
3284 result
= "".join([str(int(a
)|
int(b
)) for a
,b
in zip(opa
,opb
)])
3285 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3287 def logical_xor(self
, other
, context
=None):
3288 """Applies an 'xor' operation between self and other's digits."""
3290 context
= getcontext()
3292 other
= _convert_other(other
, raiseit
=True)
3294 if not self
._islogical
() or not other
._islogical
():
3295 return context
._raise
_error
(InvalidOperation
)
3297 # fill to context.prec
3298 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3300 # make the operation, and clean starting zeroes
3301 result
= "".join([str(int(a
)^
int(b
)) for a
,b
in zip(opa
,opb
)])
3302 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3304 def max_mag(self
, other
, context
=None):
3305 """Compares the values numerically with their sign ignored."""
3306 other
= _convert_other(other
, raiseit
=True)
3309 context
= getcontext()
3311 if self
._is
_special
or other
._is
_special
:
3312 # If one operand is a quiet NaN and the other is number, then the
3313 # number is always returned
3317 if on
== 1 and sn
== 0:
3318 return self
._fix
(context
)
3319 if sn
== 1 and on
== 0:
3320 return other
._fix
(context
)
3321 return self
._check
_nans
(other
, context
)
3323 c
= self
.copy_abs()._cmp
(other
.copy_abs())
3325 c
= self
.compare_total(other
)
3332 return ans
._fix
(context
)
3334 def min_mag(self
, other
, context
=None):
3335 """Compares the values numerically with their sign ignored."""
3336 other
= _convert_other(other
, raiseit
=True)
3339 context
= getcontext()
3341 if self
._is
_special
or other
._is
_special
:
3342 # If one operand is a quiet NaN and the other is number, then the
3343 # number is always returned
3347 if on
== 1 and sn
== 0:
3348 return self
._fix
(context
)
3349 if sn
== 1 and on
== 0:
3350 return other
._fix
(context
)
3351 return self
._check
_nans
(other
, context
)
3353 c
= self
.copy_abs()._cmp
(other
.copy_abs())
3355 c
= self
.compare_total(other
)
3362 return ans
._fix
(context
)
3364 def next_minus(self
, context
=None):
3365 """Returns the largest representable number smaller than itself."""
3367 context
= getcontext()
3369 ans
= self
._check
_nans
(context
=context
)
3373 if self
._isinfinity
() == -1:
3374 return _NegativeInfinity
3375 if self
._isinfinity
() == 1:
3376 return _dec_from_triple(0, '9'*context
.prec
, context
.Etop())
3378 context
= context
.copy()
3379 context
._set
_rounding
(ROUND_FLOOR
)
3380 context
._ignore
_all
_flags
()
3381 new_self
= self
._fix
(context
)
3382 if new_self
!= self
:
3384 return self
.__sub
__(_dec_from_triple(0, '1', context
.Etiny()-1),
3387 def next_plus(self
, context
=None):
3388 """Returns the smallest representable number larger than itself."""
3390 context
= getcontext()
3392 ans
= self
._check
_nans
(context
=context
)
3396 if self
._isinfinity
() == 1:
3398 if self
._isinfinity
() == -1:
3399 return _dec_from_triple(1, '9'*context
.prec
, context
.Etop())
3401 context
= context
.copy()
3402 context
._set
_rounding
(ROUND_CEILING
)
3403 context
._ignore
_all
_flags
()
3404 new_self
= self
._fix
(context
)
3405 if new_self
!= self
:
3407 return self
.__add
__(_dec_from_triple(0, '1', context
.Etiny()-1),
3410 def next_toward(self
, other
, context
=None):
3411 """Returns the number closest to self, in the direction towards other.
3413 The result is the closest representable number to self
3414 (excluding self) that is in the direction towards other,
3415 unless both have the same value. If the two operands are
3416 numerically equal, then the result is a copy of self with the
3417 sign set to be the same as the sign of other.
3419 other
= _convert_other(other
, raiseit
=True)
3422 context
= getcontext()
3424 ans
= self
._check
_nans
(other
, context
)
3428 comparison
= self
._cmp
(other
)
3430 return self
.copy_sign(other
)
3432 if comparison
== -1:
3433 ans
= self
.next_plus(context
)
3434 else: # comparison == 1
3435 ans
= self
.next_minus(context
)
3437 # decide which flags to raise using value of ans
3438 if ans
._isinfinity
():
3439 context
._raise
_error
(Overflow
,
3440 'Infinite result from next_toward',
3442 context
._raise
_error
(Rounded
)
3443 context
._raise
_error
(Inexact
)
3444 elif ans
.adjusted() < context
.Emin
:
3445 context
._raise
_error
(Underflow
)
3446 context
._raise
_error
(Subnormal
)
3447 context
._raise
_error
(Rounded
)
3448 context
._raise
_error
(Inexact
)
3449 # if precision == 1 then we don't raise Clamped for a
3452 context
._raise
_error
(Clamped
)
3456 def number_class(self
, context
=None):
3457 """Returns an indication of the class of self.
3459 The class is one of the following strings:
3475 inf
= self
._isinfinity
()
3486 context
= getcontext()
3487 if self
.is_subnormal(context
=context
):
3492 # just a normal, regular, boring number, :)
3499 """Just returns 10, as this is Decimal, :)"""
3502 def rotate(self
, other
, context
=None):
3503 """Returns a rotated copy of self, value-of-other times."""
3505 context
= getcontext()
3507 other
= _convert_other(other
, raiseit
=True)
3509 ans
= self
._check
_nans
(other
, context
)
3514 return context
._raise
_error
(InvalidOperation
)
3515 if not (-context
.prec
<= int(other
) <= context
.prec
):
3516 return context
._raise
_error
(InvalidOperation
)
3518 if self
._isinfinity
():
3519 return Decimal(self
)
3521 # get values, pad if necessary
3524 topad
= context
.prec
- len(rotdig
)
3526 rotdig
= '0'*topad
+ rotdig
3528 rotdig
= rotdig
[-topad
:]
3531 rotated
= rotdig
[torot
:] + rotdig
[:torot
]
3532 return _dec_from_triple(self
._sign
,
3533 rotated
.lstrip('0') or '0', self
._exp
)
3535 def scaleb(self
, other
, context
=None):
3536 """Returns self operand after adding the second value to its exp."""
3538 context
= getcontext()
3540 other
= _convert_other(other
, raiseit
=True)
3542 ans
= self
._check
_nans
(other
, context
)
3547 return context
._raise
_error
(InvalidOperation
)
3548 liminf
= -2 * (context
.Emax
+ context
.prec
)
3549 limsup
= 2 * (context
.Emax
+ context
.prec
)
3550 if not (liminf
<= int(other
) <= limsup
):
3551 return context
._raise
_error
(InvalidOperation
)
3553 if self
._isinfinity
():
3554 return Decimal(self
)
3556 d
= _dec_from_triple(self
._sign
, self
._int
, self
._exp
+ int(other
))
3560 def shift(self
, other
, context
=None):
3561 """Returns a shifted copy of self, value-of-other times."""
3563 context
= getcontext()
3565 other
= _convert_other(other
, raiseit
=True)
3567 ans
= self
._check
_nans
(other
, context
)
3572 return context
._raise
_error
(InvalidOperation
)
3573 if not (-context
.prec
<= int(other
) <= context
.prec
):
3574 return context
._raise
_error
(InvalidOperation
)
3576 if self
._isinfinity
():
3577 return Decimal(self
)
3579 # get values, pad if necessary
3582 topad
= context
.prec
- len(rotdig
)
3584 rotdig
= '0'*topad
+ rotdig
3586 rotdig
= rotdig
[-topad
:]
3590 shifted
= rotdig
[:torot
]
3592 shifted
= rotdig
+ '0'*torot
3593 shifted
= shifted
[-context
.prec
:]
3595 return _dec_from_triple(self
._sign
,
3596 shifted
.lstrip('0') or '0', self
._exp
)
3598 # Support for pickling, copy, and deepcopy
3599 def __reduce__(self
):
3600 return (self
.__class
__, (str(self
),))
3603 if type(self
) == Decimal
:
3604 return self
# I'm immutable; therefore I am my own clone
3605 return self
.__class
__(str(self
))
3607 def __deepcopy__(self
, memo
):
3608 if type(self
) == Decimal
:
3609 return self
# My components are also immutable
3610 return self
.__class
__(str(self
))
3612 # PEP 3101 support. the _localeconv keyword argument should be
3613 # considered private: it's provided for ease of testing only.
3614 def __format__(self
, specifier
, context
=None, _localeconv
=None):
3615 """Format a Decimal instance according to the given specifier.
3617 The specifier should be a standard format specifier, with the
3618 form described in PEP 3101. Formatting types 'e', 'E', 'f',
3619 'F', 'g', 'G', 'n' and '%' are supported. If the formatting
3620 type is omitted it defaults to 'g' or 'G', depending on the
3621 value of context.capitals.
3624 # Note: PEP 3101 says that if the type is not present then
3625 # there should be at least one digit after the decimal point.
3626 # We take the liberty of ignoring this requirement for
3627 # Decimal---it's presumably there to make sure that
3628 # format(float, '') behaves similarly to str(float).
3630 context
= getcontext()
3632 spec
= _parse_format_specifier(specifier
, _localeconv
=_localeconv
)
3634 # special values don't care about the type or precision
3635 if self
._is
_special
:
3636 sign
= _format_sign(self
._sign
, spec
)
3637 body
= str(self
.copy_abs())
3638 return _format_align(sign
, body
, spec
)
3640 # a type of None defaults to 'g' or 'G', depending on context
3641 if spec
['type'] is None:
3642 spec
['type'] = ['g', 'G'][context
.capitals
]
3644 # if type is '%', adjust exponent of self accordingly
3645 if spec
['type'] == '%':
3646 self
= _dec_from_triple(self
._sign
, self
._int
, self
._exp
+2)
3648 # round if necessary, taking rounding mode from the context
3649 rounding
= context
.rounding
3650 precision
= spec
['precision']
3651 if precision
is not None:
3652 if spec
['type'] in 'eE':
3653 self
= self
._round
(precision
+1, rounding
)
3654 elif spec
['type'] in 'fF%':
3655 self
= self
._rescale
(-precision
, rounding
)
3656 elif spec
['type'] in 'gG' and len(self
._int
) > precision
:
3657 self
= self
._round
(precision
, rounding
)
3658 # special case: zeros with a positive exponent can't be
3659 # represented in fixed point; rescale them to 0e0.
3660 if not self
and self
._exp
> 0 and spec
['type'] in 'fF%':
3661 self
= self
._rescale
(0, rounding
)
3663 # figure out placement of the decimal point
3664 leftdigits
= self
._exp
+ len(self
._int
)
3665 if spec
['type'] in 'eE':
3666 if not self
and precision
is not None:
3667 dotplace
= 1 - precision
3670 elif spec
['type'] in 'fF%':
3671 dotplace
= leftdigits
3672 elif spec
['type'] in 'gG':
3673 if self
._exp
<= 0 and leftdigits
> -6:
3674 dotplace
= leftdigits
3678 # find digits before and after decimal point, and get exponent
3681 fracpart
= '0'*(-dotplace
) + self
._int
3682 elif dotplace
> len(self
._int
):
3683 intpart
= self
._int
+ '0'*(dotplace
-len(self
._int
))
3686 intpart
= self
._int
[:dotplace
] or '0'
3687 fracpart
= self
._int
[dotplace
:]
3688 exp
= leftdigits
-dotplace
3690 # done with the decimal-specific stuff; hand over the rest
3691 # of the formatting to the _format_number function
3692 return _format_number(self
._sign
, intpart
, fracpart
, exp
, spec
)
3694 def _dec_from_triple(sign
, coefficient
, exponent
, special
=False):
3695 """Create a decimal instance directly, without any validation,
3696 normalization (e.g. removal of leading zeros) or argument
3699 This function is for *internal use only*.
3702 self
= object.__new
__(Decimal
)
3704 self
._int
= coefficient
3705 self
._exp
= exponent
3706 self
._is
_special
= special
3710 # Register Decimal as a kind of Number (an abstract base class).
3711 # However, do not register it as Real (because Decimals are not
3712 # interoperable with floats).
3713 _numbers
.Number
.register(Decimal
)
3716 ##### Context class #######################################################
3719 # get rounding method function:
3720 rounding_functions
= [name
for name
in Decimal
.__dict
__.keys()
3721 if name
.startswith('_round_')]
3722 for name
in rounding_functions
:
3723 # name is like _round_half_even, goes to the global ROUND_HALF_EVEN value.
3724 globalname
= name
[1:].upper()
3725 val
= globals()[globalname
]
3726 Decimal
._pick
_rounding
_function
[val
] = name
3728 del name
, val
, globalname
, rounding_functions
3730 class _ContextManager(object):
3731 """Context manager class to support localcontext().
3733 Sets a copy of the supplied context in __enter__() and restores
3734 the previous decimal context in __exit__()
3736 def __init__(self
, new_context
):
3737 self
.new_context
= new_context
.copy()
3738 def __enter__(self
):
3739 self
.saved_context
= getcontext()
3740 setcontext(self
.new_context
)
3741 return self
.new_context
3742 def __exit__(self
, t
, v
, tb
):
3743 setcontext(self
.saved_context
)
3745 class Context(object):
3746 """Contains the context for a Decimal instance.
3749 prec - precision (for use in rounding, division, square roots..)
3750 rounding - rounding type (how you round)
3751 traps - If traps[exception] = 1, then the exception is
3752 raised when it is caused. Otherwise, a value is
3754 flags - When an exception is caused, flags[exception] is set.
3755 (Whether or not the trap_enabler is set)
3756 Should be reset by user of Decimal instance.
3757 Emin - Minimum exponent
3758 Emax - Maximum exponent
3759 capitals - If 1, 1*10^1 is printed as 1E+1.
3760 If 0, printed as 1e1
3761 _clamp - If 1, change exponents if too high (Default 0)
3764 def __init__(self
, prec
=None, rounding
=None,
3765 traps
=None, flags
=None,
3766 Emin
=None, Emax
=None,
3767 capitals
=None, _clamp
=0,
3768 _ignored_flags
=None):
3771 if _ignored_flags
is None:
3773 if not isinstance(flags
, dict):
3774 flags
= dict([(s
, int(s
in flags
)) for s
in _signals
])
3775 if traps
is not None and not isinstance(traps
, dict):
3776 traps
= dict([(s
, int(s
in traps
)) for s
in _signals
])
3777 for name
, val
in locals().items():
3779 setattr(self
, name
, _copy
.copy(getattr(DefaultContext
, name
)))
3781 setattr(self
, name
, val
)
3785 """Show the current context."""
3787 s
.append('Context(prec=%(prec)d, rounding=%(rounding)s, '
3788 'Emin=%(Emin)d, Emax=%(Emax)d, capitals=%(capitals)d'
3790 names
= [f
.__name
__ for f
, v
in self
.flags
.items() if v
]
3791 s
.append('flags=[' + ', '.join(names
) + ']')
3792 names
= [t
.__name
__ for t
, v
in self
.traps
.items() if v
]
3793 s
.append('traps=[' + ', '.join(names
) + ']')
3794 return ', '.join(s
) + ')'
3796 def clear_flags(self
):
3797 """Reset all flags to zero"""
3798 for flag
in self
.flags
:
3799 self
.flags
[flag
] = 0
3801 def _shallow_copy(self
):
3802 """Returns a shallow copy from self."""
3803 nc
= Context(self
.prec
, self
.rounding
, self
.traps
,
3804 self
.flags
, self
.Emin
, self
.Emax
,
3805 self
.capitals
, self
._clamp
, self
._ignored
_flags
)
3809 """Returns a deep copy from self."""
3810 nc
= Context(self
.prec
, self
.rounding
, self
.traps
.copy(),
3811 self
.flags
.copy(), self
.Emin
, self
.Emax
,
3812 self
.capitals
, self
._clamp
, self
._ignored
_flags
)
3816 def _raise_error(self
, condition
, explanation
= None, *args
):
3819 If the flag is in _ignored_flags, returns the default response.
3820 Otherwise, it sets the flag, then, if the corresponding
3821 trap_enabler is set, it reaises the exception. Otherwise, it returns
3822 the default value after setting the flag.
3824 error
= _condition_map
.get(condition
, condition
)
3825 if error
in self
._ignored
_flags
:
3826 # Don't touch the flag
3827 return error().handle(self
, *args
)
3829 self
.flags
[error
] = 1
3830 if not self
.traps
[error
]:
3831 # The errors define how to handle themselves.
3832 return condition().handle(self
, *args
)
3834 # Errors should only be risked on copies of the context
3835 # self._ignored_flags = []
3836 raise error(explanation
)
3838 def _ignore_all_flags(self
):
3839 """Ignore all flags, if they are raised"""
3840 return self
._ignore
_flags
(*_signals
)
3842 def _ignore_flags(self
, *flags
):
3843 """Ignore the flags, if they are raised"""
3844 # Do not mutate-- This way, copies of a context leave the original
3846 self
._ignored
_flags
= (self
._ignored
_flags
+ list(flags
))
3849 def _regard_flags(self
, *flags
):
3850 """Stop ignoring the flags, if they are raised"""
3851 if flags
and isinstance(flags
[0], (tuple,list)):
3854 self
._ignored
_flags
.remove(flag
)
3856 # We inherit object.__hash__, so we must deny this explicitly
3860 """Returns Etiny (= Emin - prec + 1)"""
3861 return int(self
.Emin
- self
.prec
+ 1)
3864 """Returns maximum exponent (= Emax - prec + 1)"""
3865 return int(self
.Emax
- self
.prec
+ 1)
3867 def _set_rounding(self
, type):
3868 """Sets the rounding type.
3870 Sets the rounding type, and returns the current (previous)
3871 rounding type. Often used like:
3873 context = context.copy()
3874 # so you don't change the calling context
3875 # if an error occurs in the middle.
3876 rounding = context._set_rounding(ROUND_UP)
3877 val = self.__sub__(other, context=context)
3878 context._set_rounding(rounding)
3880 This will make it round up for that operation.
3882 rounding
= self
.rounding
3886 def create_decimal(self
, num
='0'):
3887 """Creates a new Decimal instance but using self as context.
3889 This method implements the to-number operation of the
3890 IBM Decimal specification."""
3892 if isinstance(num
, str) and num
!= num
.strip():
3893 return self
._raise
_error
(ConversionSyntax
,
3894 "no trailing or leading whitespace is "
3897 d
= Decimal(num
, context
=self
)
3898 if d
._isnan
() and len(d
._int
) > self
.prec
- self
._clamp
:
3899 return self
._raise
_error
(ConversionSyntax
,
3900 "diagnostic info too long in NaN")
3903 def create_decimal_from_float(self
, f
):
3904 """Creates a new Decimal instance from a float but rounding using self
3907 >>> context = Context(prec=5, rounding=ROUND_DOWN)
3908 >>> context.create_decimal_from_float(3.1415926535897932)
3910 >>> context = Context(prec=5, traps=[Inexact])
3911 >>> context.create_decimal_from_float(3.1415926535897932)
3912 Traceback (most recent call last):
3914 decimal.Inexact: None
3917 d
= Decimal
.from_float(f
) # An exact conversion
3918 return d
._fix
(self
) # Apply the context rounding
3922 """Returns the absolute value of the operand.
3924 If the operand is negative, the result is the same as using the minus
3925 operation on the operand. Otherwise, the result is the same as using
3926 the plus operation on the operand.
3928 >>> ExtendedContext.abs(Decimal('2.1'))
3930 >>> ExtendedContext.abs(Decimal('-100'))
3932 >>> ExtendedContext.abs(Decimal('101.5'))
3934 >>> ExtendedContext.abs(Decimal('-101.5'))
3937 return a
.__abs
__(context
=self
)
3939 def add(self
, a
, b
):
3940 """Return the sum of the two operands.
3942 >>> ExtendedContext.add(Decimal('12'), Decimal('7.00'))
3944 >>> ExtendedContext.add(Decimal('1E+2'), Decimal('1.01E+4'))
3947 return a
.__add
__(b
, context
=self
)
3949 def _apply(self
, a
):
3950 return str(a
._fix
(self
))
3952 def canonical(self
, a
):
3953 """Returns the same Decimal object.
3955 As we do not have different encodings for the same number, the
3956 received object already is in its canonical form.
3958 >>> ExtendedContext.canonical(Decimal('2.50'))
3961 return a
.canonical(context
=self
)
3963 def compare(self
, a
, b
):
3964 """Compares values numerically.
3966 If the signs of the operands differ, a value representing each operand
3967 ('-1' if the operand is less than zero, '0' if the operand is zero or
3968 negative zero, or '1' if the operand is greater than zero) is used in
3969 place of that operand for the comparison instead of the actual
3972 The comparison is then effected by subtracting the second operand from
3973 the first and then returning a value according to the result of the
3974 subtraction: '-1' if the result is less than zero, '0' if the result is
3975 zero or negative zero, or '1' if the result is greater than zero.
3977 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
3979 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
3981 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))
3983 >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))
3985 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))
3987 >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))
3990 return a
.compare(b
, context
=self
)
3992 def compare_signal(self
, a
, b
):
3993 """Compares the values of the two operands numerically.
3995 It's pretty much like compare(), but all NaNs signal, with signaling
3996 NaNs taking precedence over quiet NaNs.
3998 >>> c = ExtendedContext
3999 >>> c.compare_signal(Decimal('2.1'), Decimal('3'))
4001 >>> c.compare_signal(Decimal('2.1'), Decimal('2.1'))
4003 >>> c.flags[InvalidOperation] = 0
4004 >>> print(c.flags[InvalidOperation])
4006 >>> c.compare_signal(Decimal('NaN'), Decimal('2.1'))
4008 >>> print(c.flags[InvalidOperation])
4010 >>> c.flags[InvalidOperation] = 0
4011 >>> print(c.flags[InvalidOperation])
4013 >>> c.compare_signal(Decimal('sNaN'), Decimal('2.1'))
4015 >>> print(c.flags[InvalidOperation])
4018 return a
.compare_signal(b
, context
=self
)
4020 def compare_total(self
, a
, b
):
4021 """Compares two operands using their abstract representation.
4023 This is not like the standard compare, which use their numerical
4024 value. Note that a total ordering is defined for all possible abstract
4027 >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
4029 >>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12'))
4031 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))
4033 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))
4035 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300'))
4037 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN'))
4040 return a
.compare_total(b
)
4042 def compare_total_mag(self
, a
, b
):
4043 """Compares two operands using their abstract representation ignoring sign.
4045 Like compare_total, but with operand's sign ignored and assumed to be 0.
4047 return a
.compare_total_mag(b
)
4049 def copy_abs(self
, a
):
4050 """Returns a copy of the operand with the sign set to 0.
4052 >>> ExtendedContext.copy_abs(Decimal('2.1'))
4054 >>> ExtendedContext.copy_abs(Decimal('-100'))
4059 def copy_decimal(self
, a
):
4060 """Returns a copy of the decimal objet.
4062 >>> ExtendedContext.copy_decimal(Decimal('2.1'))
4064 >>> ExtendedContext.copy_decimal(Decimal('-1.00'))
4069 def copy_negate(self
, a
):
4070 """Returns a copy of the operand with the sign inverted.
4072 >>> ExtendedContext.copy_negate(Decimal('101.5'))
4074 >>> ExtendedContext.copy_negate(Decimal('-101.5'))
4077 return a
.copy_negate()
4079 def copy_sign(self
, a
, b
):
4080 """Copies the second operand's sign to the first one.
4082 In detail, it returns a copy of the first operand with the sign
4083 equal to the sign of the second operand.
4085 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))
4087 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))
4089 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))
4091 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))
4094 return a
.copy_sign(b
)
4096 def divide(self
, a
, b
):
4097 """Decimal division in a specified context.
4099 >>> ExtendedContext.divide(Decimal('1'), Decimal('3'))
4100 Decimal('0.333333333')
4101 >>> ExtendedContext.divide(Decimal('2'), Decimal('3'))
4102 Decimal('0.666666667')
4103 >>> ExtendedContext.divide(Decimal('5'), Decimal('2'))
4105 >>> ExtendedContext.divide(Decimal('1'), Decimal('10'))
4107 >>> ExtendedContext.divide(Decimal('12'), Decimal('12'))
4109 >>> ExtendedContext.divide(Decimal('8.00'), Decimal('2'))
4111 >>> ExtendedContext.divide(Decimal('2.400'), Decimal('2.0'))
4113 >>> ExtendedContext.divide(Decimal('1000'), Decimal('100'))
4115 >>> ExtendedContext.divide(Decimal('1000'), Decimal('1'))
4117 >>> ExtendedContext.divide(Decimal('2.40E+6'), Decimal('2'))
4120 return a
.__truediv
__(b
, context
=self
)
4122 def divide_int(self
, a
, b
):
4123 """Divides two numbers and returns the integer part of the result.
4125 >>> ExtendedContext.divide_int(Decimal('2'), Decimal('3'))
4127 >>> ExtendedContext.divide_int(Decimal('10'), Decimal('3'))
4129 >>> ExtendedContext.divide_int(Decimal('1'), Decimal('0.3'))
4132 return a
.__floordiv
__(b
, context
=self
)
4134 def divmod(self
, a
, b
):
4135 """Return (a // b, a % b)
4137 >>> ExtendedContext.divmod(Decimal(8), Decimal(3))
4138 (Decimal('2'), Decimal('2'))
4139 >>> ExtendedContext.divmod(Decimal(8), Decimal(4))
4140 (Decimal('2'), Decimal('0'))
4142 return a
.__divmod
__(b
, context
=self
)
4147 >>> c = ExtendedContext.copy()
4150 >>> c.exp(Decimal('-Infinity'))
4152 >>> c.exp(Decimal('-1'))
4153 Decimal('0.367879441')
4154 >>> c.exp(Decimal('0'))
4156 >>> c.exp(Decimal('1'))
4157 Decimal('2.71828183')
4158 >>> c.exp(Decimal('0.693147181'))
4159 Decimal('2.00000000')
4160 >>> c.exp(Decimal('+Infinity'))
4163 return a
.exp(context
=self
)
4165 def fma(self
, a
, b
, c
):
4166 """Returns a multiplied by b, plus c.
4168 The first two operands are multiplied together, using multiply,
4169 the third operand is then added to the result of that
4170 multiplication, using add, all with only one final rounding.
4172 >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
4174 >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))
4176 >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578'))
4177 Decimal('1.38435736E+12')
4179 return a
.fma(b
, c
, context
=self
)
4181 def is_canonical(self
, a
):
4182 """Return True if the operand is canonical; otherwise return False.
4184 Currently, the encoding of a Decimal instance is always
4185 canonical, so this method returns True for any Decimal.
4187 >>> ExtendedContext.is_canonical(Decimal('2.50'))
4190 return a
.is_canonical()
4192 def is_finite(self
, a
):
4193 """Return True if the operand is finite; otherwise return False.
4195 A Decimal instance is considered finite if it is neither
4198 >>> ExtendedContext.is_finite(Decimal('2.50'))
4200 >>> ExtendedContext.is_finite(Decimal('-0.3'))
4202 >>> ExtendedContext.is_finite(Decimal('0'))
4204 >>> ExtendedContext.is_finite(Decimal('Inf'))
4206 >>> ExtendedContext.is_finite(Decimal('NaN'))
4209 return a
.is_finite()
4211 def is_infinite(self
, a
):
4212 """Return True if the operand is infinite; otherwise return False.
4214 >>> ExtendedContext.is_infinite(Decimal('2.50'))
4216 >>> ExtendedContext.is_infinite(Decimal('-Inf'))
4218 >>> ExtendedContext.is_infinite(Decimal('NaN'))
4221 return a
.is_infinite()
4223 def is_nan(self
, a
):
4224 """Return True if the operand is a qNaN or sNaN;
4225 otherwise return False.
4227 >>> ExtendedContext.is_nan(Decimal('2.50'))
4229 >>> ExtendedContext.is_nan(Decimal('NaN'))
4231 >>> ExtendedContext.is_nan(Decimal('-sNaN'))
4236 def is_normal(self
, a
):
4237 """Return True if the operand is a normal number;
4238 otherwise return False.
4240 >>> c = ExtendedContext.copy()
4243 >>> c.is_normal(Decimal('2.50'))
4245 >>> c.is_normal(Decimal('0.1E-999'))
4247 >>> c.is_normal(Decimal('0.00'))
4249 >>> c.is_normal(Decimal('-Inf'))
4251 >>> c.is_normal(Decimal('NaN'))
4254 return a
.is_normal(context
=self
)
4256 def is_qnan(self
, a
):
4257 """Return True if the operand is a quiet NaN; otherwise return False.
4259 >>> ExtendedContext.is_qnan(Decimal('2.50'))
4261 >>> ExtendedContext.is_qnan(Decimal('NaN'))
4263 >>> ExtendedContext.is_qnan(Decimal('sNaN'))
4268 def is_signed(self
, a
):
4269 """Return True if the operand is negative; otherwise return False.
4271 >>> ExtendedContext.is_signed(Decimal('2.50'))
4273 >>> ExtendedContext.is_signed(Decimal('-12'))
4275 >>> ExtendedContext.is_signed(Decimal('-0'))
4278 return a
.is_signed()
4280 def is_snan(self
, a
):
4281 """Return True if the operand is a signaling NaN;
4282 otherwise return False.
4284 >>> ExtendedContext.is_snan(Decimal('2.50'))
4286 >>> ExtendedContext.is_snan(Decimal('NaN'))
4288 >>> ExtendedContext.is_snan(Decimal('sNaN'))
4293 def is_subnormal(self
, a
):
4294 """Return True if the operand is subnormal; otherwise return False.
4296 >>> c = ExtendedContext.copy()
4299 >>> c.is_subnormal(Decimal('2.50'))
4301 >>> c.is_subnormal(Decimal('0.1E-999'))
4303 >>> c.is_subnormal(Decimal('0.00'))
4305 >>> c.is_subnormal(Decimal('-Inf'))
4307 >>> c.is_subnormal(Decimal('NaN'))
4310 return a
.is_subnormal(context
=self
)
4312 def is_zero(self
, a
):
4313 """Return True if the operand is a zero; otherwise return False.
4315 >>> ExtendedContext.is_zero(Decimal('0'))
4317 >>> ExtendedContext.is_zero(Decimal('2.50'))
4319 >>> ExtendedContext.is_zero(Decimal('-0E+2'))
4325 """Returns the natural (base e) logarithm of the operand.
4327 >>> c = ExtendedContext.copy()
4330 >>> c.ln(Decimal('0'))
4331 Decimal('-Infinity')
4332 >>> c.ln(Decimal('1.000'))
4334 >>> c.ln(Decimal('2.71828183'))
4335 Decimal('1.00000000')
4336 >>> c.ln(Decimal('10'))
4337 Decimal('2.30258509')
4338 >>> c.ln(Decimal('+Infinity'))
4341 return a
.ln(context
=self
)
4344 """Returns the base 10 logarithm of the operand.
4346 >>> c = ExtendedContext.copy()
4349 >>> c.log10(Decimal('0'))
4350 Decimal('-Infinity')
4351 >>> c.log10(Decimal('0.001'))
4353 >>> c.log10(Decimal('1.000'))
4355 >>> c.log10(Decimal('2'))
4356 Decimal('0.301029996')
4357 >>> c.log10(Decimal('10'))
4359 >>> c.log10(Decimal('70'))
4360 Decimal('1.84509804')
4361 >>> c.log10(Decimal('+Infinity'))
4364 return a
.log10(context
=self
)
4367 """ Returns the exponent of the magnitude of the operand's MSD.
4369 The result is the integer which is the exponent of the magnitude
4370 of the most significant digit of the operand (as though the
4371 operand were truncated to a single digit while maintaining the
4372 value of that digit and without limiting the resulting exponent).
4374 >>> ExtendedContext.logb(Decimal('250'))
4376 >>> ExtendedContext.logb(Decimal('2.50'))
4378 >>> ExtendedContext.logb(Decimal('0.03'))
4380 >>> ExtendedContext.logb(Decimal('0'))
4381 Decimal('-Infinity')
4383 return a
.logb(context
=self
)
4385 def logical_and(self
, a
, b
):
4386 """Applies the logical operation 'and' between each operand's digits.
4388 The operands must be both logical numbers.
4390 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))
4392 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))
4394 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))
4396 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))
4398 >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))
4400 >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))
4403 return a
.logical_and(b
, context
=self
)
4405 def logical_invert(self
, a
):
4406 """Invert all the digits in the operand.
4408 The operand must be a logical number.
4410 >>> ExtendedContext.logical_invert(Decimal('0'))
4411 Decimal('111111111')
4412 >>> ExtendedContext.logical_invert(Decimal('1'))
4413 Decimal('111111110')
4414 >>> ExtendedContext.logical_invert(Decimal('111111111'))
4416 >>> ExtendedContext.logical_invert(Decimal('101010101'))
4419 return a
.logical_invert(context
=self
)
4421 def logical_or(self
, a
, b
):
4422 """Applies the logical operation 'or' between each operand's digits.
4424 The operands must be both logical numbers.
4426 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))
4428 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))
4430 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))
4432 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))
4434 >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))
4436 >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))
4439 return a
.logical_or(b
, context
=self
)
4441 def logical_xor(self
, a
, b
):
4442 """Applies the logical operation 'xor' between each operand's digits.
4444 The operands must be both logical numbers.
4446 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))
4448 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))
4450 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))
4452 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))
4454 >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))
4456 >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))
4459 return a
.logical_xor(b
, context
=self
)
4462 """max compares two values numerically and returns the maximum.
4464 If either operand is a NaN then the general rules apply.
4465 Otherwise, the operands are compared as though by the compare
4466 operation. If they are numerically equal then the left-hand operand
4467 is chosen as the result. Otherwise the maximum (closer to positive
4468 infinity) of the two operands is chosen as the result.
4470 >>> ExtendedContext.max(Decimal('3'), Decimal('2'))
4472 >>> ExtendedContext.max(Decimal('-10'), Decimal('3'))
4474 >>> ExtendedContext.max(Decimal('1.0'), Decimal('1'))
4476 >>> ExtendedContext.max(Decimal('7'), Decimal('NaN'))
4479 return a
.max(b
, context
=self
)
4481 def max_mag(self
, a
, b
):
4482 """Compares the values numerically with their sign ignored."""
4483 return a
.max_mag(b
, context
=self
)
4486 """min compares two values numerically and returns the minimum.
4488 If either operand is a NaN then the general rules apply.
4489 Otherwise, the operands are compared as though by the compare
4490 operation. If they are numerically equal then the left-hand operand
4491 is chosen as the result. Otherwise the minimum (closer to negative
4492 infinity) of the two operands is chosen as the result.
4494 >>> ExtendedContext.min(Decimal('3'), Decimal('2'))
4496 >>> ExtendedContext.min(Decimal('-10'), Decimal('3'))
4498 >>> ExtendedContext.min(Decimal('1.0'), Decimal('1'))
4500 >>> ExtendedContext.min(Decimal('7'), Decimal('NaN'))
4503 return a
.min(b
, context
=self
)
4505 def min_mag(self
, a
, b
):
4506 """Compares the values numerically with their sign ignored."""
4507 return a
.min_mag(b
, context
=self
)
4510 """Minus corresponds to unary prefix minus in Python.
4512 The operation is evaluated using the same rules as subtract; the
4513 operation minus(a) is calculated as subtract('0', a) where the '0'
4514 has the same exponent as the operand.
4516 >>> ExtendedContext.minus(Decimal('1.3'))
4518 >>> ExtendedContext.minus(Decimal('-1.3'))
4521 return a
.__neg
__(context
=self
)
4523 def multiply(self
, a
, b
):
4524 """multiply multiplies two operands.
4526 If either operand is a special value then the general rules apply.
4527 Otherwise, the operands are multiplied together ('long multiplication'),
4528 resulting in a number which may be as long as the sum of the lengths
4529 of the two operands.
4531 >>> ExtendedContext.multiply(Decimal('1.20'), Decimal('3'))
4533 >>> ExtendedContext.multiply(Decimal('7'), Decimal('3'))
4535 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('0.8'))
4537 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('-0'))
4539 >>> ExtendedContext.multiply(Decimal('654321'), Decimal('654321'))
4540 Decimal('4.28135971E+11')
4542 return a
.__mul
__(b
, context
=self
)
4544 def next_minus(self
, a
):
4545 """Returns the largest representable number smaller than a.
4547 >>> c = ExtendedContext.copy()
4550 >>> ExtendedContext.next_minus(Decimal('1'))
4551 Decimal('0.999999999')
4552 >>> c.next_minus(Decimal('1E-1007'))
4554 >>> ExtendedContext.next_minus(Decimal('-1.00000003'))
4555 Decimal('-1.00000004')
4556 >>> c.next_minus(Decimal('Infinity'))
4557 Decimal('9.99999999E+999')
4559 return a
.next_minus(context
=self
)
4561 def next_plus(self
, a
):
4562 """Returns the smallest representable number larger than a.
4564 >>> c = ExtendedContext.copy()
4567 >>> ExtendedContext.next_plus(Decimal('1'))
4568 Decimal('1.00000001')
4569 >>> c.next_plus(Decimal('-1E-1007'))
4571 >>> ExtendedContext.next_plus(Decimal('-1.00000003'))
4572 Decimal('-1.00000002')
4573 >>> c.next_plus(Decimal('-Infinity'))
4574 Decimal('-9.99999999E+999')
4576 return a
.next_plus(context
=self
)
4578 def next_toward(self
, a
, b
):
4579 """Returns the number closest to a, in direction towards b.
4581 The result is the closest representable number from the first
4582 operand (but not the first operand) that is in the direction
4583 towards the second operand, unless the operands have the same
4586 >>> c = ExtendedContext.copy()
4589 >>> c.next_toward(Decimal('1'), Decimal('2'))
4590 Decimal('1.00000001')
4591 >>> c.next_toward(Decimal('-1E-1007'), Decimal('1'))
4593 >>> c.next_toward(Decimal('-1.00000003'), Decimal('0'))
4594 Decimal('-1.00000002')
4595 >>> c.next_toward(Decimal('1'), Decimal('0'))
4596 Decimal('0.999999999')
4597 >>> c.next_toward(Decimal('1E-1007'), Decimal('-100'))
4599 >>> c.next_toward(Decimal('-1.00000003'), Decimal('-10'))
4600 Decimal('-1.00000004')
4601 >>> c.next_toward(Decimal('0.00'), Decimal('-0.0000'))
4604 return a
.next_toward(b
, context
=self
)
4606 def normalize(self
, a
):
4607 """normalize reduces an operand to its simplest form.
4609 Essentially a plus operation with all trailing zeros removed from the
4612 >>> ExtendedContext.normalize(Decimal('2.1'))
4614 >>> ExtendedContext.normalize(Decimal('-2.0'))
4616 >>> ExtendedContext.normalize(Decimal('1.200'))
4618 >>> ExtendedContext.normalize(Decimal('-120'))
4620 >>> ExtendedContext.normalize(Decimal('120.00'))
4622 >>> ExtendedContext.normalize(Decimal('0.00'))
4625 return a
.normalize(context
=self
)
4627 def number_class(self
, a
):
4628 """Returns an indication of the class of the operand.
4630 The class is one of the following strings:
4642 >>> c = Context(ExtendedContext)
4645 >>> c.number_class(Decimal('Infinity'))
4647 >>> c.number_class(Decimal('1E-10'))
4649 >>> c.number_class(Decimal('2.50'))
4651 >>> c.number_class(Decimal('0.1E-999'))
4653 >>> c.number_class(Decimal('0'))
4655 >>> c.number_class(Decimal('-0'))
4657 >>> c.number_class(Decimal('-0.1E-999'))
4659 >>> c.number_class(Decimal('-1E-10'))
4661 >>> c.number_class(Decimal('-2.50'))
4663 >>> c.number_class(Decimal('-Infinity'))
4665 >>> c.number_class(Decimal('NaN'))
4667 >>> c.number_class(Decimal('-NaN'))
4669 >>> c.number_class(Decimal('sNaN'))
4672 return a
.number_class(context
=self
)
4675 """Plus corresponds to unary prefix plus in Python.
4677 The operation is evaluated using the same rules as add; the
4678 operation plus(a) is calculated as add('0', a) where the '0'
4679 has the same exponent as the operand.
4681 >>> ExtendedContext.plus(Decimal('1.3'))
4683 >>> ExtendedContext.plus(Decimal('-1.3'))
4686 return a
.__pos
__(context
=self
)
4688 def power(self
, a
, b
, modulo
=None):
4689 """Raises a to the power of b, to modulo if given.
4691 With two arguments, compute a**b. If a is negative then b
4692 must be integral. The result will be inexact unless b is
4693 integral and the result is finite and can be expressed exactly
4694 in 'precision' digits.
4696 With three arguments, compute (a**b) % modulo. For the
4697 three argument form, the following restrictions on the
4700 - all three arguments must be integral
4701 - b must be nonnegative
4702 - at least one of a or b must be nonzero
4703 - modulo must be nonzero and have at most 'precision' digits
4705 The result of pow(a, b, modulo) is identical to the result
4706 that would be obtained by computing (a**b) % modulo with
4707 unbounded precision, but is computed more efficiently. It is
4710 >>> c = ExtendedContext.copy()
4713 >>> c.power(Decimal('2'), Decimal('3'))
4715 >>> c.power(Decimal('-2'), Decimal('3'))
4717 >>> c.power(Decimal('2'), Decimal('-3'))
4719 >>> c.power(Decimal('1.7'), Decimal('8'))
4720 Decimal('69.7575744')
4721 >>> c.power(Decimal('10'), Decimal('0.301029996'))
4722 Decimal('2.00000000')
4723 >>> c.power(Decimal('Infinity'), Decimal('-1'))
4725 >>> c.power(Decimal('Infinity'), Decimal('0'))
4727 >>> c.power(Decimal('Infinity'), Decimal('1'))
4729 >>> c.power(Decimal('-Infinity'), Decimal('-1'))
4731 >>> c.power(Decimal('-Infinity'), Decimal('0'))
4733 >>> c.power(Decimal('-Infinity'), Decimal('1'))
4734 Decimal('-Infinity')
4735 >>> c.power(Decimal('-Infinity'), Decimal('2'))
4737 >>> c.power(Decimal('0'), Decimal('0'))
4740 >>> c.power(Decimal('3'), Decimal('7'), Decimal('16'))
4742 >>> c.power(Decimal('-3'), Decimal('7'), Decimal('16'))
4744 >>> c.power(Decimal('-3'), Decimal('8'), Decimal('16'))
4746 >>> c.power(Decimal('3'), Decimal('7'), Decimal('-16'))
4748 >>> c.power(Decimal('23E12345'), Decimal('67E189'), Decimal('123456789'))
4750 >>> c.power(Decimal('-0'), Decimal('17'), Decimal('1729'))
4752 >>> c.power(Decimal('-23'), Decimal('0'), Decimal('65537'))
4755 return a
.__pow
__(b
, modulo
, context
=self
)
4757 def quantize(self
, a
, b
):
4758 """Returns a value equal to 'a' (rounded), having the exponent of 'b'.
4760 The coefficient of the result is derived from that of the left-hand
4761 operand. It may be rounded using the current rounding setting (if the
4762 exponent is being increased), multiplied by a positive power of ten (if
4763 the exponent is being decreased), or is unchanged (if the exponent is
4764 already equal to that of the right-hand operand).
4766 Unlike other operations, if the length of the coefficient after the
4767 quantize operation would be greater than precision then an Invalid
4768 operation condition is raised. This guarantees that, unless there is
4769 an error condition, the exponent of the result of a quantize is always
4770 equal to that of the right-hand operand.
4772 Also unlike other operations, quantize will never raise Underflow, even
4773 if the result is subnormal and inexact.
4775 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))
4777 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))
4779 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))
4781 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))
4783 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))
4785 >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))
4786 Decimal('-Infinity')
4787 >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))
4789 >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))
4791 >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))
4793 >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))
4795 >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))
4797 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))
4799 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))
4801 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))
4803 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))
4806 return a
.quantize(b
, context
=self
)
4809 """Just returns 10, as this is Decimal, :)
4811 >>> ExtendedContext.radix()
4816 def remainder(self
, a
, b
):
4817 """Returns the remainder from integer division.
4819 The result is the residue of the dividend after the operation of
4820 calculating integer division as described for divide-integer, rounded
4821 to precision digits if necessary. The sign of the result, if
4822 non-zero, is the same as that of the original dividend.
4824 This operation will fail under the same conditions as integer division
4825 (that is, if integer division on the same two operands would fail, the
4826 remainder cannot be calculated).
4828 >>> ExtendedContext.remainder(Decimal('2.1'), Decimal('3'))
4830 >>> ExtendedContext.remainder(Decimal('10'), Decimal('3'))
4832 >>> ExtendedContext.remainder(Decimal('-10'), Decimal('3'))
4834 >>> ExtendedContext.remainder(Decimal('10.2'), Decimal('1'))
4836 >>> ExtendedContext.remainder(Decimal('10'), Decimal('0.3'))
4838 >>> ExtendedContext.remainder(Decimal('3.6'), Decimal('1.3'))
4841 return a
.__mod
__(b
, context
=self
)
4843 def remainder_near(self
, a
, b
):
4844 """Returns to be "a - b * n", where n is the integer nearest the exact
4845 value of "x / b" (if two integers are equally near then the even one
4846 is chosen). If the result is equal to 0 then its sign will be the
4849 This operation will fail under the same conditions as integer division
4850 (that is, if integer division on the same two operands would fail, the
4851 remainder cannot be calculated).
4853 >>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))
4855 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))
4857 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))
4859 >>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))
4861 >>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))
4863 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))
4865 >>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))
4868 return a
.remainder_near(b
, context
=self
)
4870 def rotate(self
, a
, b
):
4871 """Returns a rotated copy of a, b times.
4873 The coefficient of the result is a rotated copy of the digits in
4874 the coefficient of the first operand. The number of places of
4875 rotation is taken from the absolute value of the second operand,
4876 with the rotation being to the left if the second operand is
4877 positive or to the right otherwise.
4879 >>> ExtendedContext.rotate(Decimal('34'), Decimal('8'))
4880 Decimal('400000003')
4881 >>> ExtendedContext.rotate(Decimal('12'), Decimal('9'))
4883 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('-2'))
4884 Decimal('891234567')
4885 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('0'))
4886 Decimal('123456789')
4887 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('+2'))
4888 Decimal('345678912')
4890 return a
.rotate(b
, context
=self
)
4892 def same_quantum(self
, a
, b
):
4893 """Returns True if the two operands have the same exponent.
4895 The result is never affected by either the sign or the coefficient of
4898 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))
4900 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))
4902 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))
4904 >>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))
4907 return a
.same_quantum(b
)
4909 def scaleb (self
, a
, b
):
4910 """Returns the first operand after adding the second value its exp.
4912 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('-2'))
4914 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('0'))
4916 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('3'))
4919 return a
.scaleb (b
, context
=self
)
4921 def shift(self
, a
, b
):
4922 """Returns a shifted copy of a, b times.
4924 The coefficient of the result is a shifted copy of the digits
4925 in the coefficient of the first operand. The number of places
4926 to shift is taken from the absolute value of the second operand,
4927 with the shift being to the left if the second operand is
4928 positive or to the right otherwise. Digits shifted into the
4929 coefficient are zeros.
4931 >>> ExtendedContext.shift(Decimal('34'), Decimal('8'))
4932 Decimal('400000000')
4933 >>> ExtendedContext.shift(Decimal('12'), Decimal('9'))
4935 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('-2'))
4937 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('0'))
4938 Decimal('123456789')
4939 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('+2'))
4940 Decimal('345678900')
4942 return a
.shift(b
, context
=self
)
4945 """Square root of a non-negative number to context precision.
4947 If the result must be inexact, it is rounded using the round-half-even
4950 >>> ExtendedContext.sqrt(Decimal('0'))
4952 >>> ExtendedContext.sqrt(Decimal('-0'))
4954 >>> ExtendedContext.sqrt(Decimal('0.39'))
4955 Decimal('0.624499800')
4956 >>> ExtendedContext.sqrt(Decimal('100'))
4958 >>> ExtendedContext.sqrt(Decimal('1'))
4960 >>> ExtendedContext.sqrt(Decimal('1.0'))
4962 >>> ExtendedContext.sqrt(Decimal('1.00'))
4964 >>> ExtendedContext.sqrt(Decimal('7'))
4965 Decimal('2.64575131')
4966 >>> ExtendedContext.sqrt(Decimal('10'))
4967 Decimal('3.16227766')
4968 >>> ExtendedContext.prec
4971 return a
.sqrt(context
=self
)
4973 def subtract(self
, a
, b
):
4974 """Return the difference between the two operands.
4976 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.07'))
4978 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.30'))
4980 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('2.07'))
4983 return a
.__sub
__(b
, context
=self
)
4985 def to_eng_string(self
, a
):
4986 """Converts a number to a string, using scientific notation.
4988 The operation is not affected by the context.
4990 return a
.to_eng_string(context
=self
)
4992 def to_sci_string(self
, a
):
4993 """Converts a number to a string, using scientific notation.
4995 The operation is not affected by the context.
4997 return a
.__str
__(context
=self
)
4999 def to_integral_exact(self
, a
):
5000 """Rounds to an integer.
5002 When the operand has a negative exponent, the result is the same
5003 as using the quantize() operation using the given operand as the
5004 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
5005 of the operand as the precision setting; Inexact and Rounded flags
5006 are allowed in this operation. The rounding mode is taken from the
5009 >>> ExtendedContext.to_integral_exact(Decimal('2.1'))
5011 >>> ExtendedContext.to_integral_exact(Decimal('100'))
5013 >>> ExtendedContext.to_integral_exact(Decimal('100.0'))
5015 >>> ExtendedContext.to_integral_exact(Decimal('101.5'))
5017 >>> ExtendedContext.to_integral_exact(Decimal('-101.5'))
5019 >>> ExtendedContext.to_integral_exact(Decimal('10E+5'))
5021 >>> ExtendedContext.to_integral_exact(Decimal('7.89E+77'))
5023 >>> ExtendedContext.to_integral_exact(Decimal('-Inf'))
5024 Decimal('-Infinity')
5026 return a
.to_integral_exact(context
=self
)
5028 def to_integral_value(self
, a
):
5029 """Rounds to an integer.
5031 When the operand has a negative exponent, the result is the same
5032 as using the quantize() operation using the given operand as the
5033 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
5034 of the operand as the precision setting, except that no flags will
5035 be set. The rounding mode is taken from the context.
5037 >>> ExtendedContext.to_integral_value(Decimal('2.1'))
5039 >>> ExtendedContext.to_integral_value(Decimal('100'))
5041 >>> ExtendedContext.to_integral_value(Decimal('100.0'))
5043 >>> ExtendedContext.to_integral_value(Decimal('101.5'))
5045 >>> ExtendedContext.to_integral_value(Decimal('-101.5'))
5047 >>> ExtendedContext.to_integral_value(Decimal('10E+5'))
5049 >>> ExtendedContext.to_integral_value(Decimal('7.89E+77'))
5051 >>> ExtendedContext.to_integral_value(Decimal('-Inf'))
5052 Decimal('-Infinity')
5054 return a
.to_integral_value(context
=self
)
5056 # the method name changed, but we provide also the old one, for compatibility
5057 to_integral
= to_integral_value
5059 class _WorkRep(object):
5060 __slots__
= ('sign','int','exp')
5063 # exp: None, int, or string
5065 def __init__(self
, value
=None):
5070 elif isinstance(value
, Decimal
):
5071 self
.sign
= value
._sign
5072 self
.int = int(value
._int
)
5073 self
.exp
= value
._exp
5075 # assert isinstance(value, tuple)
5076 self
.sign
= value
[0]
5081 return "(%r, %r, %r)" % (self
.sign
, self
.int, self
.exp
)
5087 def _normalize(op1
, op2
, prec
= 0):
5088 """Normalizes op1, op2 to have the same exp and length of coefficient.
5090 Done during addition.
5092 if op1
.exp
< op2
.exp
:
5099 # Let exp = min(tmp.exp - 1, tmp.adjusted() - precision - 1).
5100 # Then adding 10**exp to tmp has the same effect (after rounding)
5101 # as adding any positive quantity smaller than 10**exp; similarly
5102 # for subtraction. So if other is smaller than 10**exp we replace
5103 # it with 10**exp. This avoids tmp.exp - other.exp getting too large.
5104 tmp_len
= len(str(tmp
.int))
5105 other_len
= len(str(other
.int))
5106 exp
= tmp
.exp
+ min(-1, tmp_len
- prec
- 2)
5107 if other_len
+ other
.exp
- 1 < exp
:
5111 tmp
.int *= 10 ** (tmp
.exp
- other
.exp
)
5115 ##### Integer arithmetic functions used by ln, log10, exp and __pow__ #####
5117 # This function from Tim Peters was taken from here:
5118 # http://mail.python.org/pipermail/python-list/1999-July/007758.html
5119 # The correction being in the function definition is for speed, and
5120 # the whole function is not resolved with math.log because of avoiding
5121 # the use of floats.
5122 def _nbits(n
, correction
= {
5123 '0': 4, '1': 3, '2': 2, '3': 2,
5124 '4': 1, '5': 1, '6': 1, '7': 1,
5125 '8': 0, '9': 0, 'a': 0, 'b': 0,
5126 'c': 0, 'd': 0, 'e': 0, 'f': 0}):
5127 """Number of bits in binary representation of the positive integer n,
5131 raise ValueError("The argument to _nbits should be nonnegative.")
5133 return 4*len(hex_n
) - correction
[hex_n
[0]]
5135 def _sqrt_nearest(n
, a
):
5136 """Closest integer to the square root of the positive integer n. a is
5137 an initial approximation to the square root. Any positive integer
5138 will do for a, but the closer a is to the square root of n the
5139 faster convergence will be.
5142 if n
<= 0 or a
<= 0:
5143 raise ValueError("Both arguments to _sqrt_nearest should be positive.")
5147 b
, a
= a
, a
--n
//a
>>1
5150 def _rshift_nearest(x
, shift
):
5151 """Given an integer x and a nonnegative integer shift, return closest
5152 integer to x / 2**shift; use round-to-even in case of a tie.
5155 b
, q
= 1 << shift
, x
>> shift
5156 return q
+ (2*(x
& (b
-1)) + (q
&1) > b
)
5158 def _div_nearest(a
, b
):
5159 """Closest integer to a/b, a and b positive integers; rounds to even
5160 in the case of a tie.
5164 return q
+ (2*r
+ (q
&1) > b
)
5166 def _ilog(x
, M
, L
= 8):
5167 """Integer approximation to M*log(x/M), with absolute error boundable
5168 in terms only of x/M.
5170 Given positive integers x and M, return an integer approximation to
5171 M * log(x/M). For L = 8 and 0.1 <= x/M <= 10 the difference
5172 between the approximation and the exact result is at most 22. For
5173 L = 8 and 1.0 <= x/M <= 10.0 the difference is at most 15. In
5174 both cases these are upper bounds on the error; it will usually be
5177 # The basic algorithm is the following: let log1p be the function
5178 # log1p(x) = log(1+x). Then log(x/M) = log1p((x-M)/M). We use
5181 # log1p(y) = 2*log1p(y/(1+sqrt(1+y)))
5183 # repeatedly until the argument to log1p is small (< 2**-L in
5184 # absolute value). For small y we can use the Taylor series
5187 # log1p(y) ~ y - y**2/2 + y**3/3 - ... - (-y)**T/T
5189 # truncating at T such that y**T is small enough. The whole
5190 # computation is carried out in a form of fixed-point arithmetic,
5191 # with a real number z being represented by an integer
5192 # approximation to z*M. To avoid loss of precision, the y below
5193 # is actually an integer approximation to 2**R*y*M, where R is the
5194 # number of reductions performed so far.
5197 # argument reduction; R = number of reductions performed
5199 while (R
<= L
and abs(y
) << L
-R
>= M
or
5200 R
> L
and abs(y
) >> R
-L
>= M
):
5201 y
= _div_nearest((M
*y
) << 1,
5202 M
+ _sqrt_nearest(M
*(M
+_rshift_nearest(y
, R
)), M
))
5205 # Taylor series with T terms
5206 T
= -int(-10*len(str(M
))//(3*L
))
5207 yshift
= _rshift_nearest(y
, R
)
5208 w
= _div_nearest(M
, T
)
5209 for k
in range(T
-1, 0, -1):
5210 w
= _div_nearest(M
, k
) - _div_nearest(yshift
*w
, M
)
5212 return _div_nearest(w
*y
, M
)
5214 def _dlog10(c
, e
, p
):
5215 """Given integers c, e and p with c > 0, p >= 0, compute an integer
5216 approximation to 10**p * log10(c*10**e), with an absolute error of
5217 at most 1. Assumes that c*10**e is not exactly 1."""
5219 # increase precision by 2; compensate for this by dividing
5220 # final result by 100
5223 # write c*10**e as d*10**f with either:
5224 # f >= 0 and 1 <= d <= 10, or
5225 # f <= 0 and 0.1 <= d <= 1.
5226 # Thus for c*10**e close to 1, f = 0
5228 f
= e
+l
- (e
+l
>= 1)
5236 c
= _div_nearest(c
, 10**-k
)
5238 log_d
= _ilog(c
, M
) # error < 5 + 22 = 27
5239 log_10
= _log10_digits(p
) # error < 1
5240 log_d
= _div_nearest(log_d
*M
, log_10
)
5241 log_tenpower
= f
*M
# exact
5243 log_d
= 0 # error < 2.31
5244 log_tenpower
= _div_nearest(f
, 10**-p
) # error < 0.5
5246 return _div_nearest(log_tenpower
+log_d
, 100)
5249 """Given integers c, e and p with c > 0, compute an integer
5250 approximation to 10**p * log(c*10**e), with an absolute error of
5251 at most 1. Assumes that c*10**e is not exactly 1."""
5253 # Increase precision by 2. The precision increase is compensated
5254 # for at the end with a division by 100.
5257 # rewrite c*10**e as d*10**f with either f >= 0 and 1 <= d <= 10,
5258 # or f <= 0 and 0.1 <= d <= 1. Then we can compute 10**p * log(c*10**e)
5259 # as 10**p * log(d) + 10**p*f * log(10).
5261 f
= e
+l
- (e
+l
>= 1)
5263 # compute approximation to 10**p*log(d), with error < 27
5269 c
= _div_nearest(c
, 10**-k
) # error of <= 0.5 in c
5271 # _ilog magnifies existing error in c by a factor of at most 10
5272 log_d
= _ilog(c
, 10**p
) # error < 5 + 22 = 27
5274 # p <= 0: just approximate the whole thing by 0; error < 2.31
5277 # compute approximation to f*10**p*log(10), with error < 11.
5279 extra
= len(str(abs(f
)))-1
5281 # error in f * _log10_digits(p+extra) < |f| * 1 = |f|
5282 # after division, error < |f|/10**extra + 0.5 < 10 + 0.5 < 11
5283 f_log_ten
= _div_nearest(f
*_log10_digits(p
+extra
), 10**extra
)
5289 # error in sum < 11+27 = 38; error after division < 0.38 + 0.5 < 1
5290 return _div_nearest(f_log_ten
+ log_d
, 100)
5292 class _Log10Memoize(object):
5293 """Class to compute, store, and allow retrieval of, digits of the
5294 constant log(10) = 2.302585.... This constant is needed by
5295 Decimal.ln, Decimal.log10, Decimal.exp and Decimal.__pow__."""
5297 self
.digits
= "23025850929940456840179914546843642076011014886"
5299 def getdigits(self
, p
):
5300 """Given an integer p >= 0, return floor(10**p)*log(10).
5302 For example, self.getdigits(3) returns 2302.
5304 # digits are stored as a string, for quick conversion to
5305 # integer in the case that we've already computed enough
5306 # digits; the stored digits should always be correct
5307 # (truncated, not rounded to nearest).
5309 raise ValueError("p should be nonnegative")
5311 if p
>= len(self
.digits
):
5312 # compute p+3, p+6, p+9, ... digits; continue until at
5313 # least one of the extra digits is nonzero
5316 # compute p+extra digits, correct to within 1ulp
5318 digits
= str(_div_nearest(_ilog(10*M
, M
), 100))
5319 if digits
[-extra
:] != '0'*extra
:
5322 # keep all reliable digits so far; remove trailing zeros
5323 # and next nonzero digit
5324 self
.digits
= digits
.rstrip('0')[:-1]
5325 return int(self
.digits
[:p
+1])
5327 _log10_digits
= _Log10Memoize().getdigits
5329 def _iexp(x
, M
, L
=8):
5330 """Given integers x and M, M > 0, such that x/M is small in absolute
5331 value, compute an integer approximation to M*exp(x/M). For 0 <=
5332 x/M <= 2.4, the absolute error in the result is bounded by 60 (and
5333 is usually much smaller)."""
5335 # Algorithm: to compute exp(z) for a real number z, first divide z
5336 # by a suitable power R of 2 so that |z/2**R| < 2**-L. Then
5337 # compute expm1(z/2**R) = exp(z/2**R) - 1 using the usual Taylor
5340 # expm1(x) = x + x**2/2! + x**3/3! + ...
5342 # Now use the identity
5344 # expm1(2x) = expm1(x)*(expm1(x)+2)
5346 # R times to compute the sequence expm1(z/2**R),
5347 # expm1(z/2**(R-1)), ... , exp(z/2), exp(z).
5349 # Find R such that x/2**R/M <= 2**-L
5350 R
= _nbits((x
<<L
)//M
)
5352 # Taylor series. (2**L)**T > M
5353 T
= -int(-10*len(str(M
))//(3*L
))
5354 y
= _div_nearest(x
, T
)
5356 for i
in range(T
-1, 0, -1):
5357 y
= _div_nearest(x
*(Mshift
+ y
), Mshift
* i
)
5360 for k
in range(R
-1, -1, -1):
5362 y
= _div_nearest(y
*(y
+Mshift
), Mshift
)
5367 """Compute an approximation to exp(c*10**e), with p decimal places of
5370 Returns integers d, f such that:
5372 10**(p-1) <= d <= 10**p, and
5373 (d-1)*10**f < exp(c*10**e) < (d+1)*10**f
5375 In other words, d*10**f is an approximation to exp(c*10**e) with p
5376 digits of precision, and with an error in d of at most 1. This is
5377 almost, but not quite, the same as the error being < 1ulp: when d
5378 = 10**(p-1) the error could be up to 10 ulp."""
5380 # we'll call iexp with M = 10**(p+2), giving p+3 digits of precision
5383 # compute log(10) with extra precision = adjusted exponent of c*10**e
5384 extra
= max(0, e
+ len(str(c
)) - 1)
5387 # compute quotient c*10**e/(log(10)) = c*10**(e+q)/(log(10)*10**q),
5391 cshift
= c
*10**shift
5393 cshift
= c
//10**-shift
5394 quot
, rem
= divmod(cshift
, _log10_digits(q
))
5396 # reduce remainder back to original precision
5397 rem
= _div_nearest(rem
, 10**extra
)
5399 # error in result of _iexp < 120; error after division < 0.62
5400 return _div_nearest(_iexp(rem
, 10**p
), 1000), quot
- p
+ 3
5402 def _dpower(xc
, xe
, yc
, ye
, p
):
5403 """Given integers xc, xe, yc and ye representing Decimals x = xc*10**xe and
5404 y = yc*10**ye, compute x**y. Returns a pair of integers (c, e) such that:
5406 10**(p-1) <= c <= 10**p, and
5407 (c-1)*10**e < x**y < (c+1)*10**e
5409 in other words, c*10**e is an approximation to x**y with p digits
5410 of precision, and with an error in c of at most 1. (This is
5411 almost, but not quite, the same as the error being < 1ulp: when c
5412 == 10**(p-1) we can only guarantee error < 10ulp.)
5414 We assume that: x is positive and not equal to 1, and y is nonzero.
5417 # Find b such that 10**(b-1) <= |y| <= 10**b
5418 b
= len(str(abs(yc
))) + ye
5420 # log(x) = lxc*10**(-p-b-1), to p+b+1 places after the decimal point
5421 lxc
= _dlog(xc
, xe
, p
+b
+1)
5423 # compute product y*log(x) = yc*lxc*10**(-p-b-1+ye) = pc*10**(-p-1)
5426 pc
= lxc
*yc
*10**shift
5428 pc
= _div_nearest(lxc
*yc
, 10**-shift
)
5431 # we prefer a result that isn't exactly 1; this makes it
5432 # easier to compute a correctly rounded result in __pow__
5433 if ((len(str(xc
)) + xe
>= 1) == (yc
> 0)): # if x**y > 1:
5434 coeff
, exp
= 10**(p
-1)+1, 1-p
5436 coeff
, exp
= 10**p
-1, -p
5438 coeff
, exp
= _dexp(pc
, -(p
+1), p
+1)
5439 coeff
= _div_nearest(coeff
, 10)
5444 def _log10_lb(c
, correction
= {
5445 '1': 100, '2': 70, '3': 53, '4': 40, '5': 31,
5446 '6': 23, '7': 16, '8': 10, '9': 5}):
5447 """Compute a lower bound for 100*log10(c) for a positive integer c."""
5449 raise ValueError("The argument to _log10_lb should be nonnegative.")
5451 return 100*len(str_c
) - correction
[str_c
[0]]
5453 ##### Helper Functions ####################################################
5455 def _convert_other(other
, raiseit
=False):
5456 """Convert other to Decimal.
5458 Verifies that it's ok to use in an implicit construction.
5460 if isinstance(other
, Decimal
):
5462 if isinstance(other
, int):
5463 return Decimal(other
)
5465 raise TypeError("Unable to convert %s to Decimal" % other
)
5466 return NotImplemented
5468 ##### Setup Specific Contexts ############################################
5470 # The default context prototype used by Context()
5471 # Is mutable, so that new contexts can have different default values
5473 DefaultContext
= Context(
5474 prec
=28, rounding
=ROUND_HALF_EVEN
,
5475 traps
=[DivisionByZero
, Overflow
, InvalidOperation
],
5482 # Pre-made alternate contexts offered by the specification
5483 # Don't change these; the user should be able to select these
5484 # contexts and be able to reproduce results from other implementations
5487 BasicContext
= Context(
5488 prec
=9, rounding
=ROUND_HALF_UP
,
5489 traps
=[DivisionByZero
, Overflow
, InvalidOperation
, Clamped
, Underflow
],
5493 ExtendedContext
= Context(
5494 prec
=9, rounding
=ROUND_HALF_EVEN
,
5500 ##### crud for parsing strings #############################################
5502 # Regular expression used for parsing numeric strings. Additional
5505 # 1. Uncomment the two '\s*' lines to allow leading and/or trailing
5506 # whitespace. But note that the specification disallows whitespace in
5509 # 2. For finite numbers (not infinities and NaNs) the body of the
5510 # number between the optional sign and the optional exponent must have
5511 # at least one decimal digit, possibly after the decimal point. The
5512 # lookahead expression '(?=\d|\.\d)' checks this.
5515 _parser
= re
.compile(r
""" # A numeric string consists of:
5517 (?P<sign>[-+])? # an optional sign, followed by either...
5519 (?=\d|\.\d) # ...a number (with at least one digit)
5520 (?P<int>\d*) # having a (possibly empty) integer part
5521 (\.(?P<frac>\d*))? # followed by an optional fractional part
5522 (E(?P<exp>[-+]?\d+))? # followed by an optional exponent, or...
5524 Inf(inity)? # ...an infinity, or...
5526 (?P<signal>s)? # ...an (optionally signaling)
5528 (?P<diag>\d*) # with (possibly empty) diagnostic info.
5532 """, re
.VERBOSE | re
.IGNORECASE
).match
5534 _all_zeros
= re
.compile('0*$').match
5535 _exact_half
= re
.compile('50*$').match
5537 ##### PEP3101 support functions ##############################################
5538 # The functions in this section have little to do with the Decimal
5539 # class, and could potentially be reused or adapted for other pure
5540 # Python numeric classes that want to implement __format__
5542 # A format specifier for Decimal looks like:
5544 # [[fill]align][sign][0][minimumwidth][,][.precision][type]
5546 _parse_format_specifier_regex
= re
.compile(r
"""\A
5553 (?P<minimumwidth>(?!0)\d+)?
5554 (?P<thousands_sep>,)?
5555 (?:\.(?P<precision>0|(?!0)\d+))?
5556 (?P<type>[eEfFgGn%])?
5562 # The locale module is only needed for the 'n' format specifier. The
5563 # rest of the PEP 3101 code functions quite happily without it, so we
5564 # don't care too much if locale isn't present.
5566 import locale
as _locale
5570 def _parse_format_specifier(format_spec
, _localeconv
=None):
5571 """Parse and validate a format specifier.
5573 Turns a standard numeric format specifier into a dict, with the
5576 fill: fill character to pad field to minimum width
5577 align: alignment type, either '<', '>', '=' or '^'
5578 sign: either '+', '-' or ' '
5579 minimumwidth: nonnegative integer giving minimum width
5580 zeropad: boolean, indicating whether to pad with zeros
5581 thousands_sep: string to use as thousands separator, or ''
5582 grouping: grouping for thousands separators, in format
5584 decimal_point: string to use for decimal point
5585 precision: nonnegative integer giving precision, or None
5586 type: one of the characters 'eEfFgG%', or None
5589 m
= _parse_format_specifier_regex
.match(format_spec
)
5591 raise ValueError("Invalid format specifier: " + format_spec
)
5593 # get the dictionary
5594 format_dict
= m
.groupdict()
5596 # zeropad; defaults for fill and alignment. If zero padding
5597 # is requested, the fill and align fields should be absent.
5598 fill
= format_dict
['fill']
5599 align
= format_dict
['align']
5600 format_dict
['zeropad'] = (format_dict
['zeropad'] is not None)
5601 if format_dict
['zeropad']:
5602 if fill
is not None:
5603 raise ValueError("Fill character conflicts with '0'"
5604 " in format specifier: " + format_spec
)
5605 if align
is not None:
5606 raise ValueError("Alignment conflicts with '0' in "
5607 "format specifier: " + format_spec
)
5608 format_dict
['fill'] = fill
or ' '
5609 format_dict
['align'] = align
or '<'
5611 # default sign handling: '-' for negative, '' for positive
5612 if format_dict
['sign'] is None:
5613 format_dict
['sign'] = '-'
5615 # minimumwidth defaults to 0; precision remains None if not given
5616 format_dict
['minimumwidth'] = int(format_dict
['minimumwidth'] or '0')
5617 if format_dict
['precision'] is not None:
5618 format_dict
['precision'] = int(format_dict
['precision'])
5620 # if format type is 'g' or 'G' then a precision of 0 makes little
5621 # sense; convert it to 1. Same if format type is unspecified.
5622 if format_dict
['precision'] == 0:
5623 if format_dict
['type'] is None or format_dict
['type'] in 'gG':
5624 format_dict
['precision'] = 1
5626 # determine thousands separator, grouping, and decimal separator, and
5627 # add appropriate entries to format_dict
5628 if format_dict
['type'] == 'n':
5629 # apart from separators, 'n' behaves just like 'g'
5630 format_dict
['type'] = 'g'
5631 if _localeconv
is None:
5632 _localeconv
= _locale
.localeconv()
5633 if format_dict
['thousands_sep'] is not None:
5634 raise ValueError("Explicit thousands separator conflicts with "
5635 "'n' type in format specifier: " + format_spec
)
5636 format_dict
['thousands_sep'] = _localeconv
['thousands_sep']
5637 format_dict
['grouping'] = _localeconv
['grouping']
5638 format_dict
['decimal_point'] = _localeconv
['decimal_point']
5640 if format_dict
['thousands_sep'] is None:
5641 format_dict
['thousands_sep'] = ''
5642 format_dict
['grouping'] = [3, 0]
5643 format_dict
['decimal_point'] = '.'
5647 def _format_align(sign
, body
, spec
):
5648 """Given an unpadded, non-aligned numeric string 'body' and sign
5649 string 'sign', add padding and aligment conforming to the given
5650 format specifier dictionary 'spec' (as produced by
5651 parse_format_specifier).
5654 # how much extra space do we have to play with?
5655 minimumwidth
= spec
['minimumwidth']
5657 padding
= fill
*(minimumwidth
- len(sign
) - len(body
))
5659 align
= spec
['align']
5661 result
= sign
+ body
+ padding
5663 result
= padding
+ sign
+ body
5665 result
= sign
+ padding
+ body
5667 half
= len(padding
)//2
5668 result
= padding
[:half
] + sign
+ body
+ padding
[half
:]
5670 raise ValueError('Unrecognised alignment field')
5674 def _group_lengths(grouping
):
5675 """Convert a localeconv-style grouping into a (possibly infinite)
5676 iterable of integers representing group lengths.
5679 # The result from localeconv()['grouping'], and the input to this
5680 # function, should be a list of integers in one of the
5681 # following three forms:
5683 # (1) an empty list, or
5684 # (2) nonempty list of positive integers + [0]
5685 # (3) list of positive integers + [locale.CHAR_MAX], or
5687 from itertools
import chain
, repeat
5690 elif grouping
[-1] == 0 and len(grouping
) >= 2:
5691 return chain(grouping
[:-1], repeat(grouping
[-2]))
5692 elif grouping
[-1] == _locale
.CHAR_MAX
:
5693 return grouping
[:-1]
5695 raise ValueError('unrecognised format for grouping')
5697 def _insert_thousands_sep(digits
, spec
, min_width
=1):
5698 """Insert thousands separators into a digit string.
5700 spec is a dictionary whose keys should include 'thousands_sep' and
5701 'grouping'; typically it's the result of parsing the format
5702 specifier using _parse_format_specifier.
5704 The min_width keyword argument gives the minimum length of the
5705 result, which will be padded on the left with zeros if necessary.
5707 If necessary, the zero padding adds an extra '0' on the left to
5708 avoid a leading thousands separator. For example, inserting
5709 commas every three digits in '123456', with min_width=8, gives
5710 '0,123,456', even though that has length 9.
5714 sep
= spec
['thousands_sep']
5715 grouping
= spec
['grouping']
5718 for l
in _group_lengths(grouping
):
5720 raise ValueError("group length should be positive")
5721 # max(..., 1) forces at least 1 digit to the left of a separator
5722 l
= min(max(len(digits
), min_width
, 1), l
)
5723 groups
.append('0'*(l
- len(digits
)) + digits
[-l
:])
5724 digits
= digits
[:-l
]
5726 if not digits
and min_width
<= 0:
5728 min_width
-= len(sep
)
5730 l
= max(len(digits
), min_width
, 1)
5731 groups
.append('0'*(l
- len(digits
)) + digits
[-l
:])
5732 return sep
.join(reversed(groups
))
5734 def _format_sign(is_negative
, spec
):
5735 """Determine sign character."""
5739 elif spec
['sign'] in ' +':
5744 def _format_number(is_negative
, intpart
, fracpart
, exp
, spec
):
5745 """Format a number, given the following data:
5747 is_negative: true if the number is negative, else false
5748 intpart: string of digits that must appear before the decimal point
5749 fracpart: string of digits that must come after the point
5750 exp: exponent, as an integer
5751 spec: dictionary resulting from parsing the format specifier
5753 This function uses the information in spec to:
5754 insert separators (decimal separator and thousands separators)
5757 add trailing '%' for the '%' type
5758 zero-pad if necessary
5759 fill and align if necessary
5762 sign
= _format_sign(is_negative
, spec
)
5765 fracpart
= spec
['decimal_point'] + fracpart
5767 if exp
!= 0 or spec
['type'] in 'eE':
5768 echar
= {'E': 'E', 'e': 'e', 'G': 'E', 'g': 'e'}[spec
['type']]
5769 fracpart
+= "{0}{1:+}".format(echar
, exp
)
5770 if spec
['type'] == '%':
5774 min_width
= spec
['minimumwidth'] - len(fracpart
) - len(sign
)
5777 intpart
= _insert_thousands_sep(intpart
, spec
, min_width
)
5779 return _format_align(sign
, intpart
+fracpart
, spec
)
5782 ##### Useful Constants (internal use only) ################################
5785 _Infinity
= Decimal('Inf')
5786 _NegativeInfinity
= Decimal('-Inf')
5787 _NaN
= Decimal('NaN')
5790 _NegativeOne
= Decimal(-1)
5792 # _SignedInfinity[sign] is infinity w/ that sign
5793 _SignedInfinity
= (_Infinity
, _NegativeInfinity
)
5797 if __name__
== '__main__':
5799 doctest
.testmod(sys
.modules
[__name__
])