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 www2.hursley.ibm.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 # -Decimal('0') is Decimal('0'), not Decimal('-0')
1073 ans
= self
.copy_abs()
1075 ans
= self
.copy_negate()
1078 context
= getcontext()
1079 return ans
._fix
(context
)
1081 def __pos__(self
, context
=None):
1082 """Returns a copy, unless it is a sNaN.
1084 Rounds the number (if more then precision digits)
1086 if self
._is
_special
:
1087 ans
= self
._check
_nans
(context
=context
)
1093 ans
= self
.copy_abs()
1098 context
= getcontext()
1099 return ans
._fix
(context
)
1101 def __abs__(self
, round=True, context
=None):
1102 """Returns the absolute value of self.
1104 If the keyword argument 'round' is false, do not round. The
1105 expression self.__abs__(round=False) is equivalent to
1109 return self
.copy_abs()
1111 if self
._is
_special
:
1112 ans
= self
._check
_nans
(context
=context
)
1117 ans
= self
.__neg
__(context
=context
)
1119 ans
= self
.__pos
__(context
=context
)
1123 def __add__(self
, other
, context
=None):
1124 """Returns self + other.
1126 -INF + INF (or the reverse) cause InvalidOperation errors.
1128 other
= _convert_other(other
)
1129 if other
is NotImplemented:
1133 context
= getcontext()
1135 if self
._is
_special
or other
._is
_special
:
1136 ans
= self
._check
_nans
(other
, context
)
1140 if self
._isinfinity
():
1141 # If both INF, same sign => same as both, opposite => error.
1142 if self
._sign
!= other
._sign
and other
._isinfinity
():
1143 return context
._raise
_error
(InvalidOperation
, '-INF + INF')
1144 return Decimal(self
)
1145 if other
._isinfinity
():
1146 return Decimal(other
) # Can't both be infinity here
1148 exp
= min(self
._exp
, other
._exp
)
1150 if context
.rounding
== ROUND_FLOOR
and self
._sign
!= other
._sign
:
1151 # If the answer is 0, the sign should be negative, in this case.
1154 if not self
and not other
:
1155 sign
= min(self
._sign
, other
._sign
)
1158 ans
= _dec_from_triple(sign
, '0', exp
)
1159 ans
= ans
._fix
(context
)
1162 exp
= max(exp
, other
._exp
- context
.prec
-1)
1163 ans
= other
._rescale
(exp
, context
.rounding
)
1164 ans
= ans
._fix
(context
)
1167 exp
= max(exp
, self
._exp
- context
.prec
-1)
1168 ans
= self
._rescale
(exp
, context
.rounding
)
1169 ans
= ans
._fix
(context
)
1172 op1
= _WorkRep(self
)
1173 op2
= _WorkRep(other
)
1174 op1
, op2
= _normalize(op1
, op2
, context
.prec
)
1177 if op1
.sign
!= op2
.sign
:
1178 # Equal and opposite
1179 if op1
.int == op2
.int:
1180 ans
= _dec_from_triple(negativezero
, '0', exp
)
1181 ans
= ans
._fix
(context
)
1183 if op1
.int < op2
.int:
1185 # OK, now abs(op1) > abs(op2)
1188 op1
.sign
, op2
.sign
= op2
.sign
, op1
.sign
1191 # So we know the sign, and op1 > 0.
1194 op1
.sign
, op2
.sign
= (0, 0)
1197 # Now, op1 > abs(op2) > 0
1200 result
.int = op1
.int + op2
.int
1202 result
.int = op1
.int - op2
.int
1204 result
.exp
= op1
.exp
1205 ans
= Decimal(result
)
1206 ans
= ans
._fix
(context
)
1211 def __sub__(self
, other
, context
=None):
1212 """Return self - other"""
1213 other
= _convert_other(other
)
1214 if other
is NotImplemented:
1217 if self
._is
_special
or other
._is
_special
:
1218 ans
= self
._check
_nans
(other
, context
=context
)
1222 # self - other is computed as self + other.copy_negate()
1223 return self
.__add
__(other
.copy_negate(), context
=context
)
1225 def __rsub__(self
, other
, context
=None):
1226 """Return other - self"""
1227 other
= _convert_other(other
)
1228 if other
is NotImplemented:
1231 return other
.__sub
__(self
, context
=context
)
1233 def __mul__(self
, other
, context
=None):
1234 """Return self * other.
1236 (+-) INF * 0 (or its reverse) raise InvalidOperation.
1238 other
= _convert_other(other
)
1239 if other
is NotImplemented:
1243 context
= getcontext()
1245 resultsign
= self
._sign ^ other
._sign
1247 if self
._is
_special
or other
._is
_special
:
1248 ans
= self
._check
_nans
(other
, context
)
1252 if self
._isinfinity
():
1254 return context
._raise
_error
(InvalidOperation
, '(+-)INF * 0')
1255 return _SignedInfinity
[resultsign
]
1257 if other
._isinfinity
():
1259 return context
._raise
_error
(InvalidOperation
, '0 * (+-)INF')
1260 return _SignedInfinity
[resultsign
]
1262 resultexp
= self
._exp
+ other
._exp
1264 # Special case for multiplying by zero
1265 if not self
or not other
:
1266 ans
= _dec_from_triple(resultsign
, '0', resultexp
)
1267 # Fixing in case the exponent is out of bounds
1268 ans
= ans
._fix
(context
)
1271 # Special case for multiplying by power of 10
1272 if self
._int
== '1':
1273 ans
= _dec_from_triple(resultsign
, other
._int
, resultexp
)
1274 ans
= ans
._fix
(context
)
1276 if other
._int
== '1':
1277 ans
= _dec_from_triple(resultsign
, self
._int
, resultexp
)
1278 ans
= ans
._fix
(context
)
1281 op1
= _WorkRep(self
)
1282 op2
= _WorkRep(other
)
1284 ans
= _dec_from_triple(resultsign
, str(op1
.int * op2
.int), resultexp
)
1285 ans
= ans
._fix
(context
)
1290 def __truediv__(self
, other
, context
=None):
1291 """Return self / other."""
1292 other
= _convert_other(other
)
1293 if other
is NotImplemented:
1294 return NotImplemented
1297 context
= getcontext()
1299 sign
= self
._sign ^ other
._sign
1301 if self
._is
_special
or other
._is
_special
:
1302 ans
= self
._check
_nans
(other
, context
)
1306 if self
._isinfinity
() and other
._isinfinity
():
1307 return context
._raise
_error
(InvalidOperation
, '(+-)INF/(+-)INF')
1309 if self
._isinfinity
():
1310 return _SignedInfinity
[sign
]
1312 if other
._isinfinity
():
1313 context
._raise
_error
(Clamped
, 'Division by infinity')
1314 return _dec_from_triple(sign
, '0', context
.Etiny())
1316 # Special cases for zeroes
1319 return context
._raise
_error
(DivisionUndefined
, '0 / 0')
1320 return context
._raise
_error
(DivisionByZero
, 'x / 0', sign
)
1323 exp
= self
._exp
- other
._exp
1326 # OK, so neither = 0, INF or NaN
1327 shift
= len(other
._int
) - len(self
._int
) + context
.prec
+ 1
1328 exp
= self
._exp
- other
._exp
- shift
1329 op1
= _WorkRep(self
)
1330 op2
= _WorkRep(other
)
1332 coeff
, remainder
= divmod(op1
.int * 10**shift
, op2
.int)
1334 coeff
, remainder
= divmod(op1
.int, op2
.int * 10**-shift
)
1336 # result is not exact; adjust to ensure correct rounding
1340 # result is exact; get as close to ideal exponent as possible
1341 ideal_exp
= self
._exp
- other
._exp
1342 while exp
< ideal_exp
and coeff
% 10 == 0:
1346 ans
= _dec_from_triple(sign
, str(coeff
), exp
)
1347 return ans
._fix
(context
)
1349 def _divide(self
, other
, context
):
1350 """Return (self // other, self % other), to context.prec precision.
1352 Assumes that neither self nor other is a NaN, that self is not
1353 infinite and that other is nonzero.
1355 sign
= self
._sign ^ other
._sign
1356 if other
._isinfinity
():
1357 ideal_exp
= self
._exp
1359 ideal_exp
= min(self
._exp
, other
._exp
)
1361 expdiff
= self
.adjusted() - other
.adjusted()
1362 if not self
or other
._isinfinity
() or expdiff
<= -2:
1363 return (_dec_from_triple(sign
, '0', 0),
1364 self
._rescale
(ideal_exp
, context
.rounding
))
1365 if expdiff
<= context
.prec
:
1366 op1
= _WorkRep(self
)
1367 op2
= _WorkRep(other
)
1368 if op1
.exp
>= op2
.exp
:
1369 op1
.int *= 10**(op1
.exp
- op2
.exp
)
1371 op2
.int *= 10**(op2
.exp
- op1
.exp
)
1372 q
, r
= divmod(op1
.int, op2
.int)
1373 if q
< 10**context
.prec
:
1374 return (_dec_from_triple(sign
, str(q
), 0),
1375 _dec_from_triple(self
._sign
, str(r
), ideal_exp
))
1377 # Here the quotient is too large to be representable
1378 ans
= context
._raise
_error
(DivisionImpossible
,
1379 'quotient too large in //, % or divmod')
1382 def __rtruediv__(self
, other
, context
=None):
1383 """Swaps self/other and returns __truediv__."""
1384 other
= _convert_other(other
)
1385 if other
is NotImplemented:
1387 return other
.__truediv
__(self
, context
=context
)
1389 __div__
= __truediv__
1390 __rdiv__
= __rtruediv__
1392 def __divmod__(self
, other
, context
=None):
1394 Return (self // other, self % other)
1396 other
= _convert_other(other
)
1397 if other
is NotImplemented:
1401 context
= getcontext()
1403 ans
= self
._check
_nans
(other
, context
)
1407 sign
= self
._sign ^ other
._sign
1408 if self
._isinfinity
():
1409 if other
._isinfinity
():
1410 ans
= context
._raise
_error
(InvalidOperation
, 'divmod(INF, INF)')
1413 return (_SignedInfinity
[sign
],
1414 context
._raise
_error
(InvalidOperation
, 'INF % x'))
1418 ans
= context
._raise
_error
(DivisionUndefined
, 'divmod(0, 0)')
1421 return (context
._raise
_error
(DivisionByZero
, 'x // 0', sign
),
1422 context
._raise
_error
(InvalidOperation
, 'x % 0'))
1424 quotient
, remainder
= self
._divide
(other
, context
)
1425 remainder
= remainder
._fix
(context
)
1426 return quotient
, remainder
1428 def __rdivmod__(self
, other
, context
=None):
1429 """Swaps self/other and returns __divmod__."""
1430 other
= _convert_other(other
)
1431 if other
is NotImplemented:
1433 return other
.__divmod
__(self
, context
=context
)
1435 def __mod__(self
, other
, context
=None):
1439 other
= _convert_other(other
)
1440 if other
is NotImplemented:
1444 context
= getcontext()
1446 ans
= self
._check
_nans
(other
, context
)
1450 if self
._isinfinity
():
1451 return context
._raise
_error
(InvalidOperation
, 'INF % x')
1454 return context
._raise
_error
(InvalidOperation
, 'x % 0')
1456 return context
._raise
_error
(DivisionUndefined
, '0 % 0')
1458 remainder
= self
._divide
(other
, context
)[1]
1459 remainder
= remainder
._fix
(context
)
1462 def __rmod__(self
, other
, context
=None):
1463 """Swaps self/other and returns __mod__."""
1464 other
= _convert_other(other
)
1465 if other
is NotImplemented:
1467 return other
.__mod
__(self
, context
=context
)
1469 def remainder_near(self
, other
, context
=None):
1471 Remainder nearest to 0- abs(remainder-near) <= other/2
1474 context
= getcontext()
1476 other
= _convert_other(other
, raiseit
=True)
1478 ans
= self
._check
_nans
(other
, context
)
1482 # self == +/-infinity -> InvalidOperation
1483 if self
._isinfinity
():
1484 return context
._raise
_error
(InvalidOperation
,
1485 'remainder_near(infinity, x)')
1487 # other == 0 -> either InvalidOperation or DivisionUndefined
1490 return context
._raise
_error
(InvalidOperation
,
1491 'remainder_near(x, 0)')
1493 return context
._raise
_error
(DivisionUndefined
,
1494 'remainder_near(0, 0)')
1496 # other = +/-infinity -> remainder = self
1497 if other
._isinfinity
():
1499 return ans
._fix
(context
)
1501 # self = 0 -> remainder = self, with ideal exponent
1502 ideal_exponent
= min(self
._exp
, other
._exp
)
1504 ans
= _dec_from_triple(self
._sign
, '0', ideal_exponent
)
1505 return ans
._fix
(context
)
1507 # catch most cases of large or small quotient
1508 expdiff
= self
.adjusted() - other
.adjusted()
1509 if expdiff
>= context
.prec
+ 1:
1510 # expdiff >= prec+1 => abs(self/other) > 10**prec
1511 return context
._raise
_error
(DivisionImpossible
)
1513 # expdiff <= -2 => abs(self/other) < 0.1
1514 ans
= self
._rescale
(ideal_exponent
, context
.rounding
)
1515 return ans
._fix
(context
)
1517 # adjust both arguments to have the same exponent, then divide
1518 op1
= _WorkRep(self
)
1519 op2
= _WorkRep(other
)
1520 if op1
.exp
>= op2
.exp
:
1521 op1
.int *= 10**(op1
.exp
- op2
.exp
)
1523 op2
.int *= 10**(op2
.exp
- op1
.exp
)
1524 q
, r
= divmod(op1
.int, op2
.int)
1525 # remainder is r*10**ideal_exponent; other is +/-op2.int *
1526 # 10**ideal_exponent. Apply correction to ensure that
1527 # abs(remainder) <= abs(other)/2
1528 if 2*r
+ (q
&1) > op2
.int:
1532 if q
>= 10**context
.prec
:
1533 return context
._raise
_error
(DivisionImpossible
)
1535 # result has same sign as self unless r is negative
1541 ans
= _dec_from_triple(sign
, str(r
), ideal_exponent
)
1542 return ans
._fix
(context
)
1544 def __floordiv__(self
, other
, context
=None):
1546 other
= _convert_other(other
)
1547 if other
is NotImplemented:
1551 context
= getcontext()
1553 ans
= self
._check
_nans
(other
, context
)
1557 if self
._isinfinity
():
1558 if other
._isinfinity
():
1559 return context
._raise
_error
(InvalidOperation
, 'INF // INF')
1561 return _SignedInfinity
[self
._sign ^ other
._sign
]
1565 return context
._raise
_error
(DivisionByZero
, 'x // 0',
1566 self
._sign ^ other
._sign
)
1568 return context
._raise
_error
(DivisionUndefined
, '0 // 0')
1570 return self
._divide
(other
, context
)[0]
1572 def __rfloordiv__(self
, other
, context
=None):
1573 """Swaps self/other and returns __floordiv__."""
1574 other
= _convert_other(other
)
1575 if other
is NotImplemented:
1577 return other
.__floordiv
__(self
, context
=context
)
1579 def __float__(self
):
1580 """Float representation."""
1581 return float(str(self
))
1584 """Converts self to an int, truncating if necessary."""
1585 if self
._is
_special
:
1587 raise ValueError("Cannot convert NaN to integer")
1588 elif self
._isinfinity
():
1589 raise OverflowError("Cannot convert infinity to integer")
1590 s
= (-1)**self
._sign
1592 return s
*int(self
._int
)*10**self
._exp
1594 return s
*int(self
._int
[:self
._exp
] or '0')
1600 real
= property(real
)
1604 imag
= property(imag
)
1606 def conjugate(self
):
1609 def __complex__(self
):
1610 return complex(float(self
))
1613 """Converts to a long.
1615 Equivalent to long(int(self))
1617 return long(self
.__int
__())
1619 def _fix_nan(self
, context
):
1620 """Decapitate the payload of a NaN to fit the context"""
1623 # maximum length of payload is precision if _clamp=0,
1624 # precision-1 if _clamp=1.
1625 max_payload_len
= context
.prec
- context
._clamp
1626 if len(payload
) > max_payload_len
:
1627 payload
= payload
[len(payload
)-max_payload_len
:].lstrip('0')
1628 return _dec_from_triple(self
._sign
, payload
, self
._exp
, True)
1629 return Decimal(self
)
1631 def _fix(self
, context
):
1632 """Round if it is necessary to keep self within prec precision.
1634 Rounds and fixes the exponent. Does not raise on a sNaN.
1637 self - Decimal instance
1638 context - context used.
1641 if self
._is
_special
:
1643 # decapitate payload if necessary
1644 return self
._fix
_nan
(context
)
1646 # self is +/-Infinity; return unaltered
1647 return Decimal(self
)
1649 # if self is zero then exponent should be between Etiny and
1650 # Emax if _clamp==0, and between Etiny and Etop if _clamp==1.
1651 Etiny
= context
.Etiny()
1652 Etop
= context
.Etop()
1654 exp_max
= [context
.Emax
, Etop
][context
._clamp
]
1655 new_exp
= min(max(self
._exp
, Etiny
), exp_max
)
1656 if new_exp
!= self
._exp
:
1657 context
._raise
_error
(Clamped
)
1658 return _dec_from_triple(self
._sign
, '0', new_exp
)
1660 return Decimal(self
)
1662 # exp_min is the smallest allowable exponent of the result,
1663 # equal to max(self.adjusted()-context.prec+1, Etiny)
1664 exp_min
= len(self
._int
) + self
._exp
- context
.prec
1666 # overflow: exp_min > Etop iff self.adjusted() > Emax
1667 ans
= context
._raise
_error
(Overflow
, 'above Emax', self
._sign
)
1668 context
._raise
_error
(Inexact
)
1669 context
._raise
_error
(Rounded
)
1672 self_is_subnormal
= exp_min
< Etiny
1673 if self_is_subnormal
:
1676 # round if self has too many digits
1677 if self
._exp
< exp_min
:
1678 digits
= len(self
._int
) + self
._exp
- exp_min
1680 self
= _dec_from_triple(self
._sign
, '1', exp_min
-1)
1682 rounding_method
= self
._pick
_rounding
_function
[context
.rounding
]
1683 changed
= getattr(self
, rounding_method
)(digits
)
1684 coeff
= self
._int
[:digits
] or '0'
1686 coeff
= str(int(coeff
)+1)
1687 if len(coeff
) > context
.prec
:
1691 # check whether the rounding pushed the exponent out of range
1693 ans
= context
._raise
_error
(Overflow
, 'above Emax', self
._sign
)
1695 ans
= _dec_from_triple(self
._sign
, coeff
, exp_min
)
1697 # raise the appropriate signals, taking care to respect
1698 # the precedence described in the specification
1699 if changed
and self_is_subnormal
:
1700 context
._raise
_error
(Underflow
)
1701 if self_is_subnormal
:
1702 context
._raise
_error
(Subnormal
)
1704 context
._raise
_error
(Inexact
)
1705 context
._raise
_error
(Rounded
)
1707 # raise Clamped on underflow to 0
1708 context
._raise
_error
(Clamped
)
1711 if self_is_subnormal
:
1712 context
._raise
_error
(Subnormal
)
1714 # fold down if _clamp == 1 and self has too few digits
1715 if context
._clamp
== 1 and self
._exp
> Etop
:
1716 context
._raise
_error
(Clamped
)
1717 self_padded
= self
._int
+ '0'*(self
._exp
- Etop
)
1718 return _dec_from_triple(self
._sign
, self_padded
, Etop
)
1720 # here self was representable to begin with; return unchanged
1721 return Decimal(self
)
1723 _pick_rounding_function
= {}
1725 # for each of the rounding functions below:
1726 # self is a finite, nonzero Decimal
1727 # prec is an integer satisfying 0 <= prec < len(self._int)
1729 # each function returns either -1, 0, or 1, as follows:
1730 # 1 indicates that self should be rounded up (away from zero)
1731 # 0 indicates that self should be truncated, and that all the
1732 # digits to be truncated are zeros (so the value is unchanged)
1733 # -1 indicates that there are nonzero digits to be truncated
1735 def _round_down(self
, prec
):
1736 """Also known as round-towards-0, truncate."""
1737 if _all_zeros(self
._int
, prec
):
1742 def _round_up(self
, prec
):
1743 """Rounds away from 0."""
1744 return -self
._round
_down
(prec
)
1746 def _round_half_up(self
, prec
):
1747 """Rounds 5 up (away from 0)"""
1748 if self
._int
[prec
] in '56789':
1750 elif _all_zeros(self
._int
, prec
):
1755 def _round_half_down(self
, prec
):
1757 if _exact_half(self
._int
, prec
):
1760 return self
._round
_half
_up
(prec
)
1762 def _round_half_even(self
, prec
):
1763 """Round 5 to even, rest to nearest."""
1764 if _exact_half(self
._int
, prec
) and \
1765 (prec
== 0 or self
._int
[prec
-1] in '02468'):
1768 return self
._round
_half
_up
(prec
)
1770 def _round_ceiling(self
, prec
):
1771 """Rounds up (not away from 0 if negative.)"""
1773 return self
._round
_down
(prec
)
1775 return -self
._round
_down
(prec
)
1777 def _round_floor(self
, prec
):
1778 """Rounds down (not towards 0 if negative)"""
1780 return self
._round
_down
(prec
)
1782 return -self
._round
_down
(prec
)
1784 def _round_05up(self
, prec
):
1785 """Round down unless digit prec-1 is 0 or 5."""
1786 if prec
and self
._int
[prec
-1] not in '05':
1787 return self
._round
_down
(prec
)
1789 return -self
._round
_down
(prec
)
1791 def fma(self
, other
, third
, context
=None):
1792 """Fused multiply-add.
1794 Returns self*other+third with no rounding of the intermediate
1797 self and other are multiplied together, with no rounding of
1798 the result. The third operand is then added to the result,
1799 and a single final rounding is performed.
1802 other
= _convert_other(other
, raiseit
=True)
1804 # compute product; raise InvalidOperation if either operand is
1805 # a signaling NaN or if the product is zero times infinity.
1806 if self
._is
_special
or other
._is
_special
:
1808 context
= getcontext()
1809 if self
._exp
== 'N':
1810 return context
._raise
_error
(InvalidOperation
, 'sNaN', self
)
1811 if other
._exp
== 'N':
1812 return context
._raise
_error
(InvalidOperation
, 'sNaN', other
)
1813 if self
._exp
== 'n':
1815 elif other
._exp
== 'n':
1817 elif self
._exp
== 'F':
1819 return context
._raise
_error
(InvalidOperation
,
1821 product
= _SignedInfinity
[self
._sign ^ other
._sign
]
1822 elif other
._exp
== 'F':
1824 return context
._raise
_error
(InvalidOperation
,
1826 product
= _SignedInfinity
[self
._sign ^ other
._sign
]
1828 product
= _dec_from_triple(self
._sign ^ other
._sign
,
1829 str(int(self
._int
) * int(other
._int
)),
1830 self
._exp
+ other
._exp
)
1832 third
= _convert_other(third
, raiseit
=True)
1833 return product
.__add
__(third
, context
)
1835 def _power_modulo(self
, other
, modulo
, context
=None):
1836 """Three argument version of __pow__"""
1838 # if can't convert other and modulo to Decimal, raise
1839 # TypeError; there's no point returning NotImplemented (no
1840 # equivalent of __rpow__ for three argument pow)
1841 other
= _convert_other(other
, raiseit
=True)
1842 modulo
= _convert_other(modulo
, raiseit
=True)
1845 context
= getcontext()
1847 # deal with NaNs: if there are any sNaNs then first one wins,
1848 # (i.e. behaviour for NaNs is identical to that of fma)
1849 self_is_nan
= self
._isnan
()
1850 other_is_nan
= other
._isnan
()
1851 modulo_is_nan
= modulo
._isnan
()
1852 if self_is_nan
or other_is_nan
or modulo_is_nan
:
1853 if self_is_nan
== 2:
1854 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1856 if other_is_nan
== 2:
1857 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1859 if modulo_is_nan
== 2:
1860 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1863 return self
._fix
_nan
(context
)
1865 return other
._fix
_nan
(context
)
1866 return modulo
._fix
_nan
(context
)
1868 # check inputs: we apply same restrictions as Python's pow()
1869 if not (self
._isinteger
() and
1870 other
._isinteger
() and
1871 modulo
._isinteger
()):
1872 return context
._raise
_error
(InvalidOperation
,
1873 'pow() 3rd argument not allowed '
1874 'unless all arguments are integers')
1876 return context
._raise
_error
(InvalidOperation
,
1877 'pow() 2nd argument cannot be '
1878 'negative when 3rd argument specified')
1880 return context
._raise
_error
(InvalidOperation
,
1881 'pow() 3rd argument cannot be 0')
1883 # additional restriction for decimal: the modulus must be less
1884 # than 10**prec in absolute value
1885 if modulo
.adjusted() >= context
.prec
:
1886 return context
._raise
_error
(InvalidOperation
,
1887 'insufficient precision: pow() 3rd '
1888 'argument must not have more than '
1891 # define 0**0 == NaN, for consistency with two-argument pow
1892 # (even though it hurts!)
1893 if not other
and not self
:
1894 return context
._raise
_error
(InvalidOperation
,
1895 'at least one of pow() 1st argument '
1896 'and 2nd argument must be nonzero ;'
1897 '0**0 is not defined')
1899 # compute sign of result
1905 # convert modulo to a Python integer, and self and other to
1906 # Decimal integers (i.e. force their exponents to be >= 0)
1907 modulo
= abs(int(modulo
))
1908 base
= _WorkRep(self
.to_integral_value())
1909 exponent
= _WorkRep(other
.to_integral_value())
1911 # compute result using integer pow()
1912 base
= (base
.int % modulo
* pow(10, base
.exp
, modulo
)) % modulo
1913 for i
in xrange(exponent
.exp
):
1914 base
= pow(base
, 10, modulo
)
1915 base
= pow(base
, exponent
.int, modulo
)
1917 return _dec_from_triple(sign
, str(base
), 0)
1919 def _power_exact(self
, other
, p
):
1920 """Attempt to compute self**other exactly.
1922 Given Decimals self and other and an integer p, attempt to
1923 compute an exact result for the power self**other, with p
1924 digits of precision. Return None if self**other is not
1925 exactly representable in p digits.
1927 Assumes that elimination of special cases has already been
1928 performed: self and other must both be nonspecial; self must
1929 be positive and not numerically equal to 1; other must be
1930 nonzero. For efficiency, other._exp should not be too large,
1931 so that 10**abs(other._exp) is a feasible calculation."""
1933 # In the comments below, we write x for the value of self and
1934 # y for the value of other. Write x = xc*10**xe and y =
1937 # The main purpose of this method is to identify the *failure*
1938 # of x**y to be exactly representable with as little effort as
1939 # possible. So we look for cheap and easy tests that
1940 # eliminate the possibility of x**y being exact. Only if all
1941 # these tests are passed do we go on to actually compute x**y.
1943 # Here's the main idea. First normalize both x and y. We
1944 # express y as a rational m/n, with m and n relatively prime
1945 # and n>0. Then for x**y to be exactly representable (at
1946 # *any* precision), xc must be the nth power of a positive
1947 # integer and xe must be divisible by n. If m is negative
1948 # then additionally xc must be a power of either 2 or 5, hence
1949 # a power of 2**n or 5**n.
1951 # There's a limit to how small |y| can be: if y=m/n as above
1954 # (1) if xc != 1 then for the result to be representable we
1955 # need xc**(1/n) >= 2, and hence also xc**|y| >= 2. So
1956 # if |y| <= 1/nbits(xc) then xc < 2**nbits(xc) <=
1957 # 2**(1/|y|), hence xc**|y| < 2 and the result is not
1960 # (2) if xe != 0, |xe|*(1/n) >= 1, so |xe|*|y| >= 1. Hence if
1961 # |y| < 1/|xe| then the result is not representable.
1963 # Note that since x is not equal to 1, at least one of (1) and
1964 # (2) must apply. Now |y| < 1/nbits(xc) iff |yc|*nbits(xc) <
1965 # 10**-ye iff len(str(|yc|*nbits(xc)) <= -ye.
1967 # There's also a limit to how large y can be, at least if it's
1968 # positive: the normalized result will have coefficient xc**y,
1969 # so if it's representable then xc**y < 10**p, and y <
1970 # p/log10(xc). Hence if y*log10(xc) >= p then the result is
1971 # not exactly representable.
1973 # if len(str(abs(yc*xe)) <= -ye then abs(yc*xe) < 10**-ye,
1974 # so |y| < 1/xe and the result is not representable.
1975 # Similarly, len(str(abs(yc)*xc_bits)) <= -ye implies |y|
1979 xc
, xe
= x
.int, x
.exp
1985 yc
, ye
= y
.int, y
.exp
1990 # case where xc == 1: result is 10**(xe*y), with xe*y
1991 # required to be an integer
1994 exponent
= xe
*yc
*10**ye
1996 exponent
, remainder
= divmod(xe
*yc
, 10**-ye
)
2000 exponent
= -exponent
2001 # if other is a nonnegative integer, use ideal exponent
2002 if other
._isinteger
() and other
._sign
== 0:
2003 ideal_exponent
= self
._exp
*int(other
)
2004 zeros
= min(exponent
-ideal_exponent
, p
-1)
2007 return _dec_from_triple(0, '1' + '0'*zeros
, exponent
-zeros
)
2009 # case where y is negative: xc must be either a power
2010 # of 2 or a power of 5.
2012 last_digit
= xc
% 10
2013 if last_digit
in (2,4,6,8):
2014 # quick test for power of 2
2017 # now xc is a power of 2; e is its exponent
2019 # find e*y and xe*y; both must be integers
2021 y_as_int
= yc
*10**ye
2026 e
, remainder
= divmod(e
*yc
, ten_pow
)
2029 xe
, remainder
= divmod(xe
*yc
, ten_pow
)
2033 if e
*65 >= p
*93: # 93/65 > log(10)/log(5)
2037 elif last_digit
== 5:
2038 # e >= log_5(xc) if xc is a power of 5; we have
2039 # equality all the way up to xc=5**2658
2040 e
= _nbits(xc
)*28//65
2041 xc
, remainder
= divmod(5**e
, xc
)
2048 y_as_integer
= yc
*10**ye
2050 xe
= xe
*y_as_integer
2053 e
, remainder
= divmod(e
*yc
, ten_pow
)
2056 xe
, remainder
= divmod(xe
*yc
, ten_pow
)
2059 if e
*3 >= p
*10: # 10/3 > log(10)/log(2)
2068 return _dec_from_triple(0, str(xc
), xe
)
2070 # now y is positive; find m and n such that y = m/n
2074 if xe
!= 0 and len(str(abs(yc
*xe
))) <= -ye
:
2076 xc_bits
= _nbits(xc
)
2077 if xc
!= 1 and len(str(abs(yc
)*xc_bits
)) <= -ye
:
2079 m
, n
= yc
, 10**(-ye
)
2080 while m
% 2 == n
% 2 == 0:
2083 while m
% 5 == n
% 5 == 0:
2087 # compute nth root of xc*10**xe
2089 # if 1 < xc < 2**n then xc isn't an nth power
2090 if xc
!= 1 and xc_bits
<= n
:
2093 xe
, rem
= divmod(xe
, n
)
2097 # compute nth root of xc using Newton's method
2098 a
= 1L << -(-_nbits(xc
)//n
) # initial estimate
2100 q
, r
= divmod(xc
, a
**(n
-1))
2104 a
= (a
*(n
-1) + q
)//n
2105 if not (a
== q
and r
== 0):
2109 # now xc*10**xe is the nth root of the original xc*10**xe
2110 # compute mth power of xc*10**xe
2112 # if m > p*100//_log10_lb(xc) then m > p/log10(xc), hence xc**m >
2113 # 10**p and the result is not representable.
2114 if xc
> 1 and m
> p
*100//_log10_lb(xc
):
2121 # by this point the result *is* exactly representable
2122 # adjust the exponent to get as close as possible to the ideal
2123 # exponent, if necessary
2125 if other
._isinteger
() and other
._sign
== 0:
2126 ideal_exponent
= self
._exp
*int(other
)
2127 zeros
= min(xe
-ideal_exponent
, p
-len(str_xc
))
2130 return _dec_from_triple(0, str_xc
+'0'*zeros
, xe
-zeros
)
2132 def __pow__(self
, other
, modulo
=None, context
=None):
2133 """Return self ** other [ % modulo].
2135 With two arguments, compute self**other.
2137 With three arguments, compute (self**other) % modulo. For the
2138 three argument form, the following restrictions on the
2141 - all three arguments must be integral
2142 - other must be nonnegative
2143 - either self or other (or both) must be nonzero
2144 - modulo must be nonzero and must have at most p digits,
2145 where p is the context precision.
2147 If any of these restrictions is violated the InvalidOperation
2150 The result of pow(self, other, modulo) is identical to the
2151 result that would be obtained by computing (self**other) %
2152 modulo with unbounded precision, but is computed more
2153 efficiently. It is always exact.
2156 if modulo
is not None:
2157 return self
._power
_modulo
(other
, modulo
, context
)
2159 other
= _convert_other(other
)
2160 if other
is NotImplemented:
2164 context
= getcontext()
2166 # either argument is a NaN => result is NaN
2167 ans
= self
._check
_nans
(other
, context
)
2171 # 0**0 = NaN (!), x**0 = 1 for nonzero x (including +/-Infinity)
2174 return context
._raise
_error
(InvalidOperation
, '0 ** 0')
2178 # result has sign 1 iff self._sign is 1 and other is an odd integer
2181 if other
._isinteger
():
2182 if not other
._iseven
():
2185 # -ve**noninteger = NaN
2186 # (-0)**noninteger = 0**noninteger
2188 return context
._raise
_error
(InvalidOperation
,
2189 'x ** y with x negative and y not an integer')
2190 # negate self, without doing any unwanted rounding
2191 self
= self
.copy_negate()
2193 # 0**(+ve or Inf)= 0; 0**(-ve or -Inf) = Infinity
2195 if other
._sign
== 0:
2196 return _dec_from_triple(result_sign
, '0', 0)
2198 return _SignedInfinity
[result_sign
]
2200 # Inf**(+ve or Inf) = Inf; Inf**(-ve or -Inf) = 0
2201 if self
._isinfinity
():
2202 if other
._sign
== 0:
2203 return _SignedInfinity
[result_sign
]
2205 return _dec_from_triple(result_sign
, '0', 0)
2207 # 1**other = 1, but the choice of exponent and the flags
2208 # depend on the exponent of self, and on whether other is a
2209 # positive integer, a negative integer, or neither
2211 if other
._isinteger
():
2212 # exp = max(self._exp*max(int(other), 0),
2213 # 1-context.prec) but evaluating int(other) directly
2214 # is dangerous until we know other is small (other
2215 # could be 1e999999999)
2216 if other
._sign
== 1:
2218 elif other
> context
.prec
:
2219 multiplier
= context
.prec
2221 multiplier
= int(other
)
2223 exp
= self
._exp
* multiplier
2224 if exp
< 1-context
.prec
:
2225 exp
= 1-context
.prec
2226 context
._raise
_error
(Rounded
)
2228 context
._raise
_error
(Inexact
)
2229 context
._raise
_error
(Rounded
)
2230 exp
= 1-context
.prec
2232 return _dec_from_triple(result_sign
, '1'+'0'*-exp
, exp
)
2234 # compute adjusted exponent of self
2235 self_adj
= self
.adjusted()
2237 # self ** infinity is infinity if self > 1, 0 if self < 1
2238 # self ** -infinity is infinity if self < 1, 0 if self > 1
2239 if other
._isinfinity
():
2240 if (other
._sign
== 0) == (self_adj
< 0):
2241 return _dec_from_triple(result_sign
, '0', 0)
2243 return _SignedInfinity
[result_sign
]
2245 # from here on, the result always goes through the call
2246 # to _fix at the end of this function.
2250 # crude test to catch cases of extreme overflow/underflow. If
2251 # log10(self)*other >= 10**bound and bound >= len(str(Emax))
2252 # then 10**bound >= 10**len(str(Emax)) >= Emax+1 and hence
2253 # self**other >= 10**(Emax+1), so overflow occurs. The test
2254 # for underflow is similar.
2255 bound
= self
._log
10_exp
_bound
() + other
.adjusted()
2256 if (self_adj
>= 0) == (other
._sign
== 0):
2257 # self > 1 and other +ve, or self < 1 and other -ve
2258 # possibility of overflow
2259 if bound
>= len(str(context
.Emax
)):
2260 ans
= _dec_from_triple(result_sign
, '1', context
.Emax
+1)
2262 # self > 1 and other -ve, or self < 1 and other +ve
2263 # possibility of underflow to 0
2264 Etiny
= context
.Etiny()
2265 if bound
>= len(str(-Etiny
)):
2266 ans
= _dec_from_triple(result_sign
, '1', Etiny
-1)
2268 # try for an exact result with precision +1
2270 ans
= self
._power
_exact
(other
, context
.prec
+ 1)
2271 if ans
is not None and result_sign
== 1:
2272 ans
= _dec_from_triple(1, ans
._int
, ans
._exp
)
2275 # usual case: inexact result, x**y computed directly as exp(y*log(x))
2279 xc
, xe
= x
.int, x
.exp
2281 yc
, ye
= y
.int, y
.exp
2285 # compute correctly rounded result: start with precision +3,
2286 # then increase precision until result is unambiguously roundable
2289 coeff
, exp
= _dpower(xc
, xe
, yc
, ye
, p
+extra
)
2290 if coeff
% (5*10**(len(str(coeff
))-p
-1)):
2294 ans
= _dec_from_triple(result_sign
, str(coeff
), exp
)
2296 # unlike exp, ln and log10, the power function respects the
2297 # rounding mode; no need to switch to ROUND_HALF_EVEN here
2299 # There's a difficulty here when 'other' is not an integer and
2300 # the result is exact. In this case, the specification
2301 # requires that the Inexact flag be raised (in spite of
2302 # exactness), but since the result is exact _fix won't do this
2303 # for us. (Correspondingly, the Underflow signal should also
2304 # be raised for subnormal results.) We can't directly raise
2305 # these signals either before or after calling _fix, since
2306 # that would violate the precedence for signals. So we wrap
2307 # the ._fix call in a temporary context, and reraise
2309 if exact
and not other
._isinteger
():
2310 # pad with zeros up to length context.prec+1 if necessary; this
2311 # ensures that the Rounded signal will be raised.
2312 if len(ans
._int
) <= context
.prec
:
2313 expdiff
= context
.prec
+ 1 - len(ans
._int
)
2314 ans
= _dec_from_triple(ans
._sign
, ans
._int
+'0'*expdiff
,
2317 # create a copy of the current context, with cleared flags/traps
2318 newcontext
= context
.copy()
2319 newcontext
.clear_flags()
2320 for exception
in _signals
:
2321 newcontext
.traps
[exception
] = 0
2323 # round in the new context
2324 ans
= ans
._fix
(newcontext
)
2326 # raise Inexact, and if necessary, Underflow
2327 newcontext
._raise
_error
(Inexact
)
2328 if newcontext
.flags
[Subnormal
]:
2329 newcontext
._raise
_error
(Underflow
)
2331 # propagate signals to the original context; _fix could
2332 # have raised any of Overflow, Underflow, Subnormal,
2333 # Inexact, Rounded, Clamped. Overflow needs the correct
2334 # arguments. Note that the order of the exceptions is
2336 if newcontext
.flags
[Overflow
]:
2337 context
._raise
_error
(Overflow
, 'above Emax', ans
._sign
)
2338 for exception
in Underflow
, Subnormal
, Inexact
, Rounded
, Clamped
:
2339 if newcontext
.flags
[exception
]:
2340 context
._raise
_error
(exception
)
2343 ans
= ans
._fix
(context
)
2347 def __rpow__(self
, other
, context
=None):
2348 """Swaps self/other and returns __pow__."""
2349 other
= _convert_other(other
)
2350 if other
is NotImplemented:
2352 return other
.__pow
__(self
, context
=context
)
2354 def normalize(self
, context
=None):
2355 """Normalize- strip trailing 0s, change anything equal to 0 to 0e0"""
2358 context
= getcontext()
2360 if self
._is
_special
:
2361 ans
= self
._check
_nans
(context
=context
)
2365 dup
= self
._fix
(context
)
2366 if dup
._isinfinity
():
2370 return _dec_from_triple(dup
._sign
, '0', 0)
2371 exp_max
= [context
.Emax
, context
.Etop()][context
._clamp
]
2374 while dup
._int
[end
-1] == '0' and exp
< exp_max
:
2377 return _dec_from_triple(dup
._sign
, dup
._int
[:end
], exp
)
2379 def quantize(self
, exp
, rounding
=None, context
=None, watchexp
=True):
2380 """Quantize self so its exponent is the same as that of exp.
2382 Similar to self._rescale(exp._exp) but with error checking.
2384 exp
= _convert_other(exp
, raiseit
=True)
2387 context
= getcontext()
2388 if rounding
is None:
2389 rounding
= context
.rounding
2391 if self
._is
_special
or exp
._is
_special
:
2392 ans
= self
._check
_nans
(exp
, context
)
2396 if exp
._isinfinity
() or self
._isinfinity
():
2397 if exp
._isinfinity
() and self
._isinfinity
():
2398 return Decimal(self
) # if both are inf, it is OK
2399 return context
._raise
_error
(InvalidOperation
,
2400 'quantize with one INF')
2402 # if we're not watching exponents, do a simple rescale
2404 ans
= self
._rescale
(exp
._exp
, rounding
)
2405 # raise Inexact and Rounded where appropriate
2406 if ans
._exp
> self
._exp
:
2407 context
._raise
_error
(Rounded
)
2409 context
._raise
_error
(Inexact
)
2412 # exp._exp should be between Etiny and Emax
2413 if not (context
.Etiny() <= exp
._exp
<= context
.Emax
):
2414 return context
._raise
_error
(InvalidOperation
,
2415 'target exponent out of bounds in quantize')
2418 ans
= _dec_from_triple(self
._sign
, '0', exp
._exp
)
2419 return ans
._fix
(context
)
2421 self_adjusted
= self
.adjusted()
2422 if self_adjusted
> context
.Emax
:
2423 return context
._raise
_error
(InvalidOperation
,
2424 'exponent of quantize result too large for current context')
2425 if self_adjusted
- exp
._exp
+ 1 > context
.prec
:
2426 return context
._raise
_error
(InvalidOperation
,
2427 'quantize result has too many digits for current context')
2429 ans
= self
._rescale
(exp
._exp
, rounding
)
2430 if ans
.adjusted() > context
.Emax
:
2431 return context
._raise
_error
(InvalidOperation
,
2432 'exponent of quantize result too large for current context')
2433 if len(ans
._int
) > context
.prec
:
2434 return context
._raise
_error
(InvalidOperation
,
2435 'quantize result has too many digits for current context')
2437 # raise appropriate flags
2438 if ans
and ans
.adjusted() < context
.Emin
:
2439 context
._raise
_error
(Subnormal
)
2440 if ans
._exp
> self
._exp
:
2442 context
._raise
_error
(Inexact
)
2443 context
._raise
_error
(Rounded
)
2445 # call to fix takes care of any necessary folddown, and
2446 # signals Clamped if necessary
2447 ans
= ans
._fix
(context
)
2450 def same_quantum(self
, other
):
2451 """Return True if self and other have the same exponent; otherwise
2454 If either operand is a special value, the following rules are used:
2455 * return True if both operands are infinities
2456 * return True if both operands are NaNs
2457 * otherwise, return False.
2459 other
= _convert_other(other
, raiseit
=True)
2460 if self
._is
_special
or other
._is
_special
:
2461 return (self
.is_nan() and other
.is_nan() or
2462 self
.is_infinite() and other
.is_infinite())
2463 return self
._exp
== other
._exp
2465 def _rescale(self
, exp
, rounding
):
2466 """Rescale self so that the exponent is exp, either by padding with zeros
2467 or by truncating digits, using the given rounding mode.
2469 Specials are returned without change. This operation is
2470 quiet: it raises no flags, and uses no information from the
2473 exp = exp to scale to (an integer)
2474 rounding = rounding mode
2476 if self
._is
_special
:
2477 return Decimal(self
)
2479 return _dec_from_triple(self
._sign
, '0', exp
)
2481 if self
._exp
>= exp
:
2482 # pad answer with zeros if necessary
2483 return _dec_from_triple(self
._sign
,
2484 self
._int
+ '0'*(self
._exp
- exp
), exp
)
2486 # too many digits; round and lose data. If self.adjusted() <
2487 # exp-1, replace self by 10**(exp-1) before rounding
2488 digits
= len(self
._int
) + self
._exp
- exp
2490 self
= _dec_from_triple(self
._sign
, '1', exp
-1)
2492 this_function
= getattr(self
, self
._pick
_rounding
_function
[rounding
])
2493 changed
= this_function(digits
)
2494 coeff
= self
._int
[:digits
] or '0'
2496 coeff
= str(int(coeff
)+1)
2497 return _dec_from_triple(self
._sign
, coeff
, exp
)
2499 def _round(self
, places
, rounding
):
2500 """Round a nonzero, nonspecial Decimal to a fixed number of
2501 significant figures, using the given rounding mode.
2503 Infinities, NaNs and zeros are returned unaltered.
2505 This operation is quiet: it raises no flags, and uses no
2506 information from the context.
2510 raise ValueError("argument should be at least 1 in _round")
2511 if self
._is
_special
or not self
:
2512 return Decimal(self
)
2513 ans
= self
._rescale
(self
.adjusted()+1-places
, rounding
)
2514 # it can happen that the rescale alters the adjusted exponent;
2515 # for example when rounding 99.97 to 3 significant figures.
2516 # When this happens we end up with an extra 0 at the end of
2517 # the number; a second rescale fixes this.
2518 if ans
.adjusted() != self
.adjusted():
2519 ans
= ans
._rescale
(ans
.adjusted()+1-places
, rounding
)
2522 def to_integral_exact(self
, rounding
=None, context
=None):
2523 """Rounds to a nearby integer.
2525 If no rounding mode is specified, take the rounding mode from
2526 the context. This method raises the Rounded and Inexact flags
2529 See also: to_integral_value, which does exactly the same as
2530 this method except that it doesn't raise Inexact or Rounded.
2532 if self
._is
_special
:
2533 ans
= self
._check
_nans
(context
=context
)
2536 return Decimal(self
)
2538 return Decimal(self
)
2540 return _dec_from_triple(self
._sign
, '0', 0)
2542 context
= getcontext()
2543 if rounding
is None:
2544 rounding
= context
.rounding
2545 ans
= self
._rescale
(0, rounding
)
2547 context
._raise
_error
(Inexact
)
2548 context
._raise
_error
(Rounded
)
2551 def to_integral_value(self
, rounding
=None, context
=None):
2552 """Rounds to the nearest integer, without raising inexact, rounded."""
2554 context
= getcontext()
2555 if rounding
is None:
2556 rounding
= context
.rounding
2557 if self
._is
_special
:
2558 ans
= self
._check
_nans
(context
=context
)
2561 return Decimal(self
)
2563 return Decimal(self
)
2565 return self
._rescale
(0, rounding
)
2567 # the method name changed, but we provide also the old one, for compatibility
2568 to_integral
= to_integral_value
2570 def sqrt(self
, context
=None):
2571 """Return the square root of self."""
2573 context
= getcontext()
2575 if self
._is
_special
:
2576 ans
= self
._check
_nans
(context
=context
)
2580 if self
._isinfinity
() and self
._sign
== 0:
2581 return Decimal(self
)
2584 # exponent = self._exp // 2. sqrt(-0) = -0
2585 ans
= _dec_from_triple(self
._sign
, '0', self
._exp
// 2)
2586 return ans
._fix
(context
)
2589 return context
._raise
_error
(InvalidOperation
, 'sqrt(-x), x > 0')
2591 # At this point self represents a positive number. Let p be
2592 # the desired precision and express self in the form c*100**e
2593 # with c a positive real number and e an integer, c and e
2594 # being chosen so that 100**(p-1) <= c < 100**p. Then the
2595 # (exact) square root of self is sqrt(c)*10**e, and 10**(p-1)
2596 # <= sqrt(c) < 10**p, so the closest representable Decimal at
2597 # precision p is n*10**e where n = round_half_even(sqrt(c)),
2598 # the closest integer to sqrt(c) with the even integer chosen
2599 # in the case of a tie.
2601 # To ensure correct rounding in all cases, we use the
2602 # following trick: we compute the square root to an extra
2603 # place (precision p+1 instead of precision p), rounding down.
2604 # Then, if the result is inexact and its last digit is 0 or 5,
2605 # we increase the last digit to 1 or 6 respectively; if it's
2606 # exact we leave the last digit alone. Now the final round to
2607 # p places (or fewer in the case of underflow) will round
2608 # correctly and raise the appropriate flags.
2610 # use an extra digit of precision
2611 prec
= context
.prec
+1
2613 # write argument in the form c*100**e where e = self._exp//2
2614 # is the 'ideal' exponent, to be used if the square root is
2615 # exactly representable. l is the number of 'digits' of c in
2616 # base 100, so that 100**(l-1) <= c < 100**l.
2621 l
= (len(self
._int
) >> 1) + 1
2624 l
= len(self
._int
)+1 >> 1
2626 # rescale so that c has exactly prec base 100 'digits'
2632 c
, remainder
= divmod(c
, 100**-shift
)
2633 exact
= not remainder
2636 # find n = floor(sqrt(c)) using Newton's method
2644 exact
= exact
and n
*n
== c
2647 # result is exact; rescale to use ideal exponent e
2649 # assert n % 10**shift == 0
2655 # result is not exact; fix last digit as described above
2659 ans
= _dec_from_triple(0, str(n
), e
)
2661 # round, and fit to current context
2662 context
= context
._shallow
_copy
()
2663 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
2664 ans
= ans
._fix
(context
)
2665 context
.rounding
= rounding
2669 def max(self
, other
, context
=None):
2670 """Returns the larger value.
2672 Like max(self, other) except if one is not a number, returns
2673 NaN (and signals if one is sNaN). Also rounds.
2675 other
= _convert_other(other
, raiseit
=True)
2678 context
= getcontext()
2680 if self
._is
_special
or other
._is
_special
:
2681 # If one operand is a quiet NaN and the other is number, then the
2682 # number is always returned
2686 if on
== 1 and sn
== 0:
2687 return self
._fix
(context
)
2688 if sn
== 1 and on
== 0:
2689 return other
._fix
(context
)
2690 return self
._check
_nans
(other
, context
)
2692 c
= self
._cmp
(other
)
2694 # If both operands are finite and equal in numerical value
2695 # then an ordering is applied:
2697 # If the signs differ then max returns the operand with the
2698 # positive sign and min returns the operand with the negative sign
2700 # If the signs are the same then the exponent is used to select
2701 # the result. This is exactly the ordering used in compare_total.
2702 c
= self
.compare_total(other
)
2709 return ans
._fix
(context
)
2711 def min(self
, other
, context
=None):
2712 """Returns the smaller value.
2714 Like min(self, other) except if one is not a number, returns
2715 NaN (and signals if one is sNaN). Also rounds.
2717 other
= _convert_other(other
, raiseit
=True)
2720 context
= getcontext()
2722 if self
._is
_special
or other
._is
_special
:
2723 # If one operand is a quiet NaN and the other is number, then the
2724 # number is always returned
2728 if on
== 1 and sn
== 0:
2729 return self
._fix
(context
)
2730 if sn
== 1 and on
== 0:
2731 return other
._fix
(context
)
2732 return self
._check
_nans
(other
, context
)
2734 c
= self
._cmp
(other
)
2736 c
= self
.compare_total(other
)
2743 return ans
._fix
(context
)
2745 def _isinteger(self
):
2746 """Returns whether self is an integer"""
2747 if self
._is
_special
:
2751 rest
= self
._int
[self
._exp
:]
2752 return rest
== '0'*len(rest
)
2755 """Returns True if self is even. Assumes self is an integer."""
2756 if not self
or self
._exp
> 0:
2758 return self
._int
[-1+self
._exp
] in '02468'
2761 """Return the adjusted exponent of self"""
2763 return self
._exp
+ len(self
._int
) - 1
2764 # If NaN or Infinity, self._exp is string
2768 def canonical(self
, context
=None):
2769 """Returns the same Decimal object.
2771 As we do not have different encodings for the same number, the
2772 received object already is in its canonical form.
2776 def compare_signal(self
, other
, context
=None):
2777 """Compares self to the other operand numerically.
2779 It's pretty much like compare(), but all NaNs signal, with signaling
2780 NaNs taking precedence over quiet NaNs.
2782 other
= _convert_other(other
, raiseit
= True)
2783 ans
= self
._compare
_check
_nans
(other
, context
)
2786 return self
.compare(other
, context
=context
)
2788 def compare_total(self
, other
):
2789 """Compares self to other using the abstract representations.
2791 This is not like the standard compare, which use their numerical
2792 value. Note that a total ordering is defined for all possible abstract
2795 other
= _convert_other(other
, raiseit
=True)
2797 # if one is negative and the other is positive, it's easy
2798 if self
._sign
and not other
._sign
:
2800 if not self
._sign
and other
._sign
:
2804 # let's handle both NaN types
2805 self_nan
= self
._isnan
()
2806 other_nan
= other
._isnan
()
2807 if self_nan
or other_nan
:
2808 if self_nan
== other_nan
:
2809 # compare payloads as though they're integers
2810 self_key
= len(self
._int
), self
._int
2811 other_key
= len(other
._int
), other
._int
2812 if self_key
< other_key
:
2817 if self_key
> other_key
:
2848 if self
._exp
< other
._exp
:
2853 if self
._exp
> other
._exp
:
2861 def compare_total_mag(self
, other
):
2862 """Compares self to other using abstract repr., ignoring sign.
2864 Like compare_total, but with operand's sign ignored and assumed to be 0.
2866 other
= _convert_other(other
, raiseit
=True)
2869 o
= other
.copy_abs()
2870 return s
.compare_total(o
)
2873 """Returns a copy with the sign set to 0. """
2874 return _dec_from_triple(0, self
._int
, self
._exp
, self
._is
_special
)
2876 def copy_negate(self
):
2877 """Returns a copy with the sign inverted."""
2879 return _dec_from_triple(0, self
._int
, self
._exp
, self
._is
_special
)
2881 return _dec_from_triple(1, self
._int
, self
._exp
, self
._is
_special
)
2883 def copy_sign(self
, other
):
2884 """Returns self with the sign of other."""
2885 other
= _convert_other(other
, raiseit
=True)
2886 return _dec_from_triple(other
._sign
, self
._int
,
2887 self
._exp
, self
._is
_special
)
2889 def exp(self
, context
=None):
2890 """Returns e ** self."""
2893 context
= getcontext()
2896 ans
= self
._check
_nans
(context
=context
)
2900 # exp(-Infinity) = 0
2901 if self
._isinfinity
() == -1:
2908 # exp(Infinity) = Infinity
2909 if self
._isinfinity
() == 1:
2910 return Decimal(self
)
2912 # the result is now guaranteed to be inexact (the true
2913 # mathematical result is transcendental). There's no need to
2914 # raise Rounded and Inexact here---they'll always be raised as
2915 # a result of the call to _fix.
2917 adj
= self
.adjusted()
2919 # we only need to do any computation for quite a small range
2920 # of adjusted exponents---for example, -29 <= adj <= 10 for
2921 # the default context. For smaller exponent the result is
2922 # indistinguishable from 1 at the given precision, while for
2923 # larger exponent the result either overflows or underflows.
2924 if self
._sign
== 0 and adj
> len(str((context
.Emax
+1)*3)):
2926 ans
= _dec_from_triple(0, '1', context
.Emax
+1)
2927 elif self
._sign
== 1 and adj
> len(str((-context
.Etiny()+1)*3)):
2929 ans
= _dec_from_triple(0, '1', context
.Etiny()-1)
2930 elif self
._sign
== 0 and adj
< -p
:
2931 # p+1 digits; final round will raise correct flags
2932 ans
= _dec_from_triple(0, '1' + '0'*(p
-1) + '1', -p
)
2933 elif self
._sign
== 1 and adj
< -p
-1:
2934 # p+1 digits; final round will raise correct flags
2935 ans
= _dec_from_triple(0, '9'*(p
+1), -p
-1)
2939 c
, e
= op
.int, op
.exp
2943 # compute correctly rounded result: increase precision by
2944 # 3 digits at a time until we get an unambiguously
2948 coeff
, exp
= _dexp(c
, e
, p
+extra
)
2949 if coeff
% (5*10**(len(str(coeff
))-p
-1)):
2953 ans
= _dec_from_triple(0, str(coeff
), exp
)
2955 # at this stage, ans should round correctly with *any*
2956 # rounding mode, not just with ROUND_HALF_EVEN
2957 context
= context
._shallow
_copy
()
2958 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
2959 ans
= ans
._fix
(context
)
2960 context
.rounding
= rounding
2964 def is_canonical(self
):
2965 """Return True if self is canonical; otherwise return False.
2967 Currently, the encoding of a Decimal instance is always
2968 canonical, so this method returns True for any Decimal.
2972 def is_finite(self
):
2973 """Return True if self is finite; otherwise return False.
2975 A Decimal instance is considered finite if it is neither
2978 return not self
._is
_special
2980 def is_infinite(self
):
2981 """Return True if self is infinite; otherwise return False."""
2982 return self
._exp
== 'F'
2985 """Return True if self is a qNaN or sNaN; otherwise return False."""
2986 return self
._exp
in ('n', 'N')
2988 def is_normal(self
, context
=None):
2989 """Return True if self is a normal number; otherwise return False."""
2990 if self
._is
_special
or not self
:
2993 context
= getcontext()
2994 return context
.Emin
<= self
.adjusted()
2997 """Return True if self is a quiet NaN; otherwise return False."""
2998 return self
._exp
== 'n'
3000 def is_signed(self
):
3001 """Return True if self is negative; otherwise return False."""
3002 return self
._sign
== 1
3005 """Return True if self is a signaling NaN; otherwise return False."""
3006 return self
._exp
== 'N'
3008 def is_subnormal(self
, context
=None):
3009 """Return True if self is subnormal; otherwise return False."""
3010 if self
._is
_special
or not self
:
3013 context
= getcontext()
3014 return self
.adjusted() < context
.Emin
3017 """Return True if self is a zero; otherwise return False."""
3018 return not self
._is
_special
and self
._int
== '0'
3020 def _ln_exp_bound(self
):
3021 """Compute a lower bound for the adjusted exponent of self.ln().
3022 In other words, compute r such that self.ln() >= 10**r. Assumes
3023 that self is finite and positive and that self != 1.
3026 # for 0.1 <= x <= 10 we use the inequalities 1-1/x <= ln(x) <= x-1
3027 adj
= self
._exp
+ len(self
._int
) - 1
3029 # argument >= 10; we use 23/10 = 2.3 as a lower bound for ln(10)
3030 return len(str(adj
*23//10)) - 1
3033 return len(str((-1-adj
)*23//10)) - 1
3035 c
, e
= op
.int, op
.exp
3040 return len(num
) - len(den
) - (num
< den
)
3041 # adj == -1, 0.1 <= self < 1
3042 return e
+ len(str(10**-e
- c
)) - 1
3045 def ln(self
, context
=None):
3046 """Returns the natural (base e) logarithm of self."""
3049 context
= getcontext()
3052 ans
= self
._check
_nans
(context
=context
)
3056 # ln(0.0) == -Infinity
3058 return _NegativeInfinity
3060 # ln(Infinity) = Infinity
3061 if self
._isinfinity
() == 1:
3068 # ln(negative) raises InvalidOperation
3070 return context
._raise
_error
(InvalidOperation
,
3071 'ln of a negative value')
3073 # result is irrational, so necessarily inexact
3075 c
, e
= op
.int, op
.exp
3078 # correctly rounded result: repeatedly increase precision by 3
3079 # until we get an unambiguously roundable result
3080 places
= p
- self
._ln
_exp
_bound
() + 2 # at least p+3 places
3082 coeff
= _dlog(c
, e
, places
)
3083 # assert len(str(abs(coeff)))-p >= 1
3084 if coeff
% (5*10**(len(str(abs(coeff
)))-p
-1)):
3087 ans
= _dec_from_triple(int(coeff
<0), str(abs(coeff
)), -places
)
3089 context
= context
._shallow
_copy
()
3090 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
3091 ans
= ans
._fix
(context
)
3092 context
.rounding
= rounding
3095 def _log10_exp_bound(self
):
3096 """Compute a lower bound for the adjusted exponent of self.log10().
3097 In other words, find r such that self.log10() >= 10**r.
3098 Assumes that self is finite and positive and that self != 1.
3101 # For x >= 10 or x < 0.1 we only need a bound on the integer
3102 # part of log10(self), and this comes directly from the
3103 # exponent of x. For 0.1 <= x <= 10 we use the inequalities
3104 # 1-1/x <= log(x) <= x-1. If x > 1 we have |log10(x)| >
3105 # (1-1/x)/2.31 > 0. If x < 1 then |log10(x)| > (1-x)/2.31 > 0
3107 adj
= self
._exp
+ len(self
._int
) - 1
3110 return len(str(adj
))-1
3113 return len(str(-1-adj
))-1
3115 c
, e
= op
.int, op
.exp
3120 return len(num
) - len(den
) - (num
< den
) + 2
3121 # adj == -1, 0.1 <= self < 1
3123 return len(num
) + e
- (num
< "231") - 1
3125 def log10(self
, context
=None):
3126 """Returns the base 10 logarithm of self."""
3129 context
= getcontext()
3132 ans
= self
._check
_nans
(context
=context
)
3136 # log10(0.0) == -Infinity
3138 return _NegativeInfinity
3140 # log10(Infinity) = Infinity
3141 if self
._isinfinity
() == 1:
3144 # log10(negative or -Infinity) raises InvalidOperation
3146 return context
._raise
_error
(InvalidOperation
,
3147 'log10 of a negative value')
3150 if self
._int
[0] == '1' and self
._int
[1:] == '0'*(len(self
._int
) - 1):
3151 # answer may need rounding
3152 ans
= Decimal(self
._exp
+ len(self
._int
) - 1)
3154 # result is irrational, so necessarily inexact
3156 c
, e
= op
.int, op
.exp
3159 # correctly rounded result: repeatedly increase precision
3160 # until result is unambiguously roundable
3161 places
= p
-self
._log
10_exp
_bound
()+2
3163 coeff
= _dlog10(c
, e
, places
)
3164 # assert len(str(abs(coeff)))-p >= 1
3165 if coeff
% (5*10**(len(str(abs(coeff
)))-p
-1)):
3168 ans
= _dec_from_triple(int(coeff
<0), str(abs(coeff
)), -places
)
3170 context
= context
._shallow
_copy
()
3171 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
3172 ans
= ans
._fix
(context
)
3173 context
.rounding
= rounding
3176 def logb(self
, context
=None):
3177 """ Returns the exponent of the magnitude of self's MSD.
3179 The result is the integer which is the exponent of the magnitude
3180 of the most significant digit of self (as though it were truncated
3181 to a single digit while maintaining the value of that digit and
3182 without limiting the resulting exponent).
3185 ans
= self
._check
_nans
(context
=context
)
3190 context
= getcontext()
3192 # logb(+/-Inf) = +Inf
3193 if self
._isinfinity
():
3196 # logb(0) = -Inf, DivisionByZero
3198 return context
._raise
_error
(DivisionByZero
, 'logb(0)', 1)
3200 # otherwise, simply return the adjusted exponent of self, as a
3201 # Decimal. Note that no attempt is made to fit the result
3202 # into the current context.
3203 ans
= Decimal(self
.adjusted())
3204 return ans
._fix
(context
)
3206 def _islogical(self
):
3207 """Return True if self is a logical operand.
3209 For being logical, it must be a finite number with a sign of 0,
3210 an exponent of 0, and a coefficient whose digits must all be
3213 if self
._sign
!= 0 or self
._exp
!= 0:
3215 for dig
in self
._int
:
3220 def _fill_logical(self
, context
, opa
, opb
):
3221 dif
= context
.prec
- len(opa
)
3225 opa
= opa
[-context
.prec
:]
3226 dif
= context
.prec
- len(opb
)
3230 opb
= opb
[-context
.prec
:]
3233 def logical_and(self
, other
, context
=None):
3234 """Applies an 'and' operation between self and other's digits."""
3236 context
= getcontext()
3238 other
= _convert_other(other
, raiseit
=True)
3240 if not self
._islogical
() or not other
._islogical
():
3241 return context
._raise
_error
(InvalidOperation
)
3243 # fill to context.prec
3244 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3246 # make the operation, and clean starting zeroes
3247 result
= "".join([str(int(a
)&int(b
)) for a
,b
in zip(opa
,opb
)])
3248 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3250 def logical_invert(self
, context
=None):
3251 """Invert all its digits."""
3253 context
= getcontext()
3254 return self
.logical_xor(_dec_from_triple(0,'1'*context
.prec
,0),
3257 def logical_or(self
, other
, context
=None):
3258 """Applies an 'or' operation between self and other's digits."""
3260 context
= getcontext()
3262 other
= _convert_other(other
, raiseit
=True)
3264 if not self
._islogical
() or not other
._islogical
():
3265 return context
._raise
_error
(InvalidOperation
)
3267 # fill to context.prec
3268 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3270 # make the operation, and clean starting zeroes
3271 result
= "".join([str(int(a
)|
int(b
)) for a
,b
in zip(opa
,opb
)])
3272 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3274 def logical_xor(self
, other
, context
=None):
3275 """Applies an 'xor' operation between self and other's digits."""
3277 context
= getcontext()
3279 other
= _convert_other(other
, raiseit
=True)
3281 if not self
._islogical
() or not other
._islogical
():
3282 return context
._raise
_error
(InvalidOperation
)
3284 # fill to context.prec
3285 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3287 # make the operation, and clean starting zeroes
3288 result
= "".join([str(int(a
)^
int(b
)) for a
,b
in zip(opa
,opb
)])
3289 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3291 def max_mag(self
, other
, context
=None):
3292 """Compares the values numerically with their sign ignored."""
3293 other
= _convert_other(other
, raiseit
=True)
3296 context
= getcontext()
3298 if self
._is
_special
or other
._is
_special
:
3299 # If one operand is a quiet NaN and the other is number, then the
3300 # number is always returned
3304 if on
== 1 and sn
== 0:
3305 return self
._fix
(context
)
3306 if sn
== 1 and on
== 0:
3307 return other
._fix
(context
)
3308 return self
._check
_nans
(other
, context
)
3310 c
= self
.copy_abs()._cmp
(other
.copy_abs())
3312 c
= self
.compare_total(other
)
3319 return ans
._fix
(context
)
3321 def min_mag(self
, other
, context
=None):
3322 """Compares the values numerically with their sign ignored."""
3323 other
= _convert_other(other
, raiseit
=True)
3326 context
= getcontext()
3328 if self
._is
_special
or other
._is
_special
:
3329 # If one operand is a quiet NaN and the other is number, then the
3330 # number is always returned
3334 if on
== 1 and sn
== 0:
3335 return self
._fix
(context
)
3336 if sn
== 1 and on
== 0:
3337 return other
._fix
(context
)
3338 return self
._check
_nans
(other
, context
)
3340 c
= self
.copy_abs()._cmp
(other
.copy_abs())
3342 c
= self
.compare_total(other
)
3349 return ans
._fix
(context
)
3351 def next_minus(self
, context
=None):
3352 """Returns the largest representable number smaller than itself."""
3354 context
= getcontext()
3356 ans
= self
._check
_nans
(context
=context
)
3360 if self
._isinfinity
() == -1:
3361 return _NegativeInfinity
3362 if self
._isinfinity
() == 1:
3363 return _dec_from_triple(0, '9'*context
.prec
, context
.Etop())
3365 context
= context
.copy()
3366 context
._set
_rounding
(ROUND_FLOOR
)
3367 context
._ignore
_all
_flags
()
3368 new_self
= self
._fix
(context
)
3369 if new_self
!= self
:
3371 return self
.__sub
__(_dec_from_triple(0, '1', context
.Etiny()-1),
3374 def next_plus(self
, context
=None):
3375 """Returns the smallest representable number larger than itself."""
3377 context
= getcontext()
3379 ans
= self
._check
_nans
(context
=context
)
3383 if self
._isinfinity
() == 1:
3385 if self
._isinfinity
() == -1:
3386 return _dec_from_triple(1, '9'*context
.prec
, context
.Etop())
3388 context
= context
.copy()
3389 context
._set
_rounding
(ROUND_CEILING
)
3390 context
._ignore
_all
_flags
()
3391 new_self
= self
._fix
(context
)
3392 if new_self
!= self
:
3394 return self
.__add
__(_dec_from_triple(0, '1', context
.Etiny()-1),
3397 def next_toward(self
, other
, context
=None):
3398 """Returns the number closest to self, in the direction towards other.
3400 The result is the closest representable number to self
3401 (excluding self) that is in the direction towards other,
3402 unless both have the same value. If the two operands are
3403 numerically equal, then the result is a copy of self with the
3404 sign set to be the same as the sign of other.
3406 other
= _convert_other(other
, raiseit
=True)
3409 context
= getcontext()
3411 ans
= self
._check
_nans
(other
, context
)
3415 comparison
= self
._cmp
(other
)
3417 return self
.copy_sign(other
)
3419 if comparison
== -1:
3420 ans
= self
.next_plus(context
)
3421 else: # comparison == 1
3422 ans
= self
.next_minus(context
)
3424 # decide which flags to raise using value of ans
3425 if ans
._isinfinity
():
3426 context
._raise
_error
(Overflow
,
3427 'Infinite result from next_toward',
3429 context
._raise
_error
(Inexact
)
3430 context
._raise
_error
(Rounded
)
3431 elif ans
.adjusted() < context
.Emin
:
3432 context
._raise
_error
(Underflow
)
3433 context
._raise
_error
(Subnormal
)
3434 context
._raise
_error
(Inexact
)
3435 context
._raise
_error
(Rounded
)
3436 # if precision == 1 then we don't raise Clamped for a
3439 context
._raise
_error
(Clamped
)
3443 def number_class(self
, context
=None):
3444 """Returns an indication of the class of self.
3446 The class is one of the following strings:
3462 inf
= self
._isinfinity
()
3473 context
= getcontext()
3474 if self
.is_subnormal(context
=context
):
3479 # just a normal, regular, boring number, :)
3486 """Just returns 10, as this is Decimal, :)"""
3489 def rotate(self
, other
, context
=None):
3490 """Returns a rotated copy of self, value-of-other times."""
3492 context
= getcontext()
3494 other
= _convert_other(other
, raiseit
=True)
3496 ans
= self
._check
_nans
(other
, context
)
3501 return context
._raise
_error
(InvalidOperation
)
3502 if not (-context
.prec
<= int(other
) <= context
.prec
):
3503 return context
._raise
_error
(InvalidOperation
)
3505 if self
._isinfinity
():
3506 return Decimal(self
)
3508 # get values, pad if necessary
3511 topad
= context
.prec
- len(rotdig
)
3513 rotdig
= '0'*topad
+ rotdig
3515 rotdig
= rotdig
[-topad
:]
3518 rotated
= rotdig
[torot
:] + rotdig
[:torot
]
3519 return _dec_from_triple(self
._sign
,
3520 rotated
.lstrip('0') or '0', self
._exp
)
3522 def scaleb(self
, other
, context
=None):
3523 """Returns self operand after adding the second value to its exp."""
3525 context
= getcontext()
3527 other
= _convert_other(other
, raiseit
=True)
3529 ans
= self
._check
_nans
(other
, context
)
3534 return context
._raise
_error
(InvalidOperation
)
3535 liminf
= -2 * (context
.Emax
+ context
.prec
)
3536 limsup
= 2 * (context
.Emax
+ context
.prec
)
3537 if not (liminf
<= int(other
) <= limsup
):
3538 return context
._raise
_error
(InvalidOperation
)
3540 if self
._isinfinity
():
3541 return Decimal(self
)
3543 d
= _dec_from_triple(self
._sign
, self
._int
, self
._exp
+ int(other
))
3547 def shift(self
, other
, context
=None):
3548 """Returns a shifted copy of self, value-of-other times."""
3550 context
= getcontext()
3552 other
= _convert_other(other
, raiseit
=True)
3554 ans
= self
._check
_nans
(other
, context
)
3559 return context
._raise
_error
(InvalidOperation
)
3560 if not (-context
.prec
<= int(other
) <= context
.prec
):
3561 return context
._raise
_error
(InvalidOperation
)
3563 if self
._isinfinity
():
3564 return Decimal(self
)
3566 # get values, pad if necessary
3569 topad
= context
.prec
- len(rotdig
)
3571 rotdig
= '0'*topad
+ rotdig
3573 rotdig
= rotdig
[-topad
:]
3577 shifted
= rotdig
[:torot
]
3579 shifted
= rotdig
+ '0'*torot
3580 shifted
= shifted
[-context
.prec
:]
3582 return _dec_from_triple(self
._sign
,
3583 shifted
.lstrip('0') or '0', self
._exp
)
3585 # Support for pickling, copy, and deepcopy
3586 def __reduce__(self
):
3587 return (self
.__class
__, (str(self
),))
3590 if type(self
) is Decimal
:
3591 return self
# I'm immutable; therefore I am my own clone
3592 return self
.__class
__(str(self
))
3594 def __deepcopy__(self
, memo
):
3595 if type(self
) is Decimal
:
3596 return self
# My components are also immutable
3597 return self
.__class
__(str(self
))
3599 # PEP 3101 support. the _localeconv keyword argument should be
3600 # considered private: it's provided for ease of testing only.
3601 def __format__(self
, specifier
, context
=None, _localeconv
=None):
3602 """Format a Decimal instance according to the given specifier.
3604 The specifier should be a standard format specifier, with the
3605 form described in PEP 3101. Formatting types 'e', 'E', 'f',
3606 'F', 'g', 'G', 'n' and '%' are supported. If the formatting
3607 type is omitted it defaults to 'g' or 'G', depending on the
3608 value of context.capitals.
3611 # Note: PEP 3101 says that if the type is not present then
3612 # there should be at least one digit after the decimal point.
3613 # We take the liberty of ignoring this requirement for
3614 # Decimal---it's presumably there to make sure that
3615 # format(float, '') behaves similarly to str(float).
3617 context
= getcontext()
3619 spec
= _parse_format_specifier(specifier
, _localeconv
=_localeconv
)
3621 # special values don't care about the type or precision
3622 if self
._is
_special
:
3623 sign
= _format_sign(self
._sign
, spec
)
3624 body
= str(self
.copy_abs())
3625 return _format_align(sign
, body
, spec
)
3627 # a type of None defaults to 'g' or 'G', depending on context
3628 if spec
['type'] is None:
3629 spec
['type'] = ['g', 'G'][context
.capitals
]
3631 # if type is '%', adjust exponent of self accordingly
3632 if spec
['type'] == '%':
3633 self
= _dec_from_triple(self
._sign
, self
._int
, self
._exp
+2)
3635 # round if necessary, taking rounding mode from the context
3636 rounding
= context
.rounding
3637 precision
= spec
['precision']
3638 if precision
is not None:
3639 if spec
['type'] in 'eE':
3640 self
= self
._round
(precision
+1, rounding
)
3641 elif spec
['type'] in 'fF%':
3642 self
= self
._rescale
(-precision
, rounding
)
3643 elif spec
['type'] in 'gG' and len(self
._int
) > precision
:
3644 self
= self
._round
(precision
, rounding
)
3645 # special case: zeros with a positive exponent can't be
3646 # represented in fixed point; rescale them to 0e0.
3647 if not self
and self
._exp
> 0 and spec
['type'] in 'fF%':
3648 self
= self
._rescale
(0, rounding
)
3650 # figure out placement of the decimal point
3651 leftdigits
= self
._exp
+ len(self
._int
)
3652 if spec
['type'] in 'eE':
3653 if not self
and precision
is not None:
3654 dotplace
= 1 - precision
3657 elif spec
['type'] in 'fF%':
3658 dotplace
= leftdigits
3659 elif spec
['type'] in 'gG':
3660 if self
._exp
<= 0 and leftdigits
> -6:
3661 dotplace
= leftdigits
3665 # find digits before and after decimal point, and get exponent
3668 fracpart
= '0'*(-dotplace
) + self
._int
3669 elif dotplace
> len(self
._int
):
3670 intpart
= self
._int
+ '0'*(dotplace
-len(self
._int
))
3673 intpart
= self
._int
[:dotplace
] or '0'
3674 fracpart
= self
._int
[dotplace
:]
3675 exp
= leftdigits
-dotplace
3677 # done with the decimal-specific stuff; hand over the rest
3678 # of the formatting to the _format_number function
3679 return _format_number(self
._sign
, intpart
, fracpart
, exp
, spec
)
3681 def _dec_from_triple(sign
, coefficient
, exponent
, special
=False):
3682 """Create a decimal instance directly, without any validation,
3683 normalization (e.g. removal of leading zeros) or argument
3686 This function is for *internal use only*.
3689 self
= object.__new
__(Decimal
)
3691 self
._int
= coefficient
3692 self
._exp
= exponent
3693 self
._is
_special
= special
3697 # Register Decimal as a kind of Number (an abstract base class).
3698 # However, do not register it as Real (because Decimals are not
3699 # interoperable with floats).
3700 _numbers
.Number
.register(Decimal
)
3703 ##### Context class #######################################################
3706 # get rounding method function:
3707 rounding_functions
= [name
for name
in Decimal
.__dict
__.keys()
3708 if name
.startswith('_round_')]
3709 for name
in rounding_functions
:
3710 # name is like _round_half_even, goes to the global ROUND_HALF_EVEN value.
3711 globalname
= name
[1:].upper()
3712 val
= globals()[globalname
]
3713 Decimal
._pick
_rounding
_function
[val
] = name
3715 del name
, val
, globalname
, rounding_functions
3717 class _ContextManager(object):
3718 """Context manager class to support localcontext().
3720 Sets a copy of the supplied context in __enter__() and restores
3721 the previous decimal context in __exit__()
3723 def __init__(self
, new_context
):
3724 self
.new_context
= new_context
.copy()
3725 def __enter__(self
):
3726 self
.saved_context
= getcontext()
3727 setcontext(self
.new_context
)
3728 return self
.new_context
3729 def __exit__(self
, t
, v
, tb
):
3730 setcontext(self
.saved_context
)
3732 class Context(object):
3733 """Contains the context for a Decimal instance.
3736 prec - precision (for use in rounding, division, square roots..)
3737 rounding - rounding type (how you round)
3738 traps - If traps[exception] = 1, then the exception is
3739 raised when it is caused. Otherwise, a value is
3741 flags - When an exception is caused, flags[exception] is set.
3742 (Whether or not the trap_enabler is set)
3743 Should be reset by user of Decimal instance.
3744 Emin - Minimum exponent
3745 Emax - Maximum exponent
3746 capitals - If 1, 1*10^1 is printed as 1E+1.
3747 If 0, printed as 1e1
3748 _clamp - If 1, change exponents if too high (Default 0)
3751 def __init__(self
, prec
=None, rounding
=None,
3752 traps
=None, flags
=None,
3753 Emin
=None, Emax
=None,
3754 capitals
=None, _clamp
=0,
3755 _ignored_flags
=None):
3758 if _ignored_flags
is None:
3760 if not isinstance(flags
, dict):
3761 flags
= dict([(s
, int(s
in flags
)) for s
in _signals
])
3763 if traps
is not None and not isinstance(traps
, dict):
3764 traps
= dict([(s
, int(s
in traps
)) for s
in _signals
])
3766 for name
, val
in locals().items():
3768 setattr(self
, name
, _copy
.copy(getattr(DefaultContext
, name
)))
3770 setattr(self
, name
, val
)
3774 """Show the current context."""
3776 s
.append('Context(prec=%(prec)d, rounding=%(rounding)s, '
3777 'Emin=%(Emin)d, Emax=%(Emax)d, capitals=%(capitals)d'
3779 names
= [f
.__name
__ for f
, v
in self
.flags
.items() if v
]
3780 s
.append('flags=[' + ', '.join(names
) + ']')
3781 names
= [t
.__name
__ for t
, v
in self
.traps
.items() if v
]
3782 s
.append('traps=[' + ', '.join(names
) + ']')
3783 return ', '.join(s
) + ')'
3785 def clear_flags(self
):
3786 """Reset all flags to zero"""
3787 for flag
in self
.flags
:
3788 self
.flags
[flag
] = 0
3790 def _shallow_copy(self
):
3791 """Returns a shallow copy from self."""
3792 nc
= Context(self
.prec
, self
.rounding
, self
.traps
,
3793 self
.flags
, self
.Emin
, self
.Emax
,
3794 self
.capitals
, self
._clamp
, self
._ignored
_flags
)
3798 """Returns a deep copy from self."""
3799 nc
= Context(self
.prec
, self
.rounding
, self
.traps
.copy(),
3800 self
.flags
.copy(), self
.Emin
, self
.Emax
,
3801 self
.capitals
, self
._clamp
, self
._ignored
_flags
)
3805 def _raise_error(self
, condition
, explanation
= None, *args
):
3808 If the flag is in _ignored_flags, returns the default response.
3809 Otherwise, it sets the flag, then, if the corresponding
3810 trap_enabler is set, it reraises the exception. Otherwise, it returns
3811 the default value after setting the flag.
3813 error
= _condition_map
.get(condition
, condition
)
3814 if error
in self
._ignored
_flags
:
3815 # Don't touch the flag
3816 return error().handle(self
, *args
)
3818 self
.flags
[error
] = 1
3819 if not self
.traps
[error
]:
3820 # The errors define how to handle themselves.
3821 return condition().handle(self
, *args
)
3823 # Errors should only be risked on copies of the context
3824 # self._ignored_flags = []
3825 raise error(explanation
)
3827 def _ignore_all_flags(self
):
3828 """Ignore all flags, if they are raised"""
3829 return self
._ignore
_flags
(*_signals
)
3831 def _ignore_flags(self
, *flags
):
3832 """Ignore the flags, if they are raised"""
3833 # Do not mutate-- This way, copies of a context leave the original
3835 self
._ignored
_flags
= (self
._ignored
_flags
+ list(flags
))
3838 def _regard_flags(self
, *flags
):
3839 """Stop ignoring the flags, if they are raised"""
3840 if flags
and isinstance(flags
[0], (tuple,list)):
3843 self
._ignored
_flags
.remove(flag
)
3845 # We inherit object.__hash__, so we must deny this explicitly
3849 """Returns Etiny (= Emin - prec + 1)"""
3850 return int(self
.Emin
- self
.prec
+ 1)
3853 """Returns maximum exponent (= Emax - prec + 1)"""
3854 return int(self
.Emax
- self
.prec
+ 1)
3856 def _set_rounding(self
, type):
3857 """Sets the rounding type.
3859 Sets the rounding type, and returns the current (previous)
3860 rounding type. Often used like:
3862 context = context.copy()
3863 # so you don't change the calling context
3864 # if an error occurs in the middle.
3865 rounding = context._set_rounding(ROUND_UP)
3866 val = self.__sub__(other, context=context)
3867 context._set_rounding(rounding)
3869 This will make it round up for that operation.
3871 rounding
= self
.rounding
3875 def create_decimal(self
, num
='0'):
3876 """Creates a new Decimal instance but using self as context.
3878 This method implements the to-number operation of the
3879 IBM Decimal specification."""
3881 if isinstance(num
, basestring
) and num
!= num
.strip():
3882 return self
._raise
_error
(ConversionSyntax
,
3883 "no trailing or leading whitespace is "
3886 d
= Decimal(num
, context
=self
)
3887 if d
._isnan
() and len(d
._int
) > self
.prec
- self
._clamp
:
3888 return self
._raise
_error
(ConversionSyntax
,
3889 "diagnostic info too long in NaN")
3892 def create_decimal_from_float(self
, f
):
3893 """Creates a new Decimal instance from a float but rounding using self
3896 >>> context = Context(prec=5, rounding=ROUND_DOWN)
3897 >>> context.create_decimal_from_float(3.1415926535897932)
3899 >>> context = Context(prec=5, traps=[Inexact])
3900 >>> context.create_decimal_from_float(3.1415926535897932)
3901 Traceback (most recent call last):
3906 d
= Decimal
.from_float(f
) # An exact conversion
3907 return d
._fix
(self
) # Apply the context rounding
3911 """Returns the absolute value of the operand.
3913 If the operand is negative, the result is the same as using the minus
3914 operation on the operand. Otherwise, the result is the same as using
3915 the plus operation on the operand.
3917 >>> ExtendedContext.abs(Decimal('2.1'))
3919 >>> ExtendedContext.abs(Decimal('-100'))
3921 >>> ExtendedContext.abs(Decimal('101.5'))
3923 >>> ExtendedContext.abs(Decimal('-101.5'))
3925 >>> ExtendedContext.abs(-1)
3928 a
= _convert_other(a
, raiseit
=True)
3929 return a
.__abs
__(context
=self
)
3931 def add(self
, a
, b
):
3932 """Return the sum of the two operands.
3934 >>> ExtendedContext.add(Decimal('12'), Decimal('7.00'))
3936 >>> ExtendedContext.add(Decimal('1E+2'), Decimal('1.01E+4'))
3938 >>> ExtendedContext.add(1, Decimal(2))
3940 >>> ExtendedContext.add(Decimal(8), 5)
3942 >>> ExtendedContext.add(5, 5)
3945 a
= _convert_other(a
, raiseit
=True)
3946 r
= a
.__add
__(b
, context
=self
)
3947 if r
is NotImplemented:
3948 raise TypeError("Unable to convert %s to Decimal" % b
)
3952 def _apply(self
, a
):
3953 return str(a
._fix
(self
))
3955 def canonical(self
, a
):
3956 """Returns the same Decimal object.
3958 As we do not have different encodings for the same number, the
3959 received object already is in its canonical form.
3961 >>> ExtendedContext.canonical(Decimal('2.50'))
3964 return a
.canonical(context
=self
)
3966 def compare(self
, a
, b
):
3967 """Compares values numerically.
3969 If the signs of the operands differ, a value representing each operand
3970 ('-1' if the operand is less than zero, '0' if the operand is zero or
3971 negative zero, or '1' if the operand is greater than zero) is used in
3972 place of that operand for the comparison instead of the actual
3975 The comparison is then effected by subtracting the second operand from
3976 the first and then returning a value according to the result of the
3977 subtraction: '-1' if the result is less than zero, '0' if the result is
3978 zero or negative zero, or '1' if the result is greater than zero.
3980 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
3982 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
3984 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))
3986 >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))
3988 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))
3990 >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))
3992 >>> ExtendedContext.compare(1, 2)
3994 >>> ExtendedContext.compare(Decimal(1), 2)
3996 >>> ExtendedContext.compare(1, Decimal(2))
3999 a
= _convert_other(a
, raiseit
=True)
4000 return a
.compare(b
, context
=self
)
4002 def compare_signal(self
, a
, b
):
4003 """Compares the values of the two operands numerically.
4005 It's pretty much like compare(), but all NaNs signal, with signaling
4006 NaNs taking precedence over quiet NaNs.
4008 >>> c = ExtendedContext
4009 >>> c.compare_signal(Decimal('2.1'), Decimal('3'))
4011 >>> c.compare_signal(Decimal('2.1'), Decimal('2.1'))
4013 >>> c.flags[InvalidOperation] = 0
4014 >>> print c.flags[InvalidOperation]
4016 >>> c.compare_signal(Decimal('NaN'), Decimal('2.1'))
4018 >>> print c.flags[InvalidOperation]
4020 >>> c.flags[InvalidOperation] = 0
4021 >>> print c.flags[InvalidOperation]
4023 >>> c.compare_signal(Decimal('sNaN'), Decimal('2.1'))
4025 >>> print c.flags[InvalidOperation]
4027 >>> c.compare_signal(-1, 2)
4029 >>> c.compare_signal(Decimal(-1), 2)
4031 >>> c.compare_signal(-1, Decimal(2))
4034 a
= _convert_other(a
, raiseit
=True)
4035 return a
.compare_signal(b
, context
=self
)
4037 def compare_total(self
, a
, b
):
4038 """Compares two operands using their abstract representation.
4040 This is not like the standard compare, which use their numerical
4041 value. Note that a total ordering is defined for all possible abstract
4044 >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
4046 >>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12'))
4048 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))
4050 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))
4052 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300'))
4054 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN'))
4056 >>> ExtendedContext.compare_total(1, 2)
4058 >>> ExtendedContext.compare_total(Decimal(1), 2)
4060 >>> ExtendedContext.compare_total(1, Decimal(2))
4063 a
= _convert_other(a
, raiseit
=True)
4064 return a
.compare_total(b
)
4066 def compare_total_mag(self
, a
, b
):
4067 """Compares two operands using their abstract representation ignoring sign.
4069 Like compare_total, but with operand's sign ignored and assumed to be 0.
4071 a
= _convert_other(a
, raiseit
=True)
4072 return a
.compare_total_mag(b
)
4074 def copy_abs(self
, a
):
4075 """Returns a copy of the operand with the sign set to 0.
4077 >>> ExtendedContext.copy_abs(Decimal('2.1'))
4079 >>> ExtendedContext.copy_abs(Decimal('-100'))
4081 >>> ExtendedContext.copy_abs(-1)
4084 a
= _convert_other(a
, raiseit
=True)
4087 def copy_decimal(self
, a
):
4088 """Returns a copy of the decimal object.
4090 >>> ExtendedContext.copy_decimal(Decimal('2.1'))
4092 >>> ExtendedContext.copy_decimal(Decimal('-1.00'))
4094 >>> ExtendedContext.copy_decimal(1)
4097 a
= _convert_other(a
, raiseit
=True)
4100 def copy_negate(self
, a
):
4101 """Returns a copy of the operand with the sign inverted.
4103 >>> ExtendedContext.copy_negate(Decimal('101.5'))
4105 >>> ExtendedContext.copy_negate(Decimal('-101.5'))
4107 >>> ExtendedContext.copy_negate(1)
4110 a
= _convert_other(a
, raiseit
=True)
4111 return a
.copy_negate()
4113 def copy_sign(self
, a
, b
):
4114 """Copies the second operand's sign to the first one.
4116 In detail, it returns a copy of the first operand with the sign
4117 equal to the sign of the second operand.
4119 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))
4121 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))
4123 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))
4125 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))
4127 >>> ExtendedContext.copy_sign(1, -2)
4129 >>> ExtendedContext.copy_sign(Decimal(1), -2)
4131 >>> ExtendedContext.copy_sign(1, Decimal(-2))
4134 a
= _convert_other(a
, raiseit
=True)
4135 return a
.copy_sign(b
)
4137 def divide(self
, a
, b
):
4138 """Decimal division in a specified context.
4140 >>> ExtendedContext.divide(Decimal('1'), Decimal('3'))
4141 Decimal('0.333333333')
4142 >>> ExtendedContext.divide(Decimal('2'), Decimal('3'))
4143 Decimal('0.666666667')
4144 >>> ExtendedContext.divide(Decimal('5'), Decimal('2'))
4146 >>> ExtendedContext.divide(Decimal('1'), Decimal('10'))
4148 >>> ExtendedContext.divide(Decimal('12'), Decimal('12'))
4150 >>> ExtendedContext.divide(Decimal('8.00'), Decimal('2'))
4152 >>> ExtendedContext.divide(Decimal('2.400'), Decimal('2.0'))
4154 >>> ExtendedContext.divide(Decimal('1000'), Decimal('100'))
4156 >>> ExtendedContext.divide(Decimal('1000'), Decimal('1'))
4158 >>> ExtendedContext.divide(Decimal('2.40E+6'), Decimal('2'))
4160 >>> ExtendedContext.divide(5, 5)
4162 >>> ExtendedContext.divide(Decimal(5), 5)
4164 >>> ExtendedContext.divide(5, Decimal(5))
4167 a
= _convert_other(a
, raiseit
=True)
4168 r
= a
.__div
__(b
, context
=self
)
4169 if r
is NotImplemented:
4170 raise TypeError("Unable to convert %s to Decimal" % b
)
4174 def divide_int(self
, a
, b
):
4175 """Divides two numbers and returns the integer part of the result.
4177 >>> ExtendedContext.divide_int(Decimal('2'), Decimal('3'))
4179 >>> ExtendedContext.divide_int(Decimal('10'), Decimal('3'))
4181 >>> ExtendedContext.divide_int(Decimal('1'), Decimal('0.3'))
4183 >>> ExtendedContext.divide_int(10, 3)
4185 >>> ExtendedContext.divide_int(Decimal(10), 3)
4187 >>> ExtendedContext.divide_int(10, Decimal(3))
4190 a
= _convert_other(a
, raiseit
=True)
4191 r
= a
.__floordiv
__(b
, context
=self
)
4192 if r
is NotImplemented:
4193 raise TypeError("Unable to convert %s to Decimal" % b
)
4197 def divmod(self
, a
, b
):
4198 """Return (a // b, a % b).
4200 >>> ExtendedContext.divmod(Decimal(8), Decimal(3))
4201 (Decimal('2'), Decimal('2'))
4202 >>> ExtendedContext.divmod(Decimal(8), Decimal(4))
4203 (Decimal('2'), Decimal('0'))
4204 >>> ExtendedContext.divmod(8, 4)
4205 (Decimal('2'), Decimal('0'))
4206 >>> ExtendedContext.divmod(Decimal(8), 4)
4207 (Decimal('2'), Decimal('0'))
4208 >>> ExtendedContext.divmod(8, Decimal(4))
4209 (Decimal('2'), Decimal('0'))
4211 a
= _convert_other(a
, raiseit
=True)
4212 r
= a
.__divmod
__(b
, context
=self
)
4213 if r
is NotImplemented:
4214 raise TypeError("Unable to convert %s to Decimal" % b
)
4221 >>> c = ExtendedContext.copy()
4224 >>> c.exp(Decimal('-Infinity'))
4226 >>> c.exp(Decimal('-1'))
4227 Decimal('0.367879441')
4228 >>> c.exp(Decimal('0'))
4230 >>> c.exp(Decimal('1'))
4231 Decimal('2.71828183')
4232 >>> c.exp(Decimal('0.693147181'))
4233 Decimal('2.00000000')
4234 >>> c.exp(Decimal('+Infinity'))
4237 Decimal('22026.4658')
4239 a
=_convert_other(a
, raiseit
=True)
4240 return a
.exp(context
=self
)
4242 def fma(self
, a
, b
, c
):
4243 """Returns a multiplied by b, plus c.
4245 The first two operands are multiplied together, using multiply,
4246 the third operand is then added to the result of that
4247 multiplication, using add, all with only one final rounding.
4249 >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
4251 >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))
4253 >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578'))
4254 Decimal('1.38435736E+12')
4255 >>> ExtendedContext.fma(1, 3, 4)
4257 >>> ExtendedContext.fma(1, Decimal(3), 4)
4259 >>> ExtendedContext.fma(1, 3, Decimal(4))
4262 a
= _convert_other(a
, raiseit
=True)
4263 return a
.fma(b
, c
, context
=self
)
4265 def is_canonical(self
, a
):
4266 """Return True if the operand is canonical; otherwise return False.
4268 Currently, the encoding of a Decimal instance is always
4269 canonical, so this method returns True for any Decimal.
4271 >>> ExtendedContext.is_canonical(Decimal('2.50'))
4274 return a
.is_canonical()
4276 def is_finite(self
, a
):
4277 """Return True if the operand is finite; otherwise return False.
4279 A Decimal instance is considered finite if it is neither
4282 >>> ExtendedContext.is_finite(Decimal('2.50'))
4284 >>> ExtendedContext.is_finite(Decimal('-0.3'))
4286 >>> ExtendedContext.is_finite(Decimal('0'))
4288 >>> ExtendedContext.is_finite(Decimal('Inf'))
4290 >>> ExtendedContext.is_finite(Decimal('NaN'))
4292 >>> ExtendedContext.is_finite(1)
4295 a
= _convert_other(a
, raiseit
=True)
4296 return a
.is_finite()
4298 def is_infinite(self
, a
):
4299 """Return True if the operand is infinite; otherwise return False.
4301 >>> ExtendedContext.is_infinite(Decimal('2.50'))
4303 >>> ExtendedContext.is_infinite(Decimal('-Inf'))
4305 >>> ExtendedContext.is_infinite(Decimal('NaN'))
4307 >>> ExtendedContext.is_infinite(1)
4310 a
= _convert_other(a
, raiseit
=True)
4311 return a
.is_infinite()
4313 def is_nan(self
, a
):
4314 """Return True if the operand is a qNaN or sNaN;
4315 otherwise return False.
4317 >>> ExtendedContext.is_nan(Decimal('2.50'))
4319 >>> ExtendedContext.is_nan(Decimal('NaN'))
4321 >>> ExtendedContext.is_nan(Decimal('-sNaN'))
4323 >>> ExtendedContext.is_nan(1)
4326 a
= _convert_other(a
, raiseit
=True)
4329 def is_normal(self
, a
):
4330 """Return True if the operand is a normal number;
4331 otherwise return False.
4333 >>> c = ExtendedContext.copy()
4336 >>> c.is_normal(Decimal('2.50'))
4338 >>> c.is_normal(Decimal('0.1E-999'))
4340 >>> c.is_normal(Decimal('0.00'))
4342 >>> c.is_normal(Decimal('-Inf'))
4344 >>> c.is_normal(Decimal('NaN'))
4349 a
= _convert_other(a
, raiseit
=True)
4350 return a
.is_normal(context
=self
)
4352 def is_qnan(self
, a
):
4353 """Return True if the operand is a quiet NaN; otherwise return False.
4355 >>> ExtendedContext.is_qnan(Decimal('2.50'))
4357 >>> ExtendedContext.is_qnan(Decimal('NaN'))
4359 >>> ExtendedContext.is_qnan(Decimal('sNaN'))
4361 >>> ExtendedContext.is_qnan(1)
4364 a
= _convert_other(a
, raiseit
=True)
4367 def is_signed(self
, a
):
4368 """Return True if the operand is negative; otherwise return False.
4370 >>> ExtendedContext.is_signed(Decimal('2.50'))
4372 >>> ExtendedContext.is_signed(Decimal('-12'))
4374 >>> ExtendedContext.is_signed(Decimal('-0'))
4376 >>> ExtendedContext.is_signed(8)
4378 >>> ExtendedContext.is_signed(-8)
4381 a
= _convert_other(a
, raiseit
=True)
4382 return a
.is_signed()
4384 def is_snan(self
, a
):
4385 """Return True if the operand is a signaling NaN;
4386 otherwise return False.
4388 >>> ExtendedContext.is_snan(Decimal('2.50'))
4390 >>> ExtendedContext.is_snan(Decimal('NaN'))
4392 >>> ExtendedContext.is_snan(Decimal('sNaN'))
4394 >>> ExtendedContext.is_snan(1)
4397 a
= _convert_other(a
, raiseit
=True)
4400 def is_subnormal(self
, a
):
4401 """Return True if the operand is subnormal; otherwise return False.
4403 >>> c = ExtendedContext.copy()
4406 >>> c.is_subnormal(Decimal('2.50'))
4408 >>> c.is_subnormal(Decimal('0.1E-999'))
4410 >>> c.is_subnormal(Decimal('0.00'))
4412 >>> c.is_subnormal(Decimal('-Inf'))
4414 >>> c.is_subnormal(Decimal('NaN'))
4416 >>> c.is_subnormal(1)
4419 a
= _convert_other(a
, raiseit
=True)
4420 return a
.is_subnormal(context
=self
)
4422 def is_zero(self
, a
):
4423 """Return True if the operand is a zero; otherwise return False.
4425 >>> ExtendedContext.is_zero(Decimal('0'))
4427 >>> ExtendedContext.is_zero(Decimal('2.50'))
4429 >>> ExtendedContext.is_zero(Decimal('-0E+2'))
4431 >>> ExtendedContext.is_zero(1)
4433 >>> ExtendedContext.is_zero(0)
4436 a
= _convert_other(a
, raiseit
=True)
4440 """Returns the natural (base e) logarithm of the operand.
4442 >>> c = ExtendedContext.copy()
4445 >>> c.ln(Decimal('0'))
4446 Decimal('-Infinity')
4447 >>> c.ln(Decimal('1.000'))
4449 >>> c.ln(Decimal('2.71828183'))
4450 Decimal('1.00000000')
4451 >>> c.ln(Decimal('10'))
4452 Decimal('2.30258509')
4453 >>> c.ln(Decimal('+Infinity'))
4458 a
= _convert_other(a
, raiseit
=True)
4459 return a
.ln(context
=self
)
4462 """Returns the base 10 logarithm of the operand.
4464 >>> c = ExtendedContext.copy()
4467 >>> c.log10(Decimal('0'))
4468 Decimal('-Infinity')
4469 >>> c.log10(Decimal('0.001'))
4471 >>> c.log10(Decimal('1.000'))
4473 >>> c.log10(Decimal('2'))
4474 Decimal('0.301029996')
4475 >>> c.log10(Decimal('10'))
4477 >>> c.log10(Decimal('70'))
4478 Decimal('1.84509804')
4479 >>> c.log10(Decimal('+Infinity'))
4482 Decimal('-Infinity')
4486 a
= _convert_other(a
, raiseit
=True)
4487 return a
.log10(context
=self
)
4490 """ Returns the exponent of the magnitude of the operand's MSD.
4492 The result is the integer which is the exponent of the magnitude
4493 of the most significant digit of the operand (as though the
4494 operand were truncated to a single digit while maintaining the
4495 value of that digit and without limiting the resulting exponent).
4497 >>> ExtendedContext.logb(Decimal('250'))
4499 >>> ExtendedContext.logb(Decimal('2.50'))
4501 >>> ExtendedContext.logb(Decimal('0.03'))
4503 >>> ExtendedContext.logb(Decimal('0'))
4504 Decimal('-Infinity')
4505 >>> ExtendedContext.logb(1)
4507 >>> ExtendedContext.logb(10)
4509 >>> ExtendedContext.logb(100)
4512 a
= _convert_other(a
, raiseit
=True)
4513 return a
.logb(context
=self
)
4515 def logical_and(self
, a
, b
):
4516 """Applies the logical operation 'and' between each operand's digits.
4518 The operands must be both logical numbers.
4520 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))
4522 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))
4524 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))
4526 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))
4528 >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))
4530 >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))
4532 >>> ExtendedContext.logical_and(110, 1101)
4534 >>> ExtendedContext.logical_and(Decimal(110), 1101)
4536 >>> ExtendedContext.logical_and(110, Decimal(1101))
4539 a
= _convert_other(a
, raiseit
=True)
4540 return a
.logical_and(b
, context
=self
)
4542 def logical_invert(self
, a
):
4543 """Invert all the digits in the operand.
4545 The operand must be a logical number.
4547 >>> ExtendedContext.logical_invert(Decimal('0'))
4548 Decimal('111111111')
4549 >>> ExtendedContext.logical_invert(Decimal('1'))
4550 Decimal('111111110')
4551 >>> ExtendedContext.logical_invert(Decimal('111111111'))
4553 >>> ExtendedContext.logical_invert(Decimal('101010101'))
4555 >>> ExtendedContext.logical_invert(1101)
4556 Decimal('111110010')
4558 a
= _convert_other(a
, raiseit
=True)
4559 return a
.logical_invert(context
=self
)
4561 def logical_or(self
, a
, b
):
4562 """Applies the logical operation 'or' between each operand's digits.
4564 The operands must be both logical numbers.
4566 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))
4568 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))
4570 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))
4572 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))
4574 >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))
4576 >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))
4578 >>> ExtendedContext.logical_or(110, 1101)
4580 >>> ExtendedContext.logical_or(Decimal(110), 1101)
4582 >>> ExtendedContext.logical_or(110, Decimal(1101))
4585 a
= _convert_other(a
, raiseit
=True)
4586 return a
.logical_or(b
, context
=self
)
4588 def logical_xor(self
, a
, b
):
4589 """Applies the logical operation 'xor' between each operand's digits.
4591 The operands must be both logical numbers.
4593 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))
4595 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))
4597 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))
4599 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))
4601 >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))
4603 >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))
4605 >>> ExtendedContext.logical_xor(110, 1101)
4607 >>> ExtendedContext.logical_xor(Decimal(110), 1101)
4609 >>> ExtendedContext.logical_xor(110, Decimal(1101))
4612 a
= _convert_other(a
, raiseit
=True)
4613 return a
.logical_xor(b
, context
=self
)
4615 def max(self
, a
, b
):
4616 """max compares two values numerically and returns the maximum.
4618 If either operand is a NaN then the general rules apply.
4619 Otherwise, the operands are compared as though by the compare
4620 operation. If they are numerically equal then the left-hand operand
4621 is chosen as the result. Otherwise the maximum (closer to positive
4622 infinity) of the two operands is chosen as the result.
4624 >>> ExtendedContext.max(Decimal('3'), Decimal('2'))
4626 >>> ExtendedContext.max(Decimal('-10'), Decimal('3'))
4628 >>> ExtendedContext.max(Decimal('1.0'), Decimal('1'))
4630 >>> ExtendedContext.max(Decimal('7'), Decimal('NaN'))
4632 >>> ExtendedContext.max(1, 2)
4634 >>> ExtendedContext.max(Decimal(1), 2)
4636 >>> ExtendedContext.max(1, Decimal(2))
4639 a
= _convert_other(a
, raiseit
=True)
4640 return a
.max(b
, context
=self
)
4642 def max_mag(self
, a
, b
):
4643 """Compares the values numerically with their sign ignored.
4645 >>> ExtendedContext.max_mag(Decimal('7'), Decimal('NaN'))
4647 >>> ExtendedContext.max_mag(Decimal('7'), Decimal('-10'))
4649 >>> ExtendedContext.max_mag(1, -2)
4651 >>> ExtendedContext.max_mag(Decimal(1), -2)
4653 >>> ExtendedContext.max_mag(1, Decimal(-2))
4656 a
= _convert_other(a
, raiseit
=True)
4657 return a
.max_mag(b
, context
=self
)
4659 def min(self
, a
, b
):
4660 """min compares two values numerically and returns the minimum.
4662 If either operand is a NaN then the general rules apply.
4663 Otherwise, the operands are compared as though by the compare
4664 operation. If they are numerically equal then the left-hand operand
4665 is chosen as the result. Otherwise the minimum (closer to negative
4666 infinity) of the two operands is chosen as the result.
4668 >>> ExtendedContext.min(Decimal('3'), Decimal('2'))
4670 >>> ExtendedContext.min(Decimal('-10'), Decimal('3'))
4672 >>> ExtendedContext.min(Decimal('1.0'), Decimal('1'))
4674 >>> ExtendedContext.min(Decimal('7'), Decimal('NaN'))
4676 >>> ExtendedContext.min(1, 2)
4678 >>> ExtendedContext.min(Decimal(1), 2)
4680 >>> ExtendedContext.min(1, Decimal(29))
4683 a
= _convert_other(a
, raiseit
=True)
4684 return a
.min(b
, context
=self
)
4686 def min_mag(self
, a
, b
):
4687 """Compares the values numerically with their sign ignored.
4689 >>> ExtendedContext.min_mag(Decimal('3'), Decimal('-2'))
4691 >>> ExtendedContext.min_mag(Decimal('-3'), Decimal('NaN'))
4693 >>> ExtendedContext.min_mag(1, -2)
4695 >>> ExtendedContext.min_mag(Decimal(1), -2)
4697 >>> ExtendedContext.min_mag(1, Decimal(-2))
4700 a
= _convert_other(a
, raiseit
=True)
4701 return a
.min_mag(b
, context
=self
)
4704 """Minus corresponds to unary prefix minus in Python.
4706 The operation is evaluated using the same rules as subtract; the
4707 operation minus(a) is calculated as subtract('0', a) where the '0'
4708 has the same exponent as the operand.
4710 >>> ExtendedContext.minus(Decimal('1.3'))
4712 >>> ExtendedContext.minus(Decimal('-1.3'))
4714 >>> ExtendedContext.minus(1)
4717 a
= _convert_other(a
, raiseit
=True)
4718 return a
.__neg
__(context
=self
)
4720 def multiply(self
, a
, b
):
4721 """multiply multiplies two operands.
4723 If either operand is a special value then the general rules apply.
4724 Otherwise, the operands are multiplied together
4725 ('long multiplication'), resulting in a number which may be as long as
4726 the sum of the lengths of the two operands.
4728 >>> ExtendedContext.multiply(Decimal('1.20'), Decimal('3'))
4730 >>> ExtendedContext.multiply(Decimal('7'), Decimal('3'))
4732 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('0.8'))
4734 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('-0'))
4736 >>> ExtendedContext.multiply(Decimal('654321'), Decimal('654321'))
4737 Decimal('4.28135971E+11')
4738 >>> ExtendedContext.multiply(7, 7)
4740 >>> ExtendedContext.multiply(Decimal(7), 7)
4742 >>> ExtendedContext.multiply(7, Decimal(7))
4745 a
= _convert_other(a
, raiseit
=True)
4746 r
= a
.__mul
__(b
, context
=self
)
4747 if r
is NotImplemented:
4748 raise TypeError("Unable to convert %s to Decimal" % b
)
4752 def next_minus(self
, a
):
4753 """Returns the largest representable number smaller than a.
4755 >>> c = ExtendedContext.copy()
4758 >>> ExtendedContext.next_minus(Decimal('1'))
4759 Decimal('0.999999999')
4760 >>> c.next_minus(Decimal('1E-1007'))
4762 >>> ExtendedContext.next_minus(Decimal('-1.00000003'))
4763 Decimal('-1.00000004')
4764 >>> c.next_minus(Decimal('Infinity'))
4765 Decimal('9.99999999E+999')
4767 Decimal('0.999999999')
4769 a
= _convert_other(a
, raiseit
=True)
4770 return a
.next_minus(context
=self
)
4772 def next_plus(self
, a
):
4773 """Returns the smallest representable number larger than a.
4775 >>> c = ExtendedContext.copy()
4778 >>> ExtendedContext.next_plus(Decimal('1'))
4779 Decimal('1.00000001')
4780 >>> c.next_plus(Decimal('-1E-1007'))
4782 >>> ExtendedContext.next_plus(Decimal('-1.00000003'))
4783 Decimal('-1.00000002')
4784 >>> c.next_plus(Decimal('-Infinity'))
4785 Decimal('-9.99999999E+999')
4787 Decimal('1.00000001')
4789 a
= _convert_other(a
, raiseit
=True)
4790 return a
.next_plus(context
=self
)
4792 def next_toward(self
, a
, b
):
4793 """Returns the number closest to a, in direction towards b.
4795 The result is the closest representable number from the first
4796 operand (but not the first operand) that is in the direction
4797 towards the second operand, unless the operands have the same
4800 >>> c = ExtendedContext.copy()
4803 >>> c.next_toward(Decimal('1'), Decimal('2'))
4804 Decimal('1.00000001')
4805 >>> c.next_toward(Decimal('-1E-1007'), Decimal('1'))
4807 >>> c.next_toward(Decimal('-1.00000003'), Decimal('0'))
4808 Decimal('-1.00000002')
4809 >>> c.next_toward(Decimal('1'), Decimal('0'))
4810 Decimal('0.999999999')
4811 >>> c.next_toward(Decimal('1E-1007'), Decimal('-100'))
4813 >>> c.next_toward(Decimal('-1.00000003'), Decimal('-10'))
4814 Decimal('-1.00000004')
4815 >>> c.next_toward(Decimal('0.00'), Decimal('-0.0000'))
4817 >>> c.next_toward(0, 1)
4819 >>> c.next_toward(Decimal(0), 1)
4821 >>> c.next_toward(0, Decimal(1))
4824 a
= _convert_other(a
, raiseit
=True)
4825 return a
.next_toward(b
, context
=self
)
4827 def normalize(self
, a
):
4828 """normalize reduces an operand to its simplest form.
4830 Essentially a plus operation with all trailing zeros removed from the
4833 >>> ExtendedContext.normalize(Decimal('2.1'))
4835 >>> ExtendedContext.normalize(Decimal('-2.0'))
4837 >>> ExtendedContext.normalize(Decimal('1.200'))
4839 >>> ExtendedContext.normalize(Decimal('-120'))
4841 >>> ExtendedContext.normalize(Decimal('120.00'))
4843 >>> ExtendedContext.normalize(Decimal('0.00'))
4845 >>> ExtendedContext.normalize(6)
4848 a
= _convert_other(a
, raiseit
=True)
4849 return a
.normalize(context
=self
)
4851 def number_class(self
, a
):
4852 """Returns an indication of the class of the operand.
4854 The class is one of the following strings:
4866 >>> c = Context(ExtendedContext)
4869 >>> c.number_class(Decimal('Infinity'))
4871 >>> c.number_class(Decimal('1E-10'))
4873 >>> c.number_class(Decimal('2.50'))
4875 >>> c.number_class(Decimal('0.1E-999'))
4877 >>> c.number_class(Decimal('0'))
4879 >>> c.number_class(Decimal('-0'))
4881 >>> c.number_class(Decimal('-0.1E-999'))
4883 >>> c.number_class(Decimal('-1E-10'))
4885 >>> c.number_class(Decimal('-2.50'))
4887 >>> c.number_class(Decimal('-Infinity'))
4889 >>> c.number_class(Decimal('NaN'))
4891 >>> c.number_class(Decimal('-NaN'))
4893 >>> c.number_class(Decimal('sNaN'))
4895 >>> c.number_class(123)
4898 a
= _convert_other(a
, raiseit
=True)
4899 return a
.number_class(context
=self
)
4902 """Plus corresponds to unary prefix plus in Python.
4904 The operation is evaluated using the same rules as add; the
4905 operation plus(a) is calculated as add('0', a) where the '0'
4906 has the same exponent as the operand.
4908 >>> ExtendedContext.plus(Decimal('1.3'))
4910 >>> ExtendedContext.plus(Decimal('-1.3'))
4912 >>> ExtendedContext.plus(-1)
4915 a
= _convert_other(a
, raiseit
=True)
4916 return a
.__pos
__(context
=self
)
4918 def power(self
, a
, b
, modulo
=None):
4919 """Raises a to the power of b, to modulo if given.
4921 With two arguments, compute a**b. If a is negative then b
4922 must be integral. The result will be inexact unless b is
4923 integral and the result is finite and can be expressed exactly
4924 in 'precision' digits.
4926 With three arguments, compute (a**b) % modulo. For the
4927 three argument form, the following restrictions on the
4930 - all three arguments must be integral
4931 - b must be nonnegative
4932 - at least one of a or b must be nonzero
4933 - modulo must be nonzero and have at most 'precision' digits
4935 The result of pow(a, b, modulo) is identical to the result
4936 that would be obtained by computing (a**b) % modulo with
4937 unbounded precision, but is computed more efficiently. It is
4940 >>> c = ExtendedContext.copy()
4943 >>> c.power(Decimal('2'), Decimal('3'))
4945 >>> c.power(Decimal('-2'), Decimal('3'))
4947 >>> c.power(Decimal('2'), Decimal('-3'))
4949 >>> c.power(Decimal('1.7'), Decimal('8'))
4950 Decimal('69.7575744')
4951 >>> c.power(Decimal('10'), Decimal('0.301029996'))
4952 Decimal('2.00000000')
4953 >>> c.power(Decimal('Infinity'), Decimal('-1'))
4955 >>> c.power(Decimal('Infinity'), Decimal('0'))
4957 >>> c.power(Decimal('Infinity'), Decimal('1'))
4959 >>> c.power(Decimal('-Infinity'), Decimal('-1'))
4961 >>> c.power(Decimal('-Infinity'), Decimal('0'))
4963 >>> c.power(Decimal('-Infinity'), Decimal('1'))
4964 Decimal('-Infinity')
4965 >>> c.power(Decimal('-Infinity'), Decimal('2'))
4967 >>> c.power(Decimal('0'), Decimal('0'))
4970 >>> c.power(Decimal('3'), Decimal('7'), Decimal('16'))
4972 >>> c.power(Decimal('-3'), Decimal('7'), Decimal('16'))
4974 >>> c.power(Decimal('-3'), Decimal('8'), Decimal('16'))
4976 >>> c.power(Decimal('3'), Decimal('7'), Decimal('-16'))
4978 >>> c.power(Decimal('23E12345'), Decimal('67E189'), Decimal('123456789'))
4980 >>> c.power(Decimal('-0'), Decimal('17'), Decimal('1729'))
4982 >>> c.power(Decimal('-23'), Decimal('0'), Decimal('65537'))
4984 >>> ExtendedContext.power(7, 7)
4986 >>> ExtendedContext.power(Decimal(7), 7)
4988 >>> ExtendedContext.power(7, Decimal(7), 2)
4991 a
= _convert_other(a
, raiseit
=True)
4992 r
= a
.__pow
__(b
, modulo
, context
=self
)
4993 if r
is NotImplemented:
4994 raise TypeError("Unable to convert %s to Decimal" % b
)
4998 def quantize(self
, a
, b
):
4999 """Returns a value equal to 'a' (rounded), having the exponent of 'b'.
5001 The coefficient of the result is derived from that of the left-hand
5002 operand. It may be rounded using the current rounding setting (if the
5003 exponent is being increased), multiplied by a positive power of ten (if
5004 the exponent is being decreased), or is unchanged (if the exponent is
5005 already equal to that of the right-hand operand).
5007 Unlike other operations, if the length of the coefficient after the
5008 quantize operation would be greater than precision then an Invalid
5009 operation condition is raised. This guarantees that, unless there is
5010 an error condition, the exponent of the result of a quantize is always
5011 equal to that of the right-hand operand.
5013 Also unlike other operations, quantize will never raise Underflow, even
5014 if the result is subnormal and inexact.
5016 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))
5018 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))
5020 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))
5022 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))
5024 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))
5026 >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))
5027 Decimal('-Infinity')
5028 >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))
5030 >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))
5032 >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))
5034 >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))
5036 >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))
5038 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))
5040 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))
5042 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))
5044 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))
5046 >>> ExtendedContext.quantize(1, 2)
5048 >>> ExtendedContext.quantize(Decimal(1), 2)
5050 >>> ExtendedContext.quantize(1, Decimal(2))
5053 a
= _convert_other(a
, raiseit
=True)
5054 return a
.quantize(b
, context
=self
)
5057 """Just returns 10, as this is Decimal, :)
5059 >>> ExtendedContext.radix()
5064 def remainder(self
, a
, b
):
5065 """Returns the remainder from integer division.
5067 The result is the residue of the dividend after the operation of
5068 calculating integer division as described for divide-integer, rounded
5069 to precision digits if necessary. The sign of the result, if
5070 non-zero, is the same as that of the original dividend.
5072 This operation will fail under the same conditions as integer division
5073 (that is, if integer division on the same two operands would fail, the
5074 remainder cannot be calculated).
5076 >>> ExtendedContext.remainder(Decimal('2.1'), Decimal('3'))
5078 >>> ExtendedContext.remainder(Decimal('10'), Decimal('3'))
5080 >>> ExtendedContext.remainder(Decimal('-10'), Decimal('3'))
5082 >>> ExtendedContext.remainder(Decimal('10.2'), Decimal('1'))
5084 >>> ExtendedContext.remainder(Decimal('10'), Decimal('0.3'))
5086 >>> ExtendedContext.remainder(Decimal('3.6'), Decimal('1.3'))
5088 >>> ExtendedContext.remainder(22, 6)
5090 >>> ExtendedContext.remainder(Decimal(22), 6)
5092 >>> ExtendedContext.remainder(22, Decimal(6))
5095 a
= _convert_other(a
, raiseit
=True)
5096 r
= a
.__mod
__(b
, context
=self
)
5097 if r
is NotImplemented:
5098 raise TypeError("Unable to convert %s to Decimal" % b
)
5102 def remainder_near(self
, a
, b
):
5103 """Returns to be "a - b * n", where n is the integer nearest the exact
5104 value of "x / b" (if two integers are equally near then the even one
5105 is chosen). If the result is equal to 0 then its sign will be the
5108 This operation will fail under the same conditions as integer division
5109 (that is, if integer division on the same two operands would fail, the
5110 remainder cannot be calculated).
5112 >>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))
5114 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))
5116 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))
5118 >>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))
5120 >>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))
5122 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))
5124 >>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))
5126 >>> ExtendedContext.remainder_near(3, 11)
5128 >>> ExtendedContext.remainder_near(Decimal(3), 11)
5130 >>> ExtendedContext.remainder_near(3, Decimal(11))
5133 a
= _convert_other(a
, raiseit
=True)
5134 return a
.remainder_near(b
, context
=self
)
5136 def rotate(self
, a
, b
):
5137 """Returns a rotated copy of a, b times.
5139 The coefficient of the result is a rotated copy of the digits in
5140 the coefficient of the first operand. The number of places of
5141 rotation is taken from the absolute value of the second operand,
5142 with the rotation being to the left if the second operand is
5143 positive or to the right otherwise.
5145 >>> ExtendedContext.rotate(Decimal('34'), Decimal('8'))
5146 Decimal('400000003')
5147 >>> ExtendedContext.rotate(Decimal('12'), Decimal('9'))
5149 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('-2'))
5150 Decimal('891234567')
5151 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('0'))
5152 Decimal('123456789')
5153 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('+2'))
5154 Decimal('345678912')
5155 >>> ExtendedContext.rotate(1333333, 1)
5157 >>> ExtendedContext.rotate(Decimal(1333333), 1)
5159 >>> ExtendedContext.rotate(1333333, Decimal(1))
5162 a
= _convert_other(a
, raiseit
=True)
5163 return a
.rotate(b
, context
=self
)
5165 def same_quantum(self
, a
, b
):
5166 """Returns True if the two operands have the same exponent.
5168 The result is never affected by either the sign or the coefficient of
5171 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))
5173 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))
5175 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))
5177 >>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))
5179 >>> ExtendedContext.same_quantum(10000, -1)
5181 >>> ExtendedContext.same_quantum(Decimal(10000), -1)
5183 >>> ExtendedContext.same_quantum(10000, Decimal(-1))
5186 a
= _convert_other(a
, raiseit
=True)
5187 return a
.same_quantum(b
)
5189 def scaleb (self
, a
, b
):
5190 """Returns the first operand after adding the second value its exp.
5192 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('-2'))
5194 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('0'))
5196 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('3'))
5198 >>> ExtendedContext.scaleb(1, 4)
5200 >>> ExtendedContext.scaleb(Decimal(1), 4)
5202 >>> ExtendedContext.scaleb(1, Decimal(4))
5205 a
= _convert_other(a
, raiseit
=True)
5206 return a
.scaleb(b
, context
=self
)
5208 def shift(self
, a
, b
):
5209 """Returns a shifted copy of a, b times.
5211 The coefficient of the result is a shifted copy of the digits
5212 in the coefficient of the first operand. The number of places
5213 to shift is taken from the absolute value of the second operand,
5214 with the shift being to the left if the second operand is
5215 positive or to the right otherwise. Digits shifted into the
5216 coefficient are zeros.
5218 >>> ExtendedContext.shift(Decimal('34'), Decimal('8'))
5219 Decimal('400000000')
5220 >>> ExtendedContext.shift(Decimal('12'), Decimal('9'))
5222 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('-2'))
5224 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('0'))
5225 Decimal('123456789')
5226 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('+2'))
5227 Decimal('345678900')
5228 >>> ExtendedContext.shift(88888888, 2)
5229 Decimal('888888800')
5230 >>> ExtendedContext.shift(Decimal(88888888), 2)
5231 Decimal('888888800')
5232 >>> ExtendedContext.shift(88888888, Decimal(2))
5233 Decimal('888888800')
5235 a
= _convert_other(a
, raiseit
=True)
5236 return a
.shift(b
, context
=self
)
5239 """Square root of a non-negative number to context precision.
5241 If the result must be inexact, it is rounded using the round-half-even
5244 >>> ExtendedContext.sqrt(Decimal('0'))
5246 >>> ExtendedContext.sqrt(Decimal('-0'))
5248 >>> ExtendedContext.sqrt(Decimal('0.39'))
5249 Decimal('0.624499800')
5250 >>> ExtendedContext.sqrt(Decimal('100'))
5252 >>> ExtendedContext.sqrt(Decimal('1'))
5254 >>> ExtendedContext.sqrt(Decimal('1.0'))
5256 >>> ExtendedContext.sqrt(Decimal('1.00'))
5258 >>> ExtendedContext.sqrt(Decimal('7'))
5259 Decimal('2.64575131')
5260 >>> ExtendedContext.sqrt(Decimal('10'))
5261 Decimal('3.16227766')
5262 >>> ExtendedContext.sqrt(2)
5263 Decimal('1.41421356')
5264 >>> ExtendedContext.prec
5267 a
= _convert_other(a
, raiseit
=True)
5268 return a
.sqrt(context
=self
)
5270 def subtract(self
, a
, b
):
5271 """Return the difference between the two operands.
5273 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.07'))
5275 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.30'))
5277 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('2.07'))
5279 >>> ExtendedContext.subtract(8, 5)
5281 >>> ExtendedContext.subtract(Decimal(8), 5)
5283 >>> ExtendedContext.subtract(8, Decimal(5))
5286 a
= _convert_other(a
, raiseit
=True)
5287 r
= a
.__sub
__(b
, context
=self
)
5288 if r
is NotImplemented:
5289 raise TypeError("Unable to convert %s to Decimal" % b
)
5293 def to_eng_string(self
, a
):
5294 """Converts a number to a string, using scientific notation.
5296 The operation is not affected by the context.
5298 a
= _convert_other(a
, raiseit
=True)
5299 return a
.to_eng_string(context
=self
)
5301 def to_sci_string(self
, a
):
5302 """Converts a number to a string, using scientific notation.
5304 The operation is not affected by the context.
5306 a
= _convert_other(a
, raiseit
=True)
5307 return a
.__str
__(context
=self
)
5309 def to_integral_exact(self
, a
):
5310 """Rounds to an integer.
5312 When the operand has a negative exponent, the result is the same
5313 as using the quantize() operation using the given operand as the
5314 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
5315 of the operand as the precision setting; Inexact and Rounded flags
5316 are allowed in this operation. The rounding mode is taken from the
5319 >>> ExtendedContext.to_integral_exact(Decimal('2.1'))
5321 >>> ExtendedContext.to_integral_exact(Decimal('100'))
5323 >>> ExtendedContext.to_integral_exact(Decimal('100.0'))
5325 >>> ExtendedContext.to_integral_exact(Decimal('101.5'))
5327 >>> ExtendedContext.to_integral_exact(Decimal('-101.5'))
5329 >>> ExtendedContext.to_integral_exact(Decimal('10E+5'))
5331 >>> ExtendedContext.to_integral_exact(Decimal('7.89E+77'))
5333 >>> ExtendedContext.to_integral_exact(Decimal('-Inf'))
5334 Decimal('-Infinity')
5336 a
= _convert_other(a
, raiseit
=True)
5337 return a
.to_integral_exact(context
=self
)
5339 def to_integral_value(self
, a
):
5340 """Rounds to an integer.
5342 When the operand has a negative exponent, the result is the same
5343 as using the quantize() operation using the given operand as the
5344 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
5345 of the operand as the precision setting, except that no flags will
5346 be set. The rounding mode is taken from the context.
5348 >>> ExtendedContext.to_integral_value(Decimal('2.1'))
5350 >>> ExtendedContext.to_integral_value(Decimal('100'))
5352 >>> ExtendedContext.to_integral_value(Decimal('100.0'))
5354 >>> ExtendedContext.to_integral_value(Decimal('101.5'))
5356 >>> ExtendedContext.to_integral_value(Decimal('-101.5'))
5358 >>> ExtendedContext.to_integral_value(Decimal('10E+5'))
5360 >>> ExtendedContext.to_integral_value(Decimal('7.89E+77'))
5362 >>> ExtendedContext.to_integral_value(Decimal('-Inf'))
5363 Decimal('-Infinity')
5365 a
= _convert_other(a
, raiseit
=True)
5366 return a
.to_integral_value(context
=self
)
5368 # the method name changed, but we provide also the old one, for compatibility
5369 to_integral
= to_integral_value
5371 class _WorkRep(object):
5372 __slots__
= ('sign','int','exp')
5375 # exp: None, int, or string
5377 def __init__(self
, value
=None):
5382 elif isinstance(value
, Decimal
):
5383 self
.sign
= value
._sign
5384 self
.int = int(value
._int
)
5385 self
.exp
= value
._exp
5387 # assert isinstance(value, tuple)
5388 self
.sign
= value
[0]
5393 return "(%r, %r, %r)" % (self
.sign
, self
.int, self
.exp
)
5399 def _normalize(op1
, op2
, prec
= 0):
5400 """Normalizes op1, op2 to have the same exp and length of coefficient.
5402 Done during addition.
5404 if op1
.exp
< op2
.exp
:
5411 # Let exp = min(tmp.exp - 1, tmp.adjusted() - precision - 1).
5412 # Then adding 10**exp to tmp has the same effect (after rounding)
5413 # as adding any positive quantity smaller than 10**exp; similarly
5414 # for subtraction. So if other is smaller than 10**exp we replace
5415 # it with 10**exp. This avoids tmp.exp - other.exp getting too large.
5416 tmp_len
= len(str(tmp
.int))
5417 other_len
= len(str(other
.int))
5418 exp
= tmp
.exp
+ min(-1, tmp_len
- prec
- 2)
5419 if other_len
+ other
.exp
- 1 < exp
:
5423 tmp
.int *= 10 ** (tmp
.exp
- other
.exp
)
5427 ##### Integer arithmetic functions used by ln, log10, exp and __pow__ #####
5429 # This function from Tim Peters was taken from here:
5430 # http://mail.python.org/pipermail/python-list/1999-July/007758.html
5431 # The correction being in the function definition is for speed, and
5432 # the whole function is not resolved with math.log because of avoiding
5433 # the use of floats.
5434 def _nbits(n
, correction
= {
5435 '0': 4, '1': 3, '2': 2, '3': 2,
5436 '4': 1, '5': 1, '6': 1, '7': 1,
5437 '8': 0, '9': 0, 'a': 0, 'b': 0,
5438 'c': 0, 'd': 0, 'e': 0, 'f': 0}):
5439 """Number of bits in binary representation of the positive integer n,
5443 raise ValueError("The argument to _nbits should be nonnegative.")
5445 return 4*len(hex_n
) - correction
[hex_n
[0]]
5447 def _sqrt_nearest(n
, a
):
5448 """Closest integer to the square root of the positive integer n. a is
5449 an initial approximation to the square root. Any positive integer
5450 will do for a, but the closer a is to the square root of n the
5451 faster convergence will be.
5454 if n
<= 0 or a
<= 0:
5455 raise ValueError("Both arguments to _sqrt_nearest should be positive.")
5459 b
, a
= a
, a
--n
//a
>>1
5462 def _rshift_nearest(x
, shift
):
5463 """Given an integer x and a nonnegative integer shift, return closest
5464 integer to x / 2**shift; use round-to-even in case of a tie.
5467 b
, q
= 1L << shift
, x
>> shift
5468 return q
+ (2*(x
& (b
-1)) + (q
&1) > b
)
5470 def _div_nearest(a
, b
):
5471 """Closest integer to a/b, a and b positive integers; rounds to even
5472 in the case of a tie.
5476 return q
+ (2*r
+ (q
&1) > b
)
5478 def _ilog(x
, M
, L
= 8):
5479 """Integer approximation to M*log(x/M), with absolute error boundable
5480 in terms only of x/M.
5482 Given positive integers x and M, return an integer approximation to
5483 M * log(x/M). For L = 8 and 0.1 <= x/M <= 10 the difference
5484 between the approximation and the exact result is at most 22. For
5485 L = 8 and 1.0 <= x/M <= 10.0 the difference is at most 15. In
5486 both cases these are upper bounds on the error; it will usually be
5489 # The basic algorithm is the following: let log1p be the function
5490 # log1p(x) = log(1+x). Then log(x/M) = log1p((x-M)/M). We use
5493 # log1p(y) = 2*log1p(y/(1+sqrt(1+y)))
5495 # repeatedly until the argument to log1p is small (< 2**-L in
5496 # absolute value). For small y we can use the Taylor series
5499 # log1p(y) ~ y - y**2/2 + y**3/3 - ... - (-y)**T/T
5501 # truncating at T such that y**T is small enough. The whole
5502 # computation is carried out in a form of fixed-point arithmetic,
5503 # with a real number z being represented by an integer
5504 # approximation to z*M. To avoid loss of precision, the y below
5505 # is actually an integer approximation to 2**R*y*M, where R is the
5506 # number of reductions performed so far.
5509 # argument reduction; R = number of reductions performed
5511 while (R
<= L
and long(abs(y
)) << L
-R
>= M
or
5512 R
> L
and abs(y
) >> R
-L
>= M
):
5513 y
= _div_nearest(long(M
*y
) << 1,
5514 M
+ _sqrt_nearest(M
*(M
+_rshift_nearest(y
, R
)), M
))
5517 # Taylor series with T terms
5518 T
= -int(-10*len(str(M
))//(3*L
))
5519 yshift
= _rshift_nearest(y
, R
)
5520 w
= _div_nearest(M
, T
)
5521 for k
in xrange(T
-1, 0, -1):
5522 w
= _div_nearest(M
, k
) - _div_nearest(yshift
*w
, M
)
5524 return _div_nearest(w
*y
, M
)
5526 def _dlog10(c
, e
, p
):
5527 """Given integers c, e and p with c > 0, p >= 0, compute an integer
5528 approximation to 10**p * log10(c*10**e), with an absolute error of
5529 at most 1. Assumes that c*10**e is not exactly 1."""
5531 # increase precision by 2; compensate for this by dividing
5532 # final result by 100
5535 # write c*10**e as d*10**f with either:
5536 # f >= 0 and 1 <= d <= 10, or
5537 # f <= 0 and 0.1 <= d <= 1.
5538 # Thus for c*10**e close to 1, f = 0
5540 f
= e
+l
- (e
+l
>= 1)
5548 c
= _div_nearest(c
, 10**-k
)
5550 log_d
= _ilog(c
, M
) # error < 5 + 22 = 27
5551 log_10
= _log10_digits(p
) # error < 1
5552 log_d
= _div_nearest(log_d
*M
, log_10
)
5553 log_tenpower
= f
*M
# exact
5555 log_d
= 0 # error < 2.31
5556 log_tenpower
= _div_nearest(f
, 10**-p
) # error < 0.5
5558 return _div_nearest(log_tenpower
+log_d
, 100)
5561 """Given integers c, e and p with c > 0, compute an integer
5562 approximation to 10**p * log(c*10**e), with an absolute error of
5563 at most 1. Assumes that c*10**e is not exactly 1."""
5565 # Increase precision by 2. The precision increase is compensated
5566 # for at the end with a division by 100.
5569 # rewrite c*10**e as d*10**f with either f >= 0 and 1 <= d <= 10,
5570 # or f <= 0 and 0.1 <= d <= 1. Then we can compute 10**p * log(c*10**e)
5571 # as 10**p * log(d) + 10**p*f * log(10).
5573 f
= e
+l
- (e
+l
>= 1)
5575 # compute approximation to 10**p*log(d), with error < 27
5581 c
= _div_nearest(c
, 10**-k
) # error of <= 0.5 in c
5583 # _ilog magnifies existing error in c by a factor of at most 10
5584 log_d
= _ilog(c
, 10**p
) # error < 5 + 22 = 27
5586 # p <= 0: just approximate the whole thing by 0; error < 2.31
5589 # compute approximation to f*10**p*log(10), with error < 11.
5591 extra
= len(str(abs(f
)))-1
5593 # error in f * _log10_digits(p+extra) < |f| * 1 = |f|
5594 # after division, error < |f|/10**extra + 0.5 < 10 + 0.5 < 11
5595 f_log_ten
= _div_nearest(f
*_log10_digits(p
+extra
), 10**extra
)
5601 # error in sum < 11+27 = 38; error after division < 0.38 + 0.5 < 1
5602 return _div_nearest(f_log_ten
+ log_d
, 100)
5604 class _Log10Memoize(object):
5605 """Class to compute, store, and allow retrieval of, digits of the
5606 constant log(10) = 2.302585.... This constant is needed by
5607 Decimal.ln, Decimal.log10, Decimal.exp and Decimal.__pow__."""
5609 self
.digits
= "23025850929940456840179914546843642076011014886"
5611 def getdigits(self
, p
):
5612 """Given an integer p >= 0, return floor(10**p)*log(10).
5614 For example, self.getdigits(3) returns 2302.
5616 # digits are stored as a string, for quick conversion to
5617 # integer in the case that we've already computed enough
5618 # digits; the stored digits should always be correct
5619 # (truncated, not rounded to nearest).
5621 raise ValueError("p should be nonnegative")
5623 if p
>= len(self
.digits
):
5624 # compute p+3, p+6, p+9, ... digits; continue until at
5625 # least one of the extra digits is nonzero
5628 # compute p+extra digits, correct to within 1ulp
5630 digits
= str(_div_nearest(_ilog(10*M
, M
), 100))
5631 if digits
[-extra
:] != '0'*extra
:
5634 # keep all reliable digits so far; remove trailing zeros
5635 # and next nonzero digit
5636 self
.digits
= digits
.rstrip('0')[:-1]
5637 return int(self
.digits
[:p
+1])
5639 _log10_digits
= _Log10Memoize().getdigits
5641 def _iexp(x
, M
, L
=8):
5642 """Given integers x and M, M > 0, such that x/M is small in absolute
5643 value, compute an integer approximation to M*exp(x/M). For 0 <=
5644 x/M <= 2.4, the absolute error in the result is bounded by 60 (and
5645 is usually much smaller)."""
5647 # Algorithm: to compute exp(z) for a real number z, first divide z
5648 # by a suitable power R of 2 so that |z/2**R| < 2**-L. Then
5649 # compute expm1(z/2**R) = exp(z/2**R) - 1 using the usual Taylor
5652 # expm1(x) = x + x**2/2! + x**3/3! + ...
5654 # Now use the identity
5656 # expm1(2x) = expm1(x)*(expm1(x)+2)
5658 # R times to compute the sequence expm1(z/2**R),
5659 # expm1(z/2**(R-1)), ... , exp(z/2), exp(z).
5661 # Find R such that x/2**R/M <= 2**-L
5662 R
= _nbits((long(x
)<<L
)//M
)
5664 # Taylor series. (2**L)**T > M
5665 T
= -int(-10*len(str(M
))//(3*L
))
5666 y
= _div_nearest(x
, T
)
5668 for i
in xrange(T
-1, 0, -1):
5669 y
= _div_nearest(x
*(Mshift
+ y
), Mshift
* i
)
5672 for k
in xrange(R
-1, -1, -1):
5673 Mshift
= long(M
)<<(k
+2)
5674 y
= _div_nearest(y
*(y
+Mshift
), Mshift
)
5679 """Compute an approximation to exp(c*10**e), with p decimal places of
5682 Returns integers d, f such that:
5684 10**(p-1) <= d <= 10**p, and
5685 (d-1)*10**f < exp(c*10**e) < (d+1)*10**f
5687 In other words, d*10**f is an approximation to exp(c*10**e) with p
5688 digits of precision, and with an error in d of at most 1. This is
5689 almost, but not quite, the same as the error being < 1ulp: when d
5690 = 10**(p-1) the error could be up to 10 ulp."""
5692 # we'll call iexp with M = 10**(p+2), giving p+3 digits of precision
5695 # compute log(10) with extra precision = adjusted exponent of c*10**e
5696 extra
= max(0, e
+ len(str(c
)) - 1)
5699 # compute quotient c*10**e/(log(10)) = c*10**(e+q)/(log(10)*10**q),
5703 cshift
= c
*10**shift
5705 cshift
= c
//10**-shift
5706 quot
, rem
= divmod(cshift
, _log10_digits(q
))
5708 # reduce remainder back to original precision
5709 rem
= _div_nearest(rem
, 10**extra
)
5711 # error in result of _iexp < 120; error after division < 0.62
5712 return _div_nearest(_iexp(rem
, 10**p
), 1000), quot
- p
+ 3
5714 def _dpower(xc
, xe
, yc
, ye
, p
):
5715 """Given integers xc, xe, yc and ye representing Decimals x = xc*10**xe and
5716 y = yc*10**ye, compute x**y. Returns a pair of integers (c, e) such that:
5718 10**(p-1) <= c <= 10**p, and
5719 (c-1)*10**e < x**y < (c+1)*10**e
5721 in other words, c*10**e is an approximation to x**y with p digits
5722 of precision, and with an error in c of at most 1. (This is
5723 almost, but not quite, the same as the error being < 1ulp: when c
5724 == 10**(p-1) we can only guarantee error < 10ulp.)
5726 We assume that: x is positive and not equal to 1, and y is nonzero.
5729 # Find b such that 10**(b-1) <= |y| <= 10**b
5730 b
= len(str(abs(yc
))) + ye
5732 # log(x) = lxc*10**(-p-b-1), to p+b+1 places after the decimal point
5733 lxc
= _dlog(xc
, xe
, p
+b
+1)
5735 # compute product y*log(x) = yc*lxc*10**(-p-b-1+ye) = pc*10**(-p-1)
5738 pc
= lxc
*yc
*10**shift
5740 pc
= _div_nearest(lxc
*yc
, 10**-shift
)
5743 # we prefer a result that isn't exactly 1; this makes it
5744 # easier to compute a correctly rounded result in __pow__
5745 if ((len(str(xc
)) + xe
>= 1) == (yc
> 0)): # if x**y > 1:
5746 coeff
, exp
= 10**(p
-1)+1, 1-p
5748 coeff
, exp
= 10**p
-1, -p
5750 coeff
, exp
= _dexp(pc
, -(p
+1), p
+1)
5751 coeff
= _div_nearest(coeff
, 10)
5756 def _log10_lb(c
, correction
= {
5757 '1': 100, '2': 70, '3': 53, '4': 40, '5': 31,
5758 '6': 23, '7': 16, '8': 10, '9': 5}):
5759 """Compute a lower bound for 100*log10(c) for a positive integer c."""
5761 raise ValueError("The argument to _log10_lb should be nonnegative.")
5763 return 100*len(str_c
) - correction
[str_c
[0]]
5765 ##### Helper Functions ####################################################
5767 def _convert_other(other
, raiseit
=False, allow_float
=False):
5768 """Convert other to Decimal.
5770 Verifies that it's ok to use in an implicit construction.
5771 If allow_float is true, allow conversion from float; this
5772 is used in the comparison methods (__eq__ and friends).
5775 if isinstance(other
, Decimal
):
5777 if isinstance(other
, (int, long)):
5778 return Decimal(other
)
5779 if allow_float
and isinstance(other
, float):
5780 return Decimal
.from_float(other
)
5783 raise TypeError("Unable to convert %s to Decimal" % other
)
5784 return NotImplemented
5786 ##### Setup Specific Contexts ############################################
5788 # The default context prototype used by Context()
5789 # Is mutable, so that new contexts can have different default values
5791 DefaultContext
= Context(
5792 prec
=28, rounding
=ROUND_HALF_EVEN
,
5793 traps
=[DivisionByZero
, Overflow
, InvalidOperation
],
5800 # Pre-made alternate contexts offered by the specification
5801 # Don't change these; the user should be able to select these
5802 # contexts and be able to reproduce results from other implementations
5805 BasicContext
= Context(
5806 prec
=9, rounding
=ROUND_HALF_UP
,
5807 traps
=[DivisionByZero
, Overflow
, InvalidOperation
, Clamped
, Underflow
],
5811 ExtendedContext
= Context(
5812 prec
=9, rounding
=ROUND_HALF_EVEN
,
5818 ##### crud for parsing strings #############################################
5820 # Regular expression used for parsing numeric strings. Additional
5823 # 1. Uncomment the two '\s*' lines to allow leading and/or trailing
5824 # whitespace. But note that the specification disallows whitespace in
5827 # 2. For finite numbers (not infinities and NaNs) the body of the
5828 # number between the optional sign and the optional exponent must have
5829 # at least one decimal digit, possibly after the decimal point. The
5830 # lookahead expression '(?=\d|\.\d)' checks this.
5833 _parser
= re
.compile(r
""" # A numeric string consists of:
5835 (?P<sign>[-+])? # an optional sign, followed by either...
5837 (?=\d|\.\d) # ...a number (with at least one digit)
5838 (?P<int>\d*) # having a (possibly empty) integer part
5839 (\.(?P<frac>\d*))? # followed by an optional fractional part
5840 (E(?P<exp>[-+]?\d+))? # followed by an optional exponent, or...
5842 Inf(inity)? # ...an infinity, or...
5844 (?P<signal>s)? # ...an (optionally signaling)
5846 (?P<diag>\d*) # with (possibly empty) diagnostic info.
5850 """, re
.VERBOSE | re
.IGNORECASE | re
.UNICODE
).match
5852 _all_zeros
= re
.compile('0*$').match
5853 _exact_half
= re
.compile('50*$').match
5855 ##### PEP3101 support functions ##############################################
5856 # The functions in this section have little to do with the Decimal
5857 # class, and could potentially be reused or adapted for other pure
5858 # Python numeric classes that want to implement __format__
5860 # A format specifier for Decimal looks like:
5862 # [[fill]align][sign][0][minimumwidth][,][.precision][type]
5864 _parse_format_specifier_regex
= re
.compile(r
"""\A
5871 (?P<minimumwidth>(?!0)\d+)?
5872 (?P<thousands_sep>,)?
5873 (?:\.(?P<precision>0|(?!0)\d+))?
5874 (?P<type>[eEfFgGn%])?
5880 # The locale module is only needed for the 'n' format specifier. The
5881 # rest of the PEP 3101 code functions quite happily without it, so we
5882 # don't care too much if locale isn't present.
5884 import locale
as _locale
5888 def _parse_format_specifier(format_spec
, _localeconv
=None):
5889 """Parse and validate a format specifier.
5891 Turns a standard numeric format specifier into a dict, with the
5894 fill: fill character to pad field to minimum width
5895 align: alignment type, either '<', '>', '=' or '^'
5896 sign: either '+', '-' or ' '
5897 minimumwidth: nonnegative integer giving minimum width
5898 zeropad: boolean, indicating whether to pad with zeros
5899 thousands_sep: string to use as thousands separator, or ''
5900 grouping: grouping for thousands separators, in format
5902 decimal_point: string to use for decimal point
5903 precision: nonnegative integer giving precision, or None
5904 type: one of the characters 'eEfFgG%', or None
5905 unicode: boolean (always True for Python 3.x)
5908 m
= _parse_format_specifier_regex
.match(format_spec
)
5910 raise ValueError("Invalid format specifier: " + format_spec
)
5912 # get the dictionary
5913 format_dict
= m
.groupdict()
5915 # zeropad; defaults for fill and alignment. If zero padding
5916 # is requested, the fill and align fields should be absent.
5917 fill
= format_dict
['fill']
5918 align
= format_dict
['align']
5919 format_dict
['zeropad'] = (format_dict
['zeropad'] is not None)
5920 if format_dict
['zeropad']:
5921 if fill
is not None:
5922 raise ValueError("Fill character conflicts with '0'"
5923 " in format specifier: " + format_spec
)
5924 if align
is not None:
5925 raise ValueError("Alignment conflicts with '0' in "
5926 "format specifier: " + format_spec
)
5927 format_dict
['fill'] = fill
or ' '
5928 # PEP 3101 originally specified that the default alignment should
5929 # be left; it was later agreed that right-aligned makes more sense
5930 # for numeric types. See http://bugs.python.org/issue6857.
5931 format_dict
['align'] = align
or '>'
5933 # default sign handling: '-' for negative, '' for positive
5934 if format_dict
['sign'] is None:
5935 format_dict
['sign'] = '-'
5937 # minimumwidth defaults to 0; precision remains None if not given
5938 format_dict
['minimumwidth'] = int(format_dict
['minimumwidth'] or '0')
5939 if format_dict
['precision'] is not None:
5940 format_dict
['precision'] = int(format_dict
['precision'])
5942 # if format type is 'g' or 'G' then a precision of 0 makes little
5943 # sense; convert it to 1. Same if format type is unspecified.
5944 if format_dict
['precision'] == 0:
5945 if format_dict
['type'] is None or format_dict
['type'] in 'gG':
5946 format_dict
['precision'] = 1
5948 # determine thousands separator, grouping, and decimal separator, and
5949 # add appropriate entries to format_dict
5950 if format_dict
['type'] == 'n':
5951 # apart from separators, 'n' behaves just like 'g'
5952 format_dict
['type'] = 'g'
5953 if _localeconv
is None:
5954 _localeconv
= _locale
.localeconv()
5955 if format_dict
['thousands_sep'] is not None:
5956 raise ValueError("Explicit thousands separator conflicts with "
5957 "'n' type in format specifier: " + format_spec
)
5958 format_dict
['thousands_sep'] = _localeconv
['thousands_sep']
5959 format_dict
['grouping'] = _localeconv
['grouping']
5960 format_dict
['decimal_point'] = _localeconv
['decimal_point']
5962 if format_dict
['thousands_sep'] is None:
5963 format_dict
['thousands_sep'] = ''
5964 format_dict
['grouping'] = [3, 0]
5965 format_dict
['decimal_point'] = '.'
5967 # record whether return type should be str or unicode
5968 format_dict
['unicode'] = isinstance(format_spec
, unicode)
5972 def _format_align(sign
, body
, spec
):
5973 """Given an unpadded, non-aligned numeric string 'body' and sign
5974 string 'sign', add padding and aligment conforming to the given
5975 format specifier dictionary 'spec' (as produced by
5976 parse_format_specifier).
5978 Also converts result to unicode if necessary.
5981 # how much extra space do we have to play with?
5982 minimumwidth
= spec
['minimumwidth']
5984 padding
= fill
*(minimumwidth
- len(sign
) - len(body
))
5986 align
= spec
['align']
5988 result
= sign
+ body
+ padding
5990 result
= padding
+ sign
+ body
5992 result
= sign
+ padding
+ body
5994 half
= len(padding
)//2
5995 result
= padding
[:half
] + sign
+ body
+ padding
[half
:]
5997 raise ValueError('Unrecognised alignment field')
5999 # make sure that result is unicode if necessary
6001 result
= unicode(result
)
6005 def _group_lengths(grouping
):
6006 """Convert a localeconv-style grouping into a (possibly infinite)
6007 iterable of integers representing group lengths.
6010 # The result from localeconv()['grouping'], and the input to this
6011 # function, should be a list of integers in one of the
6012 # following three forms:
6014 # (1) an empty list, or
6015 # (2) nonempty list of positive integers + [0]
6016 # (3) list of positive integers + [locale.CHAR_MAX], or
6018 from itertools
import chain
, repeat
6021 elif grouping
[-1] == 0 and len(grouping
) >= 2:
6022 return chain(grouping
[:-1], repeat(grouping
[-2]))
6023 elif grouping
[-1] == _locale
.CHAR_MAX
:
6024 return grouping
[:-1]
6026 raise ValueError('unrecognised format for grouping')
6028 def _insert_thousands_sep(digits
, spec
, min_width
=1):
6029 """Insert thousands separators into a digit string.
6031 spec is a dictionary whose keys should include 'thousands_sep' and
6032 'grouping'; typically it's the result of parsing the format
6033 specifier using _parse_format_specifier.
6035 The min_width keyword argument gives the minimum length of the
6036 result, which will be padded on the left with zeros if necessary.
6038 If necessary, the zero padding adds an extra '0' on the left to
6039 avoid a leading thousands separator. For example, inserting
6040 commas every three digits in '123456', with min_width=8, gives
6041 '0,123,456', even though that has length 9.
6045 sep
= spec
['thousands_sep']
6046 grouping
= spec
['grouping']
6049 for l
in _group_lengths(grouping
):
6051 raise ValueError("group length should be positive")
6052 # max(..., 1) forces at least 1 digit to the left of a separator
6053 l
= min(max(len(digits
), min_width
, 1), l
)
6054 groups
.append('0'*(l
- len(digits
)) + digits
[-l
:])
6055 digits
= digits
[:-l
]
6057 if not digits
and min_width
<= 0:
6059 min_width
-= len(sep
)
6061 l
= max(len(digits
), min_width
, 1)
6062 groups
.append('0'*(l
- len(digits
)) + digits
[-l
:])
6063 return sep
.join(reversed(groups
))
6065 def _format_sign(is_negative
, spec
):
6066 """Determine sign character."""
6070 elif spec
['sign'] in ' +':
6075 def _format_number(is_negative
, intpart
, fracpart
, exp
, spec
):
6076 """Format a number, given the following data:
6078 is_negative: true if the number is negative, else false
6079 intpart: string of digits that must appear before the decimal point
6080 fracpart: string of digits that must come after the point
6081 exp: exponent, as an integer
6082 spec: dictionary resulting from parsing the format specifier
6084 This function uses the information in spec to:
6085 insert separators (decimal separator and thousands separators)
6088 add trailing '%' for the '%' type
6089 zero-pad if necessary
6090 fill and align if necessary
6093 sign
= _format_sign(is_negative
, spec
)
6096 fracpart
= spec
['decimal_point'] + fracpart
6098 if exp
!= 0 or spec
['type'] in 'eE':
6099 echar
= {'E': 'E', 'e': 'e', 'G': 'E', 'g': 'e'}[spec
['type']]
6100 fracpart
+= "{0}{1:+}".format(echar
, exp
)
6101 if spec
['type'] == '%':
6105 min_width
= spec
['minimumwidth'] - len(fracpart
) - len(sign
)
6108 intpart
= _insert_thousands_sep(intpart
, spec
, min_width
)
6110 return _format_align(sign
, intpart
+fracpart
, spec
)
6113 ##### Useful Constants (internal use only) ################################
6116 _Infinity
= Decimal('Inf')
6117 _NegativeInfinity
= Decimal('-Inf')
6118 _NaN
= Decimal('NaN')
6121 _NegativeOne
= Decimal(-1)
6123 # _SignedInfinity[sign] is infinity w/ that sign
6124 _SignedInfinity
= (_Infinity
, _NegativeInfinity
)
6128 if __name__
== '__main__':
6130 doctest
.testmod(sys
.modules
[__name__
])