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'
141 from collections
import namedtuple
as _namedtuple
142 DecimalTuple
= _namedtuple('DecimalTuple', 'sign digits exponent')
144 DecimalTuple
= lambda *args
: args
147 ROUND_DOWN
= 'ROUND_DOWN'
148 ROUND_HALF_UP
= 'ROUND_HALF_UP'
149 ROUND_HALF_EVEN
= 'ROUND_HALF_EVEN'
150 ROUND_CEILING
= 'ROUND_CEILING'
151 ROUND_FLOOR
= 'ROUND_FLOOR'
152 ROUND_UP
= 'ROUND_UP'
153 ROUND_HALF_DOWN
= 'ROUND_HALF_DOWN'
154 ROUND_05UP
= 'ROUND_05UP'
158 class DecimalException(ArithmeticError):
159 """Base exception class.
161 Used exceptions derive from this.
162 If an exception derives from another exception besides this (such as
163 Underflow (Inexact, Rounded, Subnormal) that indicates that it is only
164 called if the others are present. This isn't actually used for
167 handle -- Called when context._raise_error is called and the
168 trap_enabler is set. First argument is self, second is the
169 context. More arguments can be given, those being after
170 the explanation in _raise_error (For example,
171 context._raise_error(NewError, '(-x)!', self._sign) would
172 call NewError().handle(context, self._sign).)
174 To define a new exception, it should be sufficient to have it derive
175 from DecimalException.
177 def handle(self
, context
, *args
):
181 class Clamped(DecimalException
):
182 """Exponent of a 0 changed to fit bounds.
184 This occurs and signals clamped if the exponent of a result has been
185 altered in order to fit the constraints of a specific concrete
186 representation. This may occur when the exponent of a zero result would
187 be outside the bounds of a representation, or when a large normal
188 number would have an encoded exponent that cannot be represented. In
189 this latter case, the exponent is reduced to fit and the corresponding
190 number of zero digits are appended to the coefficient ("fold-down").
193 class InvalidOperation(DecimalException
):
194 """An invalid operation was performed.
196 Various bad things cause this:
198 Something creates a signaling NaN
204 x._rescale( non-integer )
209 An operand is invalid
211 The result of the operation after these is a quiet positive NaN,
212 except when the cause is a signaling NaN, in which case the result is
213 also a quiet NaN, but with the original sign, and an optional
214 diagnostic information.
216 def handle(self
, context
, *args
):
218 ans
= _dec_from_triple(args
[0]._sign
, args
[0]._int
, 'n', True)
219 return ans
._fix
_nan
(context
)
222 class ConversionSyntax(InvalidOperation
):
223 """Trying to convert badly formed string.
225 This occurs and signals invalid-operation if an string is being
226 converted to a number and it does not conform to the numeric string
227 syntax. The result is [0,qNaN].
229 def handle(self
, context
, *args
):
232 class DivisionByZero(DecimalException
, ZeroDivisionError):
235 This occurs and signals division-by-zero if division of a finite number
236 by zero was attempted (during a divide-integer or divide operation, or a
237 power operation with negative right-hand operand), and the dividend was
240 The result of the operation is [sign,inf], where sign is the exclusive
241 or of the signs of the operands for divide, or is 1 for an odd power of
245 def handle(self
, context
, sign
, *args
):
246 return _SignedInfinity
[sign
]
248 class DivisionImpossible(InvalidOperation
):
249 """Cannot perform the division adequately.
251 This occurs and signals invalid-operation if the integer result of a
252 divide-integer or remainder operation had too many digits (would be
253 longer than precision). The result is [0,qNaN].
256 def handle(self
, context
, *args
):
259 class DivisionUndefined(InvalidOperation
, ZeroDivisionError):
260 """Undefined result of division.
262 This occurs and signals invalid-operation if division by zero was
263 attempted (during a divide-integer, divide, or remainder operation), and
264 the dividend is also zero. The result is [0,qNaN].
267 def handle(self
, context
, *args
):
270 class Inexact(DecimalException
):
271 """Had to round, losing information.
273 This occurs and signals inexact whenever the result of an operation is
274 not exact (that is, it needed to be rounded and any discarded digits
275 were non-zero), or if an overflow or underflow condition occurs. The
276 result in all cases is unchanged.
278 The inexact signal may be tested (or trapped) to determine if a given
279 operation (or sequence of operations) was inexact.
282 class InvalidContext(InvalidOperation
):
283 """Invalid context. Unknown rounding, for example.
285 This occurs and signals invalid-operation if an invalid context was
286 detected during an operation. This can occur if contexts are not checked
287 on creation and either the precision exceeds the capability of the
288 underlying concrete representation or an unknown or unsupported rounding
289 was specified. These aspects of the context need only be checked when
290 the values are required to be used. The result is [0,qNaN].
293 def handle(self
, context
, *args
):
296 class Rounded(DecimalException
):
297 """Number got rounded (not necessarily changed during rounding).
299 This occurs and signals rounded whenever the result of an operation is
300 rounded (that is, some zero or non-zero digits were discarded from the
301 coefficient), or if an overflow or underflow condition occurs. The
302 result in all cases is unchanged.
304 The rounded signal may be tested (or trapped) to determine if a given
305 operation (or sequence of operations) caused a loss of precision.
308 class Subnormal(DecimalException
):
309 """Exponent < Emin before rounding.
311 This occurs and signals subnormal whenever the result of a conversion or
312 operation is subnormal (that is, its adjusted exponent is less than
313 Emin, before any rounding). The result in all cases is unchanged.
315 The subnormal signal may be tested (or trapped) to determine if a given
316 or operation (or sequence of operations) yielded a subnormal result.
319 class Overflow(Inexact
, Rounded
):
320 """Numerical overflow.
322 This occurs and signals overflow if the adjusted exponent of a result
323 (from a conversion or from an operation that is not an attempt to divide
324 by zero), after rounding, would be greater than the largest value that
325 can be handled by the implementation (the value Emax).
327 The result depends on the rounding mode:
329 For round-half-up and round-half-even (and for round-half-down and
330 round-up, if implemented), the result of the operation is [sign,inf],
331 where sign is the sign of the intermediate result. For round-down, the
332 result is the largest finite number that can be represented in the
333 current precision, with the sign of the intermediate result. For
334 round-ceiling, the result is the same as for round-down if the sign of
335 the intermediate result is 1, or is [0,inf] otherwise. For round-floor,
336 the result is the same as for round-down if the sign of the intermediate
337 result is 0, or is [1,inf] otherwise. In all cases, Inexact and Rounded
341 def handle(self
, context
, sign
, *args
):
342 if context
.rounding
in (ROUND_HALF_UP
, ROUND_HALF_EVEN
,
343 ROUND_HALF_DOWN
, ROUND_UP
):
344 return _SignedInfinity
[sign
]
346 if context
.rounding
== ROUND_CEILING
:
347 return _SignedInfinity
[sign
]
348 return _dec_from_triple(sign
, '9'*context
.prec
,
349 context
.Emax
-context
.prec
+1)
351 if context
.rounding
== ROUND_FLOOR
:
352 return _SignedInfinity
[sign
]
353 return _dec_from_triple(sign
, '9'*context
.prec
,
354 context
.Emax
-context
.prec
+1)
357 class Underflow(Inexact
, Rounded
, Subnormal
):
358 """Numerical underflow with result rounded to 0.
360 This occurs and signals underflow if a result is inexact and the
361 adjusted exponent of the result would be smaller (more negative) than
362 the smallest value that can be handled by the implementation (the value
363 Emin). That is, the result is both inexact and subnormal.
365 The result after an underflow will be a subnormal number rounded, if
366 necessary, so that its exponent is not less than Etiny. This may result
367 in 0 with the sign of the intermediate result and an exponent of Etiny.
369 In all cases, Inexact, Rounded, and Subnormal will also be raised.
372 # List of public traps and flags
373 _signals
= [Clamped
, DivisionByZero
, Inexact
, Overflow
, Rounded
,
374 Underflow
, InvalidOperation
, Subnormal
]
376 # Map conditions (per the spec) to signals
377 _condition_map
= {ConversionSyntax
:InvalidOperation
,
378 DivisionImpossible
:InvalidOperation
,
379 DivisionUndefined
:InvalidOperation
,
380 InvalidContext
:InvalidOperation
}
382 ##### Context Functions ##################################################
384 # The getcontext() and setcontext() function manage access to a thread-local
385 # current context. Py2.4 offers direct support for thread locals. If that
386 # is not available, use threading.currentThread() which is slower but will
387 # work for older Pythons. If threads are not part of the build, create a
388 # mock threading object with threading.local() returning the module namespace.
393 # Python was compiled without threads; create a mock object instead
395 class MockThreading(object):
396 def local(self
, sys
=sys
):
397 return sys
.modules
[__name__
]
398 threading
= MockThreading()
399 del sys
, MockThreading
404 except AttributeError:
406 # To fix reloading, force it to create a new context
407 # Old contexts have different exceptions in their dicts, making problems.
408 if hasattr(threading
.currentThread(), '__decimal_context__'):
409 del threading
.currentThread().__decimal
_context
__
411 def setcontext(context
):
412 """Set this thread's context to context."""
413 if context
in (DefaultContext
, BasicContext
, ExtendedContext
):
414 context
= context
.copy()
415 context
.clear_flags()
416 threading
.currentThread().__decimal
_context
__ = context
419 """Returns this thread's context.
421 If this thread does not yet have a context, returns
422 a new context and sets this thread's context.
423 New contexts are copies of DefaultContext.
426 return threading
.currentThread().__decimal
_context
__
427 except AttributeError:
429 threading
.currentThread().__decimal
_context
__ = context
434 local
= threading
.local()
435 if hasattr(local
, '__decimal_context__'):
436 del local
.__decimal
_context
__
438 def getcontext(_local
=local
):
439 """Returns this thread's context.
441 If this thread does not yet have a context, returns
442 a new context and sets this thread's context.
443 New contexts are copies of DefaultContext.
446 return _local
.__decimal
_context
__
447 except AttributeError:
449 _local
.__decimal
_context
__ = context
452 def setcontext(context
, _local
=local
):
453 """Set this thread's context to context."""
454 if context
in (DefaultContext
, BasicContext
, ExtendedContext
):
455 context
= context
.copy()
456 context
.clear_flags()
457 _local
.__decimal
_context
__ = context
459 del threading
, local
# Don't contaminate the namespace
461 def localcontext(ctx
=None):
462 """Return a context manager for a copy of the supplied context
464 Uses a copy of the current context if no context is specified
465 The returned context manager creates a local decimal context
468 with localcontext() as ctx:
470 # Rest of sin calculation algorithm
471 # uses a precision 2 greater than normal
472 return +s # Convert result to normal precision
475 with localcontext(ExtendedContext):
476 # Rest of sin calculation algorithm
477 # uses the Extended Context from the
478 # General Decimal Arithmetic Specification
479 return +s # Convert result to normal context
481 >>> setcontext(DefaultContext)
482 >>> print getcontext().prec
484 >>> with localcontext():
485 ... ctx = getcontext()
490 >>> with localcontext(ExtendedContext):
491 ... print getcontext().prec
494 >>> print getcontext().prec
497 if ctx
is None: ctx
= getcontext()
498 return _ContextManager(ctx
)
501 ##### Decimal class #######################################################
503 class Decimal(object):
504 """Floating point class for decimal arithmetic."""
506 __slots__
= ('_exp','_int','_sign', '_is_special')
507 # Generally, the value of the Decimal instance is given by
508 # (-1)**_sign * _int * 10**_exp
509 # Special values are signified by _is_special == True
511 # We're immutable, so use __new__ not __init__
512 def __new__(cls
, value
="0", context
=None):
513 """Create a decimal point instance.
515 >>> Decimal('3.14') # string input
517 >>> Decimal((0, (3, 1, 4), -2)) # tuple (sign, digit_tuple, exponent)
519 >>> Decimal(314) # int or long
521 >>> Decimal(Decimal(314)) # another decimal instance
523 >>> Decimal(' 3.14 \\n') # leading and trailing whitespace okay
527 # Note that the coefficient, self._int, is actually stored as
528 # a string rather than as a tuple of digits. This speeds up
529 # the "digits to integer" and "integer to digits" conversions
530 # that are used in almost every arithmetic operation on
531 # Decimals. This is an internal detail: the as_tuple function
532 # and the Decimal constructor still deal with tuples of
535 self
= object.__new
__(cls
)
538 # REs insist on real strings, so we can too.
539 if isinstance(value
, basestring
):
540 m
= _parser(value
.strip())
543 context
= getcontext()
544 return context
._raise
_error
(ConversionSyntax
,
545 "Invalid literal for Decimal: %r" % value
)
547 if m
.group('sign') == "-":
551 intpart
= m
.group('int')
552 if intpart
is not None:
554 fracpart
= m
.group('frac')
555 exp
= int(m
.group('exp') or '0')
556 if fracpart
is not None:
557 self
._int
= str((intpart
+fracpart
).lstrip('0') or '0')
558 self
._exp
= exp
- len(fracpart
)
560 self
._int
= str(intpart
.lstrip('0') or '0')
562 self
._is
_special
= False
564 diag
= m
.group('diag')
567 self
._int
= str(diag
.lstrip('0'))
568 if m
.group('signal'):
576 self
._is
_special
= True
580 if isinstance(value
, (int,long)):
586 self
._int
= str(abs(value
))
587 self
._is
_special
= False
590 # From another decimal
591 if isinstance(value
, Decimal
):
592 self
._exp
= value
._exp
593 self
._sign
= value
._sign
594 self
._int
= value
._int
595 self
._is
_special
= value
._is
_special
598 # From an internal working value
599 if isinstance(value
, _WorkRep
):
600 self
._sign
= value
.sign
601 self
._int
= str(value
.int)
602 self
._exp
= int(value
.exp
)
603 self
._is
_special
= False
606 # tuple/list conversion (possibly from as_tuple())
607 if isinstance(value
, (list,tuple)):
609 raise ValueError('Invalid tuple size in creation of Decimal '
610 'from list or tuple. The list or tuple '
611 'should have exactly three elements.')
612 # process sign. The isinstance test rejects floats
613 if not (isinstance(value
[0], (int, long)) and value
[0] in (0,1)):
614 raise ValueError("Invalid sign. The first value in the tuple "
615 "should be an integer; either 0 for a "
616 "positive number or 1 for a negative number.")
617 self
._sign
= value
[0]
619 # infinity: value[1] is ignored
622 self
._is
_special
= True
624 # process and validate the digits in value[1]
626 for digit
in value
[1]:
627 if isinstance(digit
, (int, long)) and 0 <= digit
<= 9:
629 if digits
or digit
!= 0:
632 raise ValueError("The second value in the tuple must "
633 "be composed of integers in the range "
635 if value
[2] in ('n', 'N'):
636 # NaN: digits form the diagnostic
637 self
._int
= ''.join(map(str, digits
))
639 self
._is
_special
= True
640 elif isinstance(value
[2], (int, long)):
641 # finite number: digits give the coefficient
642 self
._int
= ''.join(map(str, digits
or [0]))
644 self
._is
_special
= False
646 raise ValueError("The third value in the tuple must "
647 "be an integer, or one of the "
648 "strings 'F', 'n', 'N'.")
651 if isinstance(value
, float):
652 raise TypeError("Cannot convert float to Decimal. " +
653 "First convert the float to a string")
655 raise TypeError("Cannot convert %r to Decimal" % value
)
657 # @classmethod, but @decorator is not valid Python 2.3 syntax, so
658 # don't use it (see notes on Py2.3 compatibility at top of file)
659 def from_float(cls
, f
):
660 """Converts a float to a decimal number, exactly.
662 Note that Decimal.from_float(0.1) is not the same as Decimal('0.1').
663 Since 0.1 is not exactly representable in binary floating point, the
664 value is stored as the nearest representable value which is
665 0x1.999999999999ap-4. The exact equivalent of the value in decimal
666 is 0.1000000000000000055511151231257827021181583404541015625.
668 >>> Decimal.from_float(0.1)
669 Decimal('0.1000000000000000055511151231257827021181583404541015625')
670 >>> Decimal.from_float(float('nan'))
672 >>> Decimal.from_float(float('inf'))
674 >>> Decimal.from_float(-float('inf'))
676 >>> Decimal.from_float(-0.0)
680 if isinstance(f
, (int, long)): # handle integer inputs
682 if _math
.isinf(f
) or _math
.isnan(f
): # raises TypeError if not a float
684 if _math
.copysign(1.0, f
) == 1.0:
688 n
, d
= abs(f
).as_integer_ratio()
689 k
= d
.bit_length() - 1
690 result
= _dec_from_triple(sign
, str(n
*5**k
), -k
)
695 from_float
= classmethod(from_float
)
698 """Returns whether the number is not actually one.
712 def _isinfinity(self
):
713 """Returns whether the number is infinite
715 0 if finite or not a number
725 def _check_nans(self
, other
=None, context
=None):
726 """Returns whether the number is not actually one.
728 if self, other are sNaN, signal
729 if self, other are NaN return nan
732 Done before operations.
735 self_is_nan
= self
._isnan
()
739 other_is_nan
= other
._isnan
()
741 if self_is_nan
or other_is_nan
:
743 context
= getcontext()
746 return context
._raise
_error
(InvalidOperation
, 'sNaN',
748 if other_is_nan
== 2:
749 return context
._raise
_error
(InvalidOperation
, 'sNaN',
752 return self
._fix
_nan
(context
)
754 return other
._fix
_nan
(context
)
757 def _compare_check_nans(self
, other
, context
):
758 """Version of _check_nans used for the signaling comparisons
759 compare_signal, __le__, __lt__, __ge__, __gt__.
761 Signal InvalidOperation if either self or other is a (quiet
762 or signaling) NaN. Signaling NaNs take precedence over quiet
765 Return 0 if neither operand is a NaN.
769 context
= getcontext()
771 if self
._is
_special
or other
._is
_special
:
773 return context
._raise
_error
(InvalidOperation
,
774 'comparison involving sNaN',
776 elif other
.is_snan():
777 return context
._raise
_error
(InvalidOperation
,
778 'comparison involving sNaN',
781 return context
._raise
_error
(InvalidOperation
,
782 'comparison involving NaN',
784 elif other
.is_qnan():
785 return context
._raise
_error
(InvalidOperation
,
786 'comparison involving NaN',
790 def __nonzero__(self
):
791 """Return True if self is nonzero; otherwise return False.
793 NaNs and infinities are considered nonzero.
795 return self
._is
_special
or self
._int
!= '0'
797 def _cmp(self
, other
):
798 """Compare the two non-NaN decimal instances self and other.
800 Returns -1 if self < other, 0 if self == other and 1
801 if self > other. This routine is for internal use only."""
803 if self
._is
_special
or other
._is
_special
:
804 self_inf
= self
._isinfinity
()
805 other_inf
= other
._isinfinity
()
806 if self_inf
== other_inf
:
808 elif self_inf
< other_inf
:
813 # check for zeros; Decimal('0') == Decimal('-0')
818 return -((-1)**other
._sign
)
820 return (-1)**self
._sign
822 # If different signs, neg one is less
823 if other
._sign
< self
._sign
:
825 if self
._sign
< other
._sign
:
828 self_adjusted
= self
.adjusted()
829 other_adjusted
= other
.adjusted()
830 if self_adjusted
== other_adjusted
:
831 self_padded
= self
._int
+ '0'*(self
._exp
- other
._exp
)
832 other_padded
= other
._int
+ '0'*(other
._exp
- self
._exp
)
833 if self_padded
== other_padded
:
835 elif self_padded
< other_padded
:
836 return -(-1)**self
._sign
838 return (-1)**self
._sign
839 elif self_adjusted
> other_adjusted
:
840 return (-1)**self
._sign
841 else: # self_adjusted < other_adjusted
842 return -((-1)**self
._sign
)
844 # Note: The Decimal standard doesn't cover rich comparisons for
845 # Decimals. In particular, the specification is silent on the
846 # subject of what should happen for a comparison involving a NaN.
847 # We take the following approach:
849 # == comparisons involving a NaN always return False
850 # != comparisons involving a NaN always return True
851 # <, >, <= and >= comparisons involving a (quiet or signaling)
852 # NaN signal InvalidOperation, and return False if the
853 # InvalidOperation is not trapped.
855 # This behavior is designed to conform as closely as possible to
856 # that specified by IEEE 754.
858 def __eq__(self
, other
):
859 other
= _convert_other(other
)
860 if other
is NotImplemented:
862 if self
.is_nan() or other
.is_nan():
864 return self
._cmp
(other
) == 0
866 def __ne__(self
, other
):
867 other
= _convert_other(other
)
868 if other
is NotImplemented:
870 if self
.is_nan() or other
.is_nan():
872 return self
._cmp
(other
) != 0
874 def __lt__(self
, other
, context
=None):
875 other
= _convert_other(other
)
876 if other
is NotImplemented:
878 ans
= self
._compare
_check
_nans
(other
, context
)
881 return self
._cmp
(other
) < 0
883 def __le__(self
, other
, context
=None):
884 other
= _convert_other(other
)
885 if other
is NotImplemented:
887 ans
= self
._compare
_check
_nans
(other
, context
)
890 return self
._cmp
(other
) <= 0
892 def __gt__(self
, other
, context
=None):
893 other
= _convert_other(other
)
894 if other
is NotImplemented:
896 ans
= self
._compare
_check
_nans
(other
, context
)
899 return self
._cmp
(other
) > 0
901 def __ge__(self
, other
, context
=None):
902 other
= _convert_other(other
)
903 if other
is NotImplemented:
905 ans
= self
._compare
_check
_nans
(other
, context
)
908 return self
._cmp
(other
) >= 0
910 def compare(self
, other
, context
=None):
911 """Compares one to another.
917 Like __cmp__, but returns Decimal instances.
919 other
= _convert_other(other
, raiseit
=True)
921 # Compare(NaN, NaN) = NaN
922 if (self
._is
_special
or other
and other
._is
_special
):
923 ans
= self
._check
_nans
(other
, context
)
927 return Decimal(self
._cmp
(other
))
930 """x.__hash__() <==> hash(x)"""
931 # Decimal integers must hash the same as the ints
933 # The hash of a nonspecial noninteger Decimal must depend only
934 # on the value of that Decimal, and not on its representation.
935 # For example: hash(Decimal('100E-1')) == hash(Decimal('10')).
938 raise TypeError('Cannot hash a NaN value.')
939 return hash(str(self
))
942 if self
._isinteger
():
943 op
= _WorkRep(self
.to_integral_value())
944 # to make computation feasible for Decimals with large
945 # exponent, we use the fact that hash(n) == hash(m) for
946 # any two nonzero integers n and m such that (i) n and m
947 # have the same sign, and (ii) n is congruent to m modulo
948 # 2**64-1. So we can replace hash((-1)**s*c*10**e) with
949 # hash((-1)**s*c*pow(10, e, 2**64-1).
950 return hash((-1)**op
.sign
*op
.int*pow(10, op
.exp
, 2**64-1))
951 # The value of a nonzero nonspecial Decimal instance is
952 # faithfully represented by the triple consisting of its sign,
953 # its adjusted exponent, and its coefficient with trailing
955 return hash((self
._sign
,
956 self
._exp
+len(self
._int
),
957 self
._int
.rstrip('0')))
960 """Represents the number as a triple tuple.
962 To show the internals exactly as they are.
964 return DecimalTuple(self
._sign
, tuple(map(int, self
._int
)), self
._exp
)
967 """Represents the number as an instance of Decimal."""
968 # Invariant: eval(repr(d)) == d
969 return "Decimal('%s')" % str(self
)
971 def __str__(self
, eng
=False, context
=None):
972 """Return string representation of the number in scientific notation.
974 Captures all of the information in the underlying representation.
977 sign
= ['', '-'][self
._sign
]
980 return sign
+ 'Infinity'
981 elif self
._exp
== 'n':
982 return sign
+ 'NaN' + self
._int
983 else: # self._exp == 'N'
984 return sign
+ 'sNaN' + self
._int
986 # number of digits of self._int to left of decimal point
987 leftdigits
= self
._exp
+ len(self
._int
)
989 # dotplace is number of digits of self._int to the left of the
990 # decimal point in the mantissa of the output string (that is,
991 # after adjusting the exponent)
992 if self
._exp
<= 0 and leftdigits
> -6:
993 # no exponent required
994 dotplace
= leftdigits
996 # usual scientific notation: 1 digit on left of the point
998 elif self
._int
== '0':
999 # engineering notation, zero
1000 dotplace
= (leftdigits
+ 1) % 3 - 1
1002 # engineering notation, nonzero
1003 dotplace
= (leftdigits
- 1) % 3 + 1
1007 fracpart
= '.' + '0'*(-dotplace
) + self
._int
1008 elif dotplace
>= len(self
._int
):
1009 intpart
= self
._int
+'0'*(dotplace
-len(self
._int
))
1012 intpart
= self
._int
[:dotplace
]
1013 fracpart
= '.' + self
._int
[dotplace
:]
1014 if leftdigits
== dotplace
:
1018 context
= getcontext()
1019 exp
= ['e', 'E'][context
.capitals
] + "%+d" % (leftdigits
-dotplace
)
1021 return sign
+ intpart
+ fracpart
+ exp
1023 def to_eng_string(self
, context
=None):
1024 """Convert to engineering-type string.
1026 Engineering notation has an exponent which is a multiple of 3, so there
1027 are up to 3 digits left of the decimal place.
1029 Same rules for when in exponential and when as a value as in __str__.
1031 return self
.__str
__(eng
=True, context
=context
)
1033 def __neg__(self
, context
=None):
1034 """Returns a copy with the sign switched.
1036 Rounds, if it has reason.
1038 if self
._is
_special
:
1039 ans
= self
._check
_nans
(context
=context
)
1044 # -Decimal('0') is Decimal('0'), not Decimal('-0')
1045 ans
= self
.copy_abs()
1047 ans
= self
.copy_negate()
1050 context
= getcontext()
1051 return ans
._fix
(context
)
1053 def __pos__(self
, context
=None):
1054 """Returns a copy, unless it is a sNaN.
1056 Rounds the number (if more then precision digits)
1058 if self
._is
_special
:
1059 ans
= self
._check
_nans
(context
=context
)
1065 ans
= self
.copy_abs()
1070 context
= getcontext()
1071 return ans
._fix
(context
)
1073 def __abs__(self
, round=True, context
=None):
1074 """Returns the absolute value of self.
1076 If the keyword argument 'round' is false, do not round. The
1077 expression self.__abs__(round=False) is equivalent to
1081 return self
.copy_abs()
1083 if self
._is
_special
:
1084 ans
= self
._check
_nans
(context
=context
)
1089 ans
= self
.__neg
__(context
=context
)
1091 ans
= self
.__pos
__(context
=context
)
1095 def __add__(self
, other
, context
=None):
1096 """Returns self + other.
1098 -INF + INF (or the reverse) cause InvalidOperation errors.
1100 other
= _convert_other(other
)
1101 if other
is NotImplemented:
1105 context
= getcontext()
1107 if self
._is
_special
or other
._is
_special
:
1108 ans
= self
._check
_nans
(other
, context
)
1112 if self
._isinfinity
():
1113 # If both INF, same sign => same as both, opposite => error.
1114 if self
._sign
!= other
._sign
and other
._isinfinity
():
1115 return context
._raise
_error
(InvalidOperation
, '-INF + INF')
1116 return Decimal(self
)
1117 if other
._isinfinity
():
1118 return Decimal(other
) # Can't both be infinity here
1120 exp
= min(self
._exp
, other
._exp
)
1122 if context
.rounding
== ROUND_FLOOR
and self
._sign
!= other
._sign
:
1123 # If the answer is 0, the sign should be negative, in this case.
1126 if not self
and not other
:
1127 sign
= min(self
._sign
, other
._sign
)
1130 ans
= _dec_from_triple(sign
, '0', exp
)
1131 ans
= ans
._fix
(context
)
1134 exp
= max(exp
, other
._exp
- context
.prec
-1)
1135 ans
= other
._rescale
(exp
, context
.rounding
)
1136 ans
= ans
._fix
(context
)
1139 exp
= max(exp
, self
._exp
- context
.prec
-1)
1140 ans
= self
._rescale
(exp
, context
.rounding
)
1141 ans
= ans
._fix
(context
)
1144 op1
= _WorkRep(self
)
1145 op2
= _WorkRep(other
)
1146 op1
, op2
= _normalize(op1
, op2
, context
.prec
)
1149 if op1
.sign
!= op2
.sign
:
1150 # Equal and opposite
1151 if op1
.int == op2
.int:
1152 ans
= _dec_from_triple(negativezero
, '0', exp
)
1153 ans
= ans
._fix
(context
)
1155 if op1
.int < op2
.int:
1157 # OK, now abs(op1) > abs(op2)
1160 op1
.sign
, op2
.sign
= op2
.sign
, op1
.sign
1163 # So we know the sign, and op1 > 0.
1166 op1
.sign
, op2
.sign
= (0, 0)
1169 # Now, op1 > abs(op2) > 0
1172 result
.int = op1
.int + op2
.int
1174 result
.int = op1
.int - op2
.int
1176 result
.exp
= op1
.exp
1177 ans
= Decimal(result
)
1178 ans
= ans
._fix
(context
)
1183 def __sub__(self
, other
, context
=None):
1184 """Return self - other"""
1185 other
= _convert_other(other
)
1186 if other
is NotImplemented:
1189 if self
._is
_special
or other
._is
_special
:
1190 ans
= self
._check
_nans
(other
, context
=context
)
1194 # self - other is computed as self + other.copy_negate()
1195 return self
.__add
__(other
.copy_negate(), context
=context
)
1197 def __rsub__(self
, other
, context
=None):
1198 """Return other - self"""
1199 other
= _convert_other(other
)
1200 if other
is NotImplemented:
1203 return other
.__sub
__(self
, context
=context
)
1205 def __mul__(self
, other
, context
=None):
1206 """Return self * other.
1208 (+-) INF * 0 (or its reverse) raise InvalidOperation.
1210 other
= _convert_other(other
)
1211 if other
is NotImplemented:
1215 context
= getcontext()
1217 resultsign
= self
._sign ^ other
._sign
1219 if self
._is
_special
or other
._is
_special
:
1220 ans
= self
._check
_nans
(other
, context
)
1224 if self
._isinfinity
():
1226 return context
._raise
_error
(InvalidOperation
, '(+-)INF * 0')
1227 return _SignedInfinity
[resultsign
]
1229 if other
._isinfinity
():
1231 return context
._raise
_error
(InvalidOperation
, '0 * (+-)INF')
1232 return _SignedInfinity
[resultsign
]
1234 resultexp
= self
._exp
+ other
._exp
1236 # Special case for multiplying by zero
1237 if not self
or not other
:
1238 ans
= _dec_from_triple(resultsign
, '0', resultexp
)
1239 # Fixing in case the exponent is out of bounds
1240 ans
= ans
._fix
(context
)
1243 # Special case for multiplying by power of 10
1244 if self
._int
== '1':
1245 ans
= _dec_from_triple(resultsign
, other
._int
, resultexp
)
1246 ans
= ans
._fix
(context
)
1248 if other
._int
== '1':
1249 ans
= _dec_from_triple(resultsign
, self
._int
, resultexp
)
1250 ans
= ans
._fix
(context
)
1253 op1
= _WorkRep(self
)
1254 op2
= _WorkRep(other
)
1256 ans
= _dec_from_triple(resultsign
, str(op1
.int * op2
.int), resultexp
)
1257 ans
= ans
._fix
(context
)
1262 def __truediv__(self
, other
, context
=None):
1263 """Return self / other."""
1264 other
= _convert_other(other
)
1265 if other
is NotImplemented:
1266 return NotImplemented
1269 context
= getcontext()
1271 sign
= self
._sign ^ other
._sign
1273 if self
._is
_special
or other
._is
_special
:
1274 ans
= self
._check
_nans
(other
, context
)
1278 if self
._isinfinity
() and other
._isinfinity
():
1279 return context
._raise
_error
(InvalidOperation
, '(+-)INF/(+-)INF')
1281 if self
._isinfinity
():
1282 return _SignedInfinity
[sign
]
1284 if other
._isinfinity
():
1285 context
._raise
_error
(Clamped
, 'Division by infinity')
1286 return _dec_from_triple(sign
, '0', context
.Etiny())
1288 # Special cases for zeroes
1291 return context
._raise
_error
(DivisionUndefined
, '0 / 0')
1292 return context
._raise
_error
(DivisionByZero
, 'x / 0', sign
)
1295 exp
= self
._exp
- other
._exp
1298 # OK, so neither = 0, INF or NaN
1299 shift
= len(other
._int
) - len(self
._int
) + context
.prec
+ 1
1300 exp
= self
._exp
- other
._exp
- shift
1301 op1
= _WorkRep(self
)
1302 op2
= _WorkRep(other
)
1304 coeff
, remainder
= divmod(op1
.int * 10**shift
, op2
.int)
1306 coeff
, remainder
= divmod(op1
.int, op2
.int * 10**-shift
)
1308 # result is not exact; adjust to ensure correct rounding
1312 # result is exact; get as close to ideal exponent as possible
1313 ideal_exp
= self
._exp
- other
._exp
1314 while exp
< ideal_exp
and coeff
% 10 == 0:
1318 ans
= _dec_from_triple(sign
, str(coeff
), exp
)
1319 return ans
._fix
(context
)
1321 def _divide(self
, other
, context
):
1322 """Return (self // other, self % other), to context.prec precision.
1324 Assumes that neither self nor other is a NaN, that self is not
1325 infinite and that other is nonzero.
1327 sign
= self
._sign ^ other
._sign
1328 if other
._isinfinity
():
1329 ideal_exp
= self
._exp
1331 ideal_exp
= min(self
._exp
, other
._exp
)
1333 expdiff
= self
.adjusted() - other
.adjusted()
1334 if not self
or other
._isinfinity
() or expdiff
<= -2:
1335 return (_dec_from_triple(sign
, '0', 0),
1336 self
._rescale
(ideal_exp
, context
.rounding
))
1337 if expdiff
<= context
.prec
:
1338 op1
= _WorkRep(self
)
1339 op2
= _WorkRep(other
)
1340 if op1
.exp
>= op2
.exp
:
1341 op1
.int *= 10**(op1
.exp
- op2
.exp
)
1343 op2
.int *= 10**(op2
.exp
- op1
.exp
)
1344 q
, r
= divmod(op1
.int, op2
.int)
1345 if q
< 10**context
.prec
:
1346 return (_dec_from_triple(sign
, str(q
), 0),
1347 _dec_from_triple(self
._sign
, str(r
), ideal_exp
))
1349 # Here the quotient is too large to be representable
1350 ans
= context
._raise
_error
(DivisionImpossible
,
1351 'quotient too large in //, % or divmod')
1354 def __rtruediv__(self
, other
, context
=None):
1355 """Swaps self/other and returns __truediv__."""
1356 other
= _convert_other(other
)
1357 if other
is NotImplemented:
1359 return other
.__truediv
__(self
, context
=context
)
1361 __div__
= __truediv__
1362 __rdiv__
= __rtruediv__
1364 def __divmod__(self
, other
, context
=None):
1366 Return (self // other, self % other)
1368 other
= _convert_other(other
)
1369 if other
is NotImplemented:
1373 context
= getcontext()
1375 ans
= self
._check
_nans
(other
, context
)
1379 sign
= self
._sign ^ other
._sign
1380 if self
._isinfinity
():
1381 if other
._isinfinity
():
1382 ans
= context
._raise
_error
(InvalidOperation
, 'divmod(INF, INF)')
1385 return (_SignedInfinity
[sign
],
1386 context
._raise
_error
(InvalidOperation
, 'INF % x'))
1390 ans
= context
._raise
_error
(DivisionUndefined
, 'divmod(0, 0)')
1393 return (context
._raise
_error
(DivisionByZero
, 'x // 0', sign
),
1394 context
._raise
_error
(InvalidOperation
, 'x % 0'))
1396 quotient
, remainder
= self
._divide
(other
, context
)
1397 remainder
= remainder
._fix
(context
)
1398 return quotient
, remainder
1400 def __rdivmod__(self
, other
, context
=None):
1401 """Swaps self/other and returns __divmod__."""
1402 other
= _convert_other(other
)
1403 if other
is NotImplemented:
1405 return other
.__divmod
__(self
, context
=context
)
1407 def __mod__(self
, other
, context
=None):
1411 other
= _convert_other(other
)
1412 if other
is NotImplemented:
1416 context
= getcontext()
1418 ans
= self
._check
_nans
(other
, context
)
1422 if self
._isinfinity
():
1423 return context
._raise
_error
(InvalidOperation
, 'INF % x')
1426 return context
._raise
_error
(InvalidOperation
, 'x % 0')
1428 return context
._raise
_error
(DivisionUndefined
, '0 % 0')
1430 remainder
= self
._divide
(other
, context
)[1]
1431 remainder
= remainder
._fix
(context
)
1434 def __rmod__(self
, other
, context
=None):
1435 """Swaps self/other and returns __mod__."""
1436 other
= _convert_other(other
)
1437 if other
is NotImplemented:
1439 return other
.__mod
__(self
, context
=context
)
1441 def remainder_near(self
, other
, context
=None):
1443 Remainder nearest to 0- abs(remainder-near) <= other/2
1446 context
= getcontext()
1448 other
= _convert_other(other
, raiseit
=True)
1450 ans
= self
._check
_nans
(other
, context
)
1454 # self == +/-infinity -> InvalidOperation
1455 if self
._isinfinity
():
1456 return context
._raise
_error
(InvalidOperation
,
1457 'remainder_near(infinity, x)')
1459 # other == 0 -> either InvalidOperation or DivisionUndefined
1462 return context
._raise
_error
(InvalidOperation
,
1463 'remainder_near(x, 0)')
1465 return context
._raise
_error
(DivisionUndefined
,
1466 'remainder_near(0, 0)')
1468 # other = +/-infinity -> remainder = self
1469 if other
._isinfinity
():
1471 return ans
._fix
(context
)
1473 # self = 0 -> remainder = self, with ideal exponent
1474 ideal_exponent
= min(self
._exp
, other
._exp
)
1476 ans
= _dec_from_triple(self
._sign
, '0', ideal_exponent
)
1477 return ans
._fix
(context
)
1479 # catch most cases of large or small quotient
1480 expdiff
= self
.adjusted() - other
.adjusted()
1481 if expdiff
>= context
.prec
+ 1:
1482 # expdiff >= prec+1 => abs(self/other) > 10**prec
1483 return context
._raise
_error
(DivisionImpossible
)
1485 # expdiff <= -2 => abs(self/other) < 0.1
1486 ans
= self
._rescale
(ideal_exponent
, context
.rounding
)
1487 return ans
._fix
(context
)
1489 # adjust both arguments to have the same exponent, then divide
1490 op1
= _WorkRep(self
)
1491 op2
= _WorkRep(other
)
1492 if op1
.exp
>= op2
.exp
:
1493 op1
.int *= 10**(op1
.exp
- op2
.exp
)
1495 op2
.int *= 10**(op2
.exp
- op1
.exp
)
1496 q
, r
= divmod(op1
.int, op2
.int)
1497 # remainder is r*10**ideal_exponent; other is +/-op2.int *
1498 # 10**ideal_exponent. Apply correction to ensure that
1499 # abs(remainder) <= abs(other)/2
1500 if 2*r
+ (q
&1) > op2
.int:
1504 if q
>= 10**context
.prec
:
1505 return context
._raise
_error
(DivisionImpossible
)
1507 # result has same sign as self unless r is negative
1513 ans
= _dec_from_triple(sign
, str(r
), ideal_exponent
)
1514 return ans
._fix
(context
)
1516 def __floordiv__(self
, other
, context
=None):
1518 other
= _convert_other(other
)
1519 if other
is NotImplemented:
1523 context
= getcontext()
1525 ans
= self
._check
_nans
(other
, context
)
1529 if self
._isinfinity
():
1530 if other
._isinfinity
():
1531 return context
._raise
_error
(InvalidOperation
, 'INF // INF')
1533 return _SignedInfinity
[self
._sign ^ other
._sign
]
1537 return context
._raise
_error
(DivisionByZero
, 'x // 0',
1538 self
._sign ^ other
._sign
)
1540 return context
._raise
_error
(DivisionUndefined
, '0 // 0')
1542 return self
._divide
(other
, context
)[0]
1544 def __rfloordiv__(self
, other
, context
=None):
1545 """Swaps self/other and returns __floordiv__."""
1546 other
= _convert_other(other
)
1547 if other
is NotImplemented:
1549 return other
.__floordiv
__(self
, context
=context
)
1551 def __float__(self
):
1552 """Float representation."""
1553 return float(str(self
))
1556 """Converts self to an int, truncating if necessary."""
1557 if self
._is
_special
:
1559 context
= getcontext()
1560 return context
._raise
_error
(InvalidContext
)
1561 elif self
._isinfinity
():
1562 raise OverflowError("Cannot convert infinity to int")
1563 s
= (-1)**self
._sign
1565 return s
*int(self
._int
)*10**self
._exp
1567 return s
*int(self
._int
[:self
._exp
] or '0')
1573 real
= property(real
)
1577 imag
= property(imag
)
1579 def conjugate(self
):
1582 def __complex__(self
):
1583 return complex(float(self
))
1586 """Converts to a long.
1588 Equivalent to long(int(self))
1590 return long(self
.__int
__())
1592 def _fix_nan(self
, context
):
1593 """Decapitate the payload of a NaN to fit the context"""
1596 # maximum length of payload is precision if _clamp=0,
1597 # precision-1 if _clamp=1.
1598 max_payload_len
= context
.prec
- context
._clamp
1599 if len(payload
) > max_payload_len
:
1600 payload
= payload
[len(payload
)-max_payload_len
:].lstrip('0')
1601 return _dec_from_triple(self
._sign
, payload
, self
._exp
, True)
1602 return Decimal(self
)
1604 def _fix(self
, context
):
1605 """Round if it is necessary to keep self within prec precision.
1607 Rounds and fixes the exponent. Does not raise on a sNaN.
1610 self - Decimal instance
1611 context - context used.
1614 if self
._is
_special
:
1616 # decapitate payload if necessary
1617 return self
._fix
_nan
(context
)
1619 # self is +/-Infinity; return unaltered
1620 return Decimal(self
)
1622 # if self is zero then exponent should be between Etiny and
1623 # Emax if _clamp==0, and between Etiny and Etop if _clamp==1.
1624 Etiny
= context
.Etiny()
1625 Etop
= context
.Etop()
1627 exp_max
= [context
.Emax
, Etop
][context
._clamp
]
1628 new_exp
= min(max(self
._exp
, Etiny
), exp_max
)
1629 if new_exp
!= self
._exp
:
1630 context
._raise
_error
(Clamped
)
1631 return _dec_from_triple(self
._sign
, '0', new_exp
)
1633 return Decimal(self
)
1635 # exp_min is the smallest allowable exponent of the result,
1636 # equal to max(self.adjusted()-context.prec+1, Etiny)
1637 exp_min
= len(self
._int
) + self
._exp
- context
.prec
1639 # overflow: exp_min > Etop iff self.adjusted() > Emax
1640 context
._raise
_error
(Inexact
)
1641 context
._raise
_error
(Rounded
)
1642 return context
._raise
_error
(Overflow
, 'above Emax', self
._sign
)
1643 self_is_subnormal
= exp_min
< Etiny
1644 if self_is_subnormal
:
1645 context
._raise
_error
(Subnormal
)
1648 # round if self has too many digits
1649 if self
._exp
< exp_min
:
1650 context
._raise
_error
(Rounded
)
1651 digits
= len(self
._int
) + self
._exp
- exp_min
1653 self
= _dec_from_triple(self
._sign
, '1', exp_min
-1)
1655 this_function
= getattr(self
, self
._pick
_rounding
_function
[context
.rounding
])
1656 changed
= this_function(digits
)
1657 coeff
= self
._int
[:digits
] or '0'
1659 coeff
= str(int(coeff
)+1)
1660 ans
= _dec_from_triple(self
._sign
, coeff
, exp_min
)
1663 context
._raise
_error
(Inexact
)
1664 if self_is_subnormal
:
1665 context
._raise
_error
(Underflow
)
1667 # raise Clamped on underflow to 0
1668 context
._raise
_error
(Clamped
)
1669 elif len(ans
._int
) == context
.prec
+1:
1670 # we get here only if rescaling rounds the
1671 # cofficient up to exactly 10**context.prec
1673 ans
= _dec_from_triple(ans
._sign
,
1674 ans
._int
[:-1], ans
._exp
+1)
1676 # Inexact and Rounded have already been raised
1677 ans
= context
._raise
_error
(Overflow
, 'above Emax',
1681 # fold down if _clamp == 1 and self has too few digits
1682 if context
._clamp
== 1 and self
._exp
> Etop
:
1683 context
._raise
_error
(Clamped
)
1684 self_padded
= self
._int
+ '0'*(self
._exp
- Etop
)
1685 return _dec_from_triple(self
._sign
, self_padded
, Etop
)
1687 # here self was representable to begin with; return unchanged
1688 return Decimal(self
)
1690 _pick_rounding_function
= {}
1692 # for each of the rounding functions below:
1693 # self is a finite, nonzero Decimal
1694 # prec is an integer satisfying 0 <= prec < len(self._int)
1696 # each function returns either -1, 0, or 1, as follows:
1697 # 1 indicates that self should be rounded up (away from zero)
1698 # 0 indicates that self should be truncated, and that all the
1699 # digits to be truncated are zeros (so the value is unchanged)
1700 # -1 indicates that there are nonzero digits to be truncated
1702 def _round_down(self
, prec
):
1703 """Also known as round-towards-0, truncate."""
1704 if _all_zeros(self
._int
, prec
):
1709 def _round_up(self
, prec
):
1710 """Rounds away from 0."""
1711 return -self
._round
_down
(prec
)
1713 def _round_half_up(self
, prec
):
1714 """Rounds 5 up (away from 0)"""
1715 if self
._int
[prec
] in '56789':
1717 elif _all_zeros(self
._int
, prec
):
1722 def _round_half_down(self
, prec
):
1724 if _exact_half(self
._int
, prec
):
1727 return self
._round
_half
_up
(prec
)
1729 def _round_half_even(self
, prec
):
1730 """Round 5 to even, rest to nearest."""
1731 if _exact_half(self
._int
, prec
) and \
1732 (prec
== 0 or self
._int
[prec
-1] in '02468'):
1735 return self
._round
_half
_up
(prec
)
1737 def _round_ceiling(self
, prec
):
1738 """Rounds up (not away from 0 if negative.)"""
1740 return self
._round
_down
(prec
)
1742 return -self
._round
_down
(prec
)
1744 def _round_floor(self
, prec
):
1745 """Rounds down (not towards 0 if negative)"""
1747 return self
._round
_down
(prec
)
1749 return -self
._round
_down
(prec
)
1751 def _round_05up(self
, prec
):
1752 """Round down unless digit prec-1 is 0 or 5."""
1753 if prec
and self
._int
[prec
-1] not in '05':
1754 return self
._round
_down
(prec
)
1756 return -self
._round
_down
(prec
)
1758 def fma(self
, other
, third
, context
=None):
1759 """Fused multiply-add.
1761 Returns self*other+third with no rounding of the intermediate
1764 self and other are multiplied together, with no rounding of
1765 the result. The third operand is then added to the result,
1766 and a single final rounding is performed.
1769 other
= _convert_other(other
, raiseit
=True)
1771 # compute product; raise InvalidOperation if either operand is
1772 # a signaling NaN or if the product is zero times infinity.
1773 if self
._is
_special
or other
._is
_special
:
1775 context
= getcontext()
1776 if self
._exp
== 'N':
1777 return context
._raise
_error
(InvalidOperation
, 'sNaN', self
)
1778 if other
._exp
== 'N':
1779 return context
._raise
_error
(InvalidOperation
, 'sNaN', other
)
1780 if self
._exp
== 'n':
1782 elif other
._exp
== 'n':
1784 elif self
._exp
== 'F':
1786 return context
._raise
_error
(InvalidOperation
,
1788 product
= _SignedInfinity
[self
._sign ^ other
._sign
]
1789 elif other
._exp
== 'F':
1791 return context
._raise
_error
(InvalidOperation
,
1793 product
= _SignedInfinity
[self
._sign ^ other
._sign
]
1795 product
= _dec_from_triple(self
._sign ^ other
._sign
,
1796 str(int(self
._int
) * int(other
._int
)),
1797 self
._exp
+ other
._exp
)
1799 third
= _convert_other(third
, raiseit
=True)
1800 return product
.__add
__(third
, context
)
1802 def _power_modulo(self
, other
, modulo
, context
=None):
1803 """Three argument version of __pow__"""
1805 # if can't convert other and modulo to Decimal, raise
1806 # TypeError; there's no point returning NotImplemented (no
1807 # equivalent of __rpow__ for three argument pow)
1808 other
= _convert_other(other
, raiseit
=True)
1809 modulo
= _convert_other(modulo
, raiseit
=True)
1812 context
= getcontext()
1814 # deal with NaNs: if there are any sNaNs then first one wins,
1815 # (i.e. behaviour for NaNs is identical to that of fma)
1816 self_is_nan
= self
._isnan
()
1817 other_is_nan
= other
._isnan
()
1818 modulo_is_nan
= modulo
._isnan
()
1819 if self_is_nan
or other_is_nan
or modulo_is_nan
:
1820 if self_is_nan
== 2:
1821 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1823 if other_is_nan
== 2:
1824 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1826 if modulo_is_nan
== 2:
1827 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1830 return self
._fix
_nan
(context
)
1832 return other
._fix
_nan
(context
)
1833 return modulo
._fix
_nan
(context
)
1835 # check inputs: we apply same restrictions as Python's pow()
1836 if not (self
._isinteger
() and
1837 other
._isinteger
() and
1838 modulo
._isinteger
()):
1839 return context
._raise
_error
(InvalidOperation
,
1840 'pow() 3rd argument not allowed '
1841 'unless all arguments are integers')
1843 return context
._raise
_error
(InvalidOperation
,
1844 'pow() 2nd argument cannot be '
1845 'negative when 3rd argument specified')
1847 return context
._raise
_error
(InvalidOperation
,
1848 'pow() 3rd argument cannot be 0')
1850 # additional restriction for decimal: the modulus must be less
1851 # than 10**prec in absolute value
1852 if modulo
.adjusted() >= context
.prec
:
1853 return context
._raise
_error
(InvalidOperation
,
1854 'insufficient precision: pow() 3rd '
1855 'argument must not have more than '
1858 # define 0**0 == NaN, for consistency with two-argument pow
1859 # (even though it hurts!)
1860 if not other
and not self
:
1861 return context
._raise
_error
(InvalidOperation
,
1862 'at least one of pow() 1st argument '
1863 'and 2nd argument must be nonzero ;'
1864 '0**0 is not defined')
1866 # compute sign of result
1872 # convert modulo to a Python integer, and self and other to
1873 # Decimal integers (i.e. force their exponents to be >= 0)
1874 modulo
= abs(int(modulo
))
1875 base
= _WorkRep(self
.to_integral_value())
1876 exponent
= _WorkRep(other
.to_integral_value())
1878 # compute result using integer pow()
1879 base
= (base
.int % modulo
* pow(10, base
.exp
, modulo
)) % modulo
1880 for i
in xrange(exponent
.exp
):
1881 base
= pow(base
, 10, modulo
)
1882 base
= pow(base
, exponent
.int, modulo
)
1884 return _dec_from_triple(sign
, str(base
), 0)
1886 def _power_exact(self
, other
, p
):
1887 """Attempt to compute self**other exactly.
1889 Given Decimals self and other and an integer p, attempt to
1890 compute an exact result for the power self**other, with p
1891 digits of precision. Return None if self**other is not
1892 exactly representable in p digits.
1894 Assumes that elimination of special cases has already been
1895 performed: self and other must both be nonspecial; self must
1896 be positive and not numerically equal to 1; other must be
1897 nonzero. For efficiency, other._exp should not be too large,
1898 so that 10**abs(other._exp) is a feasible calculation."""
1900 # In the comments below, we write x for the value of self and
1901 # y for the value of other. Write x = xc*10**xe and y =
1904 # The main purpose of this method is to identify the *failure*
1905 # of x**y to be exactly representable with as little effort as
1906 # possible. So we look for cheap and easy tests that
1907 # eliminate the possibility of x**y being exact. Only if all
1908 # these tests are passed do we go on to actually compute x**y.
1910 # Here's the main idea. First normalize both x and y. We
1911 # express y as a rational m/n, with m and n relatively prime
1912 # and n>0. Then for x**y to be exactly representable (at
1913 # *any* precision), xc must be the nth power of a positive
1914 # integer and xe must be divisible by n. If m is negative
1915 # then additionally xc must be a power of either 2 or 5, hence
1916 # a power of 2**n or 5**n.
1918 # There's a limit to how small |y| can be: if y=m/n as above
1921 # (1) if xc != 1 then for the result to be representable we
1922 # need xc**(1/n) >= 2, and hence also xc**|y| >= 2. So
1923 # if |y| <= 1/nbits(xc) then xc < 2**nbits(xc) <=
1924 # 2**(1/|y|), hence xc**|y| < 2 and the result is not
1927 # (2) if xe != 0, |xe|*(1/n) >= 1, so |xe|*|y| >= 1. Hence if
1928 # |y| < 1/|xe| then the result is not representable.
1930 # Note that since x is not equal to 1, at least one of (1) and
1931 # (2) must apply. Now |y| < 1/nbits(xc) iff |yc|*nbits(xc) <
1932 # 10**-ye iff len(str(|yc|*nbits(xc)) <= -ye.
1934 # There's also a limit to how large y can be, at least if it's
1935 # positive: the normalized result will have coefficient xc**y,
1936 # so if it's representable then xc**y < 10**p, and y <
1937 # p/log10(xc). Hence if y*log10(xc) >= p then the result is
1938 # not exactly representable.
1940 # if len(str(abs(yc*xe)) <= -ye then abs(yc*xe) < 10**-ye,
1941 # so |y| < 1/xe and the result is not representable.
1942 # Similarly, len(str(abs(yc)*xc_bits)) <= -ye implies |y|
1946 xc
, xe
= x
.int, x
.exp
1952 yc
, ye
= y
.int, y
.exp
1957 # case where xc == 1: result is 10**(xe*y), with xe*y
1958 # required to be an integer
1961 exponent
= xe
*yc
*10**ye
1963 exponent
, remainder
= divmod(xe
*yc
, 10**-ye
)
1967 exponent
= -exponent
1968 # if other is a nonnegative integer, use ideal exponent
1969 if other
._isinteger
() and other
._sign
== 0:
1970 ideal_exponent
= self
._exp
*int(other
)
1971 zeros
= min(exponent
-ideal_exponent
, p
-1)
1974 return _dec_from_triple(0, '1' + '0'*zeros
, exponent
-zeros
)
1976 # case where y is negative: xc must be either a power
1977 # of 2 or a power of 5.
1979 last_digit
= xc
% 10
1980 if last_digit
in (2,4,6,8):
1981 # quick test for power of 2
1984 # now xc is a power of 2; e is its exponent
1986 # find e*y and xe*y; both must be integers
1988 y_as_int
= yc
*10**ye
1993 e
, remainder
= divmod(e
*yc
, ten_pow
)
1996 xe
, remainder
= divmod(xe
*yc
, ten_pow
)
2000 if e
*65 >= p
*93: # 93/65 > log(10)/log(5)
2004 elif last_digit
== 5:
2005 # e >= log_5(xc) if xc is a power of 5; we have
2006 # equality all the way up to xc=5**2658
2007 e
= _nbits(xc
)*28//65
2008 xc
, remainder
= divmod(5**e
, xc
)
2015 y_as_integer
= yc
*10**ye
2017 xe
= xe
*y_as_integer
2020 e
, remainder
= divmod(e
*yc
, ten_pow
)
2023 xe
, remainder
= divmod(xe
*yc
, ten_pow
)
2026 if e
*3 >= p
*10: # 10/3 > log(10)/log(2)
2035 return _dec_from_triple(0, str(xc
), xe
)
2037 # now y is positive; find m and n such that y = m/n
2041 if xe
!= 0 and len(str(abs(yc
*xe
))) <= -ye
:
2043 xc_bits
= _nbits(xc
)
2044 if xc
!= 1 and len(str(abs(yc
)*xc_bits
)) <= -ye
:
2046 m
, n
= yc
, 10**(-ye
)
2047 while m
% 2 == n
% 2 == 0:
2050 while m
% 5 == n
% 5 == 0:
2054 # compute nth root of xc*10**xe
2056 # if 1 < xc < 2**n then xc isn't an nth power
2057 if xc
!= 1 and xc_bits
<= n
:
2060 xe
, rem
= divmod(xe
, n
)
2064 # compute nth root of xc using Newton's method
2065 a
= 1L << -(-_nbits(xc
)//n
) # initial estimate
2067 q
, r
= divmod(xc
, a
**(n
-1))
2071 a
= (a
*(n
-1) + q
)//n
2072 if not (a
== q
and r
== 0):
2076 # now xc*10**xe is the nth root of the original xc*10**xe
2077 # compute mth power of xc*10**xe
2079 # if m > p*100//_log10_lb(xc) then m > p/log10(xc), hence xc**m >
2080 # 10**p and the result is not representable.
2081 if xc
> 1 and m
> p
*100//_log10_lb(xc
):
2088 # by this point the result *is* exactly representable
2089 # adjust the exponent to get as close as possible to the ideal
2090 # exponent, if necessary
2092 if other
._isinteger
() and other
._sign
== 0:
2093 ideal_exponent
= self
._exp
*int(other
)
2094 zeros
= min(xe
-ideal_exponent
, p
-len(str_xc
))
2097 return _dec_from_triple(0, str_xc
+'0'*zeros
, xe
-zeros
)
2099 def __pow__(self
, other
, modulo
=None, context
=None):
2100 """Return self ** other [ % modulo].
2102 With two arguments, compute self**other.
2104 With three arguments, compute (self**other) % modulo. For the
2105 three argument form, the following restrictions on the
2108 - all three arguments must be integral
2109 - other must be nonnegative
2110 - either self or other (or both) must be nonzero
2111 - modulo must be nonzero and must have at most p digits,
2112 where p is the context precision.
2114 If any of these restrictions is violated the InvalidOperation
2117 The result of pow(self, other, modulo) is identical to the
2118 result that would be obtained by computing (self**other) %
2119 modulo with unbounded precision, but is computed more
2120 efficiently. It is always exact.
2123 if modulo
is not None:
2124 return self
._power
_modulo
(other
, modulo
, context
)
2126 other
= _convert_other(other
)
2127 if other
is NotImplemented:
2131 context
= getcontext()
2133 # either argument is a NaN => result is NaN
2134 ans
= self
._check
_nans
(other
, context
)
2138 # 0**0 = NaN (!), x**0 = 1 for nonzero x (including +/-Infinity)
2141 return context
._raise
_error
(InvalidOperation
, '0 ** 0')
2145 # result has sign 1 iff self._sign is 1 and other is an odd integer
2148 if other
._isinteger
():
2149 if not other
._iseven
():
2152 # -ve**noninteger = NaN
2153 # (-0)**noninteger = 0**noninteger
2155 return context
._raise
_error
(InvalidOperation
,
2156 'x ** y with x negative and y not an integer')
2157 # negate self, without doing any unwanted rounding
2158 self
= self
.copy_negate()
2160 # 0**(+ve or Inf)= 0; 0**(-ve or -Inf) = Infinity
2162 if other
._sign
== 0:
2163 return _dec_from_triple(result_sign
, '0', 0)
2165 return _SignedInfinity
[result_sign
]
2167 # Inf**(+ve or Inf) = Inf; Inf**(-ve or -Inf) = 0
2168 if self
._isinfinity
():
2169 if other
._sign
== 0:
2170 return _SignedInfinity
[result_sign
]
2172 return _dec_from_triple(result_sign
, '0', 0)
2174 # 1**other = 1, but the choice of exponent and the flags
2175 # depend on the exponent of self, and on whether other is a
2176 # positive integer, a negative integer, or neither
2178 if other
._isinteger
():
2179 # exp = max(self._exp*max(int(other), 0),
2180 # 1-context.prec) but evaluating int(other) directly
2181 # is dangerous until we know other is small (other
2182 # could be 1e999999999)
2183 if other
._sign
== 1:
2185 elif other
> context
.prec
:
2186 multiplier
= context
.prec
2188 multiplier
= int(other
)
2190 exp
= self
._exp
* multiplier
2191 if exp
< 1-context
.prec
:
2192 exp
= 1-context
.prec
2193 context
._raise
_error
(Rounded
)
2195 context
._raise
_error
(Inexact
)
2196 context
._raise
_error
(Rounded
)
2197 exp
= 1-context
.prec
2199 return _dec_from_triple(result_sign
, '1'+'0'*-exp
, exp
)
2201 # compute adjusted exponent of self
2202 self_adj
= self
.adjusted()
2204 # self ** infinity is infinity if self > 1, 0 if self < 1
2205 # self ** -infinity is infinity if self < 1, 0 if self > 1
2206 if other
._isinfinity
():
2207 if (other
._sign
== 0) == (self_adj
< 0):
2208 return _dec_from_triple(result_sign
, '0', 0)
2210 return _SignedInfinity
[result_sign
]
2212 # from here on, the result always goes through the call
2213 # to _fix at the end of this function.
2216 # crude test to catch cases of extreme overflow/underflow. If
2217 # log10(self)*other >= 10**bound and bound >= len(str(Emax))
2218 # then 10**bound >= 10**len(str(Emax)) >= Emax+1 and hence
2219 # self**other >= 10**(Emax+1), so overflow occurs. The test
2220 # for underflow is similar.
2221 bound
= self
._log
10_exp
_bound
() + other
.adjusted()
2222 if (self_adj
>= 0) == (other
._sign
== 0):
2223 # self > 1 and other +ve, or self < 1 and other -ve
2224 # possibility of overflow
2225 if bound
>= len(str(context
.Emax
)):
2226 ans
= _dec_from_triple(result_sign
, '1', context
.Emax
+1)
2228 # self > 1 and other -ve, or self < 1 and other +ve
2229 # possibility of underflow to 0
2230 Etiny
= context
.Etiny()
2231 if bound
>= len(str(-Etiny
)):
2232 ans
= _dec_from_triple(result_sign
, '1', Etiny
-1)
2234 # try for an exact result with precision +1
2236 ans
= self
._power
_exact
(other
, context
.prec
+ 1)
2237 if ans
is not None and result_sign
== 1:
2238 ans
= _dec_from_triple(1, ans
._int
, ans
._exp
)
2240 # usual case: inexact result, x**y computed directly as exp(y*log(x))
2244 xc
, xe
= x
.int, x
.exp
2246 yc
, ye
= y
.int, y
.exp
2250 # compute correctly rounded result: start with precision +3,
2251 # then increase precision until result is unambiguously roundable
2254 coeff
, exp
= _dpower(xc
, xe
, yc
, ye
, p
+extra
)
2255 if coeff
% (5*10**(len(str(coeff
))-p
-1)):
2259 ans
= _dec_from_triple(result_sign
, str(coeff
), exp
)
2261 # the specification says that for non-integer other we need to
2262 # raise Inexact, even when the result is actually exact. In
2263 # the same way, we need to raise Underflow here if the result
2264 # is subnormal. (The call to _fix will take care of raising
2265 # Rounded and Subnormal, as usual.)
2266 if not other
._isinteger
():
2267 context
._raise
_error
(Inexact
)
2268 # pad with zeros up to length context.prec+1 if necessary
2269 if len(ans
._int
) <= context
.prec
:
2270 expdiff
= context
.prec
+1 - len(ans
._int
)
2271 ans
= _dec_from_triple(ans
._sign
, ans
._int
+'0'*expdiff
,
2273 if ans
.adjusted() < context
.Emin
:
2274 context
._raise
_error
(Underflow
)
2276 # unlike exp, ln and log10, the power function respects the
2277 # rounding mode; no need to use ROUND_HALF_EVEN here
2278 ans
= ans
._fix
(context
)
2281 def __rpow__(self
, other
, context
=None):
2282 """Swaps self/other and returns __pow__."""
2283 other
= _convert_other(other
)
2284 if other
is NotImplemented:
2286 return other
.__pow
__(self
, context
=context
)
2288 def normalize(self
, context
=None):
2289 """Normalize- strip trailing 0s, change anything equal to 0 to 0e0"""
2292 context
= getcontext()
2294 if self
._is
_special
:
2295 ans
= self
._check
_nans
(context
=context
)
2299 dup
= self
._fix
(context
)
2300 if dup
._isinfinity
():
2304 return _dec_from_triple(dup
._sign
, '0', 0)
2305 exp_max
= [context
.Emax
, context
.Etop()][context
._clamp
]
2308 while dup
._int
[end
-1] == '0' and exp
< exp_max
:
2311 return _dec_from_triple(dup
._sign
, dup
._int
[:end
], exp
)
2313 def quantize(self
, exp
, rounding
=None, context
=None, watchexp
=True):
2314 """Quantize self so its exponent is the same as that of exp.
2316 Similar to self._rescale(exp._exp) but with error checking.
2318 exp
= _convert_other(exp
, raiseit
=True)
2321 context
= getcontext()
2322 if rounding
is None:
2323 rounding
= context
.rounding
2325 if self
._is
_special
or exp
._is
_special
:
2326 ans
= self
._check
_nans
(exp
, context
)
2330 if exp
._isinfinity
() or self
._isinfinity
():
2331 if exp
._isinfinity
() and self
._isinfinity
():
2332 return Decimal(self
) # if both are inf, it is OK
2333 return context
._raise
_error
(InvalidOperation
,
2334 'quantize with one INF')
2336 # if we're not watching exponents, do a simple rescale
2338 ans
= self
._rescale
(exp
._exp
, rounding
)
2339 # raise Inexact and Rounded where appropriate
2340 if ans
._exp
> self
._exp
:
2341 context
._raise
_error
(Rounded
)
2343 context
._raise
_error
(Inexact
)
2346 # exp._exp should be between Etiny and Emax
2347 if not (context
.Etiny() <= exp
._exp
<= context
.Emax
):
2348 return context
._raise
_error
(InvalidOperation
,
2349 'target exponent out of bounds in quantize')
2352 ans
= _dec_from_triple(self
._sign
, '0', exp
._exp
)
2353 return ans
._fix
(context
)
2355 self_adjusted
= self
.adjusted()
2356 if self_adjusted
> context
.Emax
:
2357 return context
._raise
_error
(InvalidOperation
,
2358 'exponent of quantize result too large for current context')
2359 if self_adjusted
- exp
._exp
+ 1 > context
.prec
:
2360 return context
._raise
_error
(InvalidOperation
,
2361 'quantize result has too many digits for current context')
2363 ans
= self
._rescale
(exp
._exp
, rounding
)
2364 if ans
.adjusted() > context
.Emax
:
2365 return context
._raise
_error
(InvalidOperation
,
2366 'exponent of quantize result too large for current context')
2367 if len(ans
._int
) > context
.prec
:
2368 return context
._raise
_error
(InvalidOperation
,
2369 'quantize result has too many digits for current context')
2371 # raise appropriate flags
2372 if ans
._exp
> self
._exp
:
2373 context
._raise
_error
(Rounded
)
2375 context
._raise
_error
(Inexact
)
2376 if ans
and ans
.adjusted() < context
.Emin
:
2377 context
._raise
_error
(Subnormal
)
2379 # call to fix takes care of any necessary folddown
2380 ans
= ans
._fix
(context
)
2383 def same_quantum(self
, other
):
2384 """Return True if self and other have the same exponent; otherwise
2387 If either operand is a special value, the following rules are used:
2388 * return True if both operands are infinities
2389 * return True if both operands are NaNs
2390 * otherwise, return False.
2392 other
= _convert_other(other
, raiseit
=True)
2393 if self
._is
_special
or other
._is
_special
:
2394 return (self
.is_nan() and other
.is_nan() or
2395 self
.is_infinite() and other
.is_infinite())
2396 return self
._exp
== other
._exp
2398 def _rescale(self
, exp
, rounding
):
2399 """Rescale self so that the exponent is exp, either by padding with zeros
2400 or by truncating digits, using the given rounding mode.
2402 Specials are returned without change. This operation is
2403 quiet: it raises no flags, and uses no information from the
2406 exp = exp to scale to (an integer)
2407 rounding = rounding mode
2409 if self
._is
_special
:
2410 return Decimal(self
)
2412 return _dec_from_triple(self
._sign
, '0', exp
)
2414 if self
._exp
>= exp
:
2415 # pad answer with zeros if necessary
2416 return _dec_from_triple(self
._sign
,
2417 self
._int
+ '0'*(self
._exp
- exp
), exp
)
2419 # too many digits; round and lose data. If self.adjusted() <
2420 # exp-1, replace self by 10**(exp-1) before rounding
2421 digits
= len(self
._int
) + self
._exp
- exp
2423 self
= _dec_from_triple(self
._sign
, '1', exp
-1)
2425 this_function
= getattr(self
, self
._pick
_rounding
_function
[rounding
])
2426 changed
= this_function(digits
)
2427 coeff
= self
._int
[:digits
] or '0'
2429 coeff
= str(int(coeff
)+1)
2430 return _dec_from_triple(self
._sign
, coeff
, exp
)
2432 def _round(self
, places
, rounding
):
2433 """Round a nonzero, nonspecial Decimal to a fixed number of
2434 significant figures, using the given rounding mode.
2436 Infinities, NaNs and zeros are returned unaltered.
2438 This operation is quiet: it raises no flags, and uses no
2439 information from the context.
2443 raise ValueError("argument should be at least 1 in _round")
2444 if self
._is
_special
or not self
:
2445 return Decimal(self
)
2446 ans
= self
._rescale
(self
.adjusted()+1-places
, rounding
)
2447 # it can happen that the rescale alters the adjusted exponent;
2448 # for example when rounding 99.97 to 3 significant figures.
2449 # When this happens we end up with an extra 0 at the end of
2450 # the number; a second rescale fixes this.
2451 if ans
.adjusted() != self
.adjusted():
2452 ans
= ans
._rescale
(ans
.adjusted()+1-places
, rounding
)
2455 def to_integral_exact(self
, rounding
=None, context
=None):
2456 """Rounds to a nearby integer.
2458 If no rounding mode is specified, take the rounding mode from
2459 the context. This method raises the Rounded and Inexact flags
2462 See also: to_integral_value, which does exactly the same as
2463 this method except that it doesn't raise Inexact or Rounded.
2465 if self
._is
_special
:
2466 ans
= self
._check
_nans
(context
=context
)
2469 return Decimal(self
)
2471 return Decimal(self
)
2473 return _dec_from_triple(self
._sign
, '0', 0)
2475 context
= getcontext()
2476 if rounding
is None:
2477 rounding
= context
.rounding
2478 context
._raise
_error
(Rounded
)
2479 ans
= self
._rescale
(0, rounding
)
2481 context
._raise
_error
(Inexact
)
2484 def to_integral_value(self
, rounding
=None, context
=None):
2485 """Rounds to the nearest integer, without raising inexact, rounded."""
2487 context
= getcontext()
2488 if rounding
is None:
2489 rounding
= context
.rounding
2490 if self
._is
_special
:
2491 ans
= self
._check
_nans
(context
=context
)
2494 return Decimal(self
)
2496 return Decimal(self
)
2498 return self
._rescale
(0, rounding
)
2500 # the method name changed, but we provide also the old one, for compatibility
2501 to_integral
= to_integral_value
2503 def sqrt(self
, context
=None):
2504 """Return the square root of self."""
2506 context
= getcontext()
2508 if self
._is
_special
:
2509 ans
= self
._check
_nans
(context
=context
)
2513 if self
._isinfinity
() and self
._sign
== 0:
2514 return Decimal(self
)
2517 # exponent = self._exp // 2. sqrt(-0) = -0
2518 ans
= _dec_from_triple(self
._sign
, '0', self
._exp
// 2)
2519 return ans
._fix
(context
)
2522 return context
._raise
_error
(InvalidOperation
, 'sqrt(-x), x > 0')
2524 # At this point self represents a positive number. Let p be
2525 # the desired precision and express self in the form c*100**e
2526 # with c a positive real number and e an integer, c and e
2527 # being chosen so that 100**(p-1) <= c < 100**p. Then the
2528 # (exact) square root of self is sqrt(c)*10**e, and 10**(p-1)
2529 # <= sqrt(c) < 10**p, so the closest representable Decimal at
2530 # precision p is n*10**e where n = round_half_even(sqrt(c)),
2531 # the closest integer to sqrt(c) with the even integer chosen
2532 # in the case of a tie.
2534 # To ensure correct rounding in all cases, we use the
2535 # following trick: we compute the square root to an extra
2536 # place (precision p+1 instead of precision p), rounding down.
2537 # Then, if the result is inexact and its last digit is 0 or 5,
2538 # we increase the last digit to 1 or 6 respectively; if it's
2539 # exact we leave the last digit alone. Now the final round to
2540 # p places (or fewer in the case of underflow) will round
2541 # correctly and raise the appropriate flags.
2543 # use an extra digit of precision
2544 prec
= context
.prec
+1
2546 # write argument in the form c*100**e where e = self._exp//2
2547 # is the 'ideal' exponent, to be used if the square root is
2548 # exactly representable. l is the number of 'digits' of c in
2549 # base 100, so that 100**(l-1) <= c < 100**l.
2554 l
= (len(self
._int
) >> 1) + 1
2557 l
= len(self
._int
)+1 >> 1
2559 # rescale so that c has exactly prec base 100 'digits'
2565 c
, remainder
= divmod(c
, 100**-shift
)
2566 exact
= not remainder
2569 # find n = floor(sqrt(c)) using Newton's method
2577 exact
= exact
and n
*n
== c
2580 # result is exact; rescale to use ideal exponent e
2582 # assert n % 10**shift == 0
2588 # result is not exact; fix last digit as described above
2592 ans
= _dec_from_triple(0, str(n
), e
)
2594 # round, and fit to current context
2595 context
= context
._shallow
_copy
()
2596 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
2597 ans
= ans
._fix
(context
)
2598 context
.rounding
= rounding
2602 def max(self
, other
, context
=None):
2603 """Returns the larger value.
2605 Like max(self, other) except if one is not a number, returns
2606 NaN (and signals if one is sNaN). Also rounds.
2608 other
= _convert_other(other
, raiseit
=True)
2611 context
= getcontext()
2613 if self
._is
_special
or other
._is
_special
:
2614 # If one operand is a quiet NaN and the other is number, then the
2615 # number is always returned
2619 if on
== 1 and sn
== 0:
2620 return self
._fix
(context
)
2621 if sn
== 1 and on
== 0:
2622 return other
._fix
(context
)
2623 return self
._check
_nans
(other
, context
)
2625 c
= self
._cmp
(other
)
2627 # If both operands are finite and equal in numerical value
2628 # then an ordering is applied:
2630 # If the signs differ then max returns the operand with the
2631 # positive sign and min returns the operand with the negative sign
2633 # If the signs are the same then the exponent is used to select
2634 # the result. This is exactly the ordering used in compare_total.
2635 c
= self
.compare_total(other
)
2642 return ans
._fix
(context
)
2644 def min(self
, other
, context
=None):
2645 """Returns the smaller value.
2647 Like min(self, other) except if one is not a number, returns
2648 NaN (and signals if one is sNaN). Also rounds.
2650 other
= _convert_other(other
, raiseit
=True)
2653 context
= getcontext()
2655 if self
._is
_special
or other
._is
_special
:
2656 # If one operand is a quiet NaN and the other is number, then the
2657 # number is always returned
2661 if on
== 1 and sn
== 0:
2662 return self
._fix
(context
)
2663 if sn
== 1 and on
== 0:
2664 return other
._fix
(context
)
2665 return self
._check
_nans
(other
, context
)
2667 c
= self
._cmp
(other
)
2669 c
= self
.compare_total(other
)
2676 return ans
._fix
(context
)
2678 def _isinteger(self
):
2679 """Returns whether self is an integer"""
2680 if self
._is
_special
:
2684 rest
= self
._int
[self
._exp
:]
2685 return rest
== '0'*len(rest
)
2688 """Returns True if self is even. Assumes self is an integer."""
2689 if not self
or self
._exp
> 0:
2691 return self
._int
[-1+self
._exp
] in '02468'
2694 """Return the adjusted exponent of self"""
2696 return self
._exp
+ len(self
._int
) - 1
2697 # If NaN or Infinity, self._exp is string
2701 def canonical(self
, context
=None):
2702 """Returns the same Decimal object.
2704 As we do not have different encodings for the same number, the
2705 received object already is in its canonical form.
2709 def compare_signal(self
, other
, context
=None):
2710 """Compares self to the other operand numerically.
2712 It's pretty much like compare(), but all NaNs signal, with signaling
2713 NaNs taking precedence over quiet NaNs.
2715 other
= _convert_other(other
, raiseit
= True)
2716 ans
= self
._compare
_check
_nans
(other
, context
)
2719 return self
.compare(other
, context
=context
)
2721 def compare_total(self
, other
):
2722 """Compares self to other using the abstract representations.
2724 This is not like the standard compare, which use their numerical
2725 value. Note that a total ordering is defined for all possible abstract
2728 # if one is negative and the other is positive, it's easy
2729 if self
._sign
and not other
._sign
:
2731 if not self
._sign
and other
._sign
:
2735 # let's handle both NaN types
2736 self_nan
= self
._isnan
()
2737 other_nan
= other
._isnan
()
2738 if self_nan
or other_nan
:
2739 if self_nan
== other_nan
:
2740 if self
._int
< other
._int
:
2745 if self
._int
> other
._int
:
2776 if self
._exp
< other
._exp
:
2781 if self
._exp
> other
._exp
:
2789 def compare_total_mag(self
, other
):
2790 """Compares self to other using abstract repr., ignoring sign.
2792 Like compare_total, but with operand's sign ignored and assumed to be 0.
2795 o
= other
.copy_abs()
2796 return s
.compare_total(o
)
2799 """Returns a copy with the sign set to 0. """
2800 return _dec_from_triple(0, self
._int
, self
._exp
, self
._is
_special
)
2802 def copy_negate(self
):
2803 """Returns a copy with the sign inverted."""
2805 return _dec_from_triple(0, self
._int
, self
._exp
, self
._is
_special
)
2807 return _dec_from_triple(1, self
._int
, self
._exp
, self
._is
_special
)
2809 def copy_sign(self
, other
):
2810 """Returns self with the sign of other."""
2811 return _dec_from_triple(other
._sign
, self
._int
,
2812 self
._exp
, self
._is
_special
)
2814 def exp(self
, context
=None):
2815 """Returns e ** self."""
2818 context
= getcontext()
2821 ans
= self
._check
_nans
(context
=context
)
2825 # exp(-Infinity) = 0
2826 if self
._isinfinity
() == -1:
2833 # exp(Infinity) = Infinity
2834 if self
._isinfinity
() == 1:
2835 return Decimal(self
)
2837 # the result is now guaranteed to be inexact (the true
2838 # mathematical result is transcendental). There's no need to
2839 # raise Rounded and Inexact here---they'll always be raised as
2840 # a result of the call to _fix.
2842 adj
= self
.adjusted()
2844 # we only need to do any computation for quite a small range
2845 # of adjusted exponents---for example, -29 <= adj <= 10 for
2846 # the default context. For smaller exponent the result is
2847 # indistinguishable from 1 at the given precision, while for
2848 # larger exponent the result either overflows or underflows.
2849 if self
._sign
== 0 and adj
> len(str((context
.Emax
+1)*3)):
2851 ans
= _dec_from_triple(0, '1', context
.Emax
+1)
2852 elif self
._sign
== 1 and adj
> len(str((-context
.Etiny()+1)*3)):
2854 ans
= _dec_from_triple(0, '1', context
.Etiny()-1)
2855 elif self
._sign
== 0 and adj
< -p
:
2856 # p+1 digits; final round will raise correct flags
2857 ans
= _dec_from_triple(0, '1' + '0'*(p
-1) + '1', -p
)
2858 elif self
._sign
== 1 and adj
< -p
-1:
2859 # p+1 digits; final round will raise correct flags
2860 ans
= _dec_from_triple(0, '9'*(p
+1), -p
-1)
2864 c
, e
= op
.int, op
.exp
2868 # compute correctly rounded result: increase precision by
2869 # 3 digits at a time until we get an unambiguously
2873 coeff
, exp
= _dexp(c
, e
, p
+extra
)
2874 if coeff
% (5*10**(len(str(coeff
))-p
-1)):
2878 ans
= _dec_from_triple(0, str(coeff
), exp
)
2880 # at this stage, ans should round correctly with *any*
2881 # rounding mode, not just with ROUND_HALF_EVEN
2882 context
= context
._shallow
_copy
()
2883 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
2884 ans
= ans
._fix
(context
)
2885 context
.rounding
= rounding
2889 def is_canonical(self
):
2890 """Return True if self is canonical; otherwise return False.
2892 Currently, the encoding of a Decimal instance is always
2893 canonical, so this method returns True for any Decimal.
2897 def is_finite(self
):
2898 """Return True if self is finite; otherwise return False.
2900 A Decimal instance is considered finite if it is neither
2903 return not self
._is
_special
2905 def is_infinite(self
):
2906 """Return True if self is infinite; otherwise return False."""
2907 return self
._exp
== 'F'
2910 """Return True if self is a qNaN or sNaN; otherwise return False."""
2911 return self
._exp
in ('n', 'N')
2913 def is_normal(self
, context
=None):
2914 """Return True if self is a normal number; otherwise return False."""
2915 if self
._is
_special
or not self
:
2918 context
= getcontext()
2919 return context
.Emin
<= self
.adjusted() <= context
.Emax
2922 """Return True if self is a quiet NaN; otherwise return False."""
2923 return self
._exp
== 'n'
2925 def is_signed(self
):
2926 """Return True if self is negative; otherwise return False."""
2927 return self
._sign
== 1
2930 """Return True if self is a signaling NaN; otherwise return False."""
2931 return self
._exp
== 'N'
2933 def is_subnormal(self
, context
=None):
2934 """Return True if self is subnormal; otherwise return False."""
2935 if self
._is
_special
or not self
:
2938 context
= getcontext()
2939 return self
.adjusted() < context
.Emin
2942 """Return True if self is a zero; otherwise return False."""
2943 return not self
._is
_special
and self
._int
== '0'
2945 def _ln_exp_bound(self
):
2946 """Compute a lower bound for the adjusted exponent of self.ln().
2947 In other words, compute r such that self.ln() >= 10**r. Assumes
2948 that self is finite and positive and that self != 1.
2951 # for 0.1 <= x <= 10 we use the inequalities 1-1/x <= ln(x) <= x-1
2952 adj
= self
._exp
+ len(self
._int
) - 1
2954 # argument >= 10; we use 23/10 = 2.3 as a lower bound for ln(10)
2955 return len(str(adj
*23//10)) - 1
2958 return len(str((-1-adj
)*23//10)) - 1
2960 c
, e
= op
.int, op
.exp
2965 return len(num
) - len(den
) - (num
< den
)
2966 # adj == -1, 0.1 <= self < 1
2967 return e
+ len(str(10**-e
- c
)) - 1
2970 def ln(self
, context
=None):
2971 """Returns the natural (base e) logarithm of self."""
2974 context
= getcontext()
2977 ans
= self
._check
_nans
(context
=context
)
2981 # ln(0.0) == -Infinity
2983 return _NegativeInfinity
2985 # ln(Infinity) = Infinity
2986 if self
._isinfinity
() == 1:
2993 # ln(negative) raises InvalidOperation
2995 return context
._raise
_error
(InvalidOperation
,
2996 'ln of a negative value')
2998 # result is irrational, so necessarily inexact
3000 c
, e
= op
.int, op
.exp
3003 # correctly rounded result: repeatedly increase precision by 3
3004 # until we get an unambiguously roundable result
3005 places
= p
- self
._ln
_exp
_bound
() + 2 # at least p+3 places
3007 coeff
= _dlog(c
, e
, places
)
3008 # assert len(str(abs(coeff)))-p >= 1
3009 if coeff
% (5*10**(len(str(abs(coeff
)))-p
-1)):
3012 ans
= _dec_from_triple(int(coeff
<0), str(abs(coeff
)), -places
)
3014 context
= context
._shallow
_copy
()
3015 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
3016 ans
= ans
._fix
(context
)
3017 context
.rounding
= rounding
3020 def _log10_exp_bound(self
):
3021 """Compute a lower bound for the adjusted exponent of self.log10().
3022 In other words, find r such that self.log10() >= 10**r.
3023 Assumes that self is finite and positive and that self != 1.
3026 # For x >= 10 or x < 0.1 we only need a bound on the integer
3027 # part of log10(self), and this comes directly from the
3028 # exponent of x. For 0.1 <= x <= 10 we use the inequalities
3029 # 1-1/x <= log(x) <= x-1. If x > 1 we have |log10(x)| >
3030 # (1-1/x)/2.31 > 0. If x < 1 then |log10(x)| > (1-x)/2.31 > 0
3032 adj
= self
._exp
+ len(self
._int
) - 1
3035 return len(str(adj
))-1
3038 return len(str(-1-adj
))-1
3040 c
, e
= op
.int, op
.exp
3045 return len(num
) - len(den
) - (num
< den
) + 2
3046 # adj == -1, 0.1 <= self < 1
3048 return len(num
) + e
- (num
< "231") - 1
3050 def log10(self
, context
=None):
3051 """Returns the base 10 logarithm of self."""
3054 context
= getcontext()
3057 ans
= self
._check
_nans
(context
=context
)
3061 # log10(0.0) == -Infinity
3063 return _NegativeInfinity
3065 # log10(Infinity) = Infinity
3066 if self
._isinfinity
() == 1:
3069 # log10(negative or -Infinity) raises InvalidOperation
3071 return context
._raise
_error
(InvalidOperation
,
3072 'log10 of a negative value')
3075 if self
._int
[0] == '1' and self
._int
[1:] == '0'*(len(self
._int
) - 1):
3076 # answer may need rounding
3077 ans
= Decimal(self
._exp
+ len(self
._int
) - 1)
3079 # result is irrational, so necessarily inexact
3081 c
, e
= op
.int, op
.exp
3084 # correctly rounded result: repeatedly increase precision
3085 # until result is unambiguously roundable
3086 places
= p
-self
._log
10_exp
_bound
()+2
3088 coeff
= _dlog10(c
, e
, places
)
3089 # assert len(str(abs(coeff)))-p >= 1
3090 if coeff
% (5*10**(len(str(abs(coeff
)))-p
-1)):
3093 ans
= _dec_from_triple(int(coeff
<0), str(abs(coeff
)), -places
)
3095 context
= context
._shallow
_copy
()
3096 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
3097 ans
= ans
._fix
(context
)
3098 context
.rounding
= rounding
3101 def logb(self
, context
=None):
3102 """ Returns the exponent of the magnitude of self's MSD.
3104 The result is the integer which is the exponent of the magnitude
3105 of the most significant digit of self (as though it were truncated
3106 to a single digit while maintaining the value of that digit and
3107 without limiting the resulting exponent).
3110 ans
= self
._check
_nans
(context
=context
)
3115 context
= getcontext()
3117 # logb(+/-Inf) = +Inf
3118 if self
._isinfinity
():
3121 # logb(0) = -Inf, DivisionByZero
3123 return context
._raise
_error
(DivisionByZero
, 'logb(0)', 1)
3125 # otherwise, simply return the adjusted exponent of self, as a
3126 # Decimal. Note that no attempt is made to fit the result
3127 # into the current context.
3128 return Decimal(self
.adjusted())
3130 def _islogical(self
):
3131 """Return True if self is a logical operand.
3133 For being logical, it must be a finite number with a sign of 0,
3134 an exponent of 0, and a coefficient whose digits must all be
3137 if self
._sign
!= 0 or self
._exp
!= 0:
3139 for dig
in self
._int
:
3144 def _fill_logical(self
, context
, opa
, opb
):
3145 dif
= context
.prec
- len(opa
)
3149 opa
= opa
[-context
.prec
:]
3150 dif
= context
.prec
- len(opb
)
3154 opb
= opb
[-context
.prec
:]
3157 def logical_and(self
, other
, context
=None):
3158 """Applies an 'and' operation between self and other's digits."""
3160 context
= getcontext()
3161 if not self
._islogical
() or not other
._islogical
():
3162 return context
._raise
_error
(InvalidOperation
)
3164 # fill to context.prec
3165 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3167 # make the operation, and clean starting zeroes
3168 result
= "".join([str(int(a
)&int(b
)) for a
,b
in zip(opa
,opb
)])
3169 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3171 def logical_invert(self
, context
=None):
3172 """Invert all its digits."""
3174 context
= getcontext()
3175 return self
.logical_xor(_dec_from_triple(0,'1'*context
.prec
,0),
3178 def logical_or(self
, other
, context
=None):
3179 """Applies an 'or' operation between self and other's digits."""
3181 context
= getcontext()
3182 if not self
._islogical
() or not other
._islogical
():
3183 return context
._raise
_error
(InvalidOperation
)
3185 # fill to context.prec
3186 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3188 # make the operation, and clean starting zeroes
3189 result
= "".join([str(int(a
)|
int(b
)) for a
,b
in zip(opa
,opb
)])
3190 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3192 def logical_xor(self
, other
, context
=None):
3193 """Applies an 'xor' operation between self and other's digits."""
3195 context
= getcontext()
3196 if not self
._islogical
() or not other
._islogical
():
3197 return context
._raise
_error
(InvalidOperation
)
3199 # fill to context.prec
3200 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3202 # make the operation, and clean starting zeroes
3203 result
= "".join([str(int(a
)^
int(b
)) for a
,b
in zip(opa
,opb
)])
3204 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3206 def max_mag(self
, other
, context
=None):
3207 """Compares the values numerically with their sign ignored."""
3208 other
= _convert_other(other
, raiseit
=True)
3211 context
= getcontext()
3213 if self
._is
_special
or other
._is
_special
:
3214 # If one operand is a quiet NaN and the other is number, then the
3215 # number is always returned
3219 if on
== 1 and sn
== 0:
3220 return self
._fix
(context
)
3221 if sn
== 1 and on
== 0:
3222 return other
._fix
(context
)
3223 return self
._check
_nans
(other
, context
)
3225 c
= self
.copy_abs()._cmp
(other
.copy_abs())
3227 c
= self
.compare_total(other
)
3234 return ans
._fix
(context
)
3236 def min_mag(self
, other
, context
=None):
3237 """Compares the values numerically with their sign ignored."""
3238 other
= _convert_other(other
, raiseit
=True)
3241 context
= getcontext()
3243 if self
._is
_special
or other
._is
_special
:
3244 # If one operand is a quiet NaN and the other is number, then the
3245 # number is always returned
3249 if on
== 1 and sn
== 0:
3250 return self
._fix
(context
)
3251 if sn
== 1 and on
== 0:
3252 return other
._fix
(context
)
3253 return self
._check
_nans
(other
, context
)
3255 c
= self
.copy_abs()._cmp
(other
.copy_abs())
3257 c
= self
.compare_total(other
)
3264 return ans
._fix
(context
)
3266 def next_minus(self
, context
=None):
3267 """Returns the largest representable number smaller than itself."""
3269 context
= getcontext()
3271 ans
= self
._check
_nans
(context
=context
)
3275 if self
._isinfinity
() == -1:
3276 return _NegativeInfinity
3277 if self
._isinfinity
() == 1:
3278 return _dec_from_triple(0, '9'*context
.prec
, context
.Etop())
3280 context
= context
.copy()
3281 context
._set
_rounding
(ROUND_FLOOR
)
3282 context
._ignore
_all
_flags
()
3283 new_self
= self
._fix
(context
)
3284 if new_self
!= self
:
3286 return self
.__sub
__(_dec_from_triple(0, '1', context
.Etiny()-1),
3289 def next_plus(self
, context
=None):
3290 """Returns the smallest representable number larger than itself."""
3292 context
= getcontext()
3294 ans
= self
._check
_nans
(context
=context
)
3298 if self
._isinfinity
() == 1:
3300 if self
._isinfinity
() == -1:
3301 return _dec_from_triple(1, '9'*context
.prec
, context
.Etop())
3303 context
= context
.copy()
3304 context
._set
_rounding
(ROUND_CEILING
)
3305 context
._ignore
_all
_flags
()
3306 new_self
= self
._fix
(context
)
3307 if new_self
!= self
:
3309 return self
.__add
__(_dec_from_triple(0, '1', context
.Etiny()-1),
3312 def next_toward(self
, other
, context
=None):
3313 """Returns the number closest to self, in the direction towards other.
3315 The result is the closest representable number to self
3316 (excluding self) that is in the direction towards other,
3317 unless both have the same value. If the two operands are
3318 numerically equal, then the result is a copy of self with the
3319 sign set to be the same as the sign of other.
3321 other
= _convert_other(other
, raiseit
=True)
3324 context
= getcontext()
3326 ans
= self
._check
_nans
(other
, context
)
3330 comparison
= self
._cmp
(other
)
3332 return self
.copy_sign(other
)
3334 if comparison
== -1:
3335 ans
= self
.next_plus(context
)
3336 else: # comparison == 1
3337 ans
= self
.next_minus(context
)
3339 # decide which flags to raise using value of ans
3340 if ans
._isinfinity
():
3341 context
._raise
_error
(Overflow
,
3342 'Infinite result from next_toward',
3344 context
._raise
_error
(Rounded
)
3345 context
._raise
_error
(Inexact
)
3346 elif ans
.adjusted() < context
.Emin
:
3347 context
._raise
_error
(Underflow
)
3348 context
._raise
_error
(Subnormal
)
3349 context
._raise
_error
(Rounded
)
3350 context
._raise
_error
(Inexact
)
3351 # if precision == 1 then we don't raise Clamped for a
3354 context
._raise
_error
(Clamped
)
3358 def number_class(self
, context
=None):
3359 """Returns an indication of the class of self.
3361 The class is one of the following strings:
3377 inf
= self
._isinfinity
()
3388 context
= getcontext()
3389 if self
.is_subnormal(context
=context
):
3394 # just a normal, regular, boring number, :)
3401 """Just returns 10, as this is Decimal, :)"""
3404 def rotate(self
, other
, context
=None):
3405 """Returns a rotated copy of self, value-of-other times."""
3407 context
= getcontext()
3409 ans
= self
._check
_nans
(other
, context
)
3414 return context
._raise
_error
(InvalidOperation
)
3415 if not (-context
.prec
<= int(other
) <= context
.prec
):
3416 return context
._raise
_error
(InvalidOperation
)
3418 if self
._isinfinity
():
3419 return Decimal(self
)
3421 # get values, pad if necessary
3424 topad
= context
.prec
- len(rotdig
)
3426 rotdig
= '0'*topad
+ rotdig
3429 rotated
= rotdig
[torot
:] + rotdig
[:torot
]
3430 return _dec_from_triple(self
._sign
,
3431 rotated
.lstrip('0') or '0', self
._exp
)
3433 def scaleb (self
, other
, context
=None):
3434 """Returns self operand after adding the second value to its exp."""
3436 context
= getcontext()
3438 ans
= self
._check
_nans
(other
, context
)
3443 return context
._raise
_error
(InvalidOperation
)
3444 liminf
= -2 * (context
.Emax
+ context
.prec
)
3445 limsup
= 2 * (context
.Emax
+ context
.prec
)
3446 if not (liminf
<= int(other
) <= limsup
):
3447 return context
._raise
_error
(InvalidOperation
)
3449 if self
._isinfinity
():
3450 return Decimal(self
)
3452 d
= _dec_from_triple(self
._sign
, self
._int
, self
._exp
+ int(other
))
3456 def shift(self
, other
, context
=None):
3457 """Returns a shifted copy of self, value-of-other times."""
3459 context
= getcontext()
3461 ans
= self
._check
_nans
(other
, context
)
3466 return context
._raise
_error
(InvalidOperation
)
3467 if not (-context
.prec
<= int(other
) <= context
.prec
):
3468 return context
._raise
_error
(InvalidOperation
)
3470 if self
._isinfinity
():
3471 return Decimal(self
)
3473 # get values, pad if necessary
3476 return Decimal(self
)
3478 topad
= context
.prec
- len(rotdig
)
3480 rotdig
= '0'*topad
+ rotdig
3484 rotated
= rotdig
[:torot
]
3486 rotated
= rotdig
+ '0'*torot
3487 rotated
= rotated
[-context
.prec
:]
3489 return _dec_from_triple(self
._sign
,
3490 rotated
.lstrip('0') or '0', self
._exp
)
3492 # Support for pickling, copy, and deepcopy
3493 def __reduce__(self
):
3494 return (self
.__class
__, (str(self
),))
3497 if type(self
) == Decimal
:
3498 return self
# I'm immutable; therefore I am my own clone
3499 return self
.__class
__(str(self
))
3501 def __deepcopy__(self
, memo
):
3502 if type(self
) == Decimal
:
3503 return self
# My components are also immutable
3504 return self
.__class
__(str(self
))
3506 # PEP 3101 support. See also _parse_format_specifier and _format_align
3507 def __format__(self
, specifier
, context
=None):
3508 """Format a Decimal instance according to the given specifier.
3510 The specifier should be a standard format specifier, with the
3511 form described in PEP 3101. Formatting types 'e', 'E', 'f',
3512 'F', 'g', 'G', and '%' are supported. If the formatting type
3513 is omitted it defaults to 'g' or 'G', depending on the value
3514 of context.capitals.
3516 At this time the 'n' format specifier type (which is supposed
3517 to use the current locale) is not supported.
3520 # Note: PEP 3101 says that if the type is not present then
3521 # there should be at least one digit after the decimal point.
3522 # We take the liberty of ignoring this requirement for
3523 # Decimal---it's presumably there to make sure that
3524 # format(float, '') behaves similarly to str(float).
3526 context
= getcontext()
3528 spec
= _parse_format_specifier(specifier
)
3530 # special values don't care about the type or precision...
3531 if self
._is
_special
:
3532 return _format_align(str(self
), spec
)
3534 # a type of None defaults to 'g' or 'G', depending on context
3535 # if type is '%', adjust exponent of self accordingly
3536 if spec
['type'] is None:
3537 spec
['type'] = ['g', 'G'][context
.capitals
]
3538 elif spec
['type'] == '%':
3539 self
= _dec_from_triple(self
._sign
, self
._int
, self
._exp
+2)
3541 # round if necessary, taking rounding mode from the context
3542 rounding
= context
.rounding
3543 precision
= spec
['precision']
3544 if precision
is not None:
3545 if spec
['type'] in 'eE':
3546 self
= self
._round
(precision
+1, rounding
)
3547 elif spec
['type'] in 'gG':
3548 if len(self
._int
) > precision
:
3549 self
= self
._round
(precision
, rounding
)
3550 elif spec
['type'] in 'fF%':
3551 self
= self
._rescale
(-precision
, rounding
)
3552 # special case: zeros with a positive exponent can't be
3553 # represented in fixed point; rescale them to 0e0.
3554 elif not self
and self
._exp
> 0 and spec
['type'] in 'fF%':
3555 self
= self
._rescale
(0, rounding
)
3557 # figure out placement of the decimal point
3558 leftdigits
= self
._exp
+ len(self
._int
)
3559 if spec
['type'] in 'fF%':
3560 dotplace
= leftdigits
3561 elif spec
['type'] in 'eE':
3562 if not self
and precision
is not None:
3563 dotplace
= 1 - precision
3566 elif spec
['type'] in 'gG':
3567 if self
._exp
<= 0 and leftdigits
> -6:
3568 dotplace
= leftdigits
3572 # figure out main part of numeric string...
3574 num
= '0.' + '0'*(-dotplace
) + self
._int
3575 elif dotplace
>= len(self
._int
):
3576 # make sure we're not padding a '0' with extra zeros on the right
3577 assert dotplace
==len(self
._int
) or self
._int
!= '0'
3578 num
= self
._int
+ '0'*(dotplace
-len(self
._int
))
3580 num
= self
._int
[:dotplace
] + '.' + self
._int
[dotplace
:]
3582 # ...then the trailing exponent, or trailing '%'
3583 if leftdigits
!= dotplace
or spec
['type'] in 'eE':
3584 echar
= {'E': 'E', 'e': 'e', 'G': 'E', 'g': 'e'}[spec
['type']]
3585 num
= num
+ "{0}{1:+}".format(echar
, leftdigits
-dotplace
)
3586 elif spec
['type'] == '%':
3592 return _format_align(num
, spec
)
3595 def _dec_from_triple(sign
, coefficient
, exponent
, special
=False):
3596 """Create a decimal instance directly, without any validation,
3597 normalization (e.g. removal of leading zeros) or argument
3600 This function is for *internal use only*.
3603 self
= object.__new
__(Decimal
)
3605 self
._int
= coefficient
3606 self
._exp
= exponent
3607 self
._is
_special
= special
3611 ##### Context class #######################################################
3614 # get rounding method function:
3615 rounding_functions
= [name
for name
in Decimal
.__dict
__.keys()
3616 if name
.startswith('_round_')]
3617 for name
in rounding_functions
:
3618 # name is like _round_half_even, goes to the global ROUND_HALF_EVEN value.
3619 globalname
= name
[1:].upper()
3620 val
= globals()[globalname
]
3621 Decimal
._pick
_rounding
_function
[val
] = name
3623 del name
, val
, globalname
, rounding_functions
3625 class _ContextManager(object):
3626 """Context manager class to support localcontext().
3628 Sets a copy of the supplied context in __enter__() and restores
3629 the previous decimal context in __exit__()
3631 def __init__(self
, new_context
):
3632 self
.new_context
= new_context
.copy()
3633 def __enter__(self
):
3634 self
.saved_context
= getcontext()
3635 setcontext(self
.new_context
)
3636 return self
.new_context
3637 def __exit__(self
, t
, v
, tb
):
3638 setcontext(self
.saved_context
)
3640 class Context(object):
3641 """Contains the context for a Decimal instance.
3644 prec - precision (for use in rounding, division, square roots..)
3645 rounding - rounding type (how you round)
3646 traps - If traps[exception] = 1, then the exception is
3647 raised when it is caused. Otherwise, a value is
3649 flags - When an exception is caused, flags[exception] is set.
3650 (Whether or not the trap_enabler is set)
3651 Should be reset by user of Decimal instance.
3652 Emin - Minimum exponent
3653 Emax - Maximum exponent
3654 capitals - If 1, 1*10^1 is printed as 1E+1.
3655 If 0, printed as 1e1
3656 _clamp - If 1, change exponents if too high (Default 0)
3659 def __init__(self
, prec
=None, rounding
=None,
3660 traps
=None, flags
=None,
3661 Emin
=None, Emax
=None,
3662 capitals
=None, _clamp
=0,
3663 _ignored_flags
=None):
3666 if _ignored_flags
is None:
3668 if not isinstance(flags
, dict):
3669 flags
= dict([(s
, int(s
in flags
)) for s
in _signals
])
3671 if traps
is not None and not isinstance(traps
, dict):
3672 traps
= dict([(s
, int(s
in traps
)) for s
in _signals
])
3674 for name
, val
in locals().items():
3676 setattr(self
, name
, _copy
.copy(getattr(DefaultContext
, name
)))
3678 setattr(self
, name
, val
)
3682 """Show the current context."""
3684 s
.append('Context(prec=%(prec)d, rounding=%(rounding)s, '
3685 'Emin=%(Emin)d, Emax=%(Emax)d, capitals=%(capitals)d'
3687 names
= [f
.__name
__ for f
, v
in self
.flags
.items() if v
]
3688 s
.append('flags=[' + ', '.join(names
) + ']')
3689 names
= [t
.__name
__ for t
, v
in self
.traps
.items() if v
]
3690 s
.append('traps=[' + ', '.join(names
) + ']')
3691 return ', '.join(s
) + ')'
3693 def clear_flags(self
):
3694 """Reset all flags to zero"""
3695 for flag
in self
.flags
:
3696 self
.flags
[flag
] = 0
3698 def _shallow_copy(self
):
3699 """Returns a shallow copy from self."""
3700 nc
= Context(self
.prec
, self
.rounding
, self
.traps
,
3701 self
.flags
, self
.Emin
, self
.Emax
,
3702 self
.capitals
, self
._clamp
, self
._ignored
_flags
)
3706 """Returns a deep copy from self."""
3707 nc
= Context(self
.prec
, self
.rounding
, self
.traps
.copy(),
3708 self
.flags
.copy(), self
.Emin
, self
.Emax
,
3709 self
.capitals
, self
._clamp
, self
._ignored
_flags
)
3713 def _raise_error(self
, condition
, explanation
= None, *args
):
3716 If the flag is in _ignored_flags, returns the default response.
3717 Otherwise, it sets the flag, then, if the corresponding
3718 trap_enabler is set, it reaises the exception. Otherwise, it returns
3719 the default value after setting the flag.
3721 error
= _condition_map
.get(condition
, condition
)
3722 if error
in self
._ignored
_flags
:
3723 # Don't touch the flag
3724 return error().handle(self
, *args
)
3726 self
.flags
[error
] = 1
3727 if not self
.traps
[error
]:
3728 # The errors define how to handle themselves.
3729 return condition().handle(self
, *args
)
3731 # Errors should only be risked on copies of the context
3732 # self._ignored_flags = []
3733 raise error(explanation
)
3735 def _ignore_all_flags(self
):
3736 """Ignore all flags, if they are raised"""
3737 return self
._ignore
_flags
(*_signals
)
3739 def _ignore_flags(self
, *flags
):
3740 """Ignore the flags, if they are raised"""
3741 # Do not mutate-- This way, copies of a context leave the original
3743 self
._ignored
_flags
= (self
._ignored
_flags
+ list(flags
))
3746 def _regard_flags(self
, *flags
):
3747 """Stop ignoring the flags, if they are raised"""
3748 if flags
and isinstance(flags
[0], (tuple,list)):
3751 self
._ignored
_flags
.remove(flag
)
3753 # We inherit object.__hash__, so we must deny this explicitly
3757 """Returns Etiny (= Emin - prec + 1)"""
3758 return int(self
.Emin
- self
.prec
+ 1)
3761 """Returns maximum exponent (= Emax - prec + 1)"""
3762 return int(self
.Emax
- self
.prec
+ 1)
3764 def _set_rounding(self
, type):
3765 """Sets the rounding type.
3767 Sets the rounding type, and returns the current (previous)
3768 rounding type. Often used like:
3770 context = context.copy()
3771 # so you don't change the calling context
3772 # if an error occurs in the middle.
3773 rounding = context._set_rounding(ROUND_UP)
3774 val = self.__sub__(other, context=context)
3775 context._set_rounding(rounding)
3777 This will make it round up for that operation.
3779 rounding
= self
.rounding
3783 def create_decimal(self
, num
='0'):
3784 """Creates a new Decimal instance but using self as context.
3786 This method implements the to-number operation of the
3787 IBM Decimal specification."""
3789 if isinstance(num
, basestring
) and num
!= num
.strip():
3790 return self
._raise
_error
(ConversionSyntax
,
3791 "no trailing or leading whitespace is "
3794 d
= Decimal(num
, context
=self
)
3795 if d
._isnan
() and len(d
._int
) > self
.prec
- self
._clamp
:
3796 return self
._raise
_error
(ConversionSyntax
,
3797 "diagnostic info too long in NaN")
3800 def create_decimal_from_float(self
, f
):
3801 """Creates a new Decimal instance from a float but rounding using self
3804 >>> context = Context(prec=5, rounding=ROUND_DOWN)
3805 >>> context.create_decimal_from_float(3.1415926535897932)
3807 >>> context = Context(prec=5, traps=[Inexact])
3808 >>> context.create_decimal_from_float(3.1415926535897932)
3809 Traceback (most recent call last):
3814 d
= Decimal
.from_float(f
) # An exact conversion
3815 return d
._fix
(self
) # Apply the context rounding
3819 """Returns the absolute value of the operand.
3821 If the operand is negative, the result is the same as using the minus
3822 operation on the operand. Otherwise, the result is the same as using
3823 the plus operation on the operand.
3825 >>> ExtendedContext.abs(Decimal('2.1'))
3827 >>> ExtendedContext.abs(Decimal('-100'))
3829 >>> ExtendedContext.abs(Decimal('101.5'))
3831 >>> ExtendedContext.abs(Decimal('-101.5'))
3834 return a
.__abs
__(context
=self
)
3836 def add(self
, a
, b
):
3837 """Return the sum of the two operands.
3839 >>> ExtendedContext.add(Decimal('12'), Decimal('7.00'))
3841 >>> ExtendedContext.add(Decimal('1E+2'), Decimal('1.01E+4'))
3844 return a
.__add
__(b
, context
=self
)
3846 def _apply(self
, a
):
3847 return str(a
._fix
(self
))
3849 def canonical(self
, a
):
3850 """Returns the same Decimal object.
3852 As we do not have different encodings for the same number, the
3853 received object already is in its canonical form.
3855 >>> ExtendedContext.canonical(Decimal('2.50'))
3858 return a
.canonical(context
=self
)
3860 def compare(self
, a
, b
):
3861 """Compares values numerically.
3863 If the signs of the operands differ, a value representing each operand
3864 ('-1' if the operand is less than zero, '0' if the operand is zero or
3865 negative zero, or '1' if the operand is greater than zero) is used in
3866 place of that operand for the comparison instead of the actual
3869 The comparison is then effected by subtracting the second operand from
3870 the first and then returning a value according to the result of the
3871 subtraction: '-1' if the result is less than zero, '0' if the result is
3872 zero or negative zero, or '1' if the result is greater than zero.
3874 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
3876 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
3878 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))
3880 >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))
3882 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))
3884 >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))
3887 return a
.compare(b
, context
=self
)
3889 def compare_signal(self
, a
, b
):
3890 """Compares the values of the two operands numerically.
3892 It's pretty much like compare(), but all NaNs signal, with signaling
3893 NaNs taking precedence over quiet NaNs.
3895 >>> c = ExtendedContext
3896 >>> c.compare_signal(Decimal('2.1'), Decimal('3'))
3898 >>> c.compare_signal(Decimal('2.1'), Decimal('2.1'))
3900 >>> c.flags[InvalidOperation] = 0
3901 >>> print c.flags[InvalidOperation]
3903 >>> c.compare_signal(Decimal('NaN'), Decimal('2.1'))
3905 >>> print c.flags[InvalidOperation]
3907 >>> c.flags[InvalidOperation] = 0
3908 >>> print c.flags[InvalidOperation]
3910 >>> c.compare_signal(Decimal('sNaN'), Decimal('2.1'))
3912 >>> print c.flags[InvalidOperation]
3915 return a
.compare_signal(b
, context
=self
)
3917 def compare_total(self
, a
, b
):
3918 """Compares two operands using their abstract representation.
3920 This is not like the standard compare, which use their numerical
3921 value. Note that a total ordering is defined for all possible abstract
3924 >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
3926 >>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12'))
3928 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))
3930 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))
3932 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300'))
3934 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN'))
3937 return a
.compare_total(b
)
3939 def compare_total_mag(self
, a
, b
):
3940 """Compares two operands using their abstract representation ignoring sign.
3942 Like compare_total, but with operand's sign ignored and assumed to be 0.
3944 return a
.compare_total_mag(b
)
3946 def copy_abs(self
, a
):
3947 """Returns a copy of the operand with the sign set to 0.
3949 >>> ExtendedContext.copy_abs(Decimal('2.1'))
3951 >>> ExtendedContext.copy_abs(Decimal('-100'))
3956 def copy_decimal(self
, a
):
3957 """Returns a copy of the decimal objet.
3959 >>> ExtendedContext.copy_decimal(Decimal('2.1'))
3961 >>> ExtendedContext.copy_decimal(Decimal('-1.00'))
3966 def copy_negate(self
, a
):
3967 """Returns a copy of the operand with the sign inverted.
3969 >>> ExtendedContext.copy_negate(Decimal('101.5'))
3971 >>> ExtendedContext.copy_negate(Decimal('-101.5'))
3974 return a
.copy_negate()
3976 def copy_sign(self
, a
, b
):
3977 """Copies the second operand's sign to the first one.
3979 In detail, it returns a copy of the first operand with the sign
3980 equal to the sign of the second operand.
3982 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))
3984 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))
3986 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))
3988 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))
3991 return a
.copy_sign(b
)
3993 def divide(self
, a
, b
):
3994 """Decimal division in a specified context.
3996 >>> ExtendedContext.divide(Decimal('1'), Decimal('3'))
3997 Decimal('0.333333333')
3998 >>> ExtendedContext.divide(Decimal('2'), Decimal('3'))
3999 Decimal('0.666666667')
4000 >>> ExtendedContext.divide(Decimal('5'), Decimal('2'))
4002 >>> ExtendedContext.divide(Decimal('1'), Decimal('10'))
4004 >>> ExtendedContext.divide(Decimal('12'), Decimal('12'))
4006 >>> ExtendedContext.divide(Decimal('8.00'), Decimal('2'))
4008 >>> ExtendedContext.divide(Decimal('2.400'), Decimal('2.0'))
4010 >>> ExtendedContext.divide(Decimal('1000'), Decimal('100'))
4012 >>> ExtendedContext.divide(Decimal('1000'), Decimal('1'))
4014 >>> ExtendedContext.divide(Decimal('2.40E+6'), Decimal('2'))
4017 return a
.__div
__(b
, context
=self
)
4019 def divide_int(self
, a
, b
):
4020 """Divides two numbers and returns the integer part of the result.
4022 >>> ExtendedContext.divide_int(Decimal('2'), Decimal('3'))
4024 >>> ExtendedContext.divide_int(Decimal('10'), Decimal('3'))
4026 >>> ExtendedContext.divide_int(Decimal('1'), Decimal('0.3'))
4029 return a
.__floordiv
__(b
, context
=self
)
4031 def divmod(self
, a
, b
):
4032 return a
.__divmod
__(b
, context
=self
)
4037 >>> c = ExtendedContext.copy()
4040 >>> c.exp(Decimal('-Infinity'))
4042 >>> c.exp(Decimal('-1'))
4043 Decimal('0.367879441')
4044 >>> c.exp(Decimal('0'))
4046 >>> c.exp(Decimal('1'))
4047 Decimal('2.71828183')
4048 >>> c.exp(Decimal('0.693147181'))
4049 Decimal('2.00000000')
4050 >>> c.exp(Decimal('+Infinity'))
4053 return a
.exp(context
=self
)
4055 def fma(self
, a
, b
, c
):
4056 """Returns a multiplied by b, plus c.
4058 The first two operands are multiplied together, using multiply,
4059 the third operand is then added to the result of that
4060 multiplication, using add, all with only one final rounding.
4062 >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
4064 >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))
4066 >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578'))
4067 Decimal('1.38435736E+12')
4069 return a
.fma(b
, c
, context
=self
)
4071 def is_canonical(self
, a
):
4072 """Return True if the operand is canonical; otherwise return False.
4074 Currently, the encoding of a Decimal instance is always
4075 canonical, so this method returns True for any Decimal.
4077 >>> ExtendedContext.is_canonical(Decimal('2.50'))
4080 return a
.is_canonical()
4082 def is_finite(self
, a
):
4083 """Return True if the operand is finite; otherwise return False.
4085 A Decimal instance is considered finite if it is neither
4088 >>> ExtendedContext.is_finite(Decimal('2.50'))
4090 >>> ExtendedContext.is_finite(Decimal('-0.3'))
4092 >>> ExtendedContext.is_finite(Decimal('0'))
4094 >>> ExtendedContext.is_finite(Decimal('Inf'))
4096 >>> ExtendedContext.is_finite(Decimal('NaN'))
4099 return a
.is_finite()
4101 def is_infinite(self
, a
):
4102 """Return True if the operand is infinite; otherwise return False.
4104 >>> ExtendedContext.is_infinite(Decimal('2.50'))
4106 >>> ExtendedContext.is_infinite(Decimal('-Inf'))
4108 >>> ExtendedContext.is_infinite(Decimal('NaN'))
4111 return a
.is_infinite()
4113 def is_nan(self
, a
):
4114 """Return True if the operand is a qNaN or sNaN;
4115 otherwise return False.
4117 >>> ExtendedContext.is_nan(Decimal('2.50'))
4119 >>> ExtendedContext.is_nan(Decimal('NaN'))
4121 >>> ExtendedContext.is_nan(Decimal('-sNaN'))
4126 def is_normal(self
, a
):
4127 """Return True if the operand is a normal number;
4128 otherwise return False.
4130 >>> c = ExtendedContext.copy()
4133 >>> c.is_normal(Decimal('2.50'))
4135 >>> c.is_normal(Decimal('0.1E-999'))
4137 >>> c.is_normal(Decimal('0.00'))
4139 >>> c.is_normal(Decimal('-Inf'))
4141 >>> c.is_normal(Decimal('NaN'))
4144 return a
.is_normal(context
=self
)
4146 def is_qnan(self
, a
):
4147 """Return True if the operand is a quiet NaN; otherwise return False.
4149 >>> ExtendedContext.is_qnan(Decimal('2.50'))
4151 >>> ExtendedContext.is_qnan(Decimal('NaN'))
4153 >>> ExtendedContext.is_qnan(Decimal('sNaN'))
4158 def is_signed(self
, a
):
4159 """Return True if the operand is negative; otherwise return False.
4161 >>> ExtendedContext.is_signed(Decimal('2.50'))
4163 >>> ExtendedContext.is_signed(Decimal('-12'))
4165 >>> ExtendedContext.is_signed(Decimal('-0'))
4168 return a
.is_signed()
4170 def is_snan(self
, a
):
4171 """Return True if the operand is a signaling NaN;
4172 otherwise return False.
4174 >>> ExtendedContext.is_snan(Decimal('2.50'))
4176 >>> ExtendedContext.is_snan(Decimal('NaN'))
4178 >>> ExtendedContext.is_snan(Decimal('sNaN'))
4183 def is_subnormal(self
, a
):
4184 """Return True if the operand is subnormal; otherwise return False.
4186 >>> c = ExtendedContext.copy()
4189 >>> c.is_subnormal(Decimal('2.50'))
4191 >>> c.is_subnormal(Decimal('0.1E-999'))
4193 >>> c.is_subnormal(Decimal('0.00'))
4195 >>> c.is_subnormal(Decimal('-Inf'))
4197 >>> c.is_subnormal(Decimal('NaN'))
4200 return a
.is_subnormal(context
=self
)
4202 def is_zero(self
, a
):
4203 """Return True if the operand is a zero; otherwise return False.
4205 >>> ExtendedContext.is_zero(Decimal('0'))
4207 >>> ExtendedContext.is_zero(Decimal('2.50'))
4209 >>> ExtendedContext.is_zero(Decimal('-0E+2'))
4215 """Returns the natural (base e) logarithm of the operand.
4217 >>> c = ExtendedContext.copy()
4220 >>> c.ln(Decimal('0'))
4221 Decimal('-Infinity')
4222 >>> c.ln(Decimal('1.000'))
4224 >>> c.ln(Decimal('2.71828183'))
4225 Decimal('1.00000000')
4226 >>> c.ln(Decimal('10'))
4227 Decimal('2.30258509')
4228 >>> c.ln(Decimal('+Infinity'))
4231 return a
.ln(context
=self
)
4234 """Returns the base 10 logarithm of the operand.
4236 >>> c = ExtendedContext.copy()
4239 >>> c.log10(Decimal('0'))
4240 Decimal('-Infinity')
4241 >>> c.log10(Decimal('0.001'))
4243 >>> c.log10(Decimal('1.000'))
4245 >>> c.log10(Decimal('2'))
4246 Decimal('0.301029996')
4247 >>> c.log10(Decimal('10'))
4249 >>> c.log10(Decimal('70'))
4250 Decimal('1.84509804')
4251 >>> c.log10(Decimal('+Infinity'))
4254 return a
.log10(context
=self
)
4257 """ Returns the exponent of the magnitude of the operand's MSD.
4259 The result is the integer which is the exponent of the magnitude
4260 of the most significant digit of the operand (as though the
4261 operand were truncated to a single digit while maintaining the
4262 value of that digit and without limiting the resulting exponent).
4264 >>> ExtendedContext.logb(Decimal('250'))
4266 >>> ExtendedContext.logb(Decimal('2.50'))
4268 >>> ExtendedContext.logb(Decimal('0.03'))
4270 >>> ExtendedContext.logb(Decimal('0'))
4271 Decimal('-Infinity')
4273 return a
.logb(context
=self
)
4275 def logical_and(self
, a
, b
):
4276 """Applies the logical operation 'and' between each operand's digits.
4278 The operands must be both logical numbers.
4280 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))
4282 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))
4284 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))
4286 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))
4288 >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))
4290 >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))
4293 return a
.logical_and(b
, context
=self
)
4295 def logical_invert(self
, a
):
4296 """Invert all the digits in the operand.
4298 The operand must be a logical number.
4300 >>> ExtendedContext.logical_invert(Decimal('0'))
4301 Decimal('111111111')
4302 >>> ExtendedContext.logical_invert(Decimal('1'))
4303 Decimal('111111110')
4304 >>> ExtendedContext.logical_invert(Decimal('111111111'))
4306 >>> ExtendedContext.logical_invert(Decimal('101010101'))
4309 return a
.logical_invert(context
=self
)
4311 def logical_or(self
, a
, b
):
4312 """Applies the logical operation 'or' between each operand's digits.
4314 The operands must be both logical numbers.
4316 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))
4318 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))
4320 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))
4322 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))
4324 >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))
4326 >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))
4329 return a
.logical_or(b
, context
=self
)
4331 def logical_xor(self
, a
, b
):
4332 """Applies the logical operation 'xor' between each operand's digits.
4334 The operands must be both logical numbers.
4336 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))
4338 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))
4340 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))
4342 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))
4344 >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))
4346 >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))
4349 return a
.logical_xor(b
, context
=self
)
4352 """max compares two values numerically and returns the maximum.
4354 If either operand is a NaN then the general rules apply.
4355 Otherwise, the operands are compared as though by the compare
4356 operation. If they are numerically equal then the left-hand operand
4357 is chosen as the result. Otherwise the maximum (closer to positive
4358 infinity) of the two operands is chosen as the result.
4360 >>> ExtendedContext.max(Decimal('3'), Decimal('2'))
4362 >>> ExtendedContext.max(Decimal('-10'), Decimal('3'))
4364 >>> ExtendedContext.max(Decimal('1.0'), Decimal('1'))
4366 >>> ExtendedContext.max(Decimal('7'), Decimal('NaN'))
4369 return a
.max(b
, context
=self
)
4371 def max_mag(self
, a
, b
):
4372 """Compares the values numerically with their sign ignored."""
4373 return a
.max_mag(b
, context
=self
)
4376 """min compares two values numerically and returns the minimum.
4378 If either operand is a NaN then the general rules apply.
4379 Otherwise, the operands are compared as though by the compare
4380 operation. If they are numerically equal then the left-hand operand
4381 is chosen as the result. Otherwise the minimum (closer to negative
4382 infinity) of the two operands is chosen as the result.
4384 >>> ExtendedContext.min(Decimal('3'), Decimal('2'))
4386 >>> ExtendedContext.min(Decimal('-10'), Decimal('3'))
4388 >>> ExtendedContext.min(Decimal('1.0'), Decimal('1'))
4390 >>> ExtendedContext.min(Decimal('7'), Decimal('NaN'))
4393 return a
.min(b
, context
=self
)
4395 def min_mag(self
, a
, b
):
4396 """Compares the values numerically with their sign ignored."""
4397 return a
.min_mag(b
, context
=self
)
4400 """Minus corresponds to unary prefix minus in Python.
4402 The operation is evaluated using the same rules as subtract; the
4403 operation minus(a) is calculated as subtract('0', a) where the '0'
4404 has the same exponent as the operand.
4406 >>> ExtendedContext.minus(Decimal('1.3'))
4408 >>> ExtendedContext.minus(Decimal('-1.3'))
4411 return a
.__neg
__(context
=self
)
4413 def multiply(self
, a
, b
):
4414 """multiply multiplies two operands.
4416 If either operand is a special value then the general rules apply.
4417 Otherwise, the operands are multiplied together ('long multiplication'),
4418 resulting in a number which may be as long as the sum of the lengths
4419 of the two operands.
4421 >>> ExtendedContext.multiply(Decimal('1.20'), Decimal('3'))
4423 >>> ExtendedContext.multiply(Decimal('7'), Decimal('3'))
4425 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('0.8'))
4427 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('-0'))
4429 >>> ExtendedContext.multiply(Decimal('654321'), Decimal('654321'))
4430 Decimal('4.28135971E+11')
4432 return a
.__mul
__(b
, context
=self
)
4434 def next_minus(self
, a
):
4435 """Returns the largest representable number smaller than a.
4437 >>> c = ExtendedContext.copy()
4440 >>> ExtendedContext.next_minus(Decimal('1'))
4441 Decimal('0.999999999')
4442 >>> c.next_minus(Decimal('1E-1007'))
4444 >>> ExtendedContext.next_minus(Decimal('-1.00000003'))
4445 Decimal('-1.00000004')
4446 >>> c.next_minus(Decimal('Infinity'))
4447 Decimal('9.99999999E+999')
4449 return a
.next_minus(context
=self
)
4451 def next_plus(self
, a
):
4452 """Returns the smallest representable number larger than a.
4454 >>> c = ExtendedContext.copy()
4457 >>> ExtendedContext.next_plus(Decimal('1'))
4458 Decimal('1.00000001')
4459 >>> c.next_plus(Decimal('-1E-1007'))
4461 >>> ExtendedContext.next_plus(Decimal('-1.00000003'))
4462 Decimal('-1.00000002')
4463 >>> c.next_plus(Decimal('-Infinity'))
4464 Decimal('-9.99999999E+999')
4466 return a
.next_plus(context
=self
)
4468 def next_toward(self
, a
, b
):
4469 """Returns the number closest to a, in direction towards b.
4471 The result is the closest representable number from the first
4472 operand (but not the first operand) that is in the direction
4473 towards the second operand, unless the operands have the same
4476 >>> c = ExtendedContext.copy()
4479 >>> c.next_toward(Decimal('1'), Decimal('2'))
4480 Decimal('1.00000001')
4481 >>> c.next_toward(Decimal('-1E-1007'), Decimal('1'))
4483 >>> c.next_toward(Decimal('-1.00000003'), Decimal('0'))
4484 Decimal('-1.00000002')
4485 >>> c.next_toward(Decimal('1'), Decimal('0'))
4486 Decimal('0.999999999')
4487 >>> c.next_toward(Decimal('1E-1007'), Decimal('-100'))
4489 >>> c.next_toward(Decimal('-1.00000003'), Decimal('-10'))
4490 Decimal('-1.00000004')
4491 >>> c.next_toward(Decimal('0.00'), Decimal('-0.0000'))
4494 return a
.next_toward(b
, context
=self
)
4496 def normalize(self
, a
):
4497 """normalize reduces an operand to its simplest form.
4499 Essentially a plus operation with all trailing zeros removed from the
4502 >>> ExtendedContext.normalize(Decimal('2.1'))
4504 >>> ExtendedContext.normalize(Decimal('-2.0'))
4506 >>> ExtendedContext.normalize(Decimal('1.200'))
4508 >>> ExtendedContext.normalize(Decimal('-120'))
4510 >>> ExtendedContext.normalize(Decimal('120.00'))
4512 >>> ExtendedContext.normalize(Decimal('0.00'))
4515 return a
.normalize(context
=self
)
4517 def number_class(self
, a
):
4518 """Returns an indication of the class of the operand.
4520 The class is one of the following strings:
4532 >>> c = Context(ExtendedContext)
4535 >>> c.number_class(Decimal('Infinity'))
4537 >>> c.number_class(Decimal('1E-10'))
4539 >>> c.number_class(Decimal('2.50'))
4541 >>> c.number_class(Decimal('0.1E-999'))
4543 >>> c.number_class(Decimal('0'))
4545 >>> c.number_class(Decimal('-0'))
4547 >>> c.number_class(Decimal('-0.1E-999'))
4549 >>> c.number_class(Decimal('-1E-10'))
4551 >>> c.number_class(Decimal('-2.50'))
4553 >>> c.number_class(Decimal('-Infinity'))
4555 >>> c.number_class(Decimal('NaN'))
4557 >>> c.number_class(Decimal('-NaN'))
4559 >>> c.number_class(Decimal('sNaN'))
4562 return a
.number_class(context
=self
)
4565 """Plus corresponds to unary prefix plus in Python.
4567 The operation is evaluated using the same rules as add; the
4568 operation plus(a) is calculated as add('0', a) where the '0'
4569 has the same exponent as the operand.
4571 >>> ExtendedContext.plus(Decimal('1.3'))
4573 >>> ExtendedContext.plus(Decimal('-1.3'))
4576 return a
.__pos
__(context
=self
)
4578 def power(self
, a
, b
, modulo
=None):
4579 """Raises a to the power of b, to modulo if given.
4581 With two arguments, compute a**b. If a is negative then b
4582 must be integral. The result will be inexact unless b is
4583 integral and the result is finite and can be expressed exactly
4584 in 'precision' digits.
4586 With three arguments, compute (a**b) % modulo. For the
4587 three argument form, the following restrictions on the
4590 - all three arguments must be integral
4591 - b must be nonnegative
4592 - at least one of a or b must be nonzero
4593 - modulo must be nonzero and have at most 'precision' digits
4595 The result of pow(a, b, modulo) is identical to the result
4596 that would be obtained by computing (a**b) % modulo with
4597 unbounded precision, but is computed more efficiently. It is
4600 >>> c = ExtendedContext.copy()
4603 >>> c.power(Decimal('2'), Decimal('3'))
4605 >>> c.power(Decimal('-2'), Decimal('3'))
4607 >>> c.power(Decimal('2'), Decimal('-3'))
4609 >>> c.power(Decimal('1.7'), Decimal('8'))
4610 Decimal('69.7575744')
4611 >>> c.power(Decimal('10'), Decimal('0.301029996'))
4612 Decimal('2.00000000')
4613 >>> c.power(Decimal('Infinity'), Decimal('-1'))
4615 >>> c.power(Decimal('Infinity'), Decimal('0'))
4617 >>> c.power(Decimal('Infinity'), Decimal('1'))
4619 >>> c.power(Decimal('-Infinity'), Decimal('-1'))
4621 >>> c.power(Decimal('-Infinity'), Decimal('0'))
4623 >>> c.power(Decimal('-Infinity'), Decimal('1'))
4624 Decimal('-Infinity')
4625 >>> c.power(Decimal('-Infinity'), Decimal('2'))
4627 >>> c.power(Decimal('0'), Decimal('0'))
4630 >>> c.power(Decimal('3'), Decimal('7'), Decimal('16'))
4632 >>> c.power(Decimal('-3'), Decimal('7'), Decimal('16'))
4634 >>> c.power(Decimal('-3'), Decimal('8'), Decimal('16'))
4636 >>> c.power(Decimal('3'), Decimal('7'), Decimal('-16'))
4638 >>> c.power(Decimal('23E12345'), Decimal('67E189'), Decimal('123456789'))
4640 >>> c.power(Decimal('-0'), Decimal('17'), Decimal('1729'))
4642 >>> c.power(Decimal('-23'), Decimal('0'), Decimal('65537'))
4645 return a
.__pow
__(b
, modulo
, context
=self
)
4647 def quantize(self
, a
, b
):
4648 """Returns a value equal to 'a' (rounded), having the exponent of 'b'.
4650 The coefficient of the result is derived from that of the left-hand
4651 operand. It may be rounded using the current rounding setting (if the
4652 exponent is being increased), multiplied by a positive power of ten (if
4653 the exponent is being decreased), or is unchanged (if the exponent is
4654 already equal to that of the right-hand operand).
4656 Unlike other operations, if the length of the coefficient after the
4657 quantize operation would be greater than precision then an Invalid
4658 operation condition is raised. This guarantees that, unless there is
4659 an error condition, the exponent of the result of a quantize is always
4660 equal to that of the right-hand operand.
4662 Also unlike other operations, quantize will never raise Underflow, even
4663 if the result is subnormal and inexact.
4665 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))
4667 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))
4669 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))
4671 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))
4673 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))
4675 >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))
4676 Decimal('-Infinity')
4677 >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))
4679 >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))
4681 >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))
4683 >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))
4685 >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))
4687 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))
4689 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))
4691 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))
4693 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))
4696 return a
.quantize(b
, context
=self
)
4699 """Just returns 10, as this is Decimal, :)
4701 >>> ExtendedContext.radix()
4706 def remainder(self
, a
, b
):
4707 """Returns the remainder from integer division.
4709 The result is the residue of the dividend after the operation of
4710 calculating integer division as described for divide-integer, rounded
4711 to precision digits if necessary. The sign of the result, if
4712 non-zero, is the same as that of the original dividend.
4714 This operation will fail under the same conditions as integer division
4715 (that is, if integer division on the same two operands would fail, the
4716 remainder cannot be calculated).
4718 >>> ExtendedContext.remainder(Decimal('2.1'), Decimal('3'))
4720 >>> ExtendedContext.remainder(Decimal('10'), Decimal('3'))
4722 >>> ExtendedContext.remainder(Decimal('-10'), Decimal('3'))
4724 >>> ExtendedContext.remainder(Decimal('10.2'), Decimal('1'))
4726 >>> ExtendedContext.remainder(Decimal('10'), Decimal('0.3'))
4728 >>> ExtendedContext.remainder(Decimal('3.6'), Decimal('1.3'))
4731 return a
.__mod
__(b
, context
=self
)
4733 def remainder_near(self
, a
, b
):
4734 """Returns to be "a - b * n", where n is the integer nearest the exact
4735 value of "x / b" (if two integers are equally near then the even one
4736 is chosen). If the result is equal to 0 then its sign will be the
4739 This operation will fail under the same conditions as integer division
4740 (that is, if integer division on the same two operands would fail, the
4741 remainder cannot be calculated).
4743 >>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))
4745 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))
4747 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))
4749 >>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))
4751 >>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))
4753 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))
4755 >>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))
4758 return a
.remainder_near(b
, context
=self
)
4760 def rotate(self
, a
, b
):
4761 """Returns a rotated copy of a, b times.
4763 The coefficient of the result is a rotated copy of the digits in
4764 the coefficient of the first operand. The number of places of
4765 rotation is taken from the absolute value of the second operand,
4766 with the rotation being to the left if the second operand is
4767 positive or to the right otherwise.
4769 >>> ExtendedContext.rotate(Decimal('34'), Decimal('8'))
4770 Decimal('400000003')
4771 >>> ExtendedContext.rotate(Decimal('12'), Decimal('9'))
4773 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('-2'))
4774 Decimal('891234567')
4775 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('0'))
4776 Decimal('123456789')
4777 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('+2'))
4778 Decimal('345678912')
4780 return a
.rotate(b
, context
=self
)
4782 def same_quantum(self
, a
, b
):
4783 """Returns True if the two operands have the same exponent.
4785 The result is never affected by either the sign or the coefficient of
4788 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))
4790 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))
4792 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))
4794 >>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))
4797 return a
.same_quantum(b
)
4799 def scaleb (self
, a
, b
):
4800 """Returns the first operand after adding the second value its exp.
4802 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('-2'))
4804 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('0'))
4806 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('3'))
4809 return a
.scaleb (b
, context
=self
)
4811 def shift(self
, a
, b
):
4812 """Returns a shifted copy of a, b times.
4814 The coefficient of the result is a shifted copy of the digits
4815 in the coefficient of the first operand. The number of places
4816 to shift is taken from the absolute value of the second operand,
4817 with the shift being to the left if the second operand is
4818 positive or to the right otherwise. Digits shifted into the
4819 coefficient are zeros.
4821 >>> ExtendedContext.shift(Decimal('34'), Decimal('8'))
4822 Decimal('400000000')
4823 >>> ExtendedContext.shift(Decimal('12'), Decimal('9'))
4825 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('-2'))
4827 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('0'))
4828 Decimal('123456789')
4829 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('+2'))
4830 Decimal('345678900')
4832 return a
.shift(b
, context
=self
)
4835 """Square root of a non-negative number to context precision.
4837 If the result must be inexact, it is rounded using the round-half-even
4840 >>> ExtendedContext.sqrt(Decimal('0'))
4842 >>> ExtendedContext.sqrt(Decimal('-0'))
4844 >>> ExtendedContext.sqrt(Decimal('0.39'))
4845 Decimal('0.624499800')
4846 >>> ExtendedContext.sqrt(Decimal('100'))
4848 >>> ExtendedContext.sqrt(Decimal('1'))
4850 >>> ExtendedContext.sqrt(Decimal('1.0'))
4852 >>> ExtendedContext.sqrt(Decimal('1.00'))
4854 >>> ExtendedContext.sqrt(Decimal('7'))
4855 Decimal('2.64575131')
4856 >>> ExtendedContext.sqrt(Decimal('10'))
4857 Decimal('3.16227766')
4858 >>> ExtendedContext.prec
4861 return a
.sqrt(context
=self
)
4863 def subtract(self
, a
, b
):
4864 """Return the difference between the two operands.
4866 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.07'))
4868 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.30'))
4870 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('2.07'))
4873 return a
.__sub
__(b
, context
=self
)
4875 def to_eng_string(self
, a
):
4876 """Converts a number to a string, using scientific notation.
4878 The operation is not affected by the context.
4880 return a
.to_eng_string(context
=self
)
4882 def to_sci_string(self
, a
):
4883 """Converts a number to a string, using scientific notation.
4885 The operation is not affected by the context.
4887 return a
.__str
__(context
=self
)
4889 def to_integral_exact(self
, a
):
4890 """Rounds to an integer.
4892 When the operand has a negative exponent, the result is the same
4893 as using the quantize() operation using the given operand as the
4894 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
4895 of the operand as the precision setting; Inexact and Rounded flags
4896 are allowed in this operation. The rounding mode is taken from the
4899 >>> ExtendedContext.to_integral_exact(Decimal('2.1'))
4901 >>> ExtendedContext.to_integral_exact(Decimal('100'))
4903 >>> ExtendedContext.to_integral_exact(Decimal('100.0'))
4905 >>> ExtendedContext.to_integral_exact(Decimal('101.5'))
4907 >>> ExtendedContext.to_integral_exact(Decimal('-101.5'))
4909 >>> ExtendedContext.to_integral_exact(Decimal('10E+5'))
4911 >>> ExtendedContext.to_integral_exact(Decimal('7.89E+77'))
4913 >>> ExtendedContext.to_integral_exact(Decimal('-Inf'))
4914 Decimal('-Infinity')
4916 return a
.to_integral_exact(context
=self
)
4918 def to_integral_value(self
, a
):
4919 """Rounds to an integer.
4921 When the operand has a negative exponent, the result is the same
4922 as using the quantize() operation using the given operand as the
4923 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
4924 of the operand as the precision setting, except that no flags will
4925 be set. The rounding mode is taken from the context.
4927 >>> ExtendedContext.to_integral_value(Decimal('2.1'))
4929 >>> ExtendedContext.to_integral_value(Decimal('100'))
4931 >>> ExtendedContext.to_integral_value(Decimal('100.0'))
4933 >>> ExtendedContext.to_integral_value(Decimal('101.5'))
4935 >>> ExtendedContext.to_integral_value(Decimal('-101.5'))
4937 >>> ExtendedContext.to_integral_value(Decimal('10E+5'))
4939 >>> ExtendedContext.to_integral_value(Decimal('7.89E+77'))
4941 >>> ExtendedContext.to_integral_value(Decimal('-Inf'))
4942 Decimal('-Infinity')
4944 return a
.to_integral_value(context
=self
)
4946 # the method name changed, but we provide also the old one, for compatibility
4947 to_integral
= to_integral_value
4949 class _WorkRep(object):
4950 __slots__
= ('sign','int','exp')
4953 # exp: None, int, or string
4955 def __init__(self
, value
=None):
4960 elif isinstance(value
, Decimal
):
4961 self
.sign
= value
._sign
4962 self
.int = int(value
._int
)
4963 self
.exp
= value
._exp
4965 # assert isinstance(value, tuple)
4966 self
.sign
= value
[0]
4971 return "(%r, %r, %r)" % (self
.sign
, self
.int, self
.exp
)
4977 def _normalize(op1
, op2
, prec
= 0):
4978 """Normalizes op1, op2 to have the same exp and length of coefficient.
4980 Done during addition.
4982 if op1
.exp
< op2
.exp
:
4989 # Let exp = min(tmp.exp - 1, tmp.adjusted() - precision - 1).
4990 # Then adding 10**exp to tmp has the same effect (after rounding)
4991 # as adding any positive quantity smaller than 10**exp; similarly
4992 # for subtraction. So if other is smaller than 10**exp we replace
4993 # it with 10**exp. This avoids tmp.exp - other.exp getting too large.
4994 tmp_len
= len(str(tmp
.int))
4995 other_len
= len(str(other
.int))
4996 exp
= tmp
.exp
+ min(-1, tmp_len
- prec
- 2)
4997 if other_len
+ other
.exp
- 1 < exp
:
5001 tmp
.int *= 10 ** (tmp
.exp
- other
.exp
)
5005 ##### Integer arithmetic functions used by ln, log10, exp and __pow__ #####
5007 # This function from Tim Peters was taken from here:
5008 # http://mail.python.org/pipermail/python-list/1999-July/007758.html
5009 # The correction being in the function definition is for speed, and
5010 # the whole function is not resolved with math.log because of avoiding
5011 # the use of floats.
5012 def _nbits(n
, correction
= {
5013 '0': 4, '1': 3, '2': 2, '3': 2,
5014 '4': 1, '5': 1, '6': 1, '7': 1,
5015 '8': 0, '9': 0, 'a': 0, 'b': 0,
5016 'c': 0, 'd': 0, 'e': 0, 'f': 0}):
5017 """Number of bits in binary representation of the positive integer n,
5021 raise ValueError("The argument to _nbits should be nonnegative.")
5023 return 4*len(hex_n
) - correction
[hex_n
[0]]
5025 def _sqrt_nearest(n
, a
):
5026 """Closest integer to the square root of the positive integer n. a is
5027 an initial approximation to the square root. Any positive integer
5028 will do for a, but the closer a is to the square root of n the
5029 faster convergence will be.
5032 if n
<= 0 or a
<= 0:
5033 raise ValueError("Both arguments to _sqrt_nearest should be positive.")
5037 b
, a
= a
, a
--n
//a
>>1
5040 def _rshift_nearest(x
, shift
):
5041 """Given an integer x and a nonnegative integer shift, return closest
5042 integer to x / 2**shift; use round-to-even in case of a tie.
5045 b
, q
= 1L << shift
, x
>> shift
5046 return q
+ (2*(x
& (b
-1)) + (q
&1) > b
)
5048 def _div_nearest(a
, b
):
5049 """Closest integer to a/b, a and b positive integers; rounds to even
5050 in the case of a tie.
5054 return q
+ (2*r
+ (q
&1) > b
)
5056 def _ilog(x
, M
, L
= 8):
5057 """Integer approximation to M*log(x/M), with absolute error boundable
5058 in terms only of x/M.
5060 Given positive integers x and M, return an integer approximation to
5061 M * log(x/M). For L = 8 and 0.1 <= x/M <= 10 the difference
5062 between the approximation and the exact result is at most 22. For
5063 L = 8 and 1.0 <= x/M <= 10.0 the difference is at most 15. In
5064 both cases these are upper bounds on the error; it will usually be
5067 # The basic algorithm is the following: let log1p be the function
5068 # log1p(x) = log(1+x). Then log(x/M) = log1p((x-M)/M). We use
5071 # log1p(y) = 2*log1p(y/(1+sqrt(1+y)))
5073 # repeatedly until the argument to log1p is small (< 2**-L in
5074 # absolute value). For small y we can use the Taylor series
5077 # log1p(y) ~ y - y**2/2 + y**3/3 - ... - (-y)**T/T
5079 # truncating at T such that y**T is small enough. The whole
5080 # computation is carried out in a form of fixed-point arithmetic,
5081 # with a real number z being represented by an integer
5082 # approximation to z*M. To avoid loss of precision, the y below
5083 # is actually an integer approximation to 2**R*y*M, where R is the
5084 # number of reductions performed so far.
5087 # argument reduction; R = number of reductions performed
5089 while (R
<= L
and long(abs(y
)) << L
-R
>= M
or
5090 R
> L
and abs(y
) >> R
-L
>= M
):
5091 y
= _div_nearest(long(M
*y
) << 1,
5092 M
+ _sqrt_nearest(M
*(M
+_rshift_nearest(y
, R
)), M
))
5095 # Taylor series with T terms
5096 T
= -int(-10*len(str(M
))//(3*L
))
5097 yshift
= _rshift_nearest(y
, R
)
5098 w
= _div_nearest(M
, T
)
5099 for k
in xrange(T
-1, 0, -1):
5100 w
= _div_nearest(M
, k
) - _div_nearest(yshift
*w
, M
)
5102 return _div_nearest(w
*y
, M
)
5104 def _dlog10(c
, e
, p
):
5105 """Given integers c, e and p with c > 0, p >= 0, compute an integer
5106 approximation to 10**p * log10(c*10**e), with an absolute error of
5107 at most 1. Assumes that c*10**e is not exactly 1."""
5109 # increase precision by 2; compensate for this by dividing
5110 # final result by 100
5113 # write c*10**e as d*10**f with either:
5114 # f >= 0 and 1 <= d <= 10, or
5115 # f <= 0 and 0.1 <= d <= 1.
5116 # Thus for c*10**e close to 1, f = 0
5118 f
= e
+l
- (e
+l
>= 1)
5126 c
= _div_nearest(c
, 10**-k
)
5128 log_d
= _ilog(c
, M
) # error < 5 + 22 = 27
5129 log_10
= _log10_digits(p
) # error < 1
5130 log_d
= _div_nearest(log_d
*M
, log_10
)
5131 log_tenpower
= f
*M
# exact
5133 log_d
= 0 # error < 2.31
5134 log_tenpower
= _div_nearest(f
, 10**-p
) # error < 0.5
5136 return _div_nearest(log_tenpower
+log_d
, 100)
5139 """Given integers c, e and p with c > 0, compute an integer
5140 approximation to 10**p * log(c*10**e), with an absolute error of
5141 at most 1. Assumes that c*10**e is not exactly 1."""
5143 # Increase precision by 2. The precision increase is compensated
5144 # for at the end with a division by 100.
5147 # rewrite c*10**e as d*10**f with either f >= 0 and 1 <= d <= 10,
5148 # or f <= 0 and 0.1 <= d <= 1. Then we can compute 10**p * log(c*10**e)
5149 # as 10**p * log(d) + 10**p*f * log(10).
5151 f
= e
+l
- (e
+l
>= 1)
5153 # compute approximation to 10**p*log(d), with error < 27
5159 c
= _div_nearest(c
, 10**-k
) # error of <= 0.5 in c
5161 # _ilog magnifies existing error in c by a factor of at most 10
5162 log_d
= _ilog(c
, 10**p
) # error < 5 + 22 = 27
5164 # p <= 0: just approximate the whole thing by 0; error < 2.31
5167 # compute approximation to f*10**p*log(10), with error < 11.
5169 extra
= len(str(abs(f
)))-1
5171 # error in f * _log10_digits(p+extra) < |f| * 1 = |f|
5172 # after division, error < |f|/10**extra + 0.5 < 10 + 0.5 < 11
5173 f_log_ten
= _div_nearest(f
*_log10_digits(p
+extra
), 10**extra
)
5179 # error in sum < 11+27 = 38; error after division < 0.38 + 0.5 < 1
5180 return _div_nearest(f_log_ten
+ log_d
, 100)
5182 class _Log10Memoize(object):
5183 """Class to compute, store, and allow retrieval of, digits of the
5184 constant log(10) = 2.302585.... This constant is needed by
5185 Decimal.ln, Decimal.log10, Decimal.exp and Decimal.__pow__."""
5187 self
.digits
= "23025850929940456840179914546843642076011014886"
5189 def getdigits(self
, p
):
5190 """Given an integer p >= 0, return floor(10**p)*log(10).
5192 For example, self.getdigits(3) returns 2302.
5194 # digits are stored as a string, for quick conversion to
5195 # integer in the case that we've already computed enough
5196 # digits; the stored digits should always be correct
5197 # (truncated, not rounded to nearest).
5199 raise ValueError("p should be nonnegative")
5201 if p
>= len(self
.digits
):
5202 # compute p+3, p+6, p+9, ... digits; continue until at
5203 # least one of the extra digits is nonzero
5206 # compute p+extra digits, correct to within 1ulp
5208 digits
= str(_div_nearest(_ilog(10*M
, M
), 100))
5209 if digits
[-extra
:] != '0'*extra
:
5212 # keep all reliable digits so far; remove trailing zeros
5213 # and next nonzero digit
5214 self
.digits
= digits
.rstrip('0')[:-1]
5215 return int(self
.digits
[:p
+1])
5217 _log10_digits
= _Log10Memoize().getdigits
5219 def _iexp(x
, M
, L
=8):
5220 """Given integers x and M, M > 0, such that x/M is small in absolute
5221 value, compute an integer approximation to M*exp(x/M). For 0 <=
5222 x/M <= 2.4, the absolute error in the result is bounded by 60 (and
5223 is usually much smaller)."""
5225 # Algorithm: to compute exp(z) for a real number z, first divide z
5226 # by a suitable power R of 2 so that |z/2**R| < 2**-L. Then
5227 # compute expm1(z/2**R) = exp(z/2**R) - 1 using the usual Taylor
5230 # expm1(x) = x + x**2/2! + x**3/3! + ...
5232 # Now use the identity
5234 # expm1(2x) = expm1(x)*(expm1(x)+2)
5236 # R times to compute the sequence expm1(z/2**R),
5237 # expm1(z/2**(R-1)), ... , exp(z/2), exp(z).
5239 # Find R such that x/2**R/M <= 2**-L
5240 R
= _nbits((long(x
)<<L
)//M
)
5242 # Taylor series. (2**L)**T > M
5243 T
= -int(-10*len(str(M
))//(3*L
))
5244 y
= _div_nearest(x
, T
)
5246 for i
in xrange(T
-1, 0, -1):
5247 y
= _div_nearest(x
*(Mshift
+ y
), Mshift
* i
)
5250 for k
in xrange(R
-1, -1, -1):
5251 Mshift
= long(M
)<<(k
+2)
5252 y
= _div_nearest(y
*(y
+Mshift
), Mshift
)
5257 """Compute an approximation to exp(c*10**e), with p decimal places of
5260 Returns integers d, f such that:
5262 10**(p-1) <= d <= 10**p, and
5263 (d-1)*10**f < exp(c*10**e) < (d+1)*10**f
5265 In other words, d*10**f is an approximation to exp(c*10**e) with p
5266 digits of precision, and with an error in d of at most 1. This is
5267 almost, but not quite, the same as the error being < 1ulp: when d
5268 = 10**(p-1) the error could be up to 10 ulp."""
5270 # we'll call iexp with M = 10**(p+2), giving p+3 digits of precision
5273 # compute log(10) with extra precision = adjusted exponent of c*10**e
5274 extra
= max(0, e
+ len(str(c
)) - 1)
5277 # compute quotient c*10**e/(log(10)) = c*10**(e+q)/(log(10)*10**q),
5281 cshift
= c
*10**shift
5283 cshift
= c
//10**-shift
5284 quot
, rem
= divmod(cshift
, _log10_digits(q
))
5286 # reduce remainder back to original precision
5287 rem
= _div_nearest(rem
, 10**extra
)
5289 # error in result of _iexp < 120; error after division < 0.62
5290 return _div_nearest(_iexp(rem
, 10**p
), 1000), quot
- p
+ 3
5292 def _dpower(xc
, xe
, yc
, ye
, p
):
5293 """Given integers xc, xe, yc and ye representing Decimals x = xc*10**xe and
5294 y = yc*10**ye, compute x**y. Returns a pair of integers (c, e) such that:
5296 10**(p-1) <= c <= 10**p, and
5297 (c-1)*10**e < x**y < (c+1)*10**e
5299 in other words, c*10**e is an approximation to x**y with p digits
5300 of precision, and with an error in c of at most 1. (This is
5301 almost, but not quite, the same as the error being < 1ulp: when c
5302 == 10**(p-1) we can only guarantee error < 10ulp.)
5304 We assume that: x is positive and not equal to 1, and y is nonzero.
5307 # Find b such that 10**(b-1) <= |y| <= 10**b
5308 b
= len(str(abs(yc
))) + ye
5310 # log(x) = lxc*10**(-p-b-1), to p+b+1 places after the decimal point
5311 lxc
= _dlog(xc
, xe
, p
+b
+1)
5313 # compute product y*log(x) = yc*lxc*10**(-p-b-1+ye) = pc*10**(-p-1)
5316 pc
= lxc
*yc
*10**shift
5318 pc
= _div_nearest(lxc
*yc
, 10**-shift
)
5321 # we prefer a result that isn't exactly 1; this makes it
5322 # easier to compute a correctly rounded result in __pow__
5323 if ((len(str(xc
)) + xe
>= 1) == (yc
> 0)): # if x**y > 1:
5324 coeff
, exp
= 10**(p
-1)+1, 1-p
5326 coeff
, exp
= 10**p
-1, -p
5328 coeff
, exp
= _dexp(pc
, -(p
+1), p
+1)
5329 coeff
= _div_nearest(coeff
, 10)
5334 def _log10_lb(c
, correction
= {
5335 '1': 100, '2': 70, '3': 53, '4': 40, '5': 31,
5336 '6': 23, '7': 16, '8': 10, '9': 5}):
5337 """Compute a lower bound for 100*log10(c) for a positive integer c."""
5339 raise ValueError("The argument to _log10_lb should be nonnegative.")
5341 return 100*len(str_c
) - correction
[str_c
[0]]
5343 ##### Helper Functions ####################################################
5345 def _convert_other(other
, raiseit
=False):
5346 """Convert other to Decimal.
5348 Verifies that it's ok to use in an implicit construction.
5350 if isinstance(other
, Decimal
):
5352 if isinstance(other
, (int, long)):
5353 return Decimal(other
)
5355 raise TypeError("Unable to convert %s to Decimal" % other
)
5356 return NotImplemented
5358 ##### Setup Specific Contexts ############################################
5360 # The default context prototype used by Context()
5361 # Is mutable, so that new contexts can have different default values
5363 DefaultContext
= Context(
5364 prec
=28, rounding
=ROUND_HALF_EVEN
,
5365 traps
=[DivisionByZero
, Overflow
, InvalidOperation
],
5372 # Pre-made alternate contexts offered by the specification
5373 # Don't change these; the user should be able to select these
5374 # contexts and be able to reproduce results from other implementations
5377 BasicContext
= Context(
5378 prec
=9, rounding
=ROUND_HALF_UP
,
5379 traps
=[DivisionByZero
, Overflow
, InvalidOperation
, Clamped
, Underflow
],
5383 ExtendedContext
= Context(
5384 prec
=9, rounding
=ROUND_HALF_EVEN
,
5390 ##### crud for parsing strings #############################################
5392 # Regular expression used for parsing numeric strings. Additional
5395 # 1. Uncomment the two '\s*' lines to allow leading and/or trailing
5396 # whitespace. But note that the specification disallows whitespace in
5399 # 2. For finite numbers (not infinities and NaNs) the body of the
5400 # number between the optional sign and the optional exponent must have
5401 # at least one decimal digit, possibly after the decimal point. The
5402 # lookahead expression '(?=\d|\.\d)' checks this.
5404 # As the flag UNICODE is not enabled here, we're explicitly avoiding any
5405 # other meaning for \d than the numbers [0-9].
5408 _parser
= re
.compile(r
""" # A numeric string consists of:
5410 (?P<sign>[-+])? # an optional sign, followed by either...
5412 (?=[0-9]|\.[0-9]) # ...a number (with at least one digit)
5413 (?P<int>[0-9]*) # having a (possibly empty) integer part
5414 (\.(?P<frac>[0-9]*))? # followed by an optional fractional part
5415 (E(?P<exp>[-+]?[0-9]+))? # followed by an optional exponent, or...
5417 Inf(inity)? # ...an infinity, or...
5419 (?P<signal>s)? # ...an (optionally signaling)
5421 (?P<diag>[0-9]*) # with (possibly empty) diagnostic info.
5425 """, re
.VERBOSE | re
.IGNORECASE
).match
5427 _all_zeros
= re
.compile('0*$').match
5428 _exact_half
= re
.compile('50*$').match
5430 ##### PEP3101 support functions ##############################################
5431 # The functions parse_format_specifier and format_align have little to do
5432 # with the Decimal class, and could potentially be reused for other pure
5433 # Python numeric classes that want to implement __format__
5435 # A format specifier for Decimal looks like:
5437 # [[fill]align][sign][0][minimumwidth][.precision][type]
5440 _parse_format_specifier_regex
= re
.compile(r
"""\A
5447 (?P<minimumwidth>(?!0)\d+)?
5448 (?:\.(?P<precision>0|(?!0)\d+))?
5449 (?P<type>[eEfFgG%])?
5455 def _parse_format_specifier(format_spec
):
5456 """Parse and validate a format specifier.
5458 Turns a standard numeric format specifier into a dict, with the
5461 fill: fill character to pad field to minimum width
5462 align: alignment type, either '<', '>', '=' or '^'
5463 sign: either '+', '-' or ' '
5464 minimumwidth: nonnegative integer giving minimum width
5465 precision: nonnegative integer giving precision, or None
5466 type: one of the characters 'eEfFgG%', or None
5467 unicode: either True or False (always True for Python 3.x)
5470 m
= _parse_format_specifier_regex
.match(format_spec
)
5472 raise ValueError("Invalid format specifier: " + format_spec
)
5474 # get the dictionary
5475 format_dict
= m
.groupdict()
5477 # defaults for fill and alignment
5478 fill
= format_dict
['fill']
5479 align
= format_dict
['align']
5480 if format_dict
.pop('zeropad') is not None:
5481 # in the face of conflict, refuse the temptation to guess
5482 if fill
is not None and fill
!= '0':
5483 raise ValueError("Fill character conflicts with '0'"
5484 " in format specifier: " + format_spec
)
5485 if align
is not None and align
!= '=':
5486 raise ValueError("Alignment conflicts with '0' in "
5487 "format specifier: " + format_spec
)
5490 format_dict
['fill'] = fill
or ' '
5491 format_dict
['align'] = align
or '<'
5493 if format_dict
['sign'] is None:
5494 format_dict
['sign'] = '-'
5496 # turn minimumwidth and precision entries into integers.
5497 # minimumwidth defaults to 0; precision remains None if not given
5498 format_dict
['minimumwidth'] = int(format_dict
['minimumwidth'] or '0')
5499 if format_dict
['precision'] is not None:
5500 format_dict
['precision'] = int(format_dict
['precision'])
5502 # if format type is 'g' or 'G' then a precision of 0 makes little
5503 # sense; convert it to 1. Same if format type is unspecified.
5504 if format_dict
['precision'] == 0:
5505 if format_dict
['type'] in 'gG' or format_dict
['type'] is None:
5506 format_dict
['precision'] = 1
5508 # record whether return type should be str or unicode
5509 format_dict
['unicode'] = isinstance(format_spec
, unicode)
5513 def _format_align(body
, spec_dict
):
5514 """Given an unpadded, non-aligned numeric string, add padding and
5515 aligment to conform with the given format specifier dictionary (as
5516 output from parse_format_specifier).
5518 It's assumed that if body is negative then it starts with '-'.
5519 Any leading sign ('-' or '+') is stripped from the body before
5520 applying the alignment and padding rules, and replaced in the
5521 appropriate position.
5524 # figure out the sign; we only examine the first character, so if
5525 # body has leading whitespace the results may be surprising.
5526 if len(body
) > 0 and body
[0] in '-+':
5533 if spec_dict
['sign'] in ' +':
5534 sign
= spec_dict
['sign']
5538 # how much extra space do we have to play with?
5539 minimumwidth
= spec_dict
['minimumwidth']
5540 fill
= spec_dict
['fill']
5541 padding
= fill
*(max(minimumwidth
- (len(sign
+body
)), 0))
5543 align
= spec_dict
['align']
5545 result
= padding
+ sign
+ body
5547 result
= sign
+ body
+ padding
5549 result
= sign
+ padding
+ body
5551 half
= len(padding
)//2
5552 result
= padding
[:half
] + sign
+ body
+ padding
[half
:]
5554 # make sure that result is unicode if necessary
5555 if spec_dict
['unicode']:
5556 result
= unicode(result
)
5560 ##### Useful Constants (internal use only) ################################
5563 _Infinity
= Decimal('Inf')
5564 _NegativeInfinity
= Decimal('-Inf')
5565 _NaN
= Decimal('NaN')
5568 _NegativeOne
= Decimal(-1)
5570 # _SignedInfinity[sign] is infinity w/ that sign
5571 _SignedInfinity
= (_Infinity
, _NegativeInfinity
)
5575 if __name__
== '__main__':
5577 doctest
.testmod(sys
.modules
[__name__
])