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 is currently Py2.3 compatible and should be kept that way
11 # unless a major compelling advantage arises. IOW, 2.3 compatibility is
12 # strongly preferred, but not guaranteed.
14 # Also, this module should be kept in sync with the latest updates of
15 # the IBM specification as it evolves. Those updates will be treated
16 # as bug fixes (deviation from the spec is a compatibility, usability
17 # bug) and will be backported. At this point the spec is stabilizing
18 # and the updates are becoming fewer, smaller, and less significant.
21 This is a Py2.3 implementation of decimal floating point arithmetic based on
22 the General Decimal Arithmetic Specification:
24 http://speleotrove.com/decimal/decarith.html
26 and IEEE standard 854-1987:
28 www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html
30 Decimal floating point has finite precision with arbitrarily large bounds.
32 The purpose of this module is to support arithmetic using familiar
33 "schoolhouse" rules and to avoid some of the tricky representation
34 issues associated with binary floating point. The package is especially
35 useful for financial applications or for contexts where users have
36 expectations that are at odds with binary floating point (for instance,
37 in binary floating point, 1.00 % 0.1 gives 0.09999999999999995 instead
38 of the expected Decimal('0.00') returned by decimal floating point).
40 Here are some examples of using the decimal module:
42 >>> from decimal import *
43 >>> setcontext(ExtendedContext)
52 >>> Decimal('123.45e12345678901234567890')
53 Decimal('1.2345E+12345678901234567892')
54 >>> Decimal('1.33') + Decimal('1.27')
56 >>> Decimal('12.34') + Decimal('3.87') - Decimal('18.41')
59 >>> print dig / Decimal(3)
61 >>> getcontext().prec = 18
62 >>> print dig / Decimal(3)
66 >>> print Decimal(3).sqrt()
68 >>> print Decimal(3) ** 123
69 4.85192780976896427E+58
70 >>> inf = Decimal(1) / Decimal(0)
73 >>> neginf = Decimal(-1) / Decimal(0)
76 >>> print neginf + inf
78 >>> print neginf * inf
82 >>> getcontext().traps[DivisionByZero] = 1
84 Traceback (most recent call last):
90 >>> c.traps[InvalidOperation] = 0
91 >>> print c.flags[InvalidOperation]
93 >>> c.divide(Decimal(0), Decimal(0))
95 >>> c.traps[InvalidOperation] = 1
96 >>> print c.flags[InvalidOperation]
98 >>> c.flags[InvalidOperation] = 0
99 >>> print c.flags[InvalidOperation]
101 >>> print c.divide(Decimal(0), Decimal(0))
102 Traceback (most recent call last):
106 InvalidOperation: 0 / 0
107 >>> print c.flags[InvalidOperation]
109 >>> c.flags[InvalidOperation] = 0
110 >>> c.traps[InvalidOperation] = 0
111 >>> print c.divide(Decimal(0), Decimal(0))
113 >>> print c.flags[InvalidOperation]
120 'Decimal', 'Context',
123 'DefaultContext', 'BasicContext', 'ExtendedContext',
126 'DecimalException', 'Clamped', 'InvalidOperation', 'DivisionByZero',
127 'Inexact', 'Rounded', 'Subnormal', 'Overflow', 'Underflow',
129 # Constants for use in setting up contexts
130 'ROUND_DOWN', 'ROUND_HALF_UP', 'ROUND_HALF_EVEN', 'ROUND_CEILING',
131 'ROUND_FLOOR', 'ROUND_UP', 'ROUND_HALF_DOWN', 'ROUND_05UP',
133 # Functions for manipulating contexts
134 'setcontext', 'getcontext', 'localcontext'
137 __version__ = '1.70' # Highest version of the spec this complies with
141 import numbers as _numbers
144 from collections import namedtuple as _namedtuple
145 DecimalTuple = _namedtuple('DecimalTuple', 'sign digits exponent')
147 DecimalTuple = lambda *args: args
150 ROUND_DOWN = 'ROUND_DOWN'
151 ROUND_HALF_UP = 'ROUND_HALF_UP'
152 ROUND_HALF_EVEN = 'ROUND_HALF_EVEN'
153 ROUND_CEILING = 'ROUND_CEILING'
154 ROUND_FLOOR = 'ROUND_FLOOR'
155 ROUND_UP = 'ROUND_UP'
156 ROUND_HALF_DOWN = 'ROUND_HALF_DOWN'
157 ROUND_05UP = 'ROUND_05UP'
161 class DecimalException(ArithmeticError):
162 """Base exception class.
164 Used exceptions derive from this.
165 If an exception derives from another exception besides this (such as
166 Underflow (Inexact, Rounded, Subnormal) that indicates that it is only
167 called if the others are present. This isn't actually used for
170 handle -- Called when context._raise_error is called and the
171 trap_enabler is not set. First argument is self, second is the
172 context. More arguments can be given, those being after
173 the explanation in _raise_error (For example,
174 context._raise_error(NewError, '(-x)!', self._sign) would
175 call NewError().handle(context, self._sign).)
177 To define a new exception, it should be sufficient to have it derive
178 from DecimalException.
180 def handle(self, context, *args):
184 class Clamped(DecimalException):
185 """Exponent of a 0 changed to fit bounds.
187 This occurs and signals clamped if the exponent of a result has been
188 altered in order to fit the constraints of a specific concrete
189 representation. This may occur when the exponent of a zero result would
190 be outside the bounds of a representation, or when a large normal
191 number would have an encoded exponent that cannot be represented. In
192 this latter case, the exponent is reduced to fit and the corresponding
193 number of zero digits are appended to the coefficient ("fold-down").
196 class InvalidOperation(DecimalException):
197 """An invalid operation was performed.
199 Various bad things cause this:
201 Something creates a signaling NaN
207 x._rescale( non-integer )
212 An operand is invalid
214 The result of the operation after these is a quiet positive NaN,
215 except when the cause is a signaling NaN, in which case the result is
216 also a quiet NaN, but with the original sign, and an optional
217 diagnostic information.
219 def handle(self, context, *args):
221 ans = _dec_from_triple(args[0]._sign, args[0]._int, 'n', True)
222 return ans._fix_nan(context)
225 class ConversionSyntax(InvalidOperation):
226 """Trying to convert badly formed string.
228 This occurs and signals invalid-operation if an string is being
229 converted to a number and it does not conform to the numeric string
230 syntax. The result is [0,qNaN].
232 def handle(self, context, *args):
235 class DivisionByZero(DecimalException, ZeroDivisionError):
238 This occurs and signals division-by-zero if division of a finite number
239 by zero was attempted (during a divide-integer or divide operation, or a
240 power operation with negative right-hand operand), and the dividend was
243 The result of the operation is [sign,inf], where sign is the exclusive
244 or of the signs of the operands for divide, or is 1 for an odd power of
248 def handle(self, context, sign, *args):
249 return _SignedInfinity[sign]
251 class DivisionImpossible(InvalidOperation):
252 """Cannot perform the division adequately.
254 This occurs and signals invalid-operation if the integer result of a
255 divide-integer or remainder operation had too many digits (would be
256 longer than precision). The result is [0,qNaN].
259 def handle(self, context, *args):
262 class DivisionUndefined(InvalidOperation, ZeroDivisionError):
263 """Undefined result of division.
265 This occurs and signals invalid-operation if division by zero was
266 attempted (during a divide-integer, divide, or remainder operation), and
267 the dividend is also zero. The result is [0,qNaN].
270 def handle(self, context, *args):
273 class Inexact(DecimalException):
274 """Had to round, losing information.
276 This occurs and signals inexact whenever the result of an operation is
277 not exact (that is, it needed to be rounded and any discarded digits
278 were non-zero), or if an overflow or underflow condition occurs. The
279 result in all cases is unchanged.
281 The inexact signal may be tested (or trapped) to determine if a given
282 operation (or sequence of operations) was inexact.
285 class InvalidContext(InvalidOperation):
286 """Invalid context. Unknown rounding, for example.
288 This occurs and signals invalid-operation if an invalid context was
289 detected during an operation. This can occur if contexts are not checked
290 on creation and either the precision exceeds the capability of the
291 underlying concrete representation or an unknown or unsupported rounding
292 was specified. These aspects of the context need only be checked when
293 the values are required to be used. The result is [0,qNaN].
296 def handle(self, context, *args):
299 class Rounded(DecimalException):
300 """Number got rounded (not necessarily changed during rounding).
302 This occurs and signals rounded whenever the result of an operation is
303 rounded (that is, some zero or non-zero digits were discarded from the
304 coefficient), or if an overflow or underflow condition occurs. The
305 result in all cases is unchanged.
307 The rounded signal may be tested (or trapped) to determine if a given
308 operation (or sequence of operations) caused a loss of precision.
311 class Subnormal(DecimalException):
312 """Exponent < Emin before rounding.
314 This occurs and signals subnormal whenever the result of a conversion or
315 operation is subnormal (that is, its adjusted exponent is less than
316 Emin, before any rounding). The result in all cases is unchanged.
318 The subnormal signal may be tested (or trapped) to determine if a given
319 or operation (or sequence of operations) yielded a subnormal result.
322 class Overflow(Inexact, Rounded):
323 """Numerical overflow.
325 This occurs and signals overflow if the adjusted exponent of a result
326 (from a conversion or from an operation that is not an attempt to divide
327 by zero), after rounding, would be greater than the largest value that
328 can be handled by the implementation (the value Emax).
330 The result depends on the rounding mode:
332 For round-half-up and round-half-even (and for round-half-down and
333 round-up, if implemented), the result of the operation is [sign,inf],
334 where sign is the sign of the intermediate result. For round-down, the
335 result is the largest finite number that can be represented in the
336 current precision, with the sign of the intermediate result. For
337 round-ceiling, the result is the same as for round-down if the sign of
338 the intermediate result is 1, or is [0,inf] otherwise. For round-floor,
339 the result is the same as for round-down if the sign of the intermediate
340 result is 0, or is [1,inf] otherwise. In all cases, Inexact and Rounded
344 def handle(self, context, sign, *args):
345 if context.rounding in (ROUND_HALF_UP, ROUND_HALF_EVEN,
346 ROUND_HALF_DOWN, ROUND_UP):
347 return _SignedInfinity[sign]
349 if context.rounding == ROUND_CEILING:
350 return _SignedInfinity[sign]
351 return _dec_from_triple(sign, '9'*context.prec,
352 context.Emax-context.prec+1)
354 if context.rounding == ROUND_FLOOR:
355 return _SignedInfinity[sign]
356 return _dec_from_triple(sign, '9'*context.prec,
357 context.Emax-context.prec+1)
360 class Underflow(Inexact, Rounded, Subnormal):
361 """Numerical underflow with result rounded to 0.
363 This occurs and signals underflow if a result is inexact and the
364 adjusted exponent of the result would be smaller (more negative) than
365 the smallest value that can be handled by the implementation (the value
366 Emin). That is, the result is both inexact and subnormal.
368 The result after an underflow will be a subnormal number rounded, if
369 necessary, so that its exponent is not less than Etiny. This may result
370 in 0 with the sign of the intermediate result and an exponent of Etiny.
372 In all cases, Inexact, Rounded, and Subnormal will also be raised.
375 # List of public traps and flags
376 _signals = [Clamped, DivisionByZero, Inexact, Overflow, Rounded,
377 Underflow, InvalidOperation, Subnormal]
379 # Map conditions (per the spec) to signals
380 _condition_map = {ConversionSyntax:InvalidOperation,
381 DivisionImpossible:InvalidOperation,
382 DivisionUndefined:InvalidOperation,
383 InvalidContext:InvalidOperation}
385 ##### Context Functions ##################################################
387 # The getcontext() and setcontext() function manage access to a thread-local
388 # current context. Py2.4 offers direct support for thread locals. If that
389 # is not available, use threading.currentThread() which is slower but will
390 # work for older Pythons. If threads are not part of the build, create a
391 # mock threading object with threading.local() returning the module namespace.
396 # Python was compiled without threads; create a mock object instead
398 class MockThreading(object):
399 def local(self, sys=sys):
400 return sys.modules[__name__]
401 threading = MockThreading()
402 del sys, MockThreading
407 except AttributeError:
409 # To fix reloading, force it to create a new context
410 # Old contexts have different exceptions in their dicts, making problems.
411 if hasattr(threading.currentThread(), '__decimal_context__'):
412 del threading.currentThread().__decimal_context__
414 def setcontext(context):
415 """Set this thread's context to context."""
416 if context in (DefaultContext, BasicContext, ExtendedContext):
417 context = context.copy()
418 context.clear_flags()
419 threading.currentThread().__decimal_context__ = context
422 """Returns this thread's context.
424 If this thread does not yet have a context, returns
425 a new context and sets this thread's context.
426 New contexts are copies of DefaultContext.
429 return threading.currentThread().__decimal_context__
430 except AttributeError:
432 threading.currentThread().__decimal_context__ = context
437 local = threading.local()
438 if hasattr(local, '__decimal_context__'):
439 del local.__decimal_context__
441 def getcontext(_local=local):
442 """Returns this thread's context.
444 If this thread does not yet have a context, returns
445 a new context and sets this thread's context.
446 New contexts are copies of DefaultContext.
449 return _local.__decimal_context__
450 except AttributeError:
452 _local.__decimal_context__ = context
455 def setcontext(context, _local=local):
456 """Set this thread's context to context."""
457 if context in (DefaultContext, BasicContext, ExtendedContext):
458 context = context.copy()
459 context.clear_flags()
460 _local.__decimal_context__ = context
462 del threading, local # Don't contaminate the namespace
464 def localcontext(ctx=None):
465 """Return a context manager for a copy of the supplied context
467 Uses a copy of the current context if no context is specified
468 The returned context manager creates a local decimal context
471 with localcontext() as ctx:
473 # Rest of sin calculation algorithm
474 # uses a precision 2 greater than normal
475 return +s # Convert result to normal precision
478 with localcontext(ExtendedContext):
479 # Rest of sin calculation algorithm
480 # uses the Extended Context from the
481 # General Decimal Arithmetic Specification
482 return +s # Convert result to normal context
484 >>> setcontext(DefaultContext)
485 >>> print getcontext().prec
487 >>> with localcontext():
488 ... ctx = getcontext()
493 >>> with localcontext(ExtendedContext):
494 ... print getcontext().prec
497 >>> print getcontext().prec
500 if ctx is None: ctx = getcontext()
501 return _ContextManager(ctx)
504 ##### Decimal class #######################################################
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 or long
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, basestring):
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,long)):
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, long)) 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, long)) 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, long)):
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 value = Decimal.from_float(value)
652 self._exp = value._exp
653 self._sign = value._sign
654 self._int = value._int
655 self._is_special = value._is_special
658 raise TypeError("Cannot convert %r to Decimal" % value)
660 # @classmethod, but @decorator is not valid Python 2.3 syntax, so
661 # don't use it (see notes on Py2.3 compatibility at top of file)
662 def from_float(cls, f):
663 """Converts a float to a decimal number, exactly.
665 Note that Decimal.from_float(0.1) is not the same as Decimal('0.1').
666 Since 0.1 is not exactly representable in binary floating point, the
667 value is stored as the nearest representable value which is
668 0x1.999999999999ap-4. The exact equivalent of the value in decimal
669 is 0.1000000000000000055511151231257827021181583404541015625.
671 >>> Decimal.from_float(0.1)
672 Decimal('0.1000000000000000055511151231257827021181583404541015625')
673 >>> Decimal.from_float(float('nan'))
675 >>> Decimal.from_float(float('inf'))
677 >>> Decimal.from_float(-float('inf'))
679 >>> Decimal.from_float(-0.0)
683 if isinstance(f, (int, long)): # handle integer inputs
685 if _math.isinf(f) or _math.isnan(f): # raises TypeError if not a float
687 if _math.copysign(1.0, f) == 1.0:
691 n, d = abs(f).as_integer_ratio()
692 k = d.bit_length() - 1
693 result = _dec_from_triple(sign, str(n*5**k), -k)
698 from_float = classmethod(from_float)
701 """Returns whether the number is not actually one.
715 def _isinfinity(self):
716 """Returns whether the number is infinite
718 0 if finite or not a number
728 def _check_nans(self, other=None, context=None):
729 """Returns whether the number is not actually one.
731 if self, other are sNaN, signal
732 if self, other are NaN return nan
735 Done before operations.
738 self_is_nan = self._isnan()
742 other_is_nan = other._isnan()
744 if self_is_nan or other_is_nan:
746 context = getcontext()
749 return context._raise_error(InvalidOperation, 'sNaN',
751 if other_is_nan == 2:
752 return context._raise_error(InvalidOperation, 'sNaN',
755 return self._fix_nan(context)
757 return other._fix_nan(context)
760 def _compare_check_nans(self, other, context):
761 """Version of _check_nans used for the signaling comparisons
762 compare_signal, __le__, __lt__, __ge__, __gt__.
764 Signal InvalidOperation if either self or other is a (quiet
765 or signaling) NaN. Signaling NaNs take precedence over quiet
768 Return 0 if neither operand is a NaN.
772 context = getcontext()
774 if self._is_special or other._is_special:
776 return context._raise_error(InvalidOperation,
777 'comparison involving sNaN',
779 elif other.is_snan():
780 return context._raise_error(InvalidOperation,
781 'comparison involving sNaN',
784 return context._raise_error(InvalidOperation,
785 'comparison involving NaN',
787 elif other.is_qnan():
788 return context._raise_error(InvalidOperation,
789 'comparison involving NaN',
793 def __nonzero__(self):
794 """Return True if self is nonzero; otherwise return False.
796 NaNs and infinities are considered nonzero.
798 return self._is_special or self._int != '0'
800 def _cmp(self, other):
801 """Compare the two non-NaN decimal instances self and other.
803 Returns -1 if self < other, 0 if self == other and 1
804 if self > other. This routine is for internal use only."""
806 if self._is_special or other._is_special:
807 self_inf = self._isinfinity()
808 other_inf = other._isinfinity()
809 if self_inf == other_inf:
811 elif self_inf < other_inf:
816 # check for zeros; Decimal('0') == Decimal('-0')
821 return -((-1)**other._sign)
823 return (-1)**self._sign
825 # If different signs, neg one is less
826 if other._sign < self._sign:
828 if self._sign < other._sign:
831 self_adjusted = self.adjusted()
832 other_adjusted = other.adjusted()
833 if self_adjusted == other_adjusted:
834 self_padded = self._int + '0'*(self._exp - other._exp)
835 other_padded = other._int + '0'*(other._exp - self._exp)
836 if self_padded == other_padded:
838 elif self_padded < other_padded:
839 return -(-1)**self._sign
841 return (-1)**self._sign
842 elif self_adjusted > other_adjusted:
843 return (-1)**self._sign
844 else: # self_adjusted < other_adjusted
845 return -((-1)**self._sign)
847 # Note: The Decimal standard doesn't cover rich comparisons for
848 # Decimals. In particular, the specification is silent on the
849 # subject of what should happen for a comparison involving a NaN.
850 # We take the following approach:
852 # == comparisons involving a quiet NaN always return False
853 # != comparisons involving a quiet NaN always return True
854 # == or != comparisons involving a signaling NaN signal
855 # InvalidOperation, and return False or True as above if the
856 # InvalidOperation is not trapped.
857 # <, >, <= and >= comparisons involving a (quiet or signaling)
858 # NaN signal InvalidOperation, and return False if the
859 # InvalidOperation is not trapped.
861 # This behavior is designed to conform as closely as possible to
862 # that specified by IEEE 754.
864 def __eq__(self, other, context=None):
865 other = _convert_other(other, allow_float=True)
866 if other is NotImplemented:
868 if self._check_nans(other, context):
870 return self._cmp(other) == 0
872 def __ne__(self, other, context=None):
873 other = _convert_other(other, allow_float=True)
874 if other is NotImplemented:
876 if self._check_nans(other, context):
878 return self._cmp(other) != 0
880 def __lt__(self, other, context=None):
881 other = _convert_other(other, allow_float=True)
882 if other is NotImplemented:
884 ans = self._compare_check_nans(other, context)
887 return self._cmp(other) < 0
889 def __le__(self, other, context=None):
890 other = _convert_other(other, allow_float=True)
891 if other is NotImplemented:
893 ans = self._compare_check_nans(other, context)
896 return self._cmp(other) <= 0
898 def __gt__(self, other, context=None):
899 other = _convert_other(other, allow_float=True)
900 if other is NotImplemented:
902 ans = self._compare_check_nans(other, context)
905 return self._cmp(other) > 0
907 def __ge__(self, other, context=None):
908 other = _convert_other(other, allow_float=True)
909 if other is NotImplemented:
911 ans = self._compare_check_nans(other, context)
914 return self._cmp(other) >= 0
916 def compare(self, other, context=None):
917 """Compares one to another.
923 Like __cmp__, but returns Decimal instances.
925 other = _convert_other(other, raiseit=True)
927 # Compare(NaN, NaN) = NaN
928 if (self._is_special or other and other._is_special):
929 ans = self._check_nans(other, context)
933 return Decimal(self._cmp(other))
936 """x.__hash__() <==> hash(x)"""
937 # Decimal integers must hash the same as the ints
939 # The hash of a nonspecial noninteger Decimal must depend only
940 # on the value of that Decimal, and not on its representation.
941 # For example: hash(Decimal('100E-1')) == hash(Decimal('10')).
943 # Equality comparisons involving signaling nans can raise an
944 # exception; since equality checks are implicitly and
945 # unpredictably used when checking set and dict membership, we
946 # prevent signaling nans from being used as set elements or
947 # dict keys by making __hash__ raise an exception.
950 raise TypeError('Cannot hash a signaling NaN value.')
952 # 0 to match hash(float('nan'))
955 # values chosen to match hash(float('inf')) and
956 # hash(float('-inf')).
962 # In Python 2.7, we're allowing comparisons (but not
963 # arithmetic operations) between floats and Decimals; so if
964 # a Decimal instance is exactly representable as a float then
965 # its hash should match that of the float.
966 self_as_float = float(self)
967 if Decimal.from_float(self_as_float) == self:
968 return hash(self_as_float)
970 if self._isinteger():
971 op = _WorkRep(self.to_integral_value())
972 # to make computation feasible for Decimals with large
973 # exponent, we use the fact that hash(n) == hash(m) for
974 # any two nonzero integers n and m such that (i) n and m
975 # have the same sign, and (ii) n is congruent to m modulo
976 # 2**64-1. So we can replace hash((-1)**s*c*10**e) with
977 # hash((-1)**s*c*pow(10, e, 2**64-1).
978 return hash((-1)**op.sign*op.int*pow(10, op.exp, 2**64-1))
979 # The value of a nonzero nonspecial Decimal instance is
980 # faithfully represented by the triple consisting of its sign,
981 # its adjusted exponent, and its coefficient with trailing
983 return hash((self._sign,
984 self._exp+len(self._int),
985 self._int.rstrip('0')))
988 """Represents the number as a triple tuple.
990 To show the internals exactly as they are.
992 return DecimalTuple(self._sign, tuple(map(int, self._int)), self._exp)
995 """Represents the number as an instance of Decimal."""
996 # Invariant: eval(repr(d)) == d
997 return "Decimal('%s')" % str(self)
999 def __str__(self, eng=False, context=None):
1000 """Return string representation of the number in scientific notation.
1002 Captures all of the information in the underlying representation.
1005 sign = ['', '-'][self._sign]
1006 if self._is_special:
1007 if self._exp == 'F':
1008 return sign + 'Infinity'
1009 elif self._exp == 'n':
1010 return sign + 'NaN' + self._int
1011 else: # self._exp == 'N'
1012 return sign + 'sNaN' + self._int
1014 # number of digits of self._int to left of decimal point
1015 leftdigits = self._exp + len(self._int)
1017 # dotplace is number of digits of self._int to the left of the
1018 # decimal point in the mantissa of the output string (that is,
1019 # after adjusting the exponent)
1020 if self._exp <= 0 and leftdigits > -6:
1021 # no exponent required
1022 dotplace = leftdigits
1024 # usual scientific notation: 1 digit on left of the point
1026 elif self._int == '0':
1027 # engineering notation, zero
1028 dotplace = (leftdigits + 1) % 3 - 1
1030 # engineering notation, nonzero
1031 dotplace = (leftdigits - 1) % 3 + 1
1035 fracpart = '.' + '0'*(-dotplace) + self._int
1036 elif dotplace >= len(self._int):
1037 intpart = self._int+'0'*(dotplace-len(self._int))
1040 intpart = self._int[:dotplace]
1041 fracpart = '.' + self._int[dotplace:]
1042 if leftdigits == dotplace:
1046 context = getcontext()
1047 exp = ['e', 'E'][context.capitals] + "%+d" % (leftdigits-dotplace)
1049 return sign + intpart + fracpart + exp
1051 def to_eng_string(self, context=None):
1052 """Convert to engineering-type string.
1054 Engineering notation has an exponent which is a multiple of 3, so there
1055 are up to 3 digits left of the decimal place.
1057 Same rules for when in exponential and when as a value as in __str__.
1059 return self.__str__(eng=True, context=context)
1061 def __neg__(self, context=None):
1062 """Returns a copy with the sign switched.
1064 Rounds, if it has reason.
1066 if self._is_special:
1067 ans = self._check_nans(context=context)
1072 context = getcontext()
1074 if not self and context.rounding != ROUND_FLOOR:
1075 # -Decimal('0') is Decimal('0'), not Decimal('-0'), except
1076 # in ROUND_FLOOR rounding mode.
1077 ans = self.copy_abs()
1079 ans = self.copy_negate()
1081 return ans._fix(context)
1083 def __pos__(self, context=None):
1084 """Returns a copy, unless it is a sNaN.
1086 Rounds the number (if more then precision digits)
1088 if self._is_special:
1089 ans = self._check_nans(context=context)
1094 context = getcontext()
1096 if not self and context.rounding != ROUND_FLOOR:
1097 # + (-0) = 0, except in ROUND_FLOOR rounding mode.
1098 ans = self.copy_abs()
1102 return ans._fix(context)
1104 def __abs__(self, round=True, context=None):
1105 """Returns the absolute value of self.
1107 If the keyword argument 'round' is false, do not round. The
1108 expression self.__abs__(round=False) is equivalent to
1112 return self.copy_abs()
1114 if self._is_special:
1115 ans = self._check_nans(context=context)
1120 ans = self.__neg__(context=context)
1122 ans = self.__pos__(context=context)
1126 def __add__(self, other, context=None):
1127 """Returns self + other.
1129 -INF + INF (or the reverse) cause InvalidOperation errors.
1131 other = _convert_other(other)
1132 if other is NotImplemented:
1136 context = getcontext()
1138 if self._is_special or other._is_special:
1139 ans = self._check_nans(other, context)
1143 if self._isinfinity():
1144 # If both INF, same sign => same as both, opposite => error.
1145 if self._sign != other._sign and other._isinfinity():
1146 return context._raise_error(InvalidOperation, '-INF + INF')
1147 return Decimal(self)
1148 if other._isinfinity():
1149 return Decimal(other) # Can't both be infinity here
1151 exp = min(self._exp, other._exp)
1153 if context.rounding == ROUND_FLOOR and self._sign != other._sign:
1154 # If the answer is 0, the sign should be negative, in this case.
1157 if not self and not other:
1158 sign = min(self._sign, other._sign)
1161 ans = _dec_from_triple(sign, '0', exp)
1162 ans = ans._fix(context)
1165 exp = max(exp, other._exp - context.prec-1)
1166 ans = other._rescale(exp, context.rounding)
1167 ans = ans._fix(context)
1170 exp = max(exp, self._exp - context.prec-1)
1171 ans = self._rescale(exp, context.rounding)
1172 ans = ans._fix(context)
1175 op1 = _WorkRep(self)
1176 op2 = _WorkRep(other)
1177 op1, op2 = _normalize(op1, op2, context.prec)
1180 if op1.sign != op2.sign:
1181 # Equal and opposite
1182 if op1.int == op2.int:
1183 ans = _dec_from_triple(negativezero, '0', exp)
1184 ans = ans._fix(context)
1186 if op1.int < op2.int:
1188 # OK, now abs(op1) > abs(op2)
1191 op1.sign, op2.sign = op2.sign, op1.sign
1194 # So we know the sign, and op1 > 0.
1197 op1.sign, op2.sign = (0, 0)
1200 # Now, op1 > abs(op2) > 0
1203 result.int = op1.int + op2.int
1205 result.int = op1.int - op2.int
1207 result.exp = op1.exp
1208 ans = Decimal(result)
1209 ans = ans._fix(context)
1214 def __sub__(self, other, context=None):
1215 """Return self - other"""
1216 other = _convert_other(other)
1217 if other is NotImplemented:
1220 if self._is_special or other._is_special:
1221 ans = self._check_nans(other, context=context)
1225 # self - other is computed as self + other.copy_negate()
1226 return self.__add__(other.copy_negate(), context=context)
1228 def __rsub__(self, other, context=None):
1229 """Return other - self"""
1230 other = _convert_other(other)
1231 if other is NotImplemented:
1234 return other.__sub__(self, context=context)
1236 def __mul__(self, other, context=None):
1237 """Return self * other.
1239 (+-) INF * 0 (or its reverse) raise InvalidOperation.
1241 other = _convert_other(other)
1242 if other is NotImplemented:
1246 context = getcontext()
1248 resultsign = self._sign ^ other._sign
1250 if self._is_special or other._is_special:
1251 ans = self._check_nans(other, context)
1255 if self._isinfinity():
1257 return context._raise_error(InvalidOperation, '(+-)INF * 0')
1258 return _SignedInfinity[resultsign]
1260 if other._isinfinity():
1262 return context._raise_error(InvalidOperation, '0 * (+-)INF')
1263 return _SignedInfinity[resultsign]
1265 resultexp = self._exp + other._exp
1267 # Special case for multiplying by zero
1268 if not self or not other:
1269 ans = _dec_from_triple(resultsign, '0', resultexp)
1270 # Fixing in case the exponent is out of bounds
1271 ans = ans._fix(context)
1274 # Special case for multiplying by power of 10
1275 if self._int == '1':
1276 ans = _dec_from_triple(resultsign, other._int, resultexp)
1277 ans = ans._fix(context)
1279 if other._int == '1':
1280 ans = _dec_from_triple(resultsign, self._int, resultexp)
1281 ans = ans._fix(context)
1284 op1 = _WorkRep(self)
1285 op2 = _WorkRep(other)
1287 ans = _dec_from_triple(resultsign, str(op1.int * op2.int), resultexp)
1288 ans = ans._fix(context)
1293 def __truediv__(self, other, context=None):
1294 """Return self / other."""
1295 other = _convert_other(other)
1296 if other is NotImplemented:
1297 return NotImplemented
1300 context = getcontext()
1302 sign = self._sign ^ other._sign
1304 if self._is_special or other._is_special:
1305 ans = self._check_nans(other, context)
1309 if self._isinfinity() and other._isinfinity():
1310 return context._raise_error(InvalidOperation, '(+-)INF/(+-)INF')
1312 if self._isinfinity():
1313 return _SignedInfinity[sign]
1315 if other._isinfinity():
1316 context._raise_error(Clamped, 'Division by infinity')
1317 return _dec_from_triple(sign, '0', context.Etiny())
1319 # Special cases for zeroes
1322 return context._raise_error(DivisionUndefined, '0 / 0')
1323 return context._raise_error(DivisionByZero, 'x / 0', sign)
1326 exp = self._exp - other._exp
1329 # OK, so neither = 0, INF or NaN
1330 shift = len(other._int) - len(self._int) + context.prec + 1
1331 exp = self._exp - other._exp - shift
1332 op1 = _WorkRep(self)
1333 op2 = _WorkRep(other)
1335 coeff, remainder = divmod(op1.int * 10**shift, op2.int)
1337 coeff, remainder = divmod(op1.int, op2.int * 10**-shift)
1339 # result is not exact; adjust to ensure correct rounding
1343 # result is exact; get as close to ideal exponent as possible
1344 ideal_exp = self._exp - other._exp
1345 while exp < ideal_exp and coeff % 10 == 0:
1349 ans = _dec_from_triple(sign, str(coeff), exp)
1350 return ans._fix(context)
1352 def _divide(self, other, context):
1353 """Return (self // other, self % other), to context.prec precision.
1355 Assumes that neither self nor other is a NaN, that self is not
1356 infinite and that other is nonzero.
1358 sign = self._sign ^ other._sign
1359 if other._isinfinity():
1360 ideal_exp = self._exp
1362 ideal_exp = min(self._exp, other._exp)
1364 expdiff = self.adjusted() - other.adjusted()
1365 if not self or other._isinfinity() or expdiff <= -2:
1366 return (_dec_from_triple(sign, '0', 0),
1367 self._rescale(ideal_exp, context.rounding))
1368 if expdiff <= context.prec:
1369 op1 = _WorkRep(self)
1370 op2 = _WorkRep(other)
1371 if op1.exp >= op2.exp:
1372 op1.int *= 10**(op1.exp - op2.exp)
1374 op2.int *= 10**(op2.exp - op1.exp)
1375 q, r = divmod(op1.int, op2.int)
1376 if q < 10**context.prec:
1377 return (_dec_from_triple(sign, str(q), 0),
1378 _dec_from_triple(self._sign, str(r), ideal_exp))
1380 # Here the quotient is too large to be representable
1381 ans = context._raise_error(DivisionImpossible,
1382 'quotient too large in //, % or divmod')
1385 def __rtruediv__(self, other, context=None):
1386 """Swaps self/other and returns __truediv__."""
1387 other = _convert_other(other)
1388 if other is NotImplemented:
1390 return other.__truediv__(self, context=context)
1392 __div__ = __truediv__
1393 __rdiv__ = __rtruediv__
1395 def __divmod__(self, other, context=None):
1397 Return (self // other, self % other)
1399 other = _convert_other(other)
1400 if other is NotImplemented:
1404 context = getcontext()
1406 ans = self._check_nans(other, context)
1410 sign = self._sign ^ other._sign
1411 if self._isinfinity():
1412 if other._isinfinity():
1413 ans = context._raise_error(InvalidOperation, 'divmod(INF, INF)')
1416 return (_SignedInfinity[sign],
1417 context._raise_error(InvalidOperation, 'INF % x'))
1421 ans = context._raise_error(DivisionUndefined, 'divmod(0, 0)')
1424 return (context._raise_error(DivisionByZero, 'x // 0', sign),
1425 context._raise_error(InvalidOperation, 'x % 0'))
1427 quotient, remainder = self._divide(other, context)
1428 remainder = remainder._fix(context)
1429 return quotient, remainder
1431 def __rdivmod__(self, other, context=None):
1432 """Swaps self/other and returns __divmod__."""
1433 other = _convert_other(other)
1434 if other is NotImplemented:
1436 return other.__divmod__(self, context=context)
1438 def __mod__(self, other, context=None):
1442 other = _convert_other(other)
1443 if other is NotImplemented:
1447 context = getcontext()
1449 ans = self._check_nans(other, context)
1453 if self._isinfinity():
1454 return context._raise_error(InvalidOperation, 'INF % x')
1457 return context._raise_error(InvalidOperation, 'x % 0')
1459 return context._raise_error(DivisionUndefined, '0 % 0')
1461 remainder = self._divide(other, context)[1]
1462 remainder = remainder._fix(context)
1465 def __rmod__(self, other, context=None):
1466 """Swaps self/other and returns __mod__."""
1467 other = _convert_other(other)
1468 if other is NotImplemented:
1470 return other.__mod__(self, context=context)
1472 def remainder_near(self, other, context=None):
1474 Remainder nearest to 0- abs(remainder-near) <= other/2
1477 context = getcontext()
1479 other = _convert_other(other, raiseit=True)
1481 ans = self._check_nans(other, context)
1485 # self == +/-infinity -> InvalidOperation
1486 if self._isinfinity():
1487 return context._raise_error(InvalidOperation,
1488 'remainder_near(infinity, x)')
1490 # other == 0 -> either InvalidOperation or DivisionUndefined
1493 return context._raise_error(InvalidOperation,
1494 'remainder_near(x, 0)')
1496 return context._raise_error(DivisionUndefined,
1497 'remainder_near(0, 0)')
1499 # other = +/-infinity -> remainder = self
1500 if other._isinfinity():
1502 return ans._fix(context)
1504 # self = 0 -> remainder = self, with ideal exponent
1505 ideal_exponent = min(self._exp, other._exp)
1507 ans = _dec_from_triple(self._sign, '0', ideal_exponent)
1508 return ans._fix(context)
1510 # catch most cases of large or small quotient
1511 expdiff = self.adjusted() - other.adjusted()
1512 if expdiff >= context.prec + 1:
1513 # expdiff >= prec+1 => abs(self/other) > 10**prec
1514 return context._raise_error(DivisionImpossible)
1516 # expdiff <= -2 => abs(self/other) < 0.1
1517 ans = self._rescale(ideal_exponent, context.rounding)
1518 return ans._fix(context)
1520 # adjust both arguments to have the same exponent, then divide
1521 op1 = _WorkRep(self)
1522 op2 = _WorkRep(other)
1523 if op1.exp >= op2.exp:
1524 op1.int *= 10**(op1.exp - op2.exp)
1526 op2.int *= 10**(op2.exp - op1.exp)
1527 q, r = divmod(op1.int, op2.int)
1528 # remainder is r*10**ideal_exponent; other is +/-op2.int *
1529 # 10**ideal_exponent. Apply correction to ensure that
1530 # abs(remainder) <= abs(other)/2
1531 if 2*r + (q&1) > op2.int:
1535 if q >= 10**context.prec:
1536 return context._raise_error(DivisionImpossible)
1538 # result has same sign as self unless r is negative
1544 ans = _dec_from_triple(sign, str(r), ideal_exponent)
1545 return ans._fix(context)
1547 def __floordiv__(self, other, context=None):
1549 other = _convert_other(other)
1550 if other is NotImplemented:
1554 context = getcontext()
1556 ans = self._check_nans(other, context)
1560 if self._isinfinity():
1561 if other._isinfinity():
1562 return context._raise_error(InvalidOperation, 'INF // INF')
1564 return _SignedInfinity[self._sign ^ other._sign]
1568 return context._raise_error(DivisionByZero, 'x // 0',
1569 self._sign ^ other._sign)
1571 return context._raise_error(DivisionUndefined, '0 // 0')
1573 return self._divide(other, context)[0]
1575 def __rfloordiv__(self, other, context=None):
1576 """Swaps self/other and returns __floordiv__."""
1577 other = _convert_other(other)
1578 if other is NotImplemented:
1580 return other.__floordiv__(self, context=context)
1582 def __float__(self):
1583 """Float representation."""
1584 return float(str(self))
1587 """Converts self to an int, truncating if necessary."""
1588 if self._is_special:
1590 raise ValueError("Cannot convert NaN to integer")
1591 elif self._isinfinity():
1592 raise OverflowError("Cannot convert infinity to integer")
1593 s = (-1)**self._sign
1595 return s*int(self._int)*10**self._exp
1597 return s*int(self._int[:self._exp] or '0')
1603 real = property(real)
1607 imag = property(imag)
1609 def conjugate(self):
1612 def __complex__(self):
1613 return complex(float(self))
1616 """Converts to a long.
1618 Equivalent to long(int(self))
1620 return long(self.__int__())
1622 def _fix_nan(self, context):
1623 """Decapitate the payload of a NaN to fit the context"""
1626 # maximum length of payload is precision if _clamp=0,
1627 # precision-1 if _clamp=1.
1628 max_payload_len = context.prec - context._clamp
1629 if len(payload) > max_payload_len:
1630 payload = payload[len(payload)-max_payload_len:].lstrip('0')
1631 return _dec_from_triple(self._sign, payload, self._exp, True)
1632 return Decimal(self)
1634 def _fix(self, context):
1635 """Round if it is necessary to keep self within prec precision.
1637 Rounds and fixes the exponent. Does not raise on a sNaN.
1640 self - Decimal instance
1641 context - context used.
1644 if self._is_special:
1646 # decapitate payload if necessary
1647 return self._fix_nan(context)
1649 # self is +/-Infinity; return unaltered
1650 return Decimal(self)
1652 # if self is zero then exponent should be between Etiny and
1653 # Emax if _clamp==0, and between Etiny and Etop if _clamp==1.
1654 Etiny = context.Etiny()
1655 Etop = context.Etop()
1657 exp_max = [context.Emax, Etop][context._clamp]
1658 new_exp = min(max(self._exp, Etiny), exp_max)
1659 if new_exp != self._exp:
1660 context._raise_error(Clamped)
1661 return _dec_from_triple(self._sign, '0', new_exp)
1663 return Decimal(self)
1665 # exp_min is the smallest allowable exponent of the result,
1666 # equal to max(self.adjusted()-context.prec+1, Etiny)
1667 exp_min = len(self._int) + self._exp - context.prec
1669 # overflow: exp_min > Etop iff self.adjusted() > Emax
1670 ans = context._raise_error(Overflow, 'above Emax', self._sign)
1671 context._raise_error(Inexact)
1672 context._raise_error(Rounded)
1675 self_is_subnormal = exp_min < Etiny
1676 if self_is_subnormal:
1679 # round if self has too many digits
1680 if self._exp < exp_min:
1681 digits = len(self._int) + self._exp - exp_min
1683 self = _dec_from_triple(self._sign, '1', exp_min-1)
1685 rounding_method = self._pick_rounding_function[context.rounding]
1686 changed = rounding_method(self, digits)
1687 coeff = self._int[:digits] or '0'
1689 coeff = str(int(coeff)+1)
1690 if len(coeff) > context.prec:
1694 # check whether the rounding pushed the exponent out of range
1696 ans = context._raise_error(Overflow, 'above Emax', self._sign)
1698 ans = _dec_from_triple(self._sign, coeff, exp_min)
1700 # raise the appropriate signals, taking care to respect
1701 # the precedence described in the specification
1702 if changed and self_is_subnormal:
1703 context._raise_error(Underflow)
1704 if self_is_subnormal:
1705 context._raise_error(Subnormal)
1707 context._raise_error(Inexact)
1708 context._raise_error(Rounded)
1710 # raise Clamped on underflow to 0
1711 context._raise_error(Clamped)
1714 if self_is_subnormal:
1715 context._raise_error(Subnormal)
1717 # fold down if _clamp == 1 and self has too few digits
1718 if context._clamp == 1 and self._exp > Etop:
1719 context._raise_error(Clamped)
1720 self_padded = self._int + '0'*(self._exp - Etop)
1721 return _dec_from_triple(self._sign, self_padded, Etop)
1723 # here self was representable to begin with; return unchanged
1724 return Decimal(self)
1726 # for each of the rounding functions below:
1727 # self is a finite, nonzero Decimal
1728 # prec is an integer satisfying 0 <= prec < len(self._int)
1730 # each function returns either -1, 0, or 1, as follows:
1731 # 1 indicates that self should be rounded up (away from zero)
1732 # 0 indicates that self should be truncated, and that all the
1733 # digits to be truncated are zeros (so the value is unchanged)
1734 # -1 indicates that there are nonzero digits to be truncated
1736 def _round_down(self, prec):
1737 """Also known as round-towards-0, truncate."""
1738 if _all_zeros(self._int, prec):
1743 def _round_up(self, prec):
1744 """Rounds away from 0."""
1745 return -self._round_down(prec)
1747 def _round_half_up(self, prec):
1748 """Rounds 5 up (away from 0)"""
1749 if self._int[prec] in '56789':
1751 elif _all_zeros(self._int, prec):
1756 def _round_half_down(self, prec):
1758 if _exact_half(self._int, prec):
1761 return self._round_half_up(prec)
1763 def _round_half_even(self, prec):
1764 """Round 5 to even, rest to nearest."""
1765 if _exact_half(self._int, prec) and \
1766 (prec == 0 or self._int[prec-1] in '02468'):
1769 return self._round_half_up(prec)
1771 def _round_ceiling(self, prec):
1772 """Rounds up (not away from 0 if negative.)"""
1774 return self._round_down(prec)
1776 return -self._round_down(prec)
1778 def _round_floor(self, prec):
1779 """Rounds down (not towards 0 if negative)"""
1781 return self._round_down(prec)
1783 return -self._round_down(prec)
1785 def _round_05up(self, prec):
1786 """Round down unless digit prec-1 is 0 or 5."""
1787 if prec and self._int[prec-1] not in '05':
1788 return self._round_down(prec)
1790 return -self._round_down(prec)
1792 _pick_rounding_function = dict(
1793 ROUND_DOWN = _round_down,
1794 ROUND_UP = _round_up,
1795 ROUND_HALF_UP = _round_half_up,
1796 ROUND_HALF_DOWN = _round_half_down,
1797 ROUND_HALF_EVEN = _round_half_even,
1798 ROUND_CEILING = _round_ceiling,
1799 ROUND_FLOOR = _round_floor,
1800 ROUND_05UP = _round_05up,
1803 def fma(self, other, third, context=None):
1804 """Fused multiply-add.
1806 Returns self*other+third with no rounding of the intermediate
1809 self and other are multiplied together, with no rounding of
1810 the result. The third operand is then added to the result,
1811 and a single final rounding is performed.
1814 other = _convert_other(other, raiseit=True)
1816 # compute product; raise InvalidOperation if either operand is
1817 # a signaling NaN or if the product is zero times infinity.
1818 if self._is_special or other._is_special:
1820 context = getcontext()
1821 if self._exp == 'N':
1822 return context._raise_error(InvalidOperation, 'sNaN', self)
1823 if other._exp == 'N':
1824 return context._raise_error(InvalidOperation, 'sNaN', other)
1825 if self._exp == 'n':
1827 elif other._exp == 'n':
1829 elif self._exp == 'F':
1831 return context._raise_error(InvalidOperation,
1833 product = _SignedInfinity[self._sign ^ other._sign]
1834 elif other._exp == 'F':
1836 return context._raise_error(InvalidOperation,
1838 product = _SignedInfinity[self._sign ^ other._sign]
1840 product = _dec_from_triple(self._sign ^ other._sign,
1841 str(int(self._int) * int(other._int)),
1842 self._exp + other._exp)
1844 third = _convert_other(third, raiseit=True)
1845 return product.__add__(third, context)
1847 def _power_modulo(self, other, modulo, context=None):
1848 """Three argument version of __pow__"""
1850 # if can't convert other and modulo to Decimal, raise
1851 # TypeError; there's no point returning NotImplemented (no
1852 # equivalent of __rpow__ for three argument pow)
1853 other = _convert_other(other, raiseit=True)
1854 modulo = _convert_other(modulo, raiseit=True)
1857 context = getcontext()
1859 # deal with NaNs: if there are any sNaNs then first one wins,
1860 # (i.e. behaviour for NaNs is identical to that of fma)
1861 self_is_nan = self._isnan()
1862 other_is_nan = other._isnan()
1863 modulo_is_nan = modulo._isnan()
1864 if self_is_nan or other_is_nan or modulo_is_nan:
1865 if self_is_nan == 2:
1866 return context._raise_error(InvalidOperation, 'sNaN',
1868 if other_is_nan == 2:
1869 return context._raise_error(InvalidOperation, 'sNaN',
1871 if modulo_is_nan == 2:
1872 return context._raise_error(InvalidOperation, 'sNaN',
1875 return self._fix_nan(context)
1877 return other._fix_nan(context)
1878 return modulo._fix_nan(context)
1880 # check inputs: we apply same restrictions as Python's pow()
1881 if not (self._isinteger() and
1882 other._isinteger() and
1883 modulo._isinteger()):
1884 return context._raise_error(InvalidOperation,
1885 'pow() 3rd argument not allowed '
1886 'unless all arguments are integers')
1888 return context._raise_error(InvalidOperation,
1889 'pow() 2nd argument cannot be '
1890 'negative when 3rd argument specified')
1892 return context._raise_error(InvalidOperation,
1893 'pow() 3rd argument cannot be 0')
1895 # additional restriction for decimal: the modulus must be less
1896 # than 10**prec in absolute value
1897 if modulo.adjusted() >= context.prec:
1898 return context._raise_error(InvalidOperation,
1899 'insufficient precision: pow() 3rd '
1900 'argument must not have more than '
1903 # define 0**0 == NaN, for consistency with two-argument pow
1904 # (even though it hurts!)
1905 if not other and not self:
1906 return context._raise_error(InvalidOperation,
1907 'at least one of pow() 1st argument '
1908 'and 2nd argument must be nonzero ;'
1909 '0**0 is not defined')
1911 # compute sign of result
1917 # convert modulo to a Python integer, and self and other to
1918 # Decimal integers (i.e. force their exponents to be >= 0)
1919 modulo = abs(int(modulo))
1920 base = _WorkRep(self.to_integral_value())
1921 exponent = _WorkRep(other.to_integral_value())
1923 # compute result using integer pow()
1924 base = (base.int % modulo * pow(10, base.exp, modulo)) % modulo
1925 for i in xrange(exponent.exp):
1926 base = pow(base, 10, modulo)
1927 base = pow(base, exponent.int, modulo)
1929 return _dec_from_triple(sign, str(base), 0)
1931 def _power_exact(self, other, p):
1932 """Attempt to compute self**other exactly.
1934 Given Decimals self and other and an integer p, attempt to
1935 compute an exact result for the power self**other, with p
1936 digits of precision. Return None if self**other is not
1937 exactly representable in p digits.
1939 Assumes that elimination of special cases has already been
1940 performed: self and other must both be nonspecial; self must
1941 be positive and not numerically equal to 1; other must be
1942 nonzero. For efficiency, other._exp should not be too large,
1943 so that 10**abs(other._exp) is a feasible calculation."""
1945 # In the comments below, we write x for the value of self and y for the
1946 # value of other. Write x = xc*10**xe and abs(y) = yc*10**ye, with xc
1947 # and yc positive integers not divisible by 10.
1949 # The main purpose of this method is to identify the *failure*
1950 # of x**y to be exactly representable with as little effort as
1951 # possible. So we look for cheap and easy tests that
1952 # eliminate the possibility of x**y being exact. Only if all
1953 # these tests are passed do we go on to actually compute x**y.
1955 # Here's the main idea. Express y as a rational number m/n, with m and
1956 # n relatively prime and n>0. Then for x**y to be exactly
1957 # representable (at *any* precision), xc must be the nth power of a
1958 # positive integer and xe must be divisible by n. If y is negative
1959 # then additionally xc must be a power of either 2 or 5, hence a power
1962 # There's a limit to how small |y| can be: if y=m/n as above
1965 # (1) if xc != 1 then for the result to be representable we
1966 # need xc**(1/n) >= 2, and hence also xc**|y| >= 2. So
1967 # if |y| <= 1/nbits(xc) then xc < 2**nbits(xc) <=
1968 # 2**(1/|y|), hence xc**|y| < 2 and the result is not
1971 # (2) if xe != 0, |xe|*(1/n) >= 1, so |xe|*|y| >= 1. Hence if
1972 # |y| < 1/|xe| then the result is not representable.
1974 # Note that since x is not equal to 1, at least one of (1) and
1975 # (2) must apply. Now |y| < 1/nbits(xc) iff |yc|*nbits(xc) <
1976 # 10**-ye iff len(str(|yc|*nbits(xc)) <= -ye.
1978 # There's also a limit to how large y can be, at least if it's
1979 # positive: the normalized result will have coefficient xc**y,
1980 # so if it's representable then xc**y < 10**p, and y <
1981 # p/log10(xc). Hence if y*log10(xc) >= p then the result is
1982 # not exactly representable.
1984 # if len(str(abs(yc*xe)) <= -ye then abs(yc*xe) < 10**-ye,
1985 # so |y| < 1/xe and the result is not representable.
1986 # Similarly, len(str(abs(yc)*xc_bits)) <= -ye implies |y|
1990 xc, xe = x.int, x.exp
1996 yc, ye = y.int, y.exp
2001 # case where xc == 1: result is 10**(xe*y), with xe*y
2002 # required to be an integer
2005 # result is now 10**(xe * 10**ye); xe * 10**ye must be integral
2011 exponent = xe * 10**ye
2013 exponent = -exponent
2014 # if other is a nonnegative integer, use ideal exponent
2015 if other._isinteger() and other._sign == 0:
2016 ideal_exponent = self._exp*int(other)
2017 zeros = min(exponent-ideal_exponent, p-1)
2020 return _dec_from_triple(0, '1' + '0'*zeros, exponent-zeros)
2022 # case where y is negative: xc must be either a power
2023 # of 2 or a power of 5.
2025 last_digit = xc % 10
2026 if last_digit in (2,4,6,8):
2027 # quick test for power of 2
2030 # now xc is a power of 2; e is its exponent
2035 # x = 2**e * 10**xe, e > 0, and y < 0.
2037 # The exact result is:
2039 # x**y = 5**(-e*y) * 10**(e*y + xe*y)
2041 # provided that both e*y and xe*y are integers. Note that if
2042 # 5**(-e*y) >= 10**p, then the result can't be expressed
2043 # exactly with p digits of precision.
2045 # Using the above, we can guard against large values of ye.
2046 # 93/65 is an upper bound for log(10)/log(5), so if
2048 # ye >= len(str(93*p//65))
2052 # -e*y >= -y >= 10**ye > 93*p/65 > p*log(10)/log(5),
2054 # so 5**(-e*y) >= 10**p, and the coefficient of the result
2055 # can't be expressed in p digits.
2057 # emax >= largest e such that 5**e < 10**p.
2059 if ye >= len(str(emax)):
2062 # Find -e*y and -xe*y; both must be integers
2063 e = _decimal_lshift_exact(e * yc, ye)
2064 xe = _decimal_lshift_exact(xe * yc, ye)
2065 if e is None or xe is None:
2072 elif last_digit == 5:
2073 # e >= log_5(xc) if xc is a power of 5; we have
2074 # equality all the way up to xc=5**2658
2075 e = _nbits(xc)*28//65
2076 xc, remainder = divmod(5**e, xc)
2083 # Guard against large values of ye, using the same logic as in
2084 # the 'xc is a power of 2' branch. 10/3 is an upper bound for
2087 if ye >= len(str(emax)):
2090 e = _decimal_lshift_exact(e * yc, ye)
2091 xe = _decimal_lshift_exact(xe * yc, ye)
2092 if e is None or xe is None:
2104 return _dec_from_triple(0, str(xc), xe)
2106 # now y is positive; find m and n such that y = m/n
2110 if xe != 0 and len(str(abs(yc*xe))) <= -ye:
2112 xc_bits = _nbits(xc)
2113 if xc != 1 and len(str(abs(yc)*xc_bits)) <= -ye:
2115 m, n = yc, 10**(-ye)
2116 while m % 2 == n % 2 == 0:
2119 while m % 5 == n % 5 == 0:
2123 # compute nth root of xc*10**xe
2125 # if 1 < xc < 2**n then xc isn't an nth power
2126 if xc != 1 and xc_bits <= n:
2129 xe, rem = divmod(xe, n)
2133 # compute nth root of xc using Newton's method
2134 a = 1L << -(-_nbits(xc)//n) # initial estimate
2136 q, r = divmod(xc, a**(n-1))
2140 a = (a*(n-1) + q)//n
2141 if not (a == q and r == 0):
2145 # now xc*10**xe is the nth root of the original xc*10**xe
2146 # compute mth power of xc*10**xe
2148 # if m > p*100//_log10_lb(xc) then m > p/log10(xc), hence xc**m >
2149 # 10**p and the result is not representable.
2150 if xc > 1 and m > p*100//_log10_lb(xc):
2157 # by this point the result *is* exactly representable
2158 # adjust the exponent to get as close as possible to the ideal
2159 # exponent, if necessary
2161 if other._isinteger() and other._sign == 0:
2162 ideal_exponent = self._exp*int(other)
2163 zeros = min(xe-ideal_exponent, p-len(str_xc))
2166 return _dec_from_triple(0, str_xc+'0'*zeros, xe-zeros)
2168 def __pow__(self, other, modulo=None, context=None):
2169 """Return self ** other [ % modulo].
2171 With two arguments, compute self**other.
2173 With three arguments, compute (self**other) % modulo. For the
2174 three argument form, the following restrictions on the
2177 - all three arguments must be integral
2178 - other must be nonnegative
2179 - either self or other (or both) must be nonzero
2180 - modulo must be nonzero and must have at most p digits,
2181 where p is the context precision.
2183 If any of these restrictions is violated the InvalidOperation
2186 The result of pow(self, other, modulo) is identical to the
2187 result that would be obtained by computing (self**other) %
2188 modulo with unbounded precision, but is computed more
2189 efficiently. It is always exact.
2192 if modulo is not None:
2193 return self._power_modulo(other, modulo, context)
2195 other = _convert_other(other)
2196 if other is NotImplemented:
2200 context = getcontext()
2202 # either argument is a NaN => result is NaN
2203 ans = self._check_nans(other, context)
2207 # 0**0 = NaN (!), x**0 = 1 for nonzero x (including +/-Infinity)
2210 return context._raise_error(InvalidOperation, '0 ** 0')
2214 # result has sign 1 iff self._sign is 1 and other is an odd integer
2217 if other._isinteger():
2218 if not other._iseven():
2221 # -ve**noninteger = NaN
2222 # (-0)**noninteger = 0**noninteger
2224 return context._raise_error(InvalidOperation,
2225 'x ** y with x negative and y not an integer')
2226 # negate self, without doing any unwanted rounding
2227 self = self.copy_negate()
2229 # 0**(+ve or Inf)= 0; 0**(-ve or -Inf) = Infinity
2231 if other._sign == 0:
2232 return _dec_from_triple(result_sign, '0', 0)
2234 return _SignedInfinity[result_sign]
2236 # Inf**(+ve or Inf) = Inf; Inf**(-ve or -Inf) = 0
2237 if self._isinfinity():
2238 if other._sign == 0:
2239 return _SignedInfinity[result_sign]
2241 return _dec_from_triple(result_sign, '0', 0)
2243 # 1**other = 1, but the choice of exponent and the flags
2244 # depend on the exponent of self, and on whether other is a
2245 # positive integer, a negative integer, or neither
2247 if other._isinteger():
2248 # exp = max(self._exp*max(int(other), 0),
2249 # 1-context.prec) but evaluating int(other) directly
2250 # is dangerous until we know other is small (other
2251 # could be 1e999999999)
2252 if other._sign == 1:
2254 elif other > context.prec:
2255 multiplier = context.prec
2257 multiplier = int(other)
2259 exp = self._exp * multiplier
2260 if exp < 1-context.prec:
2261 exp = 1-context.prec
2262 context._raise_error(Rounded)
2264 context._raise_error(Inexact)
2265 context._raise_error(Rounded)
2266 exp = 1-context.prec
2268 return _dec_from_triple(result_sign, '1'+'0'*-exp, exp)
2270 # compute adjusted exponent of self
2271 self_adj = self.adjusted()
2273 # self ** infinity is infinity if self > 1, 0 if self < 1
2274 # self ** -infinity is infinity if self < 1, 0 if self > 1
2275 if other._isinfinity():
2276 if (other._sign == 0) == (self_adj < 0):
2277 return _dec_from_triple(result_sign, '0', 0)
2279 return _SignedInfinity[result_sign]
2281 # from here on, the result always goes through the call
2282 # to _fix at the end of this function.
2286 # crude test to catch cases of extreme overflow/underflow. If
2287 # log10(self)*other >= 10**bound and bound >= len(str(Emax))
2288 # then 10**bound >= 10**len(str(Emax)) >= Emax+1 and hence
2289 # self**other >= 10**(Emax+1), so overflow occurs. The test
2290 # for underflow is similar.
2291 bound = self._log10_exp_bound() + other.adjusted()
2292 if (self_adj >= 0) == (other._sign == 0):
2293 # self > 1 and other +ve, or self < 1 and other -ve
2294 # possibility of overflow
2295 if bound >= len(str(context.Emax)):
2296 ans = _dec_from_triple(result_sign, '1', context.Emax+1)
2298 # self > 1 and other -ve, or self < 1 and other +ve
2299 # possibility of underflow to 0
2300 Etiny = context.Etiny()
2301 if bound >= len(str(-Etiny)):
2302 ans = _dec_from_triple(result_sign, '1', Etiny-1)
2304 # try for an exact result with precision +1
2306 ans = self._power_exact(other, context.prec + 1)
2308 if result_sign == 1:
2309 ans = _dec_from_triple(1, ans._int, ans._exp)
2312 # usual case: inexact result, x**y computed directly as exp(y*log(x))
2316 xc, xe = x.int, x.exp
2318 yc, ye = y.int, y.exp
2322 # compute correctly rounded result: start with precision +3,
2323 # then increase precision until result is unambiguously roundable
2326 coeff, exp = _dpower(xc, xe, yc, ye, p+extra)
2327 if coeff % (5*10**(len(str(coeff))-p-1)):
2331 ans = _dec_from_triple(result_sign, str(coeff), exp)
2333 # unlike exp, ln and log10, the power function respects the
2334 # rounding mode; no need to switch to ROUND_HALF_EVEN here
2336 # There's a difficulty here when 'other' is not an integer and
2337 # the result is exact. In this case, the specification
2338 # requires that the Inexact flag be raised (in spite of
2339 # exactness), but since the result is exact _fix won't do this
2340 # for us. (Correspondingly, the Underflow signal should also
2341 # be raised for subnormal results.) We can't directly raise
2342 # these signals either before or after calling _fix, since
2343 # that would violate the precedence for signals. So we wrap
2344 # the ._fix call in a temporary context, and reraise
2346 if exact and not other._isinteger():
2347 # pad with zeros up to length context.prec+1 if necessary; this
2348 # ensures that the Rounded signal will be raised.
2349 if len(ans._int) <= context.prec:
2350 expdiff = context.prec + 1 - len(ans._int)
2351 ans = _dec_from_triple(ans._sign, ans._int+'0'*expdiff,
2354 # create a copy of the current context, with cleared flags/traps
2355 newcontext = context.copy()
2356 newcontext.clear_flags()
2357 for exception in _signals:
2358 newcontext.traps[exception] = 0
2360 # round in the new context
2361 ans = ans._fix(newcontext)
2363 # raise Inexact, and if necessary, Underflow
2364 newcontext._raise_error(Inexact)
2365 if newcontext.flags[Subnormal]:
2366 newcontext._raise_error(Underflow)
2368 # propagate signals to the original context; _fix could
2369 # have raised any of Overflow, Underflow, Subnormal,
2370 # Inexact, Rounded, Clamped. Overflow needs the correct
2371 # arguments. Note that the order of the exceptions is
2373 if newcontext.flags[Overflow]:
2374 context._raise_error(Overflow, 'above Emax', ans._sign)
2375 for exception in Underflow, Subnormal, Inexact, Rounded, Clamped:
2376 if newcontext.flags[exception]:
2377 context._raise_error(exception)
2380 ans = ans._fix(context)
2384 def __rpow__(self, other, context=None):
2385 """Swaps self/other and returns __pow__."""
2386 other = _convert_other(other)
2387 if other is NotImplemented:
2389 return other.__pow__(self, context=context)
2391 def normalize(self, context=None):
2392 """Normalize- strip trailing 0s, change anything equal to 0 to 0e0"""
2395 context = getcontext()
2397 if self._is_special:
2398 ans = self._check_nans(context=context)
2402 dup = self._fix(context)
2403 if dup._isinfinity():
2407 return _dec_from_triple(dup._sign, '0', 0)
2408 exp_max = [context.Emax, context.Etop()][context._clamp]
2411 while dup._int[end-1] == '0' and exp < exp_max:
2414 return _dec_from_triple(dup._sign, dup._int[:end], exp)
2416 def quantize(self, exp, rounding=None, context=None, watchexp=True):
2417 """Quantize self so its exponent is the same as that of exp.
2419 Similar to self._rescale(exp._exp) but with error checking.
2421 exp = _convert_other(exp, raiseit=True)
2424 context = getcontext()
2425 if rounding is None:
2426 rounding = context.rounding
2428 if self._is_special or exp._is_special:
2429 ans = self._check_nans(exp, context)
2433 if exp._isinfinity() or self._isinfinity():
2434 if exp._isinfinity() and self._isinfinity():
2435 return Decimal(self) # if both are inf, it is OK
2436 return context._raise_error(InvalidOperation,
2437 'quantize with one INF')
2439 # if we're not watching exponents, do a simple rescale
2441 ans = self._rescale(exp._exp, rounding)
2442 # raise Inexact and Rounded where appropriate
2443 if ans._exp > self._exp:
2444 context._raise_error(Rounded)
2446 context._raise_error(Inexact)
2449 # exp._exp should be between Etiny and Emax
2450 if not (context.Etiny() <= exp._exp <= context.Emax):
2451 return context._raise_error(InvalidOperation,
2452 'target exponent out of bounds in quantize')
2455 ans = _dec_from_triple(self._sign, '0', exp._exp)
2456 return ans._fix(context)
2458 self_adjusted = self.adjusted()
2459 if self_adjusted > context.Emax:
2460 return context._raise_error(InvalidOperation,
2461 'exponent of quantize result too large for current context')
2462 if self_adjusted - exp._exp + 1 > context.prec:
2463 return context._raise_error(InvalidOperation,
2464 'quantize result has too many digits for current context')
2466 ans = self._rescale(exp._exp, rounding)
2467 if ans.adjusted() > context.Emax:
2468 return context._raise_error(InvalidOperation,
2469 'exponent of quantize result too large for current context')
2470 if len(ans._int) > context.prec:
2471 return context._raise_error(InvalidOperation,
2472 'quantize result has too many digits for current context')
2474 # raise appropriate flags
2475 if ans and ans.adjusted() < context.Emin:
2476 context._raise_error(Subnormal)
2477 if ans._exp > self._exp:
2479 context._raise_error(Inexact)
2480 context._raise_error(Rounded)
2482 # call to fix takes care of any necessary folddown, and
2483 # signals Clamped if necessary
2484 ans = ans._fix(context)
2487 def same_quantum(self, other):
2488 """Return True if self and other have the same exponent; otherwise
2491 If either operand is a special value, the following rules are used:
2492 * return True if both operands are infinities
2493 * return True if both operands are NaNs
2494 * otherwise, return False.
2496 other = _convert_other(other, raiseit=True)
2497 if self._is_special or other._is_special:
2498 return (self.is_nan() and other.is_nan() or
2499 self.is_infinite() and other.is_infinite())
2500 return self._exp == other._exp
2502 def _rescale(self, exp, rounding):
2503 """Rescale self so that the exponent is exp, either by padding with zeros
2504 or by truncating digits, using the given rounding mode.
2506 Specials are returned without change. This operation is
2507 quiet: it raises no flags, and uses no information from the
2510 exp = exp to scale to (an integer)
2511 rounding = rounding mode
2513 if self._is_special:
2514 return Decimal(self)
2516 return _dec_from_triple(self._sign, '0', exp)
2518 if self._exp >= exp:
2519 # pad answer with zeros if necessary
2520 return _dec_from_triple(self._sign,
2521 self._int + '0'*(self._exp - exp), exp)
2523 # too many digits; round and lose data. If self.adjusted() <
2524 # exp-1, replace self by 10**(exp-1) before rounding
2525 digits = len(self._int) + self._exp - exp
2527 self = _dec_from_triple(self._sign, '1', exp-1)
2529 this_function = self._pick_rounding_function[rounding]
2530 changed = this_function(self, digits)
2531 coeff = self._int[:digits] or '0'
2533 coeff = str(int(coeff)+1)
2534 return _dec_from_triple(self._sign, coeff, exp)
2536 def _round(self, places, rounding):
2537 """Round a nonzero, nonspecial Decimal to a fixed number of
2538 significant figures, using the given rounding mode.
2540 Infinities, NaNs and zeros are returned unaltered.
2542 This operation is quiet: it raises no flags, and uses no
2543 information from the context.
2547 raise ValueError("argument should be at least 1 in _round")
2548 if self._is_special or not self:
2549 return Decimal(self)
2550 ans = self._rescale(self.adjusted()+1-places, rounding)
2551 # it can happen that the rescale alters the adjusted exponent;
2552 # for example when rounding 99.97 to 3 significant figures.
2553 # When this happens we end up with an extra 0 at the end of
2554 # the number; a second rescale fixes this.
2555 if ans.adjusted() != self.adjusted():
2556 ans = ans._rescale(ans.adjusted()+1-places, rounding)
2559 def to_integral_exact(self, rounding=None, context=None):
2560 """Rounds to a nearby integer.
2562 If no rounding mode is specified, take the rounding mode from
2563 the context. This method raises the Rounded and Inexact flags
2566 See also: to_integral_value, which does exactly the same as
2567 this method except that it doesn't raise Inexact or Rounded.
2569 if self._is_special:
2570 ans = self._check_nans(context=context)
2573 return Decimal(self)
2575 return Decimal(self)
2577 return _dec_from_triple(self._sign, '0', 0)
2579 context = getcontext()
2580 if rounding is None:
2581 rounding = context.rounding
2582 ans = self._rescale(0, rounding)
2584 context._raise_error(Inexact)
2585 context._raise_error(Rounded)
2588 def to_integral_value(self, rounding=None, context=None):
2589 """Rounds to the nearest integer, without raising inexact, rounded."""
2591 context = getcontext()
2592 if rounding is None:
2593 rounding = context.rounding
2594 if self._is_special:
2595 ans = self._check_nans(context=context)
2598 return Decimal(self)
2600 return Decimal(self)
2602 return self._rescale(0, rounding)
2604 # the method name changed, but we provide also the old one, for compatibility
2605 to_integral = to_integral_value
2607 def sqrt(self, context=None):
2608 """Return the square root of self."""
2610 context = getcontext()
2612 if self._is_special:
2613 ans = self._check_nans(context=context)
2617 if self._isinfinity() and self._sign == 0:
2618 return Decimal(self)
2621 # exponent = self._exp // 2. sqrt(-0) = -0
2622 ans = _dec_from_triple(self._sign, '0', self._exp // 2)
2623 return ans._fix(context)
2626 return context._raise_error(InvalidOperation, 'sqrt(-x), x > 0')
2628 # At this point self represents a positive number. Let p be
2629 # the desired precision and express self in the form c*100**e
2630 # with c a positive real number and e an integer, c and e
2631 # being chosen so that 100**(p-1) <= c < 100**p. Then the
2632 # (exact) square root of self is sqrt(c)*10**e, and 10**(p-1)
2633 # <= sqrt(c) < 10**p, so the closest representable Decimal at
2634 # precision p is n*10**e where n = round_half_even(sqrt(c)),
2635 # the closest integer to sqrt(c) with the even integer chosen
2636 # in the case of a tie.
2638 # To ensure correct rounding in all cases, we use the
2639 # following trick: we compute the square root to an extra
2640 # place (precision p+1 instead of precision p), rounding down.
2641 # Then, if the result is inexact and its last digit is 0 or 5,
2642 # we increase the last digit to 1 or 6 respectively; if it's
2643 # exact we leave the last digit alone. Now the final round to
2644 # p places (or fewer in the case of underflow) will round
2645 # correctly and raise the appropriate flags.
2647 # use an extra digit of precision
2648 prec = context.prec+1
2650 # write argument in the form c*100**e where e = self._exp//2
2651 # is the 'ideal' exponent, to be used if the square root is
2652 # exactly representable. l is the number of 'digits' of c in
2653 # base 100, so that 100**(l-1) <= c < 100**l.
2658 l = (len(self._int) >> 1) + 1
2661 l = len(self._int)+1 >> 1
2663 # rescale so that c has exactly prec base 100 'digits'
2669 c, remainder = divmod(c, 100**-shift)
2670 exact = not remainder
2673 # find n = floor(sqrt(c)) using Newton's method
2681 exact = exact and n*n == c
2684 # result is exact; rescale to use ideal exponent e
2686 # assert n % 10**shift == 0
2692 # result is not exact; fix last digit as described above
2696 ans = _dec_from_triple(0, str(n), e)
2698 # round, and fit to current context
2699 context = context._shallow_copy()
2700 rounding = context._set_rounding(ROUND_HALF_EVEN)
2701 ans = ans._fix(context)
2702 context.rounding = rounding
2706 def max(self, other, context=None):
2707 """Returns the larger value.
2709 Like max(self, other) except if one is not a number, returns
2710 NaN (and signals if one is sNaN). Also rounds.
2712 other = _convert_other(other, raiseit=True)
2715 context = getcontext()
2717 if self._is_special or other._is_special:
2718 # If one operand is a quiet NaN and the other is number, then the
2719 # number is always returned
2723 if on == 1 and sn == 0:
2724 return self._fix(context)
2725 if sn == 1 and on == 0:
2726 return other._fix(context)
2727 return self._check_nans(other, context)
2729 c = self._cmp(other)
2731 # If both operands are finite and equal in numerical value
2732 # then an ordering is applied:
2734 # If the signs differ then max returns the operand with the
2735 # positive sign and min returns the operand with the negative sign
2737 # If the signs are the same then the exponent is used to select
2738 # the result. This is exactly the ordering used in compare_total.
2739 c = self.compare_total(other)
2746 return ans._fix(context)
2748 def min(self, other, context=None):
2749 """Returns the smaller value.
2751 Like min(self, other) except if one is not a number, returns
2752 NaN (and signals if one is sNaN). Also rounds.
2754 other = _convert_other(other, raiseit=True)
2757 context = getcontext()
2759 if self._is_special or other._is_special:
2760 # If one operand is a quiet NaN and the other is number, then the
2761 # number is always returned
2765 if on == 1 and sn == 0:
2766 return self._fix(context)
2767 if sn == 1 and on == 0:
2768 return other._fix(context)
2769 return self._check_nans(other, context)
2771 c = self._cmp(other)
2773 c = self.compare_total(other)
2780 return ans._fix(context)
2782 def _isinteger(self):
2783 """Returns whether self is an integer"""
2784 if self._is_special:
2788 rest = self._int[self._exp:]
2789 return rest == '0'*len(rest)
2792 """Returns True if self is even. Assumes self is an integer."""
2793 if not self or self._exp > 0:
2795 return self._int[-1+self._exp] in '02468'
2798 """Return the adjusted exponent of self"""
2800 return self._exp + len(self._int) - 1
2801 # If NaN or Infinity, self._exp is string
2805 def canonical(self, context=None):
2806 """Returns the same Decimal object.
2808 As we do not have different encodings for the same number, the
2809 received object already is in its canonical form.
2813 def compare_signal(self, other, context=None):
2814 """Compares self to the other operand numerically.
2816 It's pretty much like compare(), but all NaNs signal, with signaling
2817 NaNs taking precedence over quiet NaNs.
2819 other = _convert_other(other, raiseit = True)
2820 ans = self._compare_check_nans(other, context)
2823 return self.compare(other, context=context)
2825 def compare_total(self, other):
2826 """Compares self to other using the abstract representations.
2828 This is not like the standard compare, which use their numerical
2829 value. Note that a total ordering is defined for all possible abstract
2832 other = _convert_other(other, raiseit=True)
2834 # if one is negative and the other is positive, it's easy
2835 if self._sign and not other._sign:
2837 if not self._sign and other._sign:
2841 # let's handle both NaN types
2842 self_nan = self._isnan()
2843 other_nan = other._isnan()
2844 if self_nan or other_nan:
2845 if self_nan == other_nan:
2846 # compare payloads as though they're integers
2847 self_key = len(self._int), self._int
2848 other_key = len(other._int), other._int
2849 if self_key < other_key:
2854 if self_key > other_key:
2885 if self._exp < other._exp:
2890 if self._exp > other._exp:
2898 def compare_total_mag(self, other):
2899 """Compares self to other using abstract repr., ignoring sign.
2901 Like compare_total, but with operand's sign ignored and assumed to be 0.
2903 other = _convert_other(other, raiseit=True)
2906 o = other.copy_abs()
2907 return s.compare_total(o)
2910 """Returns a copy with the sign set to 0. """
2911 return _dec_from_triple(0, self._int, self._exp, self._is_special)
2913 def copy_negate(self):
2914 """Returns a copy with the sign inverted."""
2916 return _dec_from_triple(0, self._int, self._exp, self._is_special)
2918 return _dec_from_triple(1, self._int, self._exp, self._is_special)
2920 def copy_sign(self, other):
2921 """Returns self with the sign of other."""
2922 other = _convert_other(other, raiseit=True)
2923 return _dec_from_triple(other._sign, self._int,
2924 self._exp, self._is_special)
2926 def exp(self, context=None):
2927 """Returns e ** self."""
2930 context = getcontext()
2933 ans = self._check_nans(context=context)
2937 # exp(-Infinity) = 0
2938 if self._isinfinity() == -1:
2945 # exp(Infinity) = Infinity
2946 if self._isinfinity() == 1:
2947 return Decimal(self)
2949 # the result is now guaranteed to be inexact (the true
2950 # mathematical result is transcendental). There's no need to
2951 # raise Rounded and Inexact here---they'll always be raised as
2952 # a result of the call to _fix.
2954 adj = self.adjusted()
2956 # we only need to do any computation for quite a small range
2957 # of adjusted exponents---for example, -29 <= adj <= 10 for
2958 # the default context. For smaller exponent the result is
2959 # indistinguishable from 1 at the given precision, while for
2960 # larger exponent the result either overflows or underflows.
2961 if self._sign == 0 and adj > len(str((context.Emax+1)*3)):
2963 ans = _dec_from_triple(0, '1', context.Emax+1)
2964 elif self._sign == 1 and adj > len(str((-context.Etiny()+1)*3)):
2966 ans = _dec_from_triple(0, '1', context.Etiny()-1)
2967 elif self._sign == 0 and adj < -p:
2968 # p+1 digits; final round will raise correct flags
2969 ans = _dec_from_triple(0, '1' + '0'*(p-1) + '1', -p)
2970 elif self._sign == 1 and adj < -p-1:
2971 # p+1 digits; final round will raise correct flags
2972 ans = _dec_from_triple(0, '9'*(p+1), -p-1)
2976 c, e = op.int, op.exp
2980 # compute correctly rounded result: increase precision by
2981 # 3 digits at a time until we get an unambiguously
2985 coeff, exp = _dexp(c, e, p+extra)
2986 if coeff % (5*10**(len(str(coeff))-p-1)):
2990 ans = _dec_from_triple(0, str(coeff), exp)
2992 # at this stage, ans should round correctly with *any*
2993 # rounding mode, not just with ROUND_HALF_EVEN
2994 context = context._shallow_copy()
2995 rounding = context._set_rounding(ROUND_HALF_EVEN)
2996 ans = ans._fix(context)
2997 context.rounding = rounding
3001 def is_canonical(self):
3002 """Return True if self is canonical; otherwise return False.
3004 Currently, the encoding of a Decimal instance is always
3005 canonical, so this method returns True for any Decimal.
3009 def is_finite(self):
3010 """Return True if self is finite; otherwise return False.
3012 A Decimal instance is considered finite if it is neither
3015 return not self._is_special
3017 def is_infinite(self):
3018 """Return True if self is infinite; otherwise return False."""
3019 return self._exp == 'F'
3022 """Return True if self is a qNaN or sNaN; otherwise return False."""
3023 return self._exp in ('n', 'N')
3025 def is_normal(self, context=None):
3026 """Return True if self is a normal number; otherwise return False."""
3027 if self._is_special or not self:
3030 context = getcontext()
3031 return context.Emin <= self.adjusted()
3034 """Return True if self is a quiet NaN; otherwise return False."""
3035 return self._exp == 'n'
3037 def is_signed(self):
3038 """Return True if self is negative; otherwise return False."""
3039 return self._sign == 1
3042 """Return True if self is a signaling NaN; otherwise return False."""
3043 return self._exp == 'N'
3045 def is_subnormal(self, context=None):
3046 """Return True if self is subnormal; otherwise return False."""
3047 if self._is_special or not self:
3050 context = getcontext()
3051 return self.adjusted() < context.Emin
3054 """Return True if self is a zero; otherwise return False."""
3055 return not self._is_special and self._int == '0'
3057 def _ln_exp_bound(self):
3058 """Compute a lower bound for the adjusted exponent of self.ln().
3059 In other words, compute r such that self.ln() >= 10**r. Assumes
3060 that self is finite and positive and that self != 1.
3063 # for 0.1 <= x <= 10 we use the inequalities 1-1/x <= ln(x) <= x-1
3064 adj = self._exp + len(self._int) - 1
3066 # argument >= 10; we use 23/10 = 2.3 as a lower bound for ln(10)
3067 return len(str(adj*23//10)) - 1
3070 return len(str((-1-adj)*23//10)) - 1
3072 c, e = op.int, op.exp
3077 return len(num) - len(den) - (num < den)
3078 # adj == -1, 0.1 <= self < 1
3079 return e + len(str(10**-e - c)) - 1
3082 def ln(self, context=None):
3083 """Returns the natural (base e) logarithm of self."""
3086 context = getcontext()
3089 ans = self._check_nans(context=context)
3093 # ln(0.0) == -Infinity
3095 return _NegativeInfinity
3097 # ln(Infinity) = Infinity
3098 if self._isinfinity() == 1:
3105 # ln(negative) raises InvalidOperation
3107 return context._raise_error(InvalidOperation,
3108 'ln of a negative value')
3110 # result is irrational, so necessarily inexact
3112 c, e = op.int, op.exp
3115 # correctly rounded result: repeatedly increase precision by 3
3116 # until we get an unambiguously roundable result
3117 places = p - self._ln_exp_bound() + 2 # at least p+3 places
3119 coeff = _dlog(c, e, places)
3120 # assert len(str(abs(coeff)))-p >= 1
3121 if coeff % (5*10**(len(str(abs(coeff)))-p-1)):
3124 ans = _dec_from_triple(int(coeff<0), str(abs(coeff)), -places)
3126 context = context._shallow_copy()
3127 rounding = context._set_rounding(ROUND_HALF_EVEN)
3128 ans = ans._fix(context)
3129 context.rounding = rounding
3132 def _log10_exp_bound(self):
3133 """Compute a lower bound for the adjusted exponent of self.log10().
3134 In other words, find r such that self.log10() >= 10**r.
3135 Assumes that self is finite and positive and that self != 1.
3138 # For x >= 10 or x < 0.1 we only need a bound on the integer
3139 # part of log10(self), and this comes directly from the
3140 # exponent of x. For 0.1 <= x <= 10 we use the inequalities
3141 # 1-1/x <= log(x) <= x-1. If x > 1 we have |log10(x)| >
3142 # (1-1/x)/2.31 > 0. If x < 1 then |log10(x)| > (1-x)/2.31 > 0
3144 adj = self._exp + len(self._int) - 1
3147 return len(str(adj))-1
3150 return len(str(-1-adj))-1
3152 c, e = op.int, op.exp
3157 return len(num) - len(den) - (num < den) + 2
3158 # adj == -1, 0.1 <= self < 1
3160 return len(num) + e - (num < "231") - 1
3162 def log10(self, context=None):
3163 """Returns the base 10 logarithm of self."""
3166 context = getcontext()
3169 ans = self._check_nans(context=context)
3173 # log10(0.0) == -Infinity
3175 return _NegativeInfinity
3177 # log10(Infinity) = Infinity
3178 if self._isinfinity() == 1:
3181 # log10(negative or -Infinity) raises InvalidOperation
3183 return context._raise_error(InvalidOperation,
3184 'log10 of a negative value')
3187 if self._int[0] == '1' and self._int[1:] == '0'*(len(self._int) - 1):
3188 # answer may need rounding
3189 ans = Decimal(self._exp + len(self._int) - 1)
3191 # result is irrational, so necessarily inexact
3193 c, e = op.int, op.exp
3196 # correctly rounded result: repeatedly increase precision
3197 # until result is unambiguously roundable
3198 places = p-self._log10_exp_bound()+2
3200 coeff = _dlog10(c, e, places)
3201 # assert len(str(abs(coeff)))-p >= 1
3202 if coeff % (5*10**(len(str(abs(coeff)))-p-1)):
3205 ans = _dec_from_triple(int(coeff<0), str(abs(coeff)), -places)
3207 context = context._shallow_copy()
3208 rounding = context._set_rounding(ROUND_HALF_EVEN)
3209 ans = ans._fix(context)
3210 context.rounding = rounding
3213 def logb(self, context=None):
3214 """ Returns the exponent of the magnitude of self's MSD.
3216 The result is the integer which is the exponent of the magnitude
3217 of the most significant digit of self (as though it were truncated
3218 to a single digit while maintaining the value of that digit and
3219 without limiting the resulting exponent).
3222 ans = self._check_nans(context=context)
3227 context = getcontext()
3229 # logb(+/-Inf) = +Inf
3230 if self._isinfinity():
3233 # logb(0) = -Inf, DivisionByZero
3235 return context._raise_error(DivisionByZero, 'logb(0)', 1)
3237 # otherwise, simply return the adjusted exponent of self, as a
3238 # Decimal. Note that no attempt is made to fit the result
3239 # into the current context.
3240 ans = Decimal(self.adjusted())
3241 return ans._fix(context)
3243 def _islogical(self):
3244 """Return True if self is a logical operand.
3246 For being logical, it must be a finite number with a sign of 0,
3247 an exponent of 0, and a coefficient whose digits must all be
3250 if self._sign != 0 or self._exp != 0:
3252 for dig in self._int:
3257 def _fill_logical(self, context, opa, opb):
3258 dif = context.prec - len(opa)
3262 opa = opa[-context.prec:]
3263 dif = context.prec - len(opb)
3267 opb = opb[-context.prec:]
3270 def logical_and(self, other, context=None):
3271 """Applies an 'and' 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_invert(self, context=None):
3288 """Invert all its digits."""
3290 context = getcontext()
3291 return self.logical_xor(_dec_from_triple(0,'1'*context.prec,0),
3294 def logical_or(self, other, context=None):
3295 """Applies an 'or' operation between self and other's digits."""
3297 context = getcontext()
3299 other = _convert_other(other, raiseit=True)
3301 if not self._islogical() or not other._islogical():
3302 return context._raise_error(InvalidOperation)
3304 # fill to context.prec
3305 (opa, opb) = self._fill_logical(context, self._int, other._int)
3307 # make the operation, and clean starting zeroes
3308 result = "".join([str(int(a)|int(b)) for a,b in zip(opa,opb)])
3309 return _dec_from_triple(0, result.lstrip('0') or '0', 0)
3311 def logical_xor(self, other, context=None):
3312 """Applies an 'xor' operation between self and other's digits."""
3314 context = getcontext()
3316 other = _convert_other(other, raiseit=True)
3318 if not self._islogical() or not other._islogical():
3319 return context._raise_error(InvalidOperation)
3321 # fill to context.prec
3322 (opa, opb) = self._fill_logical(context, self._int, other._int)
3324 # make the operation, and clean starting zeroes
3325 result = "".join([str(int(a)^int(b)) for a,b in zip(opa,opb)])
3326 return _dec_from_triple(0, result.lstrip('0') or '0', 0)
3328 def max_mag(self, other, context=None):
3329 """Compares the values numerically with their sign ignored."""
3330 other = _convert_other(other, raiseit=True)
3333 context = getcontext()
3335 if self._is_special or other._is_special:
3336 # If one operand is a quiet NaN and the other is number, then the
3337 # number is always returned
3341 if on == 1 and sn == 0:
3342 return self._fix(context)
3343 if sn == 1 and on == 0:
3344 return other._fix(context)
3345 return self._check_nans(other, context)
3347 c = self.copy_abs()._cmp(other.copy_abs())
3349 c = self.compare_total(other)
3356 return ans._fix(context)
3358 def min_mag(self, other, context=None):
3359 """Compares the values numerically with their sign ignored."""
3360 other = _convert_other(other, raiseit=True)
3363 context = getcontext()
3365 if self._is_special or other._is_special:
3366 # If one operand is a quiet NaN and the other is number, then the
3367 # number is always returned
3371 if on == 1 and sn == 0:
3372 return self._fix(context)
3373 if sn == 1 and on == 0:
3374 return other._fix(context)
3375 return self._check_nans(other, context)
3377 c = self.copy_abs()._cmp(other.copy_abs())
3379 c = self.compare_total(other)
3386 return ans._fix(context)
3388 def next_minus(self, context=None):
3389 """Returns the largest representable number smaller than itself."""
3391 context = getcontext()
3393 ans = self._check_nans(context=context)
3397 if self._isinfinity() == -1:
3398 return _NegativeInfinity
3399 if self._isinfinity() == 1:
3400 return _dec_from_triple(0, '9'*context.prec, context.Etop())
3402 context = context.copy()
3403 context._set_rounding(ROUND_FLOOR)
3404 context._ignore_all_flags()
3405 new_self = self._fix(context)
3406 if new_self != self:
3408 return self.__sub__(_dec_from_triple(0, '1', context.Etiny()-1),
3411 def next_plus(self, context=None):
3412 """Returns the smallest representable number larger than itself."""
3414 context = getcontext()
3416 ans = self._check_nans(context=context)
3420 if self._isinfinity() == 1:
3422 if self._isinfinity() == -1:
3423 return _dec_from_triple(1, '9'*context.prec, context.Etop())
3425 context = context.copy()
3426 context._set_rounding(ROUND_CEILING)
3427 context._ignore_all_flags()
3428 new_self = self._fix(context)
3429 if new_self != self:
3431 return self.__add__(_dec_from_triple(0, '1', context.Etiny()-1),
3434 def next_toward(self, other, context=None):
3435 """Returns the number closest to self, in the direction towards other.
3437 The result is the closest representable number to self
3438 (excluding self) that is in the direction towards other,
3439 unless both have the same value. If the two operands are
3440 numerically equal, then the result is a copy of self with the
3441 sign set to be the same as the sign of other.
3443 other = _convert_other(other, raiseit=True)
3446 context = getcontext()
3448 ans = self._check_nans(other, context)
3452 comparison = self._cmp(other)
3454 return self.copy_sign(other)
3456 if comparison == -1:
3457 ans = self.next_plus(context)
3458 else: # comparison == 1
3459 ans = self.next_minus(context)
3461 # decide which flags to raise using value of ans
3462 if ans._isinfinity():
3463 context._raise_error(Overflow,
3464 'Infinite result from next_toward',
3466 context._raise_error(Inexact)
3467 context._raise_error(Rounded)
3468 elif ans.adjusted() < context.Emin:
3469 context._raise_error(Underflow)
3470 context._raise_error(Subnormal)
3471 context._raise_error(Inexact)
3472 context._raise_error(Rounded)
3473 # if precision == 1 then we don't raise Clamped for a
3476 context._raise_error(Clamped)
3480 def number_class(self, context=None):
3481 """Returns an indication of the class of self.
3483 The class is one of the following strings:
3499 inf = self._isinfinity()
3510 context = getcontext()
3511 if self.is_subnormal(context=context):
3516 # just a normal, regular, boring number, :)
3523 """Just returns 10, as this is Decimal, :)"""
3526 def rotate(self, other, context=None):
3527 """Returns a rotated copy of self, value-of-other times."""
3529 context = getcontext()
3531 other = _convert_other(other, raiseit=True)
3533 ans = self._check_nans(other, context)
3538 return context._raise_error(InvalidOperation)
3539 if not (-context.prec <= int(other) <= context.prec):
3540 return context._raise_error(InvalidOperation)
3542 if self._isinfinity():
3543 return Decimal(self)
3545 # get values, pad if necessary
3548 topad = context.prec - len(rotdig)
3550 rotdig = '0'*topad + rotdig
3552 rotdig = rotdig[-topad:]
3555 rotated = rotdig[torot:] + rotdig[:torot]
3556 return _dec_from_triple(self._sign,
3557 rotated.lstrip('0') or '0', self._exp)
3559 def scaleb(self, other, context=None):
3560 """Returns self operand after adding the second value to its exp."""
3562 context = getcontext()
3564 other = _convert_other(other, raiseit=True)
3566 ans = self._check_nans(other, context)
3571 return context._raise_error(InvalidOperation)
3572 liminf = -2 * (context.Emax + context.prec)
3573 limsup = 2 * (context.Emax + context.prec)
3574 if not (liminf <= int(other) <= limsup):
3575 return context._raise_error(InvalidOperation)
3577 if self._isinfinity():
3578 return Decimal(self)
3580 d = _dec_from_triple(self._sign, self._int, self._exp + int(other))
3584 def shift(self, other, context=None):
3585 """Returns a shifted copy of self, value-of-other times."""
3587 context = getcontext()
3589 other = _convert_other(other, raiseit=True)
3591 ans = self._check_nans(other, context)
3596 return context._raise_error(InvalidOperation)
3597 if not (-context.prec <= int(other) <= context.prec):
3598 return context._raise_error(InvalidOperation)
3600 if self._isinfinity():
3601 return Decimal(self)
3603 # get values, pad if necessary
3606 topad = context.prec - len(rotdig)
3608 rotdig = '0'*topad + rotdig
3610 rotdig = rotdig[-topad:]
3614 shifted = rotdig[:torot]
3616 shifted = rotdig + '0'*torot
3617 shifted = shifted[-context.prec:]
3619 return _dec_from_triple(self._sign,
3620 shifted.lstrip('0') or '0', self._exp)
3622 # Support for pickling, copy, and deepcopy
3623 def __reduce__(self):
3624 return (self.__class__, (str(self),))
3627 if type(self) is Decimal:
3628 return self # I'm immutable; therefore I am my own clone
3629 return self.__class__(str(self))
3631 def __deepcopy__(self, memo):
3632 if type(self) is Decimal:
3633 return self # My components are also immutable
3634 return self.__class__(str(self))
3636 # PEP 3101 support. the _localeconv keyword argument should be
3637 # considered private: it's provided for ease of testing only.
3638 def __format__(self, specifier, context=None, _localeconv=None):
3639 """Format a Decimal instance according to the given specifier.
3641 The specifier should be a standard format specifier, with the
3642 form described in PEP 3101. Formatting types 'e', 'E', 'f',
3643 'F', 'g', 'G', 'n' and '%' are supported. If the formatting
3644 type is omitted it defaults to 'g' or 'G', depending on the
3645 value of context.capitals.
3648 # Note: PEP 3101 says that if the type is not present then
3649 # there should be at least one digit after the decimal point.
3650 # We take the liberty of ignoring this requirement for
3651 # Decimal---it's presumably there to make sure that
3652 # format(float, '') behaves similarly to str(float).
3654 context = getcontext()
3656 spec = _parse_format_specifier(specifier, _localeconv=_localeconv)
3658 # special values don't care about the type or precision
3659 if self._is_special:
3660 sign = _format_sign(self._sign, spec)
3661 body = str(self.copy_abs())
3662 return _format_align(sign, body, spec)
3664 # a type of None defaults to 'g' or 'G', depending on context
3665 if spec['type'] is None:
3666 spec['type'] = ['g', 'G'][context.capitals]
3668 # if type is '%', adjust exponent of self accordingly
3669 if spec['type'] == '%':
3670 self = _dec_from_triple(self._sign, self._int, self._exp+2)
3672 # round if necessary, taking rounding mode from the context
3673 rounding = context.rounding
3674 precision = spec['precision']
3675 if precision is not None:
3676 if spec['type'] in 'eE':
3677 self = self._round(precision+1, rounding)
3678 elif spec['type'] in 'fF%':
3679 self = self._rescale(-precision, rounding)
3680 elif spec['type'] in 'gG' and len(self._int) > precision:
3681 self = self._round(precision, rounding)
3682 # special case: zeros with a positive exponent can't be
3683 # represented in fixed point; rescale them to 0e0.
3684 if not self and self._exp > 0 and spec['type'] in 'fF%':
3685 self = self._rescale(0, rounding)
3687 # figure out placement of the decimal point
3688 leftdigits = self._exp + len(self._int)
3689 if spec['type'] in 'eE':
3690 if not self and precision is not None:
3691 dotplace = 1 - precision
3694 elif spec['type'] in 'fF%':
3695 dotplace = leftdigits
3696 elif spec['type'] in 'gG':
3697 if self._exp <= 0 and leftdigits > -6:
3698 dotplace = leftdigits
3702 # find digits before and after decimal point, and get exponent
3705 fracpart = '0'*(-dotplace) + self._int
3706 elif dotplace > len(self._int):
3707 intpart = self._int + '0'*(dotplace-len(self._int))
3710 intpart = self._int[:dotplace] or '0'
3711 fracpart = self._int[dotplace:]
3712 exp = leftdigits-dotplace
3714 # done with the decimal-specific stuff; hand over the rest
3715 # of the formatting to the _format_number function
3716 return _format_number(self._sign, intpart, fracpart, exp, spec)
3718 def _dec_from_triple(sign, coefficient, exponent, special=False):
3719 """Create a decimal instance directly, without any validation,
3720 normalization (e.g. removal of leading zeros) or argument
3723 This function is for *internal use only*.
3726 self = object.__new__(Decimal)
3728 self._int = coefficient
3729 self._exp = exponent
3730 self._is_special = special
3734 # Register Decimal as a kind of Number (an abstract base class).
3735 # However, do not register it as Real (because Decimals are not
3736 # interoperable with floats).
3737 _numbers.Number.register(Decimal)
3740 ##### Context class #######################################################
3742 class _ContextManager(object):
3743 """Context manager class to support localcontext().
3745 Sets a copy of the supplied context in __enter__() and restores
3746 the previous decimal context in __exit__()
3748 def __init__(self, new_context):
3749 self.new_context = new_context.copy()
3750 def __enter__(self):
3751 self.saved_context = getcontext()
3752 setcontext(self.new_context)
3753 return self.new_context
3754 def __exit__(self, t, v, tb):
3755 setcontext(self.saved_context)
3757 class Context(object):
3758 """Contains the context for a Decimal instance.
3761 prec - precision (for use in rounding, division, square roots..)
3762 rounding - rounding type (how you round)
3763 traps - If traps[exception] = 1, then the exception is
3764 raised when it is caused. Otherwise, a value is
3766 flags - When an exception is caused, flags[exception] is set.
3767 (Whether or not the trap_enabler is set)
3768 Should be reset by user of Decimal instance.
3769 Emin - Minimum exponent
3770 Emax - Maximum exponent
3771 capitals - If 1, 1*10^1 is printed as 1E+1.
3772 If 0, printed as 1e1
3773 _clamp - If 1, change exponents if too high (Default 0)
3776 def __init__(self, prec=None, rounding=None,
3777 traps=None, flags=None,
3778 Emin=None, Emax=None,
3779 capitals=None, _clamp=0,
3780 _ignored_flags=None):
3781 # Set defaults; for everything except flags and _ignored_flags,
3782 # inherit from DefaultContext.
3788 self.prec = prec if prec is not None else dc.prec
3789 self.rounding = rounding if rounding is not None else dc.rounding
3790 self.Emin = Emin if Emin is not None else dc.Emin
3791 self.Emax = Emax if Emax is not None else dc.Emax
3792 self.capitals = capitals if capitals is not None else dc.capitals
3793 self._clamp = _clamp if _clamp is not None else dc._clamp
3795 if _ignored_flags is None:
3796 self._ignored_flags = []
3798 self._ignored_flags = _ignored_flags
3801 self.traps = dc.traps.copy()
3802 elif not isinstance(traps, dict):
3803 self.traps = dict((s, int(s in traps)) for s in _signals)
3808 self.flags = dict.fromkeys(_signals, 0)
3809 elif not isinstance(flags, dict):
3810 self.flags = dict((s, int(s in flags)) for s in _signals)
3815 """Show the current context."""
3817 s.append('Context(prec=%(prec)d, rounding=%(rounding)s, '
3818 'Emin=%(Emin)d, Emax=%(Emax)d, capitals=%(capitals)d'
3820 names = [f.__name__ for f, v in self.flags.items() if v]
3821 s.append('flags=[' + ', '.join(names) + ']')
3822 names = [t.__name__ for t, v in self.traps.items() if v]
3823 s.append('traps=[' + ', '.join(names) + ']')
3824 return ', '.join(s) + ')'
3826 def clear_flags(self):
3827 """Reset all flags to zero"""
3828 for flag in self.flags:
3829 self.flags[flag] = 0
3831 def _shallow_copy(self):
3832 """Returns a shallow copy from self."""
3833 nc = Context(self.prec, self.rounding, self.traps,
3834 self.flags, self.Emin, self.Emax,
3835 self.capitals, self._clamp, self._ignored_flags)
3839 """Returns a deep copy from self."""
3840 nc = Context(self.prec, self.rounding, self.traps.copy(),
3841 self.flags.copy(), self.Emin, self.Emax,
3842 self.capitals, self._clamp, self._ignored_flags)
3846 def _raise_error(self, condition, explanation = None, *args):
3849 If the flag is in _ignored_flags, returns the default response.
3850 Otherwise, it sets the flag, then, if the corresponding
3851 trap_enabler is set, it reraises the exception. Otherwise, it returns
3852 the default value after setting the flag.
3854 error = _condition_map.get(condition, condition)
3855 if error in self._ignored_flags:
3856 # Don't touch the flag
3857 return error().handle(self, *args)
3859 self.flags[error] = 1
3860 if not self.traps[error]:
3861 # The errors define how to handle themselves.
3862 return condition().handle(self, *args)
3864 # Errors should only be risked on copies of the context
3865 # self._ignored_flags = []
3866 raise error(explanation)
3868 def _ignore_all_flags(self):
3869 """Ignore all flags, if they are raised"""
3870 return self._ignore_flags(*_signals)
3872 def _ignore_flags(self, *flags):
3873 """Ignore the flags, if they are raised"""
3874 # Do not mutate-- This way, copies of a context leave the original
3876 self._ignored_flags = (self._ignored_flags + list(flags))
3879 def _regard_flags(self, *flags):
3880 """Stop ignoring the flags, if they are raised"""
3881 if flags and isinstance(flags[0], (tuple,list)):
3884 self._ignored_flags.remove(flag)
3886 # We inherit object.__hash__, so we must deny this explicitly
3890 """Returns Etiny (= Emin - prec + 1)"""
3891 return int(self.Emin - self.prec + 1)
3894 """Returns maximum exponent (= Emax - prec + 1)"""
3895 return int(self.Emax - self.prec + 1)
3897 def _set_rounding(self, type):
3898 """Sets the rounding type.
3900 Sets the rounding type, and returns the current (previous)
3901 rounding type. Often used like:
3903 context = context.copy()
3904 # so you don't change the calling context
3905 # if an error occurs in the middle.
3906 rounding = context._set_rounding(ROUND_UP)
3907 val = self.__sub__(other, context=context)
3908 context._set_rounding(rounding)
3910 This will make it round up for that operation.
3912 rounding = self.rounding
3916 def create_decimal(self, num='0'):
3917 """Creates a new Decimal instance but using self as context.
3919 This method implements the to-number operation of the
3920 IBM Decimal specification."""
3922 if isinstance(num, basestring) and num != num.strip():
3923 return self._raise_error(ConversionSyntax,
3924 "no trailing or leading whitespace is "
3927 d = Decimal(num, context=self)
3928 if d._isnan() and len(d._int) > self.prec - self._clamp:
3929 return self._raise_error(ConversionSyntax,
3930 "diagnostic info too long in NaN")
3933 def create_decimal_from_float(self, f):
3934 """Creates a new Decimal instance from a float but rounding using self
3937 >>> context = Context(prec=5, rounding=ROUND_DOWN)
3938 >>> context.create_decimal_from_float(3.1415926535897932)
3940 >>> context = Context(prec=5, traps=[Inexact])
3941 >>> context.create_decimal_from_float(3.1415926535897932)
3942 Traceback (most recent call last):
3947 d = Decimal.from_float(f) # An exact conversion
3948 return d._fix(self) # Apply the context rounding
3952 """Returns the absolute value of the operand.
3954 If the operand is negative, the result is the same as using the minus
3955 operation on the operand. Otherwise, the result is the same as using
3956 the plus operation on the operand.
3958 >>> ExtendedContext.abs(Decimal('2.1'))
3960 >>> ExtendedContext.abs(Decimal('-100'))
3962 >>> ExtendedContext.abs(Decimal('101.5'))
3964 >>> ExtendedContext.abs(Decimal('-101.5'))
3966 >>> ExtendedContext.abs(-1)
3969 a = _convert_other(a, raiseit=True)
3970 return a.__abs__(context=self)
3972 def add(self, a, b):
3973 """Return the sum of the two operands.
3975 >>> ExtendedContext.add(Decimal('12'), Decimal('7.00'))
3977 >>> ExtendedContext.add(Decimal('1E+2'), Decimal('1.01E+4'))
3979 >>> ExtendedContext.add(1, Decimal(2))
3981 >>> ExtendedContext.add(Decimal(8), 5)
3983 >>> ExtendedContext.add(5, 5)
3986 a = _convert_other(a, raiseit=True)
3987 r = a.__add__(b, context=self)
3988 if r is NotImplemented:
3989 raise TypeError("Unable to convert %s to Decimal" % b)
3993 def _apply(self, a):
3994 return str(a._fix(self))
3996 def canonical(self, a):
3997 """Returns the same Decimal object.
3999 As we do not have different encodings for the same number, the
4000 received object already is in its canonical form.
4002 >>> ExtendedContext.canonical(Decimal('2.50'))
4005 return a.canonical(context=self)
4007 def compare(self, a, b):
4008 """Compares values numerically.
4010 If the signs of the operands differ, a value representing each operand
4011 ('-1' if the operand is less than zero, '0' if the operand is zero or
4012 negative zero, or '1' if the operand is greater than zero) is used in
4013 place of that operand for the comparison instead of the actual
4016 The comparison is then effected by subtracting the second operand from
4017 the first and then returning a value according to the result of the
4018 subtraction: '-1' if the result is less than zero, '0' if the result is
4019 zero or negative zero, or '1' if the result is greater than zero.
4021 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
4023 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
4025 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))
4027 >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))
4029 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))
4031 >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))
4033 >>> ExtendedContext.compare(1, 2)
4035 >>> ExtendedContext.compare(Decimal(1), 2)
4037 >>> ExtendedContext.compare(1, Decimal(2))
4040 a = _convert_other(a, raiseit=True)
4041 return a.compare(b, context=self)
4043 def compare_signal(self, a, b):
4044 """Compares the values of the two operands numerically.
4046 It's pretty much like compare(), but all NaNs signal, with signaling
4047 NaNs taking precedence over quiet NaNs.
4049 >>> c = ExtendedContext
4050 >>> c.compare_signal(Decimal('2.1'), Decimal('3'))
4052 >>> c.compare_signal(Decimal('2.1'), Decimal('2.1'))
4054 >>> c.flags[InvalidOperation] = 0
4055 >>> print c.flags[InvalidOperation]
4057 >>> c.compare_signal(Decimal('NaN'), Decimal('2.1'))
4059 >>> print c.flags[InvalidOperation]
4061 >>> c.flags[InvalidOperation] = 0
4062 >>> print c.flags[InvalidOperation]
4064 >>> c.compare_signal(Decimal('sNaN'), Decimal('2.1'))
4066 >>> print c.flags[InvalidOperation]
4068 >>> c.compare_signal(-1, 2)
4070 >>> c.compare_signal(Decimal(-1), 2)
4072 >>> c.compare_signal(-1, Decimal(2))
4075 a = _convert_other(a, raiseit=True)
4076 return a.compare_signal(b, context=self)
4078 def compare_total(self, a, b):
4079 """Compares two operands using their abstract representation.
4081 This is not like the standard compare, which use their numerical
4082 value. Note that a total ordering is defined for all possible abstract
4085 >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
4087 >>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12'))
4089 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))
4091 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))
4093 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300'))
4095 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN'))
4097 >>> ExtendedContext.compare_total(1, 2)
4099 >>> ExtendedContext.compare_total(Decimal(1), 2)
4101 >>> ExtendedContext.compare_total(1, Decimal(2))
4104 a = _convert_other(a, raiseit=True)
4105 return a.compare_total(b)
4107 def compare_total_mag(self, a, b):
4108 """Compares two operands using their abstract representation ignoring sign.
4110 Like compare_total, but with operand's sign ignored and assumed to be 0.
4112 a = _convert_other(a, raiseit=True)
4113 return a.compare_total_mag(b)
4115 def copy_abs(self, a):
4116 """Returns a copy of the operand with the sign set to 0.
4118 >>> ExtendedContext.copy_abs(Decimal('2.1'))
4120 >>> ExtendedContext.copy_abs(Decimal('-100'))
4122 >>> ExtendedContext.copy_abs(-1)
4125 a = _convert_other(a, raiseit=True)
4128 def copy_decimal(self, a):
4129 """Returns a copy of the decimal object.
4131 >>> ExtendedContext.copy_decimal(Decimal('2.1'))
4133 >>> ExtendedContext.copy_decimal(Decimal('-1.00'))
4135 >>> ExtendedContext.copy_decimal(1)
4138 a = _convert_other(a, raiseit=True)
4141 def copy_negate(self, a):
4142 """Returns a copy of the operand with the sign inverted.
4144 >>> ExtendedContext.copy_negate(Decimal('101.5'))
4146 >>> ExtendedContext.copy_negate(Decimal('-101.5'))
4148 >>> ExtendedContext.copy_negate(1)
4151 a = _convert_other(a, raiseit=True)
4152 return a.copy_negate()
4154 def copy_sign(self, a, b):
4155 """Copies the second operand's sign to the first one.
4157 In detail, it returns a copy of the first operand with the sign
4158 equal to the sign of the second operand.
4160 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))
4162 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))
4164 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))
4166 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))
4168 >>> ExtendedContext.copy_sign(1, -2)
4170 >>> ExtendedContext.copy_sign(Decimal(1), -2)
4172 >>> ExtendedContext.copy_sign(1, Decimal(-2))
4175 a = _convert_other(a, raiseit=True)
4176 return a.copy_sign(b)
4178 def divide(self, a, b):
4179 """Decimal division in a specified context.
4181 >>> ExtendedContext.divide(Decimal('1'), Decimal('3'))
4182 Decimal('0.333333333')
4183 >>> ExtendedContext.divide(Decimal('2'), Decimal('3'))
4184 Decimal('0.666666667')
4185 >>> ExtendedContext.divide(Decimal('5'), Decimal('2'))
4187 >>> ExtendedContext.divide(Decimal('1'), Decimal('10'))
4189 >>> ExtendedContext.divide(Decimal('12'), Decimal('12'))
4191 >>> ExtendedContext.divide(Decimal('8.00'), Decimal('2'))
4193 >>> ExtendedContext.divide(Decimal('2.400'), Decimal('2.0'))
4195 >>> ExtendedContext.divide(Decimal('1000'), Decimal('100'))
4197 >>> ExtendedContext.divide(Decimal('1000'), Decimal('1'))
4199 >>> ExtendedContext.divide(Decimal('2.40E+6'), Decimal('2'))
4201 >>> ExtendedContext.divide(5, 5)
4203 >>> ExtendedContext.divide(Decimal(5), 5)
4205 >>> ExtendedContext.divide(5, Decimal(5))
4208 a = _convert_other(a, raiseit=True)
4209 r = a.__div__(b, context=self)
4210 if r is NotImplemented:
4211 raise TypeError("Unable to convert %s to Decimal" % b)
4215 def divide_int(self, a, b):
4216 """Divides two numbers and returns the integer part of the result.
4218 >>> ExtendedContext.divide_int(Decimal('2'), Decimal('3'))
4220 >>> ExtendedContext.divide_int(Decimal('10'), Decimal('3'))
4222 >>> ExtendedContext.divide_int(Decimal('1'), Decimal('0.3'))
4224 >>> ExtendedContext.divide_int(10, 3)
4226 >>> ExtendedContext.divide_int(Decimal(10), 3)
4228 >>> ExtendedContext.divide_int(10, Decimal(3))
4231 a = _convert_other(a, raiseit=True)
4232 r = a.__floordiv__(b, context=self)
4233 if r is NotImplemented:
4234 raise TypeError("Unable to convert %s to Decimal" % b)
4238 def divmod(self, a, b):
4239 """Return (a // b, a % b).
4241 >>> ExtendedContext.divmod(Decimal(8), Decimal(3))
4242 (Decimal('2'), Decimal('2'))
4243 >>> ExtendedContext.divmod(Decimal(8), Decimal(4))
4244 (Decimal('2'), Decimal('0'))
4245 >>> ExtendedContext.divmod(8, 4)
4246 (Decimal('2'), Decimal('0'))
4247 >>> ExtendedContext.divmod(Decimal(8), 4)
4248 (Decimal('2'), Decimal('0'))
4249 >>> ExtendedContext.divmod(8, Decimal(4))
4250 (Decimal('2'), Decimal('0'))
4252 a = _convert_other(a, raiseit=True)
4253 r = a.__divmod__(b, context=self)
4254 if r is NotImplemented:
4255 raise TypeError("Unable to convert %s to Decimal" % b)
4262 >>> c = ExtendedContext.copy()
4265 >>> c.exp(Decimal('-Infinity'))
4267 >>> c.exp(Decimal('-1'))
4268 Decimal('0.367879441')
4269 >>> c.exp(Decimal('0'))
4271 >>> c.exp(Decimal('1'))
4272 Decimal('2.71828183')
4273 >>> c.exp(Decimal('0.693147181'))
4274 Decimal('2.00000000')
4275 >>> c.exp(Decimal('+Infinity'))
4278 Decimal('22026.4658')
4280 a =_convert_other(a, raiseit=True)
4281 return a.exp(context=self)
4283 def fma(self, a, b, c):
4284 """Returns a multiplied by b, plus c.
4286 The first two operands are multiplied together, using multiply,
4287 the third operand is then added to the result of that
4288 multiplication, using add, all with only one final rounding.
4290 >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
4292 >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))
4294 >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578'))
4295 Decimal('1.38435736E+12')
4296 >>> ExtendedContext.fma(1, 3, 4)
4298 >>> ExtendedContext.fma(1, Decimal(3), 4)
4300 >>> ExtendedContext.fma(1, 3, Decimal(4))
4303 a = _convert_other(a, raiseit=True)
4304 return a.fma(b, c, context=self)
4306 def is_canonical(self, a):
4307 """Return True if the operand is canonical; otherwise return False.
4309 Currently, the encoding of a Decimal instance is always
4310 canonical, so this method returns True for any Decimal.
4312 >>> ExtendedContext.is_canonical(Decimal('2.50'))
4315 return a.is_canonical()
4317 def is_finite(self, a):
4318 """Return True if the operand is finite; otherwise return False.
4320 A Decimal instance is considered finite if it is neither
4323 >>> ExtendedContext.is_finite(Decimal('2.50'))
4325 >>> ExtendedContext.is_finite(Decimal('-0.3'))
4327 >>> ExtendedContext.is_finite(Decimal('0'))
4329 >>> ExtendedContext.is_finite(Decimal('Inf'))
4331 >>> ExtendedContext.is_finite(Decimal('NaN'))
4333 >>> ExtendedContext.is_finite(1)
4336 a = _convert_other(a, raiseit=True)
4337 return a.is_finite()
4339 def is_infinite(self, a):
4340 """Return True if the operand is infinite; otherwise return False.
4342 >>> ExtendedContext.is_infinite(Decimal('2.50'))
4344 >>> ExtendedContext.is_infinite(Decimal('-Inf'))
4346 >>> ExtendedContext.is_infinite(Decimal('NaN'))
4348 >>> ExtendedContext.is_infinite(1)
4351 a = _convert_other(a, raiseit=True)
4352 return a.is_infinite()
4354 def is_nan(self, a):
4355 """Return True if the operand is a qNaN or sNaN;
4356 otherwise return False.
4358 >>> ExtendedContext.is_nan(Decimal('2.50'))
4360 >>> ExtendedContext.is_nan(Decimal('NaN'))
4362 >>> ExtendedContext.is_nan(Decimal('-sNaN'))
4364 >>> ExtendedContext.is_nan(1)
4367 a = _convert_other(a, raiseit=True)
4370 def is_normal(self, a):
4371 """Return True if the operand is a normal number;
4372 otherwise return False.
4374 >>> c = ExtendedContext.copy()
4377 >>> c.is_normal(Decimal('2.50'))
4379 >>> c.is_normal(Decimal('0.1E-999'))
4381 >>> c.is_normal(Decimal('0.00'))
4383 >>> c.is_normal(Decimal('-Inf'))
4385 >>> c.is_normal(Decimal('NaN'))
4390 a = _convert_other(a, raiseit=True)
4391 return a.is_normal(context=self)
4393 def is_qnan(self, a):
4394 """Return True if the operand is a quiet NaN; otherwise return False.
4396 >>> ExtendedContext.is_qnan(Decimal('2.50'))
4398 >>> ExtendedContext.is_qnan(Decimal('NaN'))
4400 >>> ExtendedContext.is_qnan(Decimal('sNaN'))
4402 >>> ExtendedContext.is_qnan(1)
4405 a = _convert_other(a, raiseit=True)
4408 def is_signed(self, a):
4409 """Return True if the operand is negative; otherwise return False.
4411 >>> ExtendedContext.is_signed(Decimal('2.50'))
4413 >>> ExtendedContext.is_signed(Decimal('-12'))
4415 >>> ExtendedContext.is_signed(Decimal('-0'))
4417 >>> ExtendedContext.is_signed(8)
4419 >>> ExtendedContext.is_signed(-8)
4422 a = _convert_other(a, raiseit=True)
4423 return a.is_signed()
4425 def is_snan(self, a):
4426 """Return True if the operand is a signaling NaN;
4427 otherwise return False.
4429 >>> ExtendedContext.is_snan(Decimal('2.50'))
4431 >>> ExtendedContext.is_snan(Decimal('NaN'))
4433 >>> ExtendedContext.is_snan(Decimal('sNaN'))
4435 >>> ExtendedContext.is_snan(1)
4438 a = _convert_other(a, raiseit=True)
4441 def is_subnormal(self, a):
4442 """Return True if the operand is subnormal; otherwise return False.
4444 >>> c = ExtendedContext.copy()
4447 >>> c.is_subnormal(Decimal('2.50'))
4449 >>> c.is_subnormal(Decimal('0.1E-999'))
4451 >>> c.is_subnormal(Decimal('0.00'))
4453 >>> c.is_subnormal(Decimal('-Inf'))
4455 >>> c.is_subnormal(Decimal('NaN'))
4457 >>> c.is_subnormal(1)
4460 a = _convert_other(a, raiseit=True)
4461 return a.is_subnormal(context=self)
4463 def is_zero(self, a):
4464 """Return True if the operand is a zero; otherwise return False.
4466 >>> ExtendedContext.is_zero(Decimal('0'))
4468 >>> ExtendedContext.is_zero(Decimal('2.50'))
4470 >>> ExtendedContext.is_zero(Decimal('-0E+2'))
4472 >>> ExtendedContext.is_zero(1)
4474 >>> ExtendedContext.is_zero(0)
4477 a = _convert_other(a, raiseit=True)
4481 """Returns the natural (base e) logarithm of the operand.
4483 >>> c = ExtendedContext.copy()
4486 >>> c.ln(Decimal('0'))
4487 Decimal('-Infinity')
4488 >>> c.ln(Decimal('1.000'))
4490 >>> c.ln(Decimal('2.71828183'))
4491 Decimal('1.00000000')
4492 >>> c.ln(Decimal('10'))
4493 Decimal('2.30258509')
4494 >>> c.ln(Decimal('+Infinity'))
4499 a = _convert_other(a, raiseit=True)
4500 return a.ln(context=self)
4503 """Returns the base 10 logarithm of the operand.
4505 >>> c = ExtendedContext.copy()
4508 >>> c.log10(Decimal('0'))
4509 Decimal('-Infinity')
4510 >>> c.log10(Decimal('0.001'))
4512 >>> c.log10(Decimal('1.000'))
4514 >>> c.log10(Decimal('2'))
4515 Decimal('0.301029996')
4516 >>> c.log10(Decimal('10'))
4518 >>> c.log10(Decimal('70'))
4519 Decimal('1.84509804')
4520 >>> c.log10(Decimal('+Infinity'))
4523 Decimal('-Infinity')
4527 a = _convert_other(a, raiseit=True)
4528 return a.log10(context=self)
4531 """ Returns the exponent of the magnitude of the operand's MSD.
4533 The result is the integer which is the exponent of the magnitude
4534 of the most significant digit of the operand (as though the
4535 operand were truncated to a single digit while maintaining the
4536 value of that digit and without limiting the resulting exponent).
4538 >>> ExtendedContext.logb(Decimal('250'))
4540 >>> ExtendedContext.logb(Decimal('2.50'))
4542 >>> ExtendedContext.logb(Decimal('0.03'))
4544 >>> ExtendedContext.logb(Decimal('0'))
4545 Decimal('-Infinity')
4546 >>> ExtendedContext.logb(1)
4548 >>> ExtendedContext.logb(10)
4550 >>> ExtendedContext.logb(100)
4553 a = _convert_other(a, raiseit=True)
4554 return a.logb(context=self)
4556 def logical_and(self, a, b):
4557 """Applies the logical operation 'and' between each operand's digits.
4559 The operands must be both logical numbers.
4561 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))
4563 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))
4565 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))
4567 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))
4569 >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))
4571 >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))
4573 >>> ExtendedContext.logical_and(110, 1101)
4575 >>> ExtendedContext.logical_and(Decimal(110), 1101)
4577 >>> ExtendedContext.logical_and(110, Decimal(1101))
4580 a = _convert_other(a, raiseit=True)
4581 return a.logical_and(b, context=self)
4583 def logical_invert(self, a):
4584 """Invert all the digits in the operand.
4586 The operand must be a logical number.
4588 >>> ExtendedContext.logical_invert(Decimal('0'))
4589 Decimal('111111111')
4590 >>> ExtendedContext.logical_invert(Decimal('1'))
4591 Decimal('111111110')
4592 >>> ExtendedContext.logical_invert(Decimal('111111111'))
4594 >>> ExtendedContext.logical_invert(Decimal('101010101'))
4596 >>> ExtendedContext.logical_invert(1101)
4597 Decimal('111110010')
4599 a = _convert_other(a, raiseit=True)
4600 return a.logical_invert(context=self)
4602 def logical_or(self, a, b):
4603 """Applies the logical operation 'or' between each operand's digits.
4605 The operands must be both logical numbers.
4607 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))
4609 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))
4611 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))
4613 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))
4615 >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))
4617 >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))
4619 >>> ExtendedContext.logical_or(110, 1101)
4621 >>> ExtendedContext.logical_or(Decimal(110), 1101)
4623 >>> ExtendedContext.logical_or(110, Decimal(1101))
4626 a = _convert_other(a, raiseit=True)
4627 return a.logical_or(b, context=self)
4629 def logical_xor(self, a, b):
4630 """Applies the logical operation 'xor' between each operand's digits.
4632 The operands must be both logical numbers.
4634 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))
4636 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))
4638 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))
4640 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))
4642 >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))
4644 >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))
4646 >>> ExtendedContext.logical_xor(110, 1101)
4648 >>> ExtendedContext.logical_xor(Decimal(110), 1101)
4650 >>> ExtendedContext.logical_xor(110, Decimal(1101))
4653 a = _convert_other(a, raiseit=True)
4654 return a.logical_xor(b, context=self)
4656 def max(self, a, b):
4657 """max compares two values numerically and returns the maximum.
4659 If either operand is a NaN then the general rules apply.
4660 Otherwise, the operands are compared as though by the compare
4661 operation. If they are numerically equal then the left-hand operand
4662 is chosen as the result. Otherwise the maximum (closer to positive
4663 infinity) of the two operands is chosen as the result.
4665 >>> ExtendedContext.max(Decimal('3'), Decimal('2'))
4667 >>> ExtendedContext.max(Decimal('-10'), Decimal('3'))
4669 >>> ExtendedContext.max(Decimal('1.0'), Decimal('1'))
4671 >>> ExtendedContext.max(Decimal('7'), Decimal('NaN'))
4673 >>> ExtendedContext.max(1, 2)
4675 >>> ExtendedContext.max(Decimal(1), 2)
4677 >>> ExtendedContext.max(1, Decimal(2))
4680 a = _convert_other(a, raiseit=True)
4681 return a.max(b, context=self)
4683 def max_mag(self, a, b):
4684 """Compares the values numerically with their sign ignored.
4686 >>> ExtendedContext.max_mag(Decimal('7'), Decimal('NaN'))
4688 >>> ExtendedContext.max_mag(Decimal('7'), Decimal('-10'))
4690 >>> ExtendedContext.max_mag(1, -2)
4692 >>> ExtendedContext.max_mag(Decimal(1), -2)
4694 >>> ExtendedContext.max_mag(1, Decimal(-2))
4697 a = _convert_other(a, raiseit=True)
4698 return a.max_mag(b, context=self)
4700 def min(self, a, b):
4701 """min compares two values numerically and returns the minimum.
4703 If either operand is a NaN then the general rules apply.
4704 Otherwise, the operands are compared as though by the compare
4705 operation. If they are numerically equal then the left-hand operand
4706 is chosen as the result. Otherwise the minimum (closer to negative
4707 infinity) of the two operands is chosen as the result.
4709 >>> ExtendedContext.min(Decimal('3'), Decimal('2'))
4711 >>> ExtendedContext.min(Decimal('-10'), Decimal('3'))
4713 >>> ExtendedContext.min(Decimal('1.0'), Decimal('1'))
4715 >>> ExtendedContext.min(Decimal('7'), Decimal('NaN'))
4717 >>> ExtendedContext.min(1, 2)
4719 >>> ExtendedContext.min(Decimal(1), 2)
4721 >>> ExtendedContext.min(1, Decimal(29))
4724 a = _convert_other(a, raiseit=True)
4725 return a.min(b, context=self)
4727 def min_mag(self, a, b):
4728 """Compares the values numerically with their sign ignored.
4730 >>> ExtendedContext.min_mag(Decimal('3'), Decimal('-2'))
4732 >>> ExtendedContext.min_mag(Decimal('-3'), Decimal('NaN'))
4734 >>> ExtendedContext.min_mag(1, -2)
4736 >>> ExtendedContext.min_mag(Decimal(1), -2)
4738 >>> ExtendedContext.min_mag(1, Decimal(-2))
4741 a = _convert_other(a, raiseit=True)
4742 return a.min_mag(b, context=self)
4745 """Minus corresponds to unary prefix minus in Python.
4747 The operation is evaluated using the same rules as subtract; the
4748 operation minus(a) is calculated as subtract('0', a) where the '0'
4749 has the same exponent as the operand.
4751 >>> ExtendedContext.minus(Decimal('1.3'))
4753 >>> ExtendedContext.minus(Decimal('-1.3'))
4755 >>> ExtendedContext.minus(1)
4758 a = _convert_other(a, raiseit=True)
4759 return a.__neg__(context=self)
4761 def multiply(self, a, b):
4762 """multiply multiplies two operands.
4764 If either operand is a special value then the general rules apply.
4765 Otherwise, the operands are multiplied together
4766 ('long multiplication'), resulting in a number which may be as long as
4767 the sum of the lengths of the two operands.
4769 >>> ExtendedContext.multiply(Decimal('1.20'), Decimal('3'))
4771 >>> ExtendedContext.multiply(Decimal('7'), Decimal('3'))
4773 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('0.8'))
4775 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('-0'))
4777 >>> ExtendedContext.multiply(Decimal('654321'), Decimal('654321'))
4778 Decimal('4.28135971E+11')
4779 >>> ExtendedContext.multiply(7, 7)
4781 >>> ExtendedContext.multiply(Decimal(7), 7)
4783 >>> ExtendedContext.multiply(7, Decimal(7))
4786 a = _convert_other(a, raiseit=True)
4787 r = a.__mul__(b, context=self)
4788 if r is NotImplemented:
4789 raise TypeError("Unable to convert %s to Decimal" % b)
4793 def next_minus(self, a):
4794 """Returns the largest representable number smaller than a.
4796 >>> c = ExtendedContext.copy()
4799 >>> ExtendedContext.next_minus(Decimal('1'))
4800 Decimal('0.999999999')
4801 >>> c.next_minus(Decimal('1E-1007'))
4803 >>> ExtendedContext.next_minus(Decimal('-1.00000003'))
4804 Decimal('-1.00000004')
4805 >>> c.next_minus(Decimal('Infinity'))
4806 Decimal('9.99999999E+999')
4808 Decimal('0.999999999')
4810 a = _convert_other(a, raiseit=True)
4811 return a.next_minus(context=self)
4813 def next_plus(self, a):
4814 """Returns the smallest representable number larger than a.
4816 >>> c = ExtendedContext.copy()
4819 >>> ExtendedContext.next_plus(Decimal('1'))
4820 Decimal('1.00000001')
4821 >>> c.next_plus(Decimal('-1E-1007'))
4823 >>> ExtendedContext.next_plus(Decimal('-1.00000003'))
4824 Decimal('-1.00000002')
4825 >>> c.next_plus(Decimal('-Infinity'))
4826 Decimal('-9.99999999E+999')
4828 Decimal('1.00000001')
4830 a = _convert_other(a, raiseit=True)
4831 return a.next_plus(context=self)
4833 def next_toward(self, a, b):
4834 """Returns the number closest to a, in direction towards b.
4836 The result is the closest representable number from the first
4837 operand (but not the first operand) that is in the direction
4838 towards the second operand, unless the operands have the same
4841 >>> c = ExtendedContext.copy()
4844 >>> c.next_toward(Decimal('1'), Decimal('2'))
4845 Decimal('1.00000001')
4846 >>> c.next_toward(Decimal('-1E-1007'), Decimal('1'))
4848 >>> c.next_toward(Decimal('-1.00000003'), Decimal('0'))
4849 Decimal('-1.00000002')
4850 >>> c.next_toward(Decimal('1'), Decimal('0'))
4851 Decimal('0.999999999')
4852 >>> c.next_toward(Decimal('1E-1007'), Decimal('-100'))
4854 >>> c.next_toward(Decimal('-1.00000003'), Decimal('-10'))
4855 Decimal('-1.00000004')
4856 >>> c.next_toward(Decimal('0.00'), Decimal('-0.0000'))
4858 >>> c.next_toward(0, 1)
4860 >>> c.next_toward(Decimal(0), 1)
4862 >>> c.next_toward(0, Decimal(1))
4865 a = _convert_other(a, raiseit=True)
4866 return a.next_toward(b, context=self)
4868 def normalize(self, a):
4869 """normalize reduces an operand to its simplest form.
4871 Essentially a plus operation with all trailing zeros removed from the
4874 >>> ExtendedContext.normalize(Decimal('2.1'))
4876 >>> ExtendedContext.normalize(Decimal('-2.0'))
4878 >>> ExtendedContext.normalize(Decimal('1.200'))
4880 >>> ExtendedContext.normalize(Decimal('-120'))
4882 >>> ExtendedContext.normalize(Decimal('120.00'))
4884 >>> ExtendedContext.normalize(Decimal('0.00'))
4886 >>> ExtendedContext.normalize(6)
4889 a = _convert_other(a, raiseit=True)
4890 return a.normalize(context=self)
4892 def number_class(self, a):
4893 """Returns an indication of the class of the operand.
4895 The class is one of the following strings:
4907 >>> c = Context(ExtendedContext)
4910 >>> c.number_class(Decimal('Infinity'))
4912 >>> c.number_class(Decimal('1E-10'))
4914 >>> c.number_class(Decimal('2.50'))
4916 >>> c.number_class(Decimal('0.1E-999'))
4918 >>> c.number_class(Decimal('0'))
4920 >>> c.number_class(Decimal('-0'))
4922 >>> c.number_class(Decimal('-0.1E-999'))
4924 >>> c.number_class(Decimal('-1E-10'))
4926 >>> c.number_class(Decimal('-2.50'))
4928 >>> c.number_class(Decimal('-Infinity'))
4930 >>> c.number_class(Decimal('NaN'))
4932 >>> c.number_class(Decimal('-NaN'))
4934 >>> c.number_class(Decimal('sNaN'))
4936 >>> c.number_class(123)
4939 a = _convert_other(a, raiseit=True)
4940 return a.number_class(context=self)
4943 """Plus corresponds to unary prefix plus in Python.
4945 The operation is evaluated using the same rules as add; the
4946 operation plus(a) is calculated as add('0', a) where the '0'
4947 has the same exponent as the operand.
4949 >>> ExtendedContext.plus(Decimal('1.3'))
4951 >>> ExtendedContext.plus(Decimal('-1.3'))
4953 >>> ExtendedContext.plus(-1)
4956 a = _convert_other(a, raiseit=True)
4957 return a.__pos__(context=self)
4959 def power(self, a, b, modulo=None):
4960 """Raises a to the power of b, to modulo if given.
4962 With two arguments, compute a**b. If a is negative then b
4963 must be integral. The result will be inexact unless b is
4964 integral and the result is finite and can be expressed exactly
4965 in 'precision' digits.
4967 With three arguments, compute (a**b) % modulo. For the
4968 three argument form, the following restrictions on the
4971 - all three arguments must be integral
4972 - b must be nonnegative
4973 - at least one of a or b must be nonzero
4974 - modulo must be nonzero and have at most 'precision' digits
4976 The result of pow(a, b, modulo) is identical to the result
4977 that would be obtained by computing (a**b) % modulo with
4978 unbounded precision, but is computed more efficiently. It is
4981 >>> c = ExtendedContext.copy()
4984 >>> c.power(Decimal('2'), Decimal('3'))
4986 >>> c.power(Decimal('-2'), Decimal('3'))
4988 >>> c.power(Decimal('2'), Decimal('-3'))
4990 >>> c.power(Decimal('1.7'), Decimal('8'))
4991 Decimal('69.7575744')
4992 >>> c.power(Decimal('10'), Decimal('0.301029996'))
4993 Decimal('2.00000000')
4994 >>> c.power(Decimal('Infinity'), Decimal('-1'))
4996 >>> c.power(Decimal('Infinity'), Decimal('0'))
4998 >>> c.power(Decimal('Infinity'), Decimal('1'))
5000 >>> c.power(Decimal('-Infinity'), Decimal('-1'))
5002 >>> c.power(Decimal('-Infinity'), Decimal('0'))
5004 >>> c.power(Decimal('-Infinity'), Decimal('1'))
5005 Decimal('-Infinity')
5006 >>> c.power(Decimal('-Infinity'), Decimal('2'))
5008 >>> c.power(Decimal('0'), Decimal('0'))
5011 >>> c.power(Decimal('3'), Decimal('7'), Decimal('16'))
5013 >>> c.power(Decimal('-3'), Decimal('7'), Decimal('16'))
5015 >>> c.power(Decimal('-3'), Decimal('8'), Decimal('16'))
5017 >>> c.power(Decimal('3'), Decimal('7'), Decimal('-16'))
5019 >>> c.power(Decimal('23E12345'), Decimal('67E189'), Decimal('123456789'))
5021 >>> c.power(Decimal('-0'), Decimal('17'), Decimal('1729'))
5023 >>> c.power(Decimal('-23'), Decimal('0'), Decimal('65537'))
5025 >>> ExtendedContext.power(7, 7)
5027 >>> ExtendedContext.power(Decimal(7), 7)
5029 >>> ExtendedContext.power(7, Decimal(7), 2)
5032 a = _convert_other(a, raiseit=True)
5033 r = a.__pow__(b, modulo, context=self)
5034 if r is NotImplemented:
5035 raise TypeError("Unable to convert %s to Decimal" % b)
5039 def quantize(self, a, b):
5040 """Returns a value equal to 'a' (rounded), having the exponent of 'b'.
5042 The coefficient of the result is derived from that of the left-hand
5043 operand. It may be rounded using the current rounding setting (if the
5044 exponent is being increased), multiplied by a positive power of ten (if
5045 the exponent is being decreased), or is unchanged (if the exponent is
5046 already equal to that of the right-hand operand).
5048 Unlike other operations, if the length of the coefficient after the
5049 quantize operation would be greater than precision then an Invalid
5050 operation condition is raised. This guarantees that, unless there is
5051 an error condition, the exponent of the result of a quantize is always
5052 equal to that of the right-hand operand.
5054 Also unlike other operations, quantize will never raise Underflow, even
5055 if the result is subnormal and inexact.
5057 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))
5059 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))
5061 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))
5063 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))
5065 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))
5067 >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))
5068 Decimal('-Infinity')
5069 >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))
5071 >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))
5073 >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))
5075 >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))
5077 >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))
5079 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))
5081 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))
5083 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))
5085 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))
5087 >>> ExtendedContext.quantize(1, 2)
5089 >>> ExtendedContext.quantize(Decimal(1), 2)
5091 >>> ExtendedContext.quantize(1, Decimal(2))
5094 a = _convert_other(a, raiseit=True)
5095 return a.quantize(b, context=self)
5098 """Just returns 10, as this is Decimal, :)
5100 >>> ExtendedContext.radix()
5105 def remainder(self, a, b):
5106 """Returns the remainder from integer division.
5108 The result is the residue of the dividend after the operation of
5109 calculating integer division as described for divide-integer, rounded
5110 to precision digits if necessary. The sign of the result, if
5111 non-zero, is the same as that of the original dividend.
5113 This operation will fail under the same conditions as integer division
5114 (that is, if integer division on the same two operands would fail, the
5115 remainder cannot be calculated).
5117 >>> ExtendedContext.remainder(Decimal('2.1'), Decimal('3'))
5119 >>> ExtendedContext.remainder(Decimal('10'), Decimal('3'))
5121 >>> ExtendedContext.remainder(Decimal('-10'), Decimal('3'))
5123 >>> ExtendedContext.remainder(Decimal('10.2'), Decimal('1'))
5125 >>> ExtendedContext.remainder(Decimal('10'), Decimal('0.3'))
5127 >>> ExtendedContext.remainder(Decimal('3.6'), Decimal('1.3'))
5129 >>> ExtendedContext.remainder(22, 6)
5131 >>> ExtendedContext.remainder(Decimal(22), 6)
5133 >>> ExtendedContext.remainder(22, Decimal(6))
5136 a = _convert_other(a, raiseit=True)
5137 r = a.__mod__(b, context=self)
5138 if r is NotImplemented:
5139 raise TypeError("Unable to convert %s to Decimal" % b)
5143 def remainder_near(self, a, b):
5144 """Returns to be "a - b * n", where n is the integer nearest the exact
5145 value of "x / b" (if two integers are equally near then the even one
5146 is chosen). If the result is equal to 0 then its sign will be the
5149 This operation will fail under the same conditions as integer division
5150 (that is, if integer division on the same two operands would fail, the
5151 remainder cannot be calculated).
5153 >>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))
5155 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))
5157 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))
5159 >>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))
5161 >>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))
5163 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))
5165 >>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))
5167 >>> ExtendedContext.remainder_near(3, 11)
5169 >>> ExtendedContext.remainder_near(Decimal(3), 11)
5171 >>> ExtendedContext.remainder_near(3, Decimal(11))
5174 a = _convert_other(a, raiseit=True)
5175 return a.remainder_near(b, context=self)
5177 def rotate(self, a, b):
5178 """Returns a rotated copy of a, b times.
5180 The coefficient of the result is a rotated copy of the digits in
5181 the coefficient of the first operand. The number of places of
5182 rotation is taken from the absolute value of the second operand,
5183 with the rotation being to the left if the second operand is
5184 positive or to the right otherwise.
5186 >>> ExtendedContext.rotate(Decimal('34'), Decimal('8'))
5187 Decimal('400000003')
5188 >>> ExtendedContext.rotate(Decimal('12'), Decimal('9'))
5190 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('-2'))
5191 Decimal('891234567')
5192 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('0'))
5193 Decimal('123456789')
5194 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('+2'))
5195 Decimal('345678912')
5196 >>> ExtendedContext.rotate(1333333, 1)
5198 >>> ExtendedContext.rotate(Decimal(1333333), 1)
5200 >>> ExtendedContext.rotate(1333333, Decimal(1))
5203 a = _convert_other(a, raiseit=True)
5204 return a.rotate(b, context=self)
5206 def same_quantum(self, a, b):
5207 """Returns True if the two operands have the same exponent.
5209 The result is never affected by either the sign or the coefficient of
5212 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))
5214 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))
5216 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))
5218 >>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))
5220 >>> ExtendedContext.same_quantum(10000, -1)
5222 >>> ExtendedContext.same_quantum(Decimal(10000), -1)
5224 >>> ExtendedContext.same_quantum(10000, Decimal(-1))
5227 a = _convert_other(a, raiseit=True)
5228 return a.same_quantum(b)
5230 def scaleb (self, a, b):
5231 """Returns the first operand after adding the second value its exp.
5233 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('-2'))
5235 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('0'))
5237 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('3'))
5239 >>> ExtendedContext.scaleb(1, 4)
5241 >>> ExtendedContext.scaleb(Decimal(1), 4)
5243 >>> ExtendedContext.scaleb(1, Decimal(4))
5246 a = _convert_other(a, raiseit=True)
5247 return a.scaleb(b, context=self)
5249 def shift(self, a, b):
5250 """Returns a shifted copy of a, b times.
5252 The coefficient of the result is a shifted copy of the digits
5253 in the coefficient of the first operand. The number of places
5254 to shift is taken from the absolute value of the second operand,
5255 with the shift being to the left if the second operand is
5256 positive or to the right otherwise. Digits shifted into the
5257 coefficient are zeros.
5259 >>> ExtendedContext.shift(Decimal('34'), Decimal('8'))
5260 Decimal('400000000')
5261 >>> ExtendedContext.shift(Decimal('12'), Decimal('9'))
5263 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('-2'))
5265 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('0'))
5266 Decimal('123456789')
5267 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('+2'))
5268 Decimal('345678900')
5269 >>> ExtendedContext.shift(88888888, 2)
5270 Decimal('888888800')
5271 >>> ExtendedContext.shift(Decimal(88888888), 2)
5272 Decimal('888888800')
5273 >>> ExtendedContext.shift(88888888, Decimal(2))
5274 Decimal('888888800')
5276 a = _convert_other(a, raiseit=True)
5277 return a.shift(b, context=self)
5280 """Square root of a non-negative number to context precision.
5282 If the result must be inexact, it is rounded using the round-half-even
5285 >>> ExtendedContext.sqrt(Decimal('0'))
5287 >>> ExtendedContext.sqrt(Decimal('-0'))
5289 >>> ExtendedContext.sqrt(Decimal('0.39'))
5290 Decimal('0.624499800')
5291 >>> ExtendedContext.sqrt(Decimal('100'))
5293 >>> ExtendedContext.sqrt(Decimal('1'))
5295 >>> ExtendedContext.sqrt(Decimal('1.0'))
5297 >>> ExtendedContext.sqrt(Decimal('1.00'))
5299 >>> ExtendedContext.sqrt(Decimal('7'))
5300 Decimal('2.64575131')
5301 >>> ExtendedContext.sqrt(Decimal('10'))
5302 Decimal('3.16227766')
5303 >>> ExtendedContext.sqrt(2)
5304 Decimal('1.41421356')
5305 >>> ExtendedContext.prec
5308 a = _convert_other(a, raiseit=True)
5309 return a.sqrt(context=self)
5311 def subtract(self, a, b):
5312 """Return the difference between the two operands.
5314 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.07'))
5316 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.30'))
5318 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('2.07'))
5320 >>> ExtendedContext.subtract(8, 5)
5322 >>> ExtendedContext.subtract(Decimal(8), 5)
5324 >>> ExtendedContext.subtract(8, Decimal(5))
5327 a = _convert_other(a, raiseit=True)
5328 r = a.__sub__(b, context=self)
5329 if r is NotImplemented:
5330 raise TypeError("Unable to convert %s to Decimal" % b)
5334 def to_eng_string(self, a):
5335 """Converts a number to a string, using scientific notation.
5337 The operation is not affected by the context.
5339 a = _convert_other(a, raiseit=True)
5340 return a.to_eng_string(context=self)
5342 def to_sci_string(self, a):
5343 """Converts a number to a string, using scientific notation.
5345 The operation is not affected by the context.
5347 a = _convert_other(a, raiseit=True)
5348 return a.__str__(context=self)
5350 def to_integral_exact(self, a):
5351 """Rounds to an integer.
5353 When the operand has a negative exponent, the result is the same
5354 as using the quantize() operation using the given operand as the
5355 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
5356 of the operand as the precision setting; Inexact and Rounded flags
5357 are allowed in this operation. The rounding mode is taken from the
5360 >>> ExtendedContext.to_integral_exact(Decimal('2.1'))
5362 >>> ExtendedContext.to_integral_exact(Decimal('100'))
5364 >>> ExtendedContext.to_integral_exact(Decimal('100.0'))
5366 >>> ExtendedContext.to_integral_exact(Decimal('101.5'))
5368 >>> ExtendedContext.to_integral_exact(Decimal('-101.5'))
5370 >>> ExtendedContext.to_integral_exact(Decimal('10E+5'))
5372 >>> ExtendedContext.to_integral_exact(Decimal('7.89E+77'))
5374 >>> ExtendedContext.to_integral_exact(Decimal('-Inf'))
5375 Decimal('-Infinity')
5377 a = _convert_other(a, raiseit=True)
5378 return a.to_integral_exact(context=self)
5380 def to_integral_value(self, a):
5381 """Rounds to an integer.
5383 When the operand has a negative exponent, the result is the same
5384 as using the quantize() operation using the given operand as the
5385 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
5386 of the operand as the precision setting, except that no flags will
5387 be set. The rounding mode is taken from the context.
5389 >>> ExtendedContext.to_integral_value(Decimal('2.1'))
5391 >>> ExtendedContext.to_integral_value(Decimal('100'))
5393 >>> ExtendedContext.to_integral_value(Decimal('100.0'))
5395 >>> ExtendedContext.to_integral_value(Decimal('101.5'))
5397 >>> ExtendedContext.to_integral_value(Decimal('-101.5'))
5399 >>> ExtendedContext.to_integral_value(Decimal('10E+5'))
5401 >>> ExtendedContext.to_integral_value(Decimal('7.89E+77'))
5403 >>> ExtendedContext.to_integral_value(Decimal('-Inf'))
5404 Decimal('-Infinity')
5406 a = _convert_other(a, raiseit=True)
5407 return a.to_integral_value(context=self)
5409 # the method name changed, but we provide also the old one, for compatibility
5410 to_integral = to_integral_value
5412 class _WorkRep(object):
5413 __slots__ = ('sign','int','exp')
5416 # exp: None, int, or string
5418 def __init__(self, value=None):
5423 elif isinstance(value, Decimal):
5424 self.sign = value._sign
5425 self.int = int(value._int)
5426 self.exp = value._exp
5428 # assert isinstance(value, tuple)
5429 self.sign = value[0]
5434 return "(%r, %r, %r)" % (self.sign, self.int, self.exp)
5440 def _normalize(op1, op2, prec = 0):
5441 """Normalizes op1, op2 to have the same exp and length of coefficient.
5443 Done during addition.
5445 if op1.exp < op2.exp:
5452 # Let exp = min(tmp.exp - 1, tmp.adjusted() - precision - 1).
5453 # Then adding 10**exp to tmp has the same effect (after rounding)
5454 # as adding any positive quantity smaller than 10**exp; similarly
5455 # for subtraction. So if other is smaller than 10**exp we replace
5456 # it with 10**exp. This avoids tmp.exp - other.exp getting too large.
5457 tmp_len = len(str(tmp.int))
5458 other_len = len(str(other.int))
5459 exp = tmp.exp + min(-1, tmp_len - prec - 2)
5460 if other_len + other.exp - 1 < exp:
5464 tmp.int *= 10 ** (tmp.exp - other.exp)
5468 ##### Integer arithmetic functions used by ln, log10, exp and __pow__ #####
5470 # This function from Tim Peters was taken from here:
5471 # http://mail.python.org/pipermail/python-list/1999-July/007758.html
5472 # The correction being in the function definition is for speed, and
5473 # the whole function is not resolved with math.log because of avoiding
5474 # the use of floats.
5475 def _nbits(n, correction = {
5476 '0': 4, '1': 3, '2': 2, '3': 2,
5477 '4': 1, '5': 1, '6': 1, '7': 1,
5478 '8': 0, '9': 0, 'a': 0, 'b': 0,
5479 'c': 0, 'd': 0, 'e': 0, 'f': 0}):
5480 """Number of bits in binary representation of the positive integer n,
5484 raise ValueError("The argument to _nbits should be nonnegative.")
5486 return 4*len(hex_n) - correction[hex_n[0]]
5488 def _decimal_lshift_exact(n, e):
5489 """ Given integers n and e, return n * 10**e if it's an integer, else None.
5491 The computation is designed to avoid computing large powers of 10
5494 >>> _decimal_lshift_exact(3, 4)
5496 >>> _decimal_lshift_exact(300, -999999999) # returns None
5504 # val_n = largest power of 10 dividing n.
5506 val_n = len(str_n) - len(str_n.rstrip('0'))
5507 return None if val_n < -e else n // 10**-e
5509 def _sqrt_nearest(n, a):
5510 """Closest integer to the square root of the positive integer n. a is
5511 an initial approximation to the square root. Any positive integer
5512 will do for a, but the closer a is to the square root of n the
5513 faster convergence will be.
5516 if n <= 0 or a <= 0:
5517 raise ValueError("Both arguments to _sqrt_nearest should be positive.")
5521 b, a = a, a--n//a>>1
5524 def _rshift_nearest(x, shift):
5525 """Given an integer x and a nonnegative integer shift, return closest
5526 integer to x / 2**shift; use round-to-even in case of a tie.
5529 b, q = 1L << shift, x >> shift
5530 return q + (2*(x & (b-1)) + (q&1) > b)
5532 def _div_nearest(a, b):
5533 """Closest integer to a/b, a and b positive integers; rounds to even
5534 in the case of a tie.
5538 return q + (2*r + (q&1) > b)
5540 def _ilog(x, M, L = 8):
5541 """Integer approximation to M*log(x/M), with absolute error boundable
5542 in terms only of x/M.
5544 Given positive integers x and M, return an integer approximation to
5545 M * log(x/M). For L = 8 and 0.1 <= x/M <= 10 the difference
5546 between the approximation and the exact result is at most 22. For
5547 L = 8 and 1.0 <= x/M <= 10.0 the difference is at most 15. In
5548 both cases these are upper bounds on the error; it will usually be
5551 # The basic algorithm is the following: let log1p be the function
5552 # log1p(x) = log(1+x). Then log(x/M) = log1p((x-M)/M). We use
5555 # log1p(y) = 2*log1p(y/(1+sqrt(1+y)))
5557 # repeatedly until the argument to log1p is small (< 2**-L in
5558 # absolute value). For small y we can use the Taylor series
5561 # log1p(y) ~ y - y**2/2 + y**3/3 - ... - (-y)**T/T
5563 # truncating at T such that y**T is small enough. The whole
5564 # computation is carried out in a form of fixed-point arithmetic,
5565 # with a real number z being represented by an integer
5566 # approximation to z*M. To avoid loss of precision, the y below
5567 # is actually an integer approximation to 2**R*y*M, where R is the
5568 # number of reductions performed so far.
5571 # argument reduction; R = number of reductions performed
5573 while (R <= L and long(abs(y)) << L-R >= M or
5574 R > L and abs(y) >> R-L >= M):
5575 y = _div_nearest(long(M*y) << 1,
5576 M + _sqrt_nearest(M*(M+_rshift_nearest(y, R)), M))
5579 # Taylor series with T terms
5580 T = -int(-10*len(str(M))//(3*L))
5581 yshift = _rshift_nearest(y, R)
5582 w = _div_nearest(M, T)
5583 for k in xrange(T-1, 0, -1):
5584 w = _div_nearest(M, k) - _div_nearest(yshift*w, M)
5586 return _div_nearest(w*y, M)
5588 def _dlog10(c, e, p):
5589 """Given integers c, e and p with c > 0, p >= 0, compute an integer
5590 approximation to 10**p * log10(c*10**e), with an absolute error of
5591 at most 1. Assumes that c*10**e is not exactly 1."""
5593 # increase precision by 2; compensate for this by dividing
5594 # final result by 100
5597 # write c*10**e as d*10**f with either:
5598 # f >= 0 and 1 <= d <= 10, or
5599 # f <= 0 and 0.1 <= d <= 1.
5600 # Thus for c*10**e close to 1, f = 0
5602 f = e+l - (e+l >= 1)
5610 c = _div_nearest(c, 10**-k)
5612 log_d = _ilog(c, M) # error < 5 + 22 = 27
5613 log_10 = _log10_digits(p) # error < 1
5614 log_d = _div_nearest(log_d*M, log_10)
5615 log_tenpower = f*M # exact
5617 log_d = 0 # error < 2.31
5618 log_tenpower = _div_nearest(f, 10**-p) # error < 0.5
5620 return _div_nearest(log_tenpower+log_d, 100)
5623 """Given integers c, e and p with c > 0, compute an integer
5624 approximation to 10**p * log(c*10**e), with an absolute error of
5625 at most 1. Assumes that c*10**e is not exactly 1."""
5627 # Increase precision by 2. The precision increase is compensated
5628 # for at the end with a division by 100.
5631 # rewrite c*10**e as d*10**f with either f >= 0 and 1 <= d <= 10,
5632 # or f <= 0 and 0.1 <= d <= 1. Then we can compute 10**p * log(c*10**e)
5633 # as 10**p * log(d) + 10**p*f * log(10).
5635 f = e+l - (e+l >= 1)
5637 # compute approximation to 10**p*log(d), with error < 27
5643 c = _div_nearest(c, 10**-k) # error of <= 0.5 in c
5645 # _ilog magnifies existing error in c by a factor of at most 10
5646 log_d = _ilog(c, 10**p) # error < 5 + 22 = 27
5648 # p <= 0: just approximate the whole thing by 0; error < 2.31
5651 # compute approximation to f*10**p*log(10), with error < 11.
5653 extra = len(str(abs(f)))-1
5655 # error in f * _log10_digits(p+extra) < |f| * 1 = |f|
5656 # after division, error < |f|/10**extra + 0.5 < 10 + 0.5 < 11
5657 f_log_ten = _div_nearest(f*_log10_digits(p+extra), 10**extra)
5663 # error in sum < 11+27 = 38; error after division < 0.38 + 0.5 < 1
5664 return _div_nearest(f_log_ten + log_d, 100)
5666 class _Log10Memoize(object):
5667 """Class to compute, store, and allow retrieval of, digits of the
5668 constant log(10) = 2.302585.... This constant is needed by
5669 Decimal.ln, Decimal.log10, Decimal.exp and Decimal.__pow__."""
5671 self.digits = "23025850929940456840179914546843642076011014886"
5673 def getdigits(self, p):
5674 """Given an integer p >= 0, return floor(10**p)*log(10).
5676 For example, self.getdigits(3) returns 2302.
5678 # digits are stored as a string, for quick conversion to
5679 # integer in the case that we've already computed enough
5680 # digits; the stored digits should always be correct
5681 # (truncated, not rounded to nearest).
5683 raise ValueError("p should be nonnegative")
5685 if p >= len(self.digits):
5686 # compute p+3, p+6, p+9, ... digits; continue until at
5687 # least one of the extra digits is nonzero
5690 # compute p+extra digits, correct to within 1ulp
5692 digits = str(_div_nearest(_ilog(10*M, M), 100))
5693 if digits[-extra:] != '0'*extra:
5696 # keep all reliable digits so far; remove trailing zeros
5697 # and next nonzero digit
5698 self.digits = digits.rstrip('0')[:-1]
5699 return int(self.digits[:p+1])
5701 _log10_digits = _Log10Memoize().getdigits
5703 def _iexp(x, M, L=8):
5704 """Given integers x and M, M > 0, such that x/M is small in absolute
5705 value, compute an integer approximation to M*exp(x/M). For 0 <=
5706 x/M <= 2.4, the absolute error in the result is bounded by 60 (and
5707 is usually much smaller)."""
5709 # Algorithm: to compute exp(z) for a real number z, first divide z
5710 # by a suitable power R of 2 so that |z/2**R| < 2**-L. Then
5711 # compute expm1(z/2**R) = exp(z/2**R) - 1 using the usual Taylor
5714 # expm1(x) = x + x**2/2! + x**3/3! + ...
5716 # Now use the identity
5718 # expm1(2x) = expm1(x)*(expm1(x)+2)
5720 # R times to compute the sequence expm1(z/2**R),
5721 # expm1(z/2**(R-1)), ... , exp(z/2), exp(z).
5723 # Find R such that x/2**R/M <= 2**-L
5724 R = _nbits((long(x)<<L)//M)
5726 # Taylor series. (2**L)**T > M
5727 T = -int(-10*len(str(M))//(3*L))
5728 y = _div_nearest(x, T)
5730 for i in xrange(T-1, 0, -1):
5731 y = _div_nearest(x*(Mshift + y), Mshift * i)
5734 for k in xrange(R-1, -1, -1):
5735 Mshift = long(M)<<(k+2)
5736 y = _div_nearest(y*(y+Mshift), Mshift)
5741 """Compute an approximation to exp(c*10**e), with p decimal places of
5744 Returns integers d, f such that:
5746 10**(p-1) <= d <= 10**p, and
5747 (d-1)*10**f < exp(c*10**e) < (d+1)*10**f
5749 In other words, d*10**f is an approximation to exp(c*10**e) with p
5750 digits of precision, and with an error in d of at most 1. This is
5751 almost, but not quite, the same as the error being < 1ulp: when d
5752 = 10**(p-1) the error could be up to 10 ulp."""
5754 # we'll call iexp with M = 10**(p+2), giving p+3 digits of precision
5757 # compute log(10) with extra precision = adjusted exponent of c*10**e
5758 extra = max(0, e + len(str(c)) - 1)
5761 # compute quotient c*10**e/(log(10)) = c*10**(e+q)/(log(10)*10**q),
5765 cshift = c*10**shift
5767 cshift = c//10**-shift
5768 quot, rem = divmod(cshift, _log10_digits(q))
5770 # reduce remainder back to original precision
5771 rem = _div_nearest(rem, 10**extra)
5773 # error in result of _iexp < 120; error after division < 0.62
5774 return _div_nearest(_iexp(rem, 10**p), 1000), quot - p + 3
5776 def _dpower(xc, xe, yc, ye, p):
5777 """Given integers xc, xe, yc and ye representing Decimals x = xc*10**xe and
5778 y = yc*10**ye, compute x**y. Returns a pair of integers (c, e) such that:
5780 10**(p-1) <= c <= 10**p, and
5781 (c-1)*10**e < x**y < (c+1)*10**e
5783 in other words, c*10**e is an approximation to x**y with p digits
5784 of precision, and with an error in c of at most 1. (This is
5785 almost, but not quite, the same as the error being < 1ulp: when c
5786 == 10**(p-1) we can only guarantee error < 10ulp.)
5788 We assume that: x is positive and not equal to 1, and y is nonzero.
5791 # Find b such that 10**(b-1) <= |y| <= 10**b
5792 b = len(str(abs(yc))) + ye
5794 # log(x) = lxc*10**(-p-b-1), to p+b+1 places after the decimal point
5795 lxc = _dlog(xc, xe, p+b+1)
5797 # compute product y*log(x) = yc*lxc*10**(-p-b-1+ye) = pc*10**(-p-1)
5800 pc = lxc*yc*10**shift
5802 pc = _div_nearest(lxc*yc, 10**-shift)
5805 # we prefer a result that isn't exactly 1; this makes it
5806 # easier to compute a correctly rounded result in __pow__
5807 if ((len(str(xc)) + xe >= 1) == (yc > 0)): # if x**y > 1:
5808 coeff, exp = 10**(p-1)+1, 1-p
5810 coeff, exp = 10**p-1, -p
5812 coeff, exp = _dexp(pc, -(p+1), p+1)
5813 coeff = _div_nearest(coeff, 10)
5818 def _log10_lb(c, correction = {
5819 '1': 100, '2': 70, '3': 53, '4': 40, '5': 31,
5820 '6': 23, '7': 16, '8': 10, '9': 5}):
5821 """Compute a lower bound for 100*log10(c) for a positive integer c."""
5823 raise ValueError("The argument to _log10_lb should be nonnegative.")
5825 return 100*len(str_c) - correction[str_c[0]]
5827 ##### Helper Functions ####################################################
5829 def _convert_other(other, raiseit=False, allow_float=False):
5830 """Convert other to Decimal.
5832 Verifies that it's ok to use in an implicit construction.
5833 If allow_float is true, allow conversion from float; this
5834 is used in the comparison methods (__eq__ and friends).
5837 if isinstance(other, Decimal):
5839 if isinstance(other, (int, long)):
5840 return Decimal(other)
5841 if allow_float and isinstance(other, float):
5842 return Decimal.from_float(other)
5845 raise TypeError("Unable to convert %s to Decimal" % other)
5846 return NotImplemented
5848 ##### Setup Specific Contexts ############################################
5850 # The default context prototype used by Context()
5851 # Is mutable, so that new contexts can have different default values
5853 DefaultContext = Context(
5854 prec=28, rounding=ROUND_HALF_EVEN,
5855 traps=[DivisionByZero, Overflow, InvalidOperation],
5862 # Pre-made alternate contexts offered by the specification
5863 # Don't change these; the user should be able to select these
5864 # contexts and be able to reproduce results from other implementations
5867 BasicContext = Context(
5868 prec=9, rounding=ROUND_HALF_UP,
5869 traps=[DivisionByZero, Overflow, InvalidOperation, Clamped, Underflow],
5873 ExtendedContext = Context(
5874 prec=9, rounding=ROUND_HALF_EVEN,
5880 ##### crud for parsing strings #############################################
5882 # Regular expression used for parsing numeric strings. Additional
5885 # 1. Uncomment the two '\s*' lines to allow leading and/or trailing
5886 # whitespace. But note that the specification disallows whitespace in
5889 # 2. For finite numbers (not infinities and NaNs) the body of the
5890 # number between the optional sign and the optional exponent must have
5891 # at least one decimal digit, possibly after the decimal point. The
5892 # lookahead expression '(?=\d|\.\d)' checks this.
5895 _parser = re.compile(r""" # A numeric string consists of:
5897 (?P<sign>[-+])? # an optional sign, followed by either...
5899 (?=\d|\.\d) # ...a number (with at least one digit)
5900 (?P<int>\d*) # having a (possibly empty) integer part
5901 (\.(?P<frac>\d*))? # followed by an optional fractional part
5902 (E(?P<exp>[-+]?\d+))? # followed by an optional exponent, or...
5904 Inf(inity)? # ...an infinity, or...
5906 (?P<signal>s)? # ...an (optionally signaling)
5908 (?P<diag>\d*) # with (possibly empty) diagnostic info.
5912 """, re.VERBOSE | re.IGNORECASE | re.UNICODE).match
5914 _all_zeros = re.compile('0*$').match
5915 _exact_half = re.compile('50*$').match
5917 ##### PEP3101 support functions ##############################################
5918 # The functions in this section have little to do with the Decimal
5919 # class, and could potentially be reused or adapted for other pure
5920 # Python numeric classes that want to implement __format__
5922 # A format specifier for Decimal looks like:
5924 # [[fill]align][sign][0][minimumwidth][,][.precision][type]
5926 _parse_format_specifier_regex = re.compile(r"""\A
5933 (?P<minimumwidth>(?!0)\d+)?
5934 (?P<thousands_sep>,)?
5935 (?:\.(?P<precision>0|(?!0)\d+))?
5936 (?P<type>[eEfFgGn%])?
5942 # The locale module is only needed for the 'n' format specifier. The
5943 # rest of the PEP 3101 code functions quite happily without it, so we
5944 # don't care too much if locale isn't present.
5946 import locale as _locale
5950 def _parse_format_specifier(format_spec, _localeconv=None):
5951 """Parse and validate a format specifier.
5953 Turns a standard numeric format specifier into a dict, with the
5956 fill: fill character to pad field to minimum width
5957 align: alignment type, either '<', '>', '=' or '^'
5958 sign: either '+', '-' or ' '
5959 minimumwidth: nonnegative integer giving minimum width
5960 zeropad: boolean, indicating whether to pad with zeros
5961 thousands_sep: string to use as thousands separator, or ''
5962 grouping: grouping for thousands separators, in format
5964 decimal_point: string to use for decimal point
5965 precision: nonnegative integer giving precision, or None
5966 type: one of the characters 'eEfFgG%', or None
5967 unicode: boolean (always True for Python 3.x)
5970 m = _parse_format_specifier_regex.match(format_spec)
5972 raise ValueError("Invalid format specifier: " + format_spec)
5974 # get the dictionary
5975 format_dict = m.groupdict()
5977 # zeropad; defaults for fill and alignment. If zero padding
5978 # is requested, the fill and align fields should be absent.
5979 fill = format_dict['fill']
5980 align = format_dict['align']
5981 format_dict['zeropad'] = (format_dict['zeropad'] is not None)
5982 if format_dict['zeropad']:
5983 if fill is not None:
5984 raise ValueError("Fill character conflicts with '0'"
5985 " in format specifier: " + format_spec)
5986 if align is not None:
5987 raise ValueError("Alignment conflicts with '0' in "
5988 "format specifier: " + format_spec)
5989 format_dict['fill'] = fill or ' '
5990 # PEP 3101 originally specified that the default alignment should
5991 # be left; it was later agreed that right-aligned makes more sense
5992 # for numeric types. See http://bugs.python.org/issue6857.
5993 format_dict['align'] = align or '>'
5995 # default sign handling: '-' for negative, '' for positive
5996 if format_dict['sign'] is None:
5997 format_dict['sign'] = '-'
5999 # minimumwidth defaults to 0; precision remains None if not given
6000 format_dict['minimumwidth'] = int(format_dict['minimumwidth'] or '0')
6001 if format_dict['precision'] is not None:
6002 format_dict['precision'] = int(format_dict['precision'])
6004 # if format type is 'g' or 'G' then a precision of 0 makes little
6005 # sense; convert it to 1. Same if format type is unspecified.
6006 if format_dict['precision'] == 0:
6007 if format_dict['type'] is None or format_dict['type'] in 'gG':
6008 format_dict['precision'] = 1
6010 # determine thousands separator, grouping, and decimal separator, and
6011 # add appropriate entries to format_dict
6012 if format_dict['type'] == 'n':
6013 # apart from separators, 'n' behaves just like 'g'
6014 format_dict['type'] = 'g'
6015 if _localeconv is None:
6016 _localeconv = _locale.localeconv()
6017 if format_dict['thousands_sep'] is not None:
6018 raise ValueError("Explicit thousands separator conflicts with "
6019 "'n' type in format specifier: " + format_spec)
6020 format_dict['thousands_sep'] = _localeconv['thousands_sep']
6021 format_dict['grouping'] = _localeconv['grouping']
6022 format_dict['decimal_point'] = _localeconv['decimal_point']
6024 if format_dict['thousands_sep'] is None:
6025 format_dict['thousands_sep'] = ''
6026 format_dict['grouping'] = [3, 0]
6027 format_dict['decimal_point'] = '.'
6029 # record whether return type should be str or unicode
6030 format_dict['unicode'] = isinstance(format_spec, unicode)
6034 def _format_align(sign, body, spec):
6035 """Given an unpadded, non-aligned numeric string 'body' and sign
6036 string 'sign', add padding and alignment conforming to the given
6037 format specifier dictionary 'spec' (as produced by
6038 parse_format_specifier).
6040 Also converts result to unicode if necessary.
6043 # how much extra space do we have to play with?
6044 minimumwidth = spec['minimumwidth']
6046 padding = fill*(minimumwidth - len(sign) - len(body))
6048 align = spec['align']
6050 result = sign + body + padding
6052 result = padding + sign + body
6054 result = sign + padding + body
6056 half = len(padding)//2
6057 result = padding[:half] + sign + body + padding[half:]
6059 raise ValueError('Unrecognised alignment field')
6061 # make sure that result is unicode if necessary
6063 result = unicode(result)
6067 def _group_lengths(grouping):
6068 """Convert a localeconv-style grouping into a (possibly infinite)
6069 iterable of integers representing group lengths.
6072 # The result from localeconv()['grouping'], and the input to this
6073 # function, should be a list of integers in one of the
6074 # following three forms:
6076 # (1) an empty list, or
6077 # (2) nonempty list of positive integers + [0]
6078 # (3) list of positive integers + [locale.CHAR_MAX], or
6080 from itertools import chain, repeat
6083 elif grouping[-1] == 0 and len(grouping) >= 2:
6084 return chain(grouping[:-1], repeat(grouping[-2]))
6085 elif grouping[-1] == _locale.CHAR_MAX:
6086 return grouping[:-1]
6088 raise ValueError('unrecognised format for grouping')
6090 def _insert_thousands_sep(digits, spec, min_width=1):
6091 """Insert thousands separators into a digit string.
6093 spec is a dictionary whose keys should include 'thousands_sep' and
6094 'grouping'; typically it's the result of parsing the format
6095 specifier using _parse_format_specifier.
6097 The min_width keyword argument gives the minimum length of the
6098 result, which will be padded on the left with zeros if necessary.
6100 If necessary, the zero padding adds an extra '0' on the left to
6101 avoid a leading thousands separator. For example, inserting
6102 commas every three digits in '123456', with min_width=8, gives
6103 '0,123,456', even though that has length 9.
6107 sep = spec['thousands_sep']
6108 grouping = spec['grouping']
6111 for l in _group_lengths(grouping):
6113 raise ValueError("group length should be positive")
6114 # max(..., 1) forces at least 1 digit to the left of a separator
6115 l = min(max(len(digits), min_width, 1), l)
6116 groups.append('0'*(l - len(digits)) + digits[-l:])
6117 digits = digits[:-l]
6119 if not digits and min_width <= 0:
6121 min_width -= len(sep)
6123 l = max(len(digits), min_width, 1)
6124 groups.append('0'*(l - len(digits)) + digits[-l:])
6125 return sep.join(reversed(groups))
6127 def _format_sign(is_negative, spec):
6128 """Determine sign character."""
6132 elif spec['sign'] in ' +':
6137 def _format_number(is_negative, intpart, fracpart, exp, spec):
6138 """Format a number, given the following data:
6140 is_negative: true if the number is negative, else false
6141 intpart: string of digits that must appear before the decimal point
6142 fracpart: string of digits that must come after the point
6143 exp: exponent, as an integer
6144 spec: dictionary resulting from parsing the format specifier
6146 This function uses the information in spec to:
6147 insert separators (decimal separator and thousands separators)
6150 add trailing '%' for the '%' type
6151 zero-pad if necessary
6152 fill and align if necessary
6155 sign = _format_sign(is_negative, spec)
6158 fracpart = spec['decimal_point'] + fracpart
6160 if exp != 0 or spec['type'] in 'eE':
6161 echar = {'E': 'E', 'e': 'e', 'G': 'E', 'g': 'e'}[spec['type']]
6162 fracpart += "{0}{1:+}".format(echar, exp)
6163 if spec['type'] == '%':
6167 min_width = spec['minimumwidth'] - len(fracpart) - len(sign)
6170 intpart = _insert_thousands_sep(intpart, spec, min_width)
6172 return _format_align(sign, intpart+fracpart, spec)
6175 ##### Useful Constants (internal use only) ################################
6178 _Infinity = Decimal('Inf')
6179 _NegativeInfinity = Decimal('-Inf')
6180 _NaN = Decimal('NaN')
6183 _NegativeOne = Decimal(-1)
6185 # _SignedInfinity[sign] is infinity w/ that sign
6186 _SignedInfinity = (_Infinity, _NegativeInfinity)
6190 if __name__ == '__main__':
6192 doctest.testmod(sys.modules[__name__])