1 # Copyright (c) 2004 Python Software Foundation.
4 # Written by Eric Price <eprice at tjhsst.edu>
5 # and Facundo Batista <facundo at taniquetil.com.ar>
6 # and Raymond Hettinger <python at rcn.com>
7 # and Aahz <aahz at pobox.com>
10 # This module is currently Py2.3 compatible and should be kept that way
11 # unless a major compelling advantage arises. IOW, 2.3 compatibility is
12 # strongly preferred, but not guaranteed.
14 # Also, this module should be kept in sync with the latest updates of
15 # the IBM specification as it evolves. Those updates will be treated
16 # as bug fixes (deviation from the spec is a compatibility, usability
17 # bug) and will be backported. At this point the spec is stabilizing
18 # and the updates are becoming fewer, smaller, and less significant.
21 This is a Py2.3 implementation of decimal floating point arithmetic based on
22 the General Decimal Arithmetic Specification:
24 www2.hursley.ibm.com/decimal/decarith.html
26 and IEEE standard 854-1987:
28 www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html
30 Decimal floating point has finite precision with arbitrarily large bounds.
32 The purpose of this module is to support arithmetic using familiar
33 "schoolhouse" rules and to avoid some of the tricky representation
34 issues associated with binary floating point. The package is especially
35 useful for financial applications or for contexts where users have
36 expectations that are at odds with binary floating point (for instance,
37 in binary floating point, 1.00 % 0.1 gives 0.09999999999999995 instead
38 of the expected Decimal('0.00') returned by decimal floating point).
40 Here are some examples of using the decimal module:
42 >>> from decimal import *
43 >>> setcontext(ExtendedContext)
52 >>> Decimal('123.45e12345678901234567890')
53 Decimal('1.2345E+12345678901234567892')
54 >>> Decimal('1.33') + Decimal('1.27')
56 >>> Decimal('12.34') + Decimal('3.87') - Decimal('18.41')
59 >>> print dig / Decimal(3)
61 >>> getcontext().prec = 18
62 >>> print dig / Decimal(3)
66 >>> print Decimal(3).sqrt()
68 >>> print Decimal(3) ** 123
69 4.85192780976896427E+58
70 >>> inf = Decimal(1) / Decimal(0)
73 >>> neginf = Decimal(-1) / Decimal(0)
76 >>> print neginf + inf
78 >>> print neginf * inf
82 >>> getcontext().traps[DivisionByZero] = 1
84 Traceback (most recent call last):
90 >>> c.traps[InvalidOperation] = 0
91 >>> print c.flags[InvalidOperation]
93 >>> c.divide(Decimal(0), Decimal(0))
95 >>> c.traps[InvalidOperation] = 1
96 >>> print c.flags[InvalidOperation]
98 >>> c.flags[InvalidOperation] = 0
99 >>> print c.flags[InvalidOperation]
101 >>> print c.divide(Decimal(0), Decimal(0))
102 Traceback (most recent call last):
106 InvalidOperation: 0 / 0
107 >>> print c.flags[InvalidOperation]
109 >>> c.flags[InvalidOperation] = 0
110 >>> c.traps[InvalidOperation] = 0
111 >>> print c.divide(Decimal(0), Decimal(0))
113 >>> print c.flags[InvalidOperation]
120 'Decimal', 'Context',
123 'DefaultContext', 'BasicContext', 'ExtendedContext',
126 'DecimalException', 'Clamped', 'InvalidOperation', 'DivisionByZero',
127 'Inexact', 'Rounded', 'Subnormal', 'Overflow', 'Underflow',
129 # Constants for use in setting up contexts
130 'ROUND_DOWN', 'ROUND_HALF_UP', 'ROUND_HALF_EVEN', 'ROUND_CEILING',
131 'ROUND_FLOOR', 'ROUND_UP', 'ROUND_HALF_DOWN', 'ROUND_05UP',
133 # Functions for manipulating contexts
134 'setcontext', 'getcontext', 'localcontext'
137 __version__
= '1.70' # Highest version of the spec this complies with
141 import numbers
as _numbers
144 from collections
import namedtuple
as _namedtuple
145 DecimalTuple
= _namedtuple('DecimalTuple', 'sign digits exponent')
147 DecimalTuple
= lambda *args
: args
150 ROUND_DOWN
= 'ROUND_DOWN'
151 ROUND_HALF_UP
= 'ROUND_HALF_UP'
152 ROUND_HALF_EVEN
= 'ROUND_HALF_EVEN'
153 ROUND_CEILING
= 'ROUND_CEILING'
154 ROUND_FLOOR
= 'ROUND_FLOOR'
155 ROUND_UP
= 'ROUND_UP'
156 ROUND_HALF_DOWN
= 'ROUND_HALF_DOWN'
157 ROUND_05UP
= 'ROUND_05UP'
161 class DecimalException(ArithmeticError):
162 """Base exception class.
164 Used exceptions derive from this.
165 If an exception derives from another exception besides this (such as
166 Underflow (Inexact, Rounded, Subnormal) that indicates that it is only
167 called if the others are present. This isn't actually used for
170 handle -- Called when context._raise_error is called and the
171 trap_enabler is set. First argument is self, second is the
172 context. More arguments can be given, those being after
173 the explanation in _raise_error (For example,
174 context._raise_error(NewError, '(-x)!', self._sign) would
175 call NewError().handle(context, self._sign).)
177 To define a new exception, it should be sufficient to have it derive
178 from DecimalException.
180 def handle(self
, context
, *args
):
184 class Clamped(DecimalException
):
185 """Exponent of a 0 changed to fit bounds.
187 This occurs and signals clamped if the exponent of a result has been
188 altered in order to fit the constraints of a specific concrete
189 representation. This may occur when the exponent of a zero result would
190 be outside the bounds of a representation, or when a large normal
191 number would have an encoded exponent that cannot be represented. In
192 this latter case, the exponent is reduced to fit and the corresponding
193 number of zero digits are appended to the coefficient ("fold-down").
196 class InvalidOperation(DecimalException
):
197 """An invalid operation was performed.
199 Various bad things cause this:
201 Something creates a signaling NaN
207 x._rescale( non-integer )
212 An operand is invalid
214 The result of the operation after these is a quiet positive NaN,
215 except when the cause is a signaling NaN, in which case the result is
216 also a quiet NaN, but with the original sign, and an optional
217 diagnostic information.
219 def handle(self
, context
, *args
):
221 ans
= _dec_from_triple(args
[0]._sign
, args
[0]._int
, 'n', True)
222 return ans
._fix
_nan
(context
)
225 class ConversionSyntax(InvalidOperation
):
226 """Trying to convert badly formed string.
228 This occurs and signals invalid-operation if an string is being
229 converted to a number and it does not conform to the numeric string
230 syntax. The result is [0,qNaN].
232 def handle(self
, context
, *args
):
235 class DivisionByZero(DecimalException
, ZeroDivisionError):
238 This occurs and signals division-by-zero if division of a finite number
239 by zero was attempted (during a divide-integer or divide operation, or a
240 power operation with negative right-hand operand), and the dividend was
243 The result of the operation is [sign,inf], where sign is the exclusive
244 or of the signs of the operands for divide, or is 1 for an odd power of
248 def handle(self
, context
, sign
, *args
):
249 return _SignedInfinity
[sign
]
251 class DivisionImpossible(InvalidOperation
):
252 """Cannot perform the division adequately.
254 This occurs and signals invalid-operation if the integer result of a
255 divide-integer or remainder operation had too many digits (would be
256 longer than precision). The result is [0,qNaN].
259 def handle(self
, context
, *args
):
262 class DivisionUndefined(InvalidOperation
, ZeroDivisionError):
263 """Undefined result of division.
265 This occurs and signals invalid-operation if division by zero was
266 attempted (during a divide-integer, divide, or remainder operation), and
267 the dividend is also zero. The result is [0,qNaN].
270 def handle(self
, context
, *args
):
273 class Inexact(DecimalException
):
274 """Had to round, losing information.
276 This occurs and signals inexact whenever the result of an operation is
277 not exact (that is, it needed to be rounded and any discarded digits
278 were non-zero), or if an overflow or underflow condition occurs. The
279 result in all cases is unchanged.
281 The inexact signal may be tested (or trapped) to determine if a given
282 operation (or sequence of operations) was inexact.
285 class InvalidContext(InvalidOperation
):
286 """Invalid context. Unknown rounding, for example.
288 This occurs and signals invalid-operation if an invalid context was
289 detected during an operation. This can occur if contexts are not checked
290 on creation and either the precision exceeds the capability of the
291 underlying concrete representation or an unknown or unsupported rounding
292 was specified. These aspects of the context need only be checked when
293 the values are required to be used. The result is [0,qNaN].
296 def handle(self
, context
, *args
):
299 class Rounded(DecimalException
):
300 """Number got rounded (not necessarily changed during rounding).
302 This occurs and signals rounded whenever the result of an operation is
303 rounded (that is, some zero or non-zero digits were discarded from the
304 coefficient), or if an overflow or underflow condition occurs. The
305 result in all cases is unchanged.
307 The rounded signal may be tested (or trapped) to determine if a given
308 operation (or sequence of operations) caused a loss of precision.
311 class Subnormal(DecimalException
):
312 """Exponent < Emin before rounding.
314 This occurs and signals subnormal whenever the result of a conversion or
315 operation is subnormal (that is, its adjusted exponent is less than
316 Emin, before any rounding). The result in all cases is unchanged.
318 The subnormal signal may be tested (or trapped) to determine if a given
319 or operation (or sequence of operations) yielded a subnormal result.
322 class Overflow(Inexact
, Rounded
):
323 """Numerical overflow.
325 This occurs and signals overflow if the adjusted exponent of a result
326 (from a conversion or from an operation that is not an attempt to divide
327 by zero), after rounding, would be greater than the largest value that
328 can be handled by the implementation (the value Emax).
330 The result depends on the rounding mode:
332 For round-half-up and round-half-even (and for round-half-down and
333 round-up, if implemented), the result of the operation is [sign,inf],
334 where sign is the sign of the intermediate result. For round-down, the
335 result is the largest finite number that can be represented in the
336 current precision, with the sign of the intermediate result. For
337 round-ceiling, the result is the same as for round-down if the sign of
338 the intermediate result is 1, or is [0,inf] otherwise. For round-floor,
339 the result is the same as for round-down if the sign of the intermediate
340 result is 0, or is [1,inf] otherwise. In all cases, Inexact and Rounded
344 def handle(self
, context
, sign
, *args
):
345 if context
.rounding
in (ROUND_HALF_UP
, ROUND_HALF_EVEN
,
346 ROUND_HALF_DOWN
, ROUND_UP
):
347 return _SignedInfinity
[sign
]
349 if context
.rounding
== ROUND_CEILING
:
350 return _SignedInfinity
[sign
]
351 return _dec_from_triple(sign
, '9'*context
.prec
,
352 context
.Emax
-context
.prec
+1)
354 if context
.rounding
== ROUND_FLOOR
:
355 return _SignedInfinity
[sign
]
356 return _dec_from_triple(sign
, '9'*context
.prec
,
357 context
.Emax
-context
.prec
+1)
360 class Underflow(Inexact
, Rounded
, Subnormal
):
361 """Numerical underflow with result rounded to 0.
363 This occurs and signals underflow if a result is inexact and the
364 adjusted exponent of the result would be smaller (more negative) than
365 the smallest value that can be handled by the implementation (the value
366 Emin). That is, the result is both inexact and subnormal.
368 The result after an underflow will be a subnormal number rounded, if
369 necessary, so that its exponent is not less than Etiny. This may result
370 in 0 with the sign of the intermediate result and an exponent of Etiny.
372 In all cases, Inexact, Rounded, and Subnormal will also be raised.
375 # List of public traps and flags
376 _signals
= [Clamped
, DivisionByZero
, Inexact
, Overflow
, Rounded
,
377 Underflow
, InvalidOperation
, Subnormal
]
379 # Map conditions (per the spec) to signals
380 _condition_map
= {ConversionSyntax
:InvalidOperation
,
381 DivisionImpossible
:InvalidOperation
,
382 DivisionUndefined
:InvalidOperation
,
383 InvalidContext
:InvalidOperation
}
385 ##### Context Functions ##################################################
387 # The getcontext() and setcontext() function manage access to a thread-local
388 # current context. Py2.4 offers direct support for thread locals. If that
389 # is not available, use threading.currentThread() which is slower but will
390 # work for older Pythons. If threads are not part of the build, create a
391 # mock threading object with threading.local() returning the module namespace.
396 # Python was compiled without threads; create a mock object instead
398 class MockThreading(object):
399 def local(self
, sys
=sys
):
400 return sys
.modules
[__name__
]
401 threading
= MockThreading()
402 del sys
, MockThreading
407 except AttributeError:
409 # To fix reloading, force it to create a new context
410 # Old contexts have different exceptions in their dicts, making problems.
411 if hasattr(threading
.currentThread(), '__decimal_context__'):
412 del threading
.currentThread().__decimal
_context
__
414 def setcontext(context
):
415 """Set this thread's context to context."""
416 if context
in (DefaultContext
, BasicContext
, ExtendedContext
):
417 context
= context
.copy()
418 context
.clear_flags()
419 threading
.currentThread().__decimal
_context
__ = context
422 """Returns this thread's context.
424 If this thread does not yet have a context, returns
425 a new context and sets this thread's context.
426 New contexts are copies of DefaultContext.
429 return threading
.currentThread().__decimal
_context
__
430 except AttributeError:
432 threading
.currentThread().__decimal
_context
__ = context
437 local
= threading
.local()
438 if hasattr(local
, '__decimal_context__'):
439 del local
.__decimal
_context
__
441 def getcontext(_local
=local
):
442 """Returns this thread's context.
444 If this thread does not yet have a context, returns
445 a new context and sets this thread's context.
446 New contexts are copies of DefaultContext.
449 return _local
.__decimal
_context
__
450 except AttributeError:
452 _local
.__decimal
_context
__ = context
455 def setcontext(context
, _local
=local
):
456 """Set this thread's context to context."""
457 if context
in (DefaultContext
, BasicContext
, ExtendedContext
):
458 context
= context
.copy()
459 context
.clear_flags()
460 _local
.__decimal
_context
__ = context
462 del threading
, local
# Don't contaminate the namespace
464 def localcontext(ctx
=None):
465 """Return a context manager for a copy of the supplied context
467 Uses a copy of the current context if no context is specified
468 The returned context manager creates a local decimal context
471 with localcontext() as ctx:
473 # Rest of sin calculation algorithm
474 # uses a precision 2 greater than normal
475 return +s # Convert result to normal precision
478 with localcontext(ExtendedContext):
479 # Rest of sin calculation algorithm
480 # uses the Extended Context from the
481 # General Decimal Arithmetic Specification
482 return +s # Convert result to normal context
484 >>> setcontext(DefaultContext)
485 >>> print getcontext().prec
487 >>> with localcontext():
488 ... ctx = getcontext()
493 >>> with localcontext(ExtendedContext):
494 ... print getcontext().prec
497 >>> print getcontext().prec
500 if ctx
is None: ctx
= getcontext()
501 return _ContextManager(ctx
)
504 ##### Decimal class #######################################################
506 class Decimal(object):
507 """Floating point class for decimal arithmetic."""
509 __slots__
= ('_exp','_int','_sign', '_is_special')
510 # Generally, the value of the Decimal instance is given by
511 # (-1)**_sign * _int * 10**_exp
512 # Special values are signified by _is_special == True
514 # We're immutable, so use __new__ not __init__
515 def __new__(cls
, value
="0", context
=None):
516 """Create a decimal point instance.
518 >>> Decimal('3.14') # string input
520 >>> Decimal((0, (3, 1, 4), -2)) # tuple (sign, digit_tuple, exponent)
522 >>> Decimal(314) # int or long
524 >>> Decimal(Decimal(314)) # another decimal instance
526 >>> Decimal(' 3.14 \\n') # leading and trailing whitespace okay
530 # Note that the coefficient, self._int, is actually stored as
531 # a string rather than as a tuple of digits. This speeds up
532 # the "digits to integer" and "integer to digits" conversions
533 # that are used in almost every arithmetic operation on
534 # Decimals. This is an internal detail: the as_tuple function
535 # and the Decimal constructor still deal with tuples of
538 self
= object.__new
__(cls
)
541 # REs insist on real strings, so we can too.
542 if isinstance(value
, basestring
):
543 m
= _parser(value
.strip())
546 context
= getcontext()
547 return context
._raise
_error
(ConversionSyntax
,
548 "Invalid literal for Decimal: %r" % value
)
550 if m
.group('sign') == "-":
554 intpart
= m
.group('int')
555 if intpart
is not None:
557 fracpart
= m
.group('frac') or ''
558 exp
= int(m
.group('exp') or '0')
559 self
._int
= str(int(intpart
+fracpart
))
560 self
._exp
= exp
- len(fracpart
)
561 self
._is
_special
= False
563 diag
= m
.group('diag')
566 self
._int
= str(int(diag
or '0')).lstrip('0')
567 if m
.group('signal'):
575 self
._is
_special
= True
579 if isinstance(value
, (int,long)):
585 self
._int
= str(abs(value
))
586 self
._is
_special
= False
589 # From another decimal
590 if isinstance(value
, Decimal
):
591 self
._exp
= value
._exp
592 self
._sign
= value
._sign
593 self
._int
= value
._int
594 self
._is
_special
= value
._is
_special
597 # From an internal working value
598 if isinstance(value
, _WorkRep
):
599 self
._sign
= value
.sign
600 self
._int
= str(value
.int)
601 self
._exp
= int(value
.exp
)
602 self
._is
_special
= False
605 # tuple/list conversion (possibly from as_tuple())
606 if isinstance(value
, (list,tuple)):
608 raise ValueError('Invalid tuple size in creation of Decimal '
609 'from list or tuple. The list or tuple '
610 'should have exactly three elements.')
611 # process sign. The isinstance test rejects floats
612 if not (isinstance(value
[0], (int, long)) and value
[0] in (0,1)):
613 raise ValueError("Invalid sign. The first value in the tuple "
614 "should be an integer; either 0 for a "
615 "positive number or 1 for a negative number.")
616 self
._sign
= value
[0]
618 # infinity: value[1] is ignored
621 self
._is
_special
= True
623 # process and validate the digits in value[1]
625 for digit
in value
[1]:
626 if isinstance(digit
, (int, long)) and 0 <= digit
<= 9:
628 if digits
or digit
!= 0:
631 raise ValueError("The second value in the tuple must "
632 "be composed of integers in the range "
634 if value
[2] in ('n', 'N'):
635 # NaN: digits form the diagnostic
636 self
._int
= ''.join(map(str, digits
))
638 self
._is
_special
= True
639 elif isinstance(value
[2], (int, long)):
640 # finite number: digits give the coefficient
641 self
._int
= ''.join(map(str, digits
or [0]))
643 self
._is
_special
= False
645 raise ValueError("The third value in the tuple must "
646 "be an integer, or one of the "
647 "strings 'F', 'n', 'N'.")
650 if isinstance(value
, float):
651 raise TypeError("Cannot convert float to Decimal. " +
652 "First convert the float to a string")
654 raise TypeError("Cannot convert %r to Decimal" % value
)
656 # @classmethod, but @decorator is not valid Python 2.3 syntax, so
657 # don't use it (see notes on Py2.3 compatibility at top of file)
658 def from_float(cls
, f
):
659 """Converts a float to a decimal number, exactly.
661 Note that Decimal.from_float(0.1) is not the same as Decimal('0.1').
662 Since 0.1 is not exactly representable in binary floating point, the
663 value is stored as the nearest representable value which is
664 0x1.999999999999ap-4. The exact equivalent of the value in decimal
665 is 0.1000000000000000055511151231257827021181583404541015625.
667 >>> Decimal.from_float(0.1)
668 Decimal('0.1000000000000000055511151231257827021181583404541015625')
669 >>> Decimal.from_float(float('nan'))
671 >>> Decimal.from_float(float('inf'))
673 >>> Decimal.from_float(-float('inf'))
675 >>> Decimal.from_float(-0.0)
679 if isinstance(f
, (int, long)): # handle integer inputs
681 if _math
.isinf(f
) or _math
.isnan(f
): # raises TypeError if not a float
683 if _math
.copysign(1.0, f
) == 1.0:
687 n
, d
= abs(f
).as_integer_ratio()
688 k
= d
.bit_length() - 1
689 result
= _dec_from_triple(sign
, str(n
*5**k
), -k
)
694 from_float
= classmethod(from_float
)
697 """Returns whether the number is not actually one.
711 def _isinfinity(self
):
712 """Returns whether the number is infinite
714 0 if finite or not a number
724 def _check_nans(self
, other
=None, context
=None):
725 """Returns whether the number is not actually one.
727 if self, other are sNaN, signal
728 if self, other are NaN return nan
731 Done before operations.
734 self_is_nan
= self
._isnan
()
738 other_is_nan
= other
._isnan
()
740 if self_is_nan
or other_is_nan
:
742 context
= getcontext()
745 return context
._raise
_error
(InvalidOperation
, 'sNaN',
747 if other_is_nan
== 2:
748 return context
._raise
_error
(InvalidOperation
, 'sNaN',
751 return self
._fix
_nan
(context
)
753 return other
._fix
_nan
(context
)
756 def _compare_check_nans(self
, other
, context
):
757 """Version of _check_nans used for the signaling comparisons
758 compare_signal, __le__, __lt__, __ge__, __gt__.
760 Signal InvalidOperation if either self or other is a (quiet
761 or signaling) NaN. Signaling NaNs take precedence over quiet
764 Return 0 if neither operand is a NaN.
768 context
= getcontext()
770 if self
._is
_special
or other
._is
_special
:
772 return context
._raise
_error
(InvalidOperation
,
773 'comparison involving sNaN',
775 elif other
.is_snan():
776 return context
._raise
_error
(InvalidOperation
,
777 'comparison involving sNaN',
780 return context
._raise
_error
(InvalidOperation
,
781 'comparison involving NaN',
783 elif other
.is_qnan():
784 return context
._raise
_error
(InvalidOperation
,
785 'comparison involving NaN',
789 def __nonzero__(self
):
790 """Return True if self is nonzero; otherwise return False.
792 NaNs and infinities are considered nonzero.
794 return self
._is
_special
or self
._int
!= '0'
796 def _cmp(self
, other
):
797 """Compare the two non-NaN decimal instances self and other.
799 Returns -1 if self < other, 0 if self == other and 1
800 if self > other. This routine is for internal use only."""
802 if self
._is
_special
or other
._is
_special
:
803 self_inf
= self
._isinfinity
()
804 other_inf
= other
._isinfinity
()
805 if self_inf
== other_inf
:
807 elif self_inf
< other_inf
:
812 # check for zeros; Decimal('0') == Decimal('-0')
817 return -((-1)**other
._sign
)
819 return (-1)**self
._sign
821 # If different signs, neg one is less
822 if other
._sign
< self
._sign
:
824 if self
._sign
< other
._sign
:
827 self_adjusted
= self
.adjusted()
828 other_adjusted
= other
.adjusted()
829 if self_adjusted
== other_adjusted
:
830 self_padded
= self
._int
+ '0'*(self
._exp
- other
._exp
)
831 other_padded
= other
._int
+ '0'*(other
._exp
- self
._exp
)
832 if self_padded
== other_padded
:
834 elif self_padded
< other_padded
:
835 return -(-1)**self
._sign
837 return (-1)**self
._sign
838 elif self_adjusted
> other_adjusted
:
839 return (-1)**self
._sign
840 else: # self_adjusted < other_adjusted
841 return -((-1)**self
._sign
)
843 # Note: The Decimal standard doesn't cover rich comparisons for
844 # Decimals. In particular, the specification is silent on the
845 # subject of what should happen for a comparison involving a NaN.
846 # We take the following approach:
848 # == comparisons involving a NaN always return False
849 # != comparisons involving a NaN always return True
850 # <, >, <= and >= comparisons involving a (quiet or signaling)
851 # NaN signal InvalidOperation, and return False if the
852 # InvalidOperation is not trapped.
854 # This behavior is designed to conform as closely as possible to
855 # that specified by IEEE 754.
857 def __eq__(self
, other
):
858 other
= _convert_other(other
)
859 if other
is NotImplemented:
861 if self
.is_nan() or other
.is_nan():
863 return self
._cmp
(other
) == 0
865 def __ne__(self
, other
):
866 other
= _convert_other(other
)
867 if other
is NotImplemented:
869 if self
.is_nan() or other
.is_nan():
871 return self
._cmp
(other
) != 0
873 def __lt__(self
, other
, context
=None):
874 other
= _convert_other(other
)
875 if other
is NotImplemented:
877 ans
= self
._compare
_check
_nans
(other
, context
)
880 return self
._cmp
(other
) < 0
882 def __le__(self
, other
, context
=None):
883 other
= _convert_other(other
)
884 if other
is NotImplemented:
886 ans
= self
._compare
_check
_nans
(other
, context
)
889 return self
._cmp
(other
) <= 0
891 def __gt__(self
, other
, context
=None):
892 other
= _convert_other(other
)
893 if other
is NotImplemented:
895 ans
= self
._compare
_check
_nans
(other
, context
)
898 return self
._cmp
(other
) > 0
900 def __ge__(self
, other
, context
=None):
901 other
= _convert_other(other
)
902 if other
is NotImplemented:
904 ans
= self
._compare
_check
_nans
(other
, context
)
907 return self
._cmp
(other
) >= 0
909 def compare(self
, other
, context
=None):
910 """Compares one to another.
916 Like __cmp__, but returns Decimal instances.
918 other
= _convert_other(other
, raiseit
=True)
920 # Compare(NaN, NaN) = NaN
921 if (self
._is
_special
or other
and other
._is
_special
):
922 ans
= self
._check
_nans
(other
, context
)
926 return Decimal(self
._cmp
(other
))
929 """x.__hash__() <==> hash(x)"""
930 # Decimal integers must hash the same as the ints
932 # The hash of a nonspecial noninteger Decimal must depend only
933 # on the value of that Decimal, and not on its representation.
934 # For example: hash(Decimal('100E-1')) == hash(Decimal('10')).
937 raise TypeError('Cannot hash a NaN value.')
938 return hash(str(self
))
941 if self
._isinteger
():
942 op
= _WorkRep(self
.to_integral_value())
943 # to make computation feasible for Decimals with large
944 # exponent, we use the fact that hash(n) == hash(m) for
945 # any two nonzero integers n and m such that (i) n and m
946 # have the same sign, and (ii) n is congruent to m modulo
947 # 2**64-1. So we can replace hash((-1)**s*c*10**e) with
948 # hash((-1)**s*c*pow(10, e, 2**64-1).
949 return hash((-1)**op
.sign
*op
.int*pow(10, op
.exp
, 2**64-1))
950 # The value of a nonzero nonspecial Decimal instance is
951 # faithfully represented by the triple consisting of its sign,
952 # its adjusted exponent, and its coefficient with trailing
954 return hash((self
._sign
,
955 self
._exp
+len(self
._int
),
956 self
._int
.rstrip('0')))
959 """Represents the number as a triple tuple.
961 To show the internals exactly as they are.
963 return DecimalTuple(self
._sign
, tuple(map(int, self
._int
)), self
._exp
)
966 """Represents the number as an instance of Decimal."""
967 # Invariant: eval(repr(d)) == d
968 return "Decimal('%s')" % str(self
)
970 def __str__(self
, eng
=False, context
=None):
971 """Return string representation of the number in scientific notation.
973 Captures all of the information in the underlying representation.
976 sign
= ['', '-'][self
._sign
]
979 return sign
+ 'Infinity'
980 elif self
._exp
== 'n':
981 return sign
+ 'NaN' + self
._int
982 else: # self._exp == 'N'
983 return sign
+ 'sNaN' + self
._int
985 # number of digits of self._int to left of decimal point
986 leftdigits
= self
._exp
+ len(self
._int
)
988 # dotplace is number of digits of self._int to the left of the
989 # decimal point in the mantissa of the output string (that is,
990 # after adjusting the exponent)
991 if self
._exp
<= 0 and leftdigits
> -6:
992 # no exponent required
993 dotplace
= leftdigits
995 # usual scientific notation: 1 digit on left of the point
997 elif self
._int
== '0':
998 # engineering notation, zero
999 dotplace
= (leftdigits
+ 1) % 3 - 1
1001 # engineering notation, nonzero
1002 dotplace
= (leftdigits
- 1) % 3 + 1
1006 fracpart
= '.' + '0'*(-dotplace
) + self
._int
1007 elif dotplace
>= len(self
._int
):
1008 intpart
= self
._int
+'0'*(dotplace
-len(self
._int
))
1011 intpart
= self
._int
[:dotplace
]
1012 fracpart
= '.' + self
._int
[dotplace
:]
1013 if leftdigits
== dotplace
:
1017 context
= getcontext()
1018 exp
= ['e', 'E'][context
.capitals
] + "%+d" % (leftdigits
-dotplace
)
1020 return sign
+ intpart
+ fracpart
+ exp
1022 def to_eng_string(self
, context
=None):
1023 """Convert to engineering-type string.
1025 Engineering notation has an exponent which is a multiple of 3, so there
1026 are up to 3 digits left of the decimal place.
1028 Same rules for when in exponential and when as a value as in __str__.
1030 return self
.__str
__(eng
=True, context
=context
)
1032 def __neg__(self
, context
=None):
1033 """Returns a copy with the sign switched.
1035 Rounds, if it has reason.
1037 if self
._is
_special
:
1038 ans
= self
._check
_nans
(context
=context
)
1043 # -Decimal('0') is Decimal('0'), not Decimal('-0')
1044 ans
= self
.copy_abs()
1046 ans
= self
.copy_negate()
1049 context
= getcontext()
1050 return ans
._fix
(context
)
1052 def __pos__(self
, context
=None):
1053 """Returns a copy, unless it is a sNaN.
1055 Rounds the number (if more then precision digits)
1057 if self
._is
_special
:
1058 ans
= self
._check
_nans
(context
=context
)
1064 ans
= self
.copy_abs()
1069 context
= getcontext()
1070 return ans
._fix
(context
)
1072 def __abs__(self
, round=True, context
=None):
1073 """Returns the absolute value of self.
1075 If the keyword argument 'round' is false, do not round. The
1076 expression self.__abs__(round=False) is equivalent to
1080 return self
.copy_abs()
1082 if self
._is
_special
:
1083 ans
= self
._check
_nans
(context
=context
)
1088 ans
= self
.__neg
__(context
=context
)
1090 ans
= self
.__pos
__(context
=context
)
1094 def __add__(self
, other
, context
=None):
1095 """Returns self + other.
1097 -INF + INF (or the reverse) cause InvalidOperation errors.
1099 other
= _convert_other(other
)
1100 if other
is NotImplemented:
1104 context
= getcontext()
1106 if self
._is
_special
or other
._is
_special
:
1107 ans
= self
._check
_nans
(other
, context
)
1111 if self
._isinfinity
():
1112 # If both INF, same sign => same as both, opposite => error.
1113 if self
._sign
!= other
._sign
and other
._isinfinity
():
1114 return context
._raise
_error
(InvalidOperation
, '-INF + INF')
1115 return Decimal(self
)
1116 if other
._isinfinity
():
1117 return Decimal(other
) # Can't both be infinity here
1119 exp
= min(self
._exp
, other
._exp
)
1121 if context
.rounding
== ROUND_FLOOR
and self
._sign
!= other
._sign
:
1122 # If the answer is 0, the sign should be negative, in this case.
1125 if not self
and not other
:
1126 sign
= min(self
._sign
, other
._sign
)
1129 ans
= _dec_from_triple(sign
, '0', exp
)
1130 ans
= ans
._fix
(context
)
1133 exp
= max(exp
, other
._exp
- context
.prec
-1)
1134 ans
= other
._rescale
(exp
, context
.rounding
)
1135 ans
= ans
._fix
(context
)
1138 exp
= max(exp
, self
._exp
- context
.prec
-1)
1139 ans
= self
._rescale
(exp
, context
.rounding
)
1140 ans
= ans
._fix
(context
)
1143 op1
= _WorkRep(self
)
1144 op2
= _WorkRep(other
)
1145 op1
, op2
= _normalize(op1
, op2
, context
.prec
)
1148 if op1
.sign
!= op2
.sign
:
1149 # Equal and opposite
1150 if op1
.int == op2
.int:
1151 ans
= _dec_from_triple(negativezero
, '0', exp
)
1152 ans
= ans
._fix
(context
)
1154 if op1
.int < op2
.int:
1156 # OK, now abs(op1) > abs(op2)
1159 op1
.sign
, op2
.sign
= op2
.sign
, op1
.sign
1162 # So we know the sign, and op1 > 0.
1165 op1
.sign
, op2
.sign
= (0, 0)
1168 # Now, op1 > abs(op2) > 0
1171 result
.int = op1
.int + op2
.int
1173 result
.int = op1
.int - op2
.int
1175 result
.exp
= op1
.exp
1176 ans
= Decimal(result
)
1177 ans
= ans
._fix
(context
)
1182 def __sub__(self
, other
, context
=None):
1183 """Return self - other"""
1184 other
= _convert_other(other
)
1185 if other
is NotImplemented:
1188 if self
._is
_special
or other
._is
_special
:
1189 ans
= self
._check
_nans
(other
, context
=context
)
1193 # self - other is computed as self + other.copy_negate()
1194 return self
.__add
__(other
.copy_negate(), context
=context
)
1196 def __rsub__(self
, other
, context
=None):
1197 """Return other - self"""
1198 other
= _convert_other(other
)
1199 if other
is NotImplemented:
1202 return other
.__sub
__(self
, context
=context
)
1204 def __mul__(self
, other
, context
=None):
1205 """Return self * other.
1207 (+-) INF * 0 (or its reverse) raise InvalidOperation.
1209 other
= _convert_other(other
)
1210 if other
is NotImplemented:
1214 context
= getcontext()
1216 resultsign
= self
._sign ^ other
._sign
1218 if self
._is
_special
or other
._is
_special
:
1219 ans
= self
._check
_nans
(other
, context
)
1223 if self
._isinfinity
():
1225 return context
._raise
_error
(InvalidOperation
, '(+-)INF * 0')
1226 return _SignedInfinity
[resultsign
]
1228 if other
._isinfinity
():
1230 return context
._raise
_error
(InvalidOperation
, '0 * (+-)INF')
1231 return _SignedInfinity
[resultsign
]
1233 resultexp
= self
._exp
+ other
._exp
1235 # Special case for multiplying by zero
1236 if not self
or not other
:
1237 ans
= _dec_from_triple(resultsign
, '0', resultexp
)
1238 # Fixing in case the exponent is out of bounds
1239 ans
= ans
._fix
(context
)
1242 # Special case for multiplying by power of 10
1243 if self
._int
== '1':
1244 ans
= _dec_from_triple(resultsign
, other
._int
, resultexp
)
1245 ans
= ans
._fix
(context
)
1247 if other
._int
== '1':
1248 ans
= _dec_from_triple(resultsign
, self
._int
, resultexp
)
1249 ans
= ans
._fix
(context
)
1252 op1
= _WorkRep(self
)
1253 op2
= _WorkRep(other
)
1255 ans
= _dec_from_triple(resultsign
, str(op1
.int * op2
.int), resultexp
)
1256 ans
= ans
._fix
(context
)
1261 def __truediv__(self
, other
, context
=None):
1262 """Return self / other."""
1263 other
= _convert_other(other
)
1264 if other
is NotImplemented:
1265 return NotImplemented
1268 context
= getcontext()
1270 sign
= self
._sign ^ other
._sign
1272 if self
._is
_special
or other
._is
_special
:
1273 ans
= self
._check
_nans
(other
, context
)
1277 if self
._isinfinity
() and other
._isinfinity
():
1278 return context
._raise
_error
(InvalidOperation
, '(+-)INF/(+-)INF')
1280 if self
._isinfinity
():
1281 return _SignedInfinity
[sign
]
1283 if other
._isinfinity
():
1284 context
._raise
_error
(Clamped
, 'Division by infinity')
1285 return _dec_from_triple(sign
, '0', context
.Etiny())
1287 # Special cases for zeroes
1290 return context
._raise
_error
(DivisionUndefined
, '0 / 0')
1291 return context
._raise
_error
(DivisionByZero
, 'x / 0', sign
)
1294 exp
= self
._exp
- other
._exp
1297 # OK, so neither = 0, INF or NaN
1298 shift
= len(other
._int
) - len(self
._int
) + context
.prec
+ 1
1299 exp
= self
._exp
- other
._exp
- shift
1300 op1
= _WorkRep(self
)
1301 op2
= _WorkRep(other
)
1303 coeff
, remainder
= divmod(op1
.int * 10**shift
, op2
.int)
1305 coeff
, remainder
= divmod(op1
.int, op2
.int * 10**-shift
)
1307 # result is not exact; adjust to ensure correct rounding
1311 # result is exact; get as close to ideal exponent as possible
1312 ideal_exp
= self
._exp
- other
._exp
1313 while exp
< ideal_exp
and coeff
% 10 == 0:
1317 ans
= _dec_from_triple(sign
, str(coeff
), exp
)
1318 return ans
._fix
(context
)
1320 def _divide(self
, other
, context
):
1321 """Return (self // other, self % other), to context.prec precision.
1323 Assumes that neither self nor other is a NaN, that self is not
1324 infinite and that other is nonzero.
1326 sign
= self
._sign ^ other
._sign
1327 if other
._isinfinity
():
1328 ideal_exp
= self
._exp
1330 ideal_exp
= min(self
._exp
, other
._exp
)
1332 expdiff
= self
.adjusted() - other
.adjusted()
1333 if not self
or other
._isinfinity
() or expdiff
<= -2:
1334 return (_dec_from_triple(sign
, '0', 0),
1335 self
._rescale
(ideal_exp
, context
.rounding
))
1336 if expdiff
<= context
.prec
:
1337 op1
= _WorkRep(self
)
1338 op2
= _WorkRep(other
)
1339 if op1
.exp
>= op2
.exp
:
1340 op1
.int *= 10**(op1
.exp
- op2
.exp
)
1342 op2
.int *= 10**(op2
.exp
- op1
.exp
)
1343 q
, r
= divmod(op1
.int, op2
.int)
1344 if q
< 10**context
.prec
:
1345 return (_dec_from_triple(sign
, str(q
), 0),
1346 _dec_from_triple(self
._sign
, str(r
), ideal_exp
))
1348 # Here the quotient is too large to be representable
1349 ans
= context
._raise
_error
(DivisionImpossible
,
1350 'quotient too large in //, % or divmod')
1353 def __rtruediv__(self
, other
, context
=None):
1354 """Swaps self/other and returns __truediv__."""
1355 other
= _convert_other(other
)
1356 if other
is NotImplemented:
1358 return other
.__truediv
__(self
, context
=context
)
1360 __div__
= __truediv__
1361 __rdiv__
= __rtruediv__
1363 def __divmod__(self
, other
, context
=None):
1365 Return (self // other, self % other)
1367 other
= _convert_other(other
)
1368 if other
is NotImplemented:
1372 context
= getcontext()
1374 ans
= self
._check
_nans
(other
, context
)
1378 sign
= self
._sign ^ other
._sign
1379 if self
._isinfinity
():
1380 if other
._isinfinity
():
1381 ans
= context
._raise
_error
(InvalidOperation
, 'divmod(INF, INF)')
1384 return (_SignedInfinity
[sign
],
1385 context
._raise
_error
(InvalidOperation
, 'INF % x'))
1389 ans
= context
._raise
_error
(DivisionUndefined
, 'divmod(0, 0)')
1392 return (context
._raise
_error
(DivisionByZero
, 'x // 0', sign
),
1393 context
._raise
_error
(InvalidOperation
, 'x % 0'))
1395 quotient
, remainder
= self
._divide
(other
, context
)
1396 remainder
= remainder
._fix
(context
)
1397 return quotient
, remainder
1399 def __rdivmod__(self
, other
, context
=None):
1400 """Swaps self/other and returns __divmod__."""
1401 other
= _convert_other(other
)
1402 if other
is NotImplemented:
1404 return other
.__divmod
__(self
, context
=context
)
1406 def __mod__(self
, other
, context
=None):
1410 other
= _convert_other(other
)
1411 if other
is NotImplemented:
1415 context
= getcontext()
1417 ans
= self
._check
_nans
(other
, context
)
1421 if self
._isinfinity
():
1422 return context
._raise
_error
(InvalidOperation
, 'INF % x')
1425 return context
._raise
_error
(InvalidOperation
, 'x % 0')
1427 return context
._raise
_error
(DivisionUndefined
, '0 % 0')
1429 remainder
= self
._divide
(other
, context
)[1]
1430 remainder
= remainder
._fix
(context
)
1433 def __rmod__(self
, other
, context
=None):
1434 """Swaps self/other and returns __mod__."""
1435 other
= _convert_other(other
)
1436 if other
is NotImplemented:
1438 return other
.__mod
__(self
, context
=context
)
1440 def remainder_near(self
, other
, context
=None):
1442 Remainder nearest to 0- abs(remainder-near) <= other/2
1445 context
= getcontext()
1447 other
= _convert_other(other
, raiseit
=True)
1449 ans
= self
._check
_nans
(other
, context
)
1453 # self == +/-infinity -> InvalidOperation
1454 if self
._isinfinity
():
1455 return context
._raise
_error
(InvalidOperation
,
1456 'remainder_near(infinity, x)')
1458 # other == 0 -> either InvalidOperation or DivisionUndefined
1461 return context
._raise
_error
(InvalidOperation
,
1462 'remainder_near(x, 0)')
1464 return context
._raise
_error
(DivisionUndefined
,
1465 'remainder_near(0, 0)')
1467 # other = +/-infinity -> remainder = self
1468 if other
._isinfinity
():
1470 return ans
._fix
(context
)
1472 # self = 0 -> remainder = self, with ideal exponent
1473 ideal_exponent
= min(self
._exp
, other
._exp
)
1475 ans
= _dec_from_triple(self
._sign
, '0', ideal_exponent
)
1476 return ans
._fix
(context
)
1478 # catch most cases of large or small quotient
1479 expdiff
= self
.adjusted() - other
.adjusted()
1480 if expdiff
>= context
.prec
+ 1:
1481 # expdiff >= prec+1 => abs(self/other) > 10**prec
1482 return context
._raise
_error
(DivisionImpossible
)
1484 # expdiff <= -2 => abs(self/other) < 0.1
1485 ans
= self
._rescale
(ideal_exponent
, context
.rounding
)
1486 return ans
._fix
(context
)
1488 # adjust both arguments to have the same exponent, then divide
1489 op1
= _WorkRep(self
)
1490 op2
= _WorkRep(other
)
1491 if op1
.exp
>= op2
.exp
:
1492 op1
.int *= 10**(op1
.exp
- op2
.exp
)
1494 op2
.int *= 10**(op2
.exp
- op1
.exp
)
1495 q
, r
= divmod(op1
.int, op2
.int)
1496 # remainder is r*10**ideal_exponent; other is +/-op2.int *
1497 # 10**ideal_exponent. Apply correction to ensure that
1498 # abs(remainder) <= abs(other)/2
1499 if 2*r
+ (q
&1) > op2
.int:
1503 if q
>= 10**context
.prec
:
1504 return context
._raise
_error
(DivisionImpossible
)
1506 # result has same sign as self unless r is negative
1512 ans
= _dec_from_triple(sign
, str(r
), ideal_exponent
)
1513 return ans
._fix
(context
)
1515 def __floordiv__(self
, other
, context
=None):
1517 other
= _convert_other(other
)
1518 if other
is NotImplemented:
1522 context
= getcontext()
1524 ans
= self
._check
_nans
(other
, context
)
1528 if self
._isinfinity
():
1529 if other
._isinfinity
():
1530 return context
._raise
_error
(InvalidOperation
, 'INF // INF')
1532 return _SignedInfinity
[self
._sign ^ other
._sign
]
1536 return context
._raise
_error
(DivisionByZero
, 'x // 0',
1537 self
._sign ^ other
._sign
)
1539 return context
._raise
_error
(DivisionUndefined
, '0 // 0')
1541 return self
._divide
(other
, context
)[0]
1543 def __rfloordiv__(self
, other
, context
=None):
1544 """Swaps self/other and returns __floordiv__."""
1545 other
= _convert_other(other
)
1546 if other
is NotImplemented:
1548 return other
.__floordiv
__(self
, context
=context
)
1550 def __float__(self
):
1551 """Float representation."""
1552 return float(str(self
))
1555 """Converts self to an int, truncating if necessary."""
1556 if self
._is
_special
:
1558 raise ValueError("Cannot convert NaN to integer")
1559 elif self
._isinfinity
():
1560 raise OverflowError("Cannot convert infinity to integer")
1561 s
= (-1)**self
._sign
1563 return s
*int(self
._int
)*10**self
._exp
1565 return s
*int(self
._int
[:self
._exp
] or '0')
1571 real
= property(real
)
1575 imag
= property(imag
)
1577 def conjugate(self
):
1580 def __complex__(self
):
1581 return complex(float(self
))
1584 """Converts to a long.
1586 Equivalent to long(int(self))
1588 return long(self
.__int
__())
1590 def _fix_nan(self
, context
):
1591 """Decapitate the payload of a NaN to fit the context"""
1594 # maximum length of payload is precision if _clamp=0,
1595 # precision-1 if _clamp=1.
1596 max_payload_len
= context
.prec
- context
._clamp
1597 if len(payload
) > max_payload_len
:
1598 payload
= payload
[len(payload
)-max_payload_len
:].lstrip('0')
1599 return _dec_from_triple(self
._sign
, payload
, self
._exp
, True)
1600 return Decimal(self
)
1602 def _fix(self
, context
):
1603 """Round if it is necessary to keep self within prec precision.
1605 Rounds and fixes the exponent. Does not raise on a sNaN.
1608 self - Decimal instance
1609 context - context used.
1612 if self
._is
_special
:
1614 # decapitate payload if necessary
1615 return self
._fix
_nan
(context
)
1617 # self is +/-Infinity; return unaltered
1618 return Decimal(self
)
1620 # if self is zero then exponent should be between Etiny and
1621 # Emax if _clamp==0, and between Etiny and Etop if _clamp==1.
1622 Etiny
= context
.Etiny()
1623 Etop
= context
.Etop()
1625 exp_max
= [context
.Emax
, Etop
][context
._clamp
]
1626 new_exp
= min(max(self
._exp
, Etiny
), exp_max
)
1627 if new_exp
!= self
._exp
:
1628 context
._raise
_error
(Clamped
)
1629 return _dec_from_triple(self
._sign
, '0', new_exp
)
1631 return Decimal(self
)
1633 # exp_min is the smallest allowable exponent of the result,
1634 # equal to max(self.adjusted()-context.prec+1, Etiny)
1635 exp_min
= len(self
._int
) + self
._exp
- context
.prec
1637 # overflow: exp_min > Etop iff self.adjusted() > Emax
1638 context
._raise
_error
(Inexact
)
1639 context
._raise
_error
(Rounded
)
1640 return context
._raise
_error
(Overflow
, 'above Emax', self
._sign
)
1641 self_is_subnormal
= exp_min
< Etiny
1642 if self_is_subnormal
:
1643 context
._raise
_error
(Subnormal
)
1646 # round if self has too many digits
1647 if self
._exp
< exp_min
:
1648 context
._raise
_error
(Rounded
)
1649 digits
= len(self
._int
) + self
._exp
- exp_min
1651 self
= _dec_from_triple(self
._sign
, '1', exp_min
-1)
1653 this_function
= getattr(self
, self
._pick
_rounding
_function
[context
.rounding
])
1654 changed
= this_function(digits
)
1655 coeff
= self
._int
[:digits
] or '0'
1657 coeff
= str(int(coeff
)+1)
1658 ans
= _dec_from_triple(self
._sign
, coeff
, exp_min
)
1661 context
._raise
_error
(Inexact
)
1662 if self_is_subnormal
:
1663 context
._raise
_error
(Underflow
)
1665 # raise Clamped on underflow to 0
1666 context
._raise
_error
(Clamped
)
1667 elif len(ans
._int
) == context
.prec
+1:
1668 # we get here only if rescaling rounds the
1669 # cofficient up to exactly 10**context.prec
1671 ans
= _dec_from_triple(ans
._sign
,
1672 ans
._int
[:-1], ans
._exp
+1)
1674 # Inexact and Rounded have already been raised
1675 ans
= context
._raise
_error
(Overflow
, 'above Emax',
1679 # fold down if _clamp == 1 and self has too few digits
1680 if context
._clamp
== 1 and self
._exp
> Etop
:
1681 context
._raise
_error
(Clamped
)
1682 self_padded
= self
._int
+ '0'*(self
._exp
- Etop
)
1683 return _dec_from_triple(self
._sign
, self_padded
, Etop
)
1685 # here self was representable to begin with; return unchanged
1686 return Decimal(self
)
1688 _pick_rounding_function
= {}
1690 # for each of the rounding functions below:
1691 # self is a finite, nonzero Decimal
1692 # prec is an integer satisfying 0 <= prec < len(self._int)
1694 # each function returns either -1, 0, or 1, as follows:
1695 # 1 indicates that self should be rounded up (away from zero)
1696 # 0 indicates that self should be truncated, and that all the
1697 # digits to be truncated are zeros (so the value is unchanged)
1698 # -1 indicates that there are nonzero digits to be truncated
1700 def _round_down(self
, prec
):
1701 """Also known as round-towards-0, truncate."""
1702 if _all_zeros(self
._int
, prec
):
1707 def _round_up(self
, prec
):
1708 """Rounds away from 0."""
1709 return -self
._round
_down
(prec
)
1711 def _round_half_up(self
, prec
):
1712 """Rounds 5 up (away from 0)"""
1713 if self
._int
[prec
] in '56789':
1715 elif _all_zeros(self
._int
, prec
):
1720 def _round_half_down(self
, prec
):
1722 if _exact_half(self
._int
, prec
):
1725 return self
._round
_half
_up
(prec
)
1727 def _round_half_even(self
, prec
):
1728 """Round 5 to even, rest to nearest."""
1729 if _exact_half(self
._int
, prec
) and \
1730 (prec
== 0 or self
._int
[prec
-1] in '02468'):
1733 return self
._round
_half
_up
(prec
)
1735 def _round_ceiling(self
, prec
):
1736 """Rounds up (not away from 0 if negative.)"""
1738 return self
._round
_down
(prec
)
1740 return -self
._round
_down
(prec
)
1742 def _round_floor(self
, prec
):
1743 """Rounds down (not towards 0 if negative)"""
1745 return self
._round
_down
(prec
)
1747 return -self
._round
_down
(prec
)
1749 def _round_05up(self
, prec
):
1750 """Round down unless digit prec-1 is 0 or 5."""
1751 if prec
and self
._int
[prec
-1] not in '05':
1752 return self
._round
_down
(prec
)
1754 return -self
._round
_down
(prec
)
1756 def fma(self
, other
, third
, context
=None):
1757 """Fused multiply-add.
1759 Returns self*other+third with no rounding of the intermediate
1762 self and other are multiplied together, with no rounding of
1763 the result. The third operand is then added to the result,
1764 and a single final rounding is performed.
1767 other
= _convert_other(other
, raiseit
=True)
1769 # compute product; raise InvalidOperation if either operand is
1770 # a signaling NaN or if the product is zero times infinity.
1771 if self
._is
_special
or other
._is
_special
:
1773 context
= getcontext()
1774 if self
._exp
== 'N':
1775 return context
._raise
_error
(InvalidOperation
, 'sNaN', self
)
1776 if other
._exp
== 'N':
1777 return context
._raise
_error
(InvalidOperation
, 'sNaN', other
)
1778 if self
._exp
== 'n':
1780 elif other
._exp
== 'n':
1782 elif self
._exp
== 'F':
1784 return context
._raise
_error
(InvalidOperation
,
1786 product
= _SignedInfinity
[self
._sign ^ other
._sign
]
1787 elif other
._exp
== 'F':
1789 return context
._raise
_error
(InvalidOperation
,
1791 product
= _SignedInfinity
[self
._sign ^ other
._sign
]
1793 product
= _dec_from_triple(self
._sign ^ other
._sign
,
1794 str(int(self
._int
) * int(other
._int
)),
1795 self
._exp
+ other
._exp
)
1797 third
= _convert_other(third
, raiseit
=True)
1798 return product
.__add
__(third
, context
)
1800 def _power_modulo(self
, other
, modulo
, context
=None):
1801 """Three argument version of __pow__"""
1803 # if can't convert other and modulo to Decimal, raise
1804 # TypeError; there's no point returning NotImplemented (no
1805 # equivalent of __rpow__ for three argument pow)
1806 other
= _convert_other(other
, raiseit
=True)
1807 modulo
= _convert_other(modulo
, raiseit
=True)
1810 context
= getcontext()
1812 # deal with NaNs: if there are any sNaNs then first one wins,
1813 # (i.e. behaviour for NaNs is identical to that of fma)
1814 self_is_nan
= self
._isnan
()
1815 other_is_nan
= other
._isnan
()
1816 modulo_is_nan
= modulo
._isnan
()
1817 if self_is_nan
or other_is_nan
or modulo_is_nan
:
1818 if self_is_nan
== 2:
1819 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1821 if other_is_nan
== 2:
1822 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1824 if modulo_is_nan
== 2:
1825 return context
._raise
_error
(InvalidOperation
, 'sNaN',
1828 return self
._fix
_nan
(context
)
1830 return other
._fix
_nan
(context
)
1831 return modulo
._fix
_nan
(context
)
1833 # check inputs: we apply same restrictions as Python's pow()
1834 if not (self
._isinteger
() and
1835 other
._isinteger
() and
1836 modulo
._isinteger
()):
1837 return context
._raise
_error
(InvalidOperation
,
1838 'pow() 3rd argument not allowed '
1839 'unless all arguments are integers')
1841 return context
._raise
_error
(InvalidOperation
,
1842 'pow() 2nd argument cannot be '
1843 'negative when 3rd argument specified')
1845 return context
._raise
_error
(InvalidOperation
,
1846 'pow() 3rd argument cannot be 0')
1848 # additional restriction for decimal: the modulus must be less
1849 # than 10**prec in absolute value
1850 if modulo
.adjusted() >= context
.prec
:
1851 return context
._raise
_error
(InvalidOperation
,
1852 'insufficient precision: pow() 3rd '
1853 'argument must not have more than '
1856 # define 0**0 == NaN, for consistency with two-argument pow
1857 # (even though it hurts!)
1858 if not other
and not self
:
1859 return context
._raise
_error
(InvalidOperation
,
1860 'at least one of pow() 1st argument '
1861 'and 2nd argument must be nonzero ;'
1862 '0**0 is not defined')
1864 # compute sign of result
1870 # convert modulo to a Python integer, and self and other to
1871 # Decimal integers (i.e. force their exponents to be >= 0)
1872 modulo
= abs(int(modulo
))
1873 base
= _WorkRep(self
.to_integral_value())
1874 exponent
= _WorkRep(other
.to_integral_value())
1876 # compute result using integer pow()
1877 base
= (base
.int % modulo
* pow(10, base
.exp
, modulo
)) % modulo
1878 for i
in xrange(exponent
.exp
):
1879 base
= pow(base
, 10, modulo
)
1880 base
= pow(base
, exponent
.int, modulo
)
1882 return _dec_from_triple(sign
, str(base
), 0)
1884 def _power_exact(self
, other
, p
):
1885 """Attempt to compute self**other exactly.
1887 Given Decimals self and other and an integer p, attempt to
1888 compute an exact result for the power self**other, with p
1889 digits of precision. Return None if self**other is not
1890 exactly representable in p digits.
1892 Assumes that elimination of special cases has already been
1893 performed: self and other must both be nonspecial; self must
1894 be positive and not numerically equal to 1; other must be
1895 nonzero. For efficiency, other._exp should not be too large,
1896 so that 10**abs(other._exp) is a feasible calculation."""
1898 # In the comments below, we write x for the value of self and
1899 # y for the value of other. Write x = xc*10**xe and y =
1902 # The main purpose of this method is to identify the *failure*
1903 # of x**y to be exactly representable with as little effort as
1904 # possible. So we look for cheap and easy tests that
1905 # eliminate the possibility of x**y being exact. Only if all
1906 # these tests are passed do we go on to actually compute x**y.
1908 # Here's the main idea. First normalize both x and y. We
1909 # express y as a rational m/n, with m and n relatively prime
1910 # and n>0. Then for x**y to be exactly representable (at
1911 # *any* precision), xc must be the nth power of a positive
1912 # integer and xe must be divisible by n. If m is negative
1913 # then additionally xc must be a power of either 2 or 5, hence
1914 # a power of 2**n or 5**n.
1916 # There's a limit to how small |y| can be: if y=m/n as above
1919 # (1) if xc != 1 then for the result to be representable we
1920 # need xc**(1/n) >= 2, and hence also xc**|y| >= 2. So
1921 # if |y| <= 1/nbits(xc) then xc < 2**nbits(xc) <=
1922 # 2**(1/|y|), hence xc**|y| < 2 and the result is not
1925 # (2) if xe != 0, |xe|*(1/n) >= 1, so |xe|*|y| >= 1. Hence if
1926 # |y| < 1/|xe| then the result is not representable.
1928 # Note that since x is not equal to 1, at least one of (1) and
1929 # (2) must apply. Now |y| < 1/nbits(xc) iff |yc|*nbits(xc) <
1930 # 10**-ye iff len(str(|yc|*nbits(xc)) <= -ye.
1932 # There's also a limit to how large y can be, at least if it's
1933 # positive: the normalized result will have coefficient xc**y,
1934 # so if it's representable then xc**y < 10**p, and y <
1935 # p/log10(xc). Hence if y*log10(xc) >= p then the result is
1936 # not exactly representable.
1938 # if len(str(abs(yc*xe)) <= -ye then abs(yc*xe) < 10**-ye,
1939 # so |y| < 1/xe and the result is not representable.
1940 # Similarly, len(str(abs(yc)*xc_bits)) <= -ye implies |y|
1944 xc
, xe
= x
.int, x
.exp
1950 yc
, ye
= y
.int, y
.exp
1955 # case where xc == 1: result is 10**(xe*y), with xe*y
1956 # required to be an integer
1959 exponent
= xe
*yc
*10**ye
1961 exponent
, remainder
= divmod(xe
*yc
, 10**-ye
)
1965 exponent
= -exponent
1966 # if other is a nonnegative integer, use ideal exponent
1967 if other
._isinteger
() and other
._sign
== 0:
1968 ideal_exponent
= self
._exp
*int(other
)
1969 zeros
= min(exponent
-ideal_exponent
, p
-1)
1972 return _dec_from_triple(0, '1' + '0'*zeros
, exponent
-zeros
)
1974 # case where y is negative: xc must be either a power
1975 # of 2 or a power of 5.
1977 last_digit
= xc
% 10
1978 if last_digit
in (2,4,6,8):
1979 # quick test for power of 2
1982 # now xc is a power of 2; e is its exponent
1984 # find e*y and xe*y; both must be integers
1986 y_as_int
= yc
*10**ye
1991 e
, remainder
= divmod(e
*yc
, ten_pow
)
1994 xe
, remainder
= divmod(xe
*yc
, ten_pow
)
1998 if e
*65 >= p
*93: # 93/65 > log(10)/log(5)
2002 elif last_digit
== 5:
2003 # e >= log_5(xc) if xc is a power of 5; we have
2004 # equality all the way up to xc=5**2658
2005 e
= _nbits(xc
)*28//65
2006 xc
, remainder
= divmod(5**e
, xc
)
2013 y_as_integer
= yc
*10**ye
2015 xe
= xe
*y_as_integer
2018 e
, remainder
= divmod(e
*yc
, ten_pow
)
2021 xe
, remainder
= divmod(xe
*yc
, ten_pow
)
2024 if e
*3 >= p
*10: # 10/3 > log(10)/log(2)
2033 return _dec_from_triple(0, str(xc
), xe
)
2035 # now y is positive; find m and n such that y = m/n
2039 if xe
!= 0 and len(str(abs(yc
*xe
))) <= -ye
:
2041 xc_bits
= _nbits(xc
)
2042 if xc
!= 1 and len(str(abs(yc
)*xc_bits
)) <= -ye
:
2044 m
, n
= yc
, 10**(-ye
)
2045 while m
% 2 == n
% 2 == 0:
2048 while m
% 5 == n
% 5 == 0:
2052 # compute nth root of xc*10**xe
2054 # if 1 < xc < 2**n then xc isn't an nth power
2055 if xc
!= 1 and xc_bits
<= n
:
2058 xe
, rem
= divmod(xe
, n
)
2062 # compute nth root of xc using Newton's method
2063 a
= 1L << -(-_nbits(xc
)//n
) # initial estimate
2065 q
, r
= divmod(xc
, a
**(n
-1))
2069 a
= (a
*(n
-1) + q
)//n
2070 if not (a
== q
and r
== 0):
2074 # now xc*10**xe is the nth root of the original xc*10**xe
2075 # compute mth power of xc*10**xe
2077 # if m > p*100//_log10_lb(xc) then m > p/log10(xc), hence xc**m >
2078 # 10**p and the result is not representable.
2079 if xc
> 1 and m
> p
*100//_log10_lb(xc
):
2086 # by this point the result *is* exactly representable
2087 # adjust the exponent to get as close as possible to the ideal
2088 # exponent, if necessary
2090 if other
._isinteger
() and other
._sign
== 0:
2091 ideal_exponent
= self
._exp
*int(other
)
2092 zeros
= min(xe
-ideal_exponent
, p
-len(str_xc
))
2095 return _dec_from_triple(0, str_xc
+'0'*zeros
, xe
-zeros
)
2097 def __pow__(self
, other
, modulo
=None, context
=None):
2098 """Return self ** other [ % modulo].
2100 With two arguments, compute self**other.
2102 With three arguments, compute (self**other) % modulo. For the
2103 three argument form, the following restrictions on the
2106 - all three arguments must be integral
2107 - other must be nonnegative
2108 - either self or other (or both) must be nonzero
2109 - modulo must be nonzero and must have at most p digits,
2110 where p is the context precision.
2112 If any of these restrictions is violated the InvalidOperation
2115 The result of pow(self, other, modulo) is identical to the
2116 result that would be obtained by computing (self**other) %
2117 modulo with unbounded precision, but is computed more
2118 efficiently. It is always exact.
2121 if modulo
is not None:
2122 return self
._power
_modulo
(other
, modulo
, context
)
2124 other
= _convert_other(other
)
2125 if other
is NotImplemented:
2129 context
= getcontext()
2131 # either argument is a NaN => result is NaN
2132 ans
= self
._check
_nans
(other
, context
)
2136 # 0**0 = NaN (!), x**0 = 1 for nonzero x (including +/-Infinity)
2139 return context
._raise
_error
(InvalidOperation
, '0 ** 0')
2143 # result has sign 1 iff self._sign is 1 and other is an odd integer
2146 if other
._isinteger
():
2147 if not other
._iseven
():
2150 # -ve**noninteger = NaN
2151 # (-0)**noninteger = 0**noninteger
2153 return context
._raise
_error
(InvalidOperation
,
2154 'x ** y with x negative and y not an integer')
2155 # negate self, without doing any unwanted rounding
2156 self
= self
.copy_negate()
2158 # 0**(+ve or Inf)= 0; 0**(-ve or -Inf) = Infinity
2160 if other
._sign
== 0:
2161 return _dec_from_triple(result_sign
, '0', 0)
2163 return _SignedInfinity
[result_sign
]
2165 # Inf**(+ve or Inf) = Inf; Inf**(-ve or -Inf) = 0
2166 if self
._isinfinity
():
2167 if other
._sign
== 0:
2168 return _SignedInfinity
[result_sign
]
2170 return _dec_from_triple(result_sign
, '0', 0)
2172 # 1**other = 1, but the choice of exponent and the flags
2173 # depend on the exponent of self, and on whether other is a
2174 # positive integer, a negative integer, or neither
2176 if other
._isinteger
():
2177 # exp = max(self._exp*max(int(other), 0),
2178 # 1-context.prec) but evaluating int(other) directly
2179 # is dangerous until we know other is small (other
2180 # could be 1e999999999)
2181 if other
._sign
== 1:
2183 elif other
> context
.prec
:
2184 multiplier
= context
.prec
2186 multiplier
= int(other
)
2188 exp
= self
._exp
* multiplier
2189 if exp
< 1-context
.prec
:
2190 exp
= 1-context
.prec
2191 context
._raise
_error
(Rounded
)
2193 context
._raise
_error
(Inexact
)
2194 context
._raise
_error
(Rounded
)
2195 exp
= 1-context
.prec
2197 return _dec_from_triple(result_sign
, '1'+'0'*-exp
, exp
)
2199 # compute adjusted exponent of self
2200 self_adj
= self
.adjusted()
2202 # self ** infinity is infinity if self > 1, 0 if self < 1
2203 # self ** -infinity is infinity if self < 1, 0 if self > 1
2204 if other
._isinfinity
():
2205 if (other
._sign
== 0) == (self_adj
< 0):
2206 return _dec_from_triple(result_sign
, '0', 0)
2208 return _SignedInfinity
[result_sign
]
2210 # from here on, the result always goes through the call
2211 # to _fix at the end of this function.
2214 # crude test to catch cases of extreme overflow/underflow. If
2215 # log10(self)*other >= 10**bound and bound >= len(str(Emax))
2216 # then 10**bound >= 10**len(str(Emax)) >= Emax+1 and hence
2217 # self**other >= 10**(Emax+1), so overflow occurs. The test
2218 # for underflow is similar.
2219 bound
= self
._log
10_exp
_bound
() + other
.adjusted()
2220 if (self_adj
>= 0) == (other
._sign
== 0):
2221 # self > 1 and other +ve, or self < 1 and other -ve
2222 # possibility of overflow
2223 if bound
>= len(str(context
.Emax
)):
2224 ans
= _dec_from_triple(result_sign
, '1', context
.Emax
+1)
2226 # self > 1 and other -ve, or self < 1 and other +ve
2227 # possibility of underflow to 0
2228 Etiny
= context
.Etiny()
2229 if bound
>= len(str(-Etiny
)):
2230 ans
= _dec_from_triple(result_sign
, '1', Etiny
-1)
2232 # try for an exact result with precision +1
2234 ans
= self
._power
_exact
(other
, context
.prec
+ 1)
2235 if ans
is not None and result_sign
== 1:
2236 ans
= _dec_from_triple(1, ans
._int
, ans
._exp
)
2238 # usual case: inexact result, x**y computed directly as exp(y*log(x))
2242 xc
, xe
= x
.int, x
.exp
2244 yc
, ye
= y
.int, y
.exp
2248 # compute correctly rounded result: start with precision +3,
2249 # then increase precision until result is unambiguously roundable
2252 coeff
, exp
= _dpower(xc
, xe
, yc
, ye
, p
+extra
)
2253 if coeff
% (5*10**(len(str(coeff
))-p
-1)):
2257 ans
= _dec_from_triple(result_sign
, str(coeff
), exp
)
2259 # the specification says that for non-integer other we need to
2260 # raise Inexact, even when the result is actually exact. In
2261 # the same way, we need to raise Underflow here if the result
2262 # is subnormal. (The call to _fix will take care of raising
2263 # Rounded and Subnormal, as usual.)
2264 if not other
._isinteger
():
2265 context
._raise
_error
(Inexact
)
2266 # pad with zeros up to length context.prec+1 if necessary
2267 if len(ans
._int
) <= context
.prec
:
2268 expdiff
= context
.prec
+1 - len(ans
._int
)
2269 ans
= _dec_from_triple(ans
._sign
, ans
._int
+'0'*expdiff
,
2271 if ans
.adjusted() < context
.Emin
:
2272 context
._raise
_error
(Underflow
)
2274 # unlike exp, ln and log10, the power function respects the
2275 # rounding mode; no need to use ROUND_HALF_EVEN here
2276 ans
= ans
._fix
(context
)
2279 def __rpow__(self
, other
, context
=None):
2280 """Swaps self/other and returns __pow__."""
2281 other
= _convert_other(other
)
2282 if other
is NotImplemented:
2284 return other
.__pow
__(self
, context
=context
)
2286 def normalize(self
, context
=None):
2287 """Normalize- strip trailing 0s, change anything equal to 0 to 0e0"""
2290 context
= getcontext()
2292 if self
._is
_special
:
2293 ans
= self
._check
_nans
(context
=context
)
2297 dup
= self
._fix
(context
)
2298 if dup
._isinfinity
():
2302 return _dec_from_triple(dup
._sign
, '0', 0)
2303 exp_max
= [context
.Emax
, context
.Etop()][context
._clamp
]
2306 while dup
._int
[end
-1] == '0' and exp
< exp_max
:
2309 return _dec_from_triple(dup
._sign
, dup
._int
[:end
], exp
)
2311 def quantize(self
, exp
, rounding
=None, context
=None, watchexp
=True):
2312 """Quantize self so its exponent is the same as that of exp.
2314 Similar to self._rescale(exp._exp) but with error checking.
2316 exp
= _convert_other(exp
, raiseit
=True)
2319 context
= getcontext()
2320 if rounding
is None:
2321 rounding
= context
.rounding
2323 if self
._is
_special
or exp
._is
_special
:
2324 ans
= self
._check
_nans
(exp
, context
)
2328 if exp
._isinfinity
() or self
._isinfinity
():
2329 if exp
._isinfinity
() and self
._isinfinity
():
2330 return Decimal(self
) # if both are inf, it is OK
2331 return context
._raise
_error
(InvalidOperation
,
2332 'quantize with one INF')
2334 # if we're not watching exponents, do a simple rescale
2336 ans
= self
._rescale
(exp
._exp
, rounding
)
2337 # raise Inexact and Rounded where appropriate
2338 if ans
._exp
> self
._exp
:
2339 context
._raise
_error
(Rounded
)
2341 context
._raise
_error
(Inexact
)
2344 # exp._exp should be between Etiny and Emax
2345 if not (context
.Etiny() <= exp
._exp
<= context
.Emax
):
2346 return context
._raise
_error
(InvalidOperation
,
2347 'target exponent out of bounds in quantize')
2350 ans
= _dec_from_triple(self
._sign
, '0', exp
._exp
)
2351 return ans
._fix
(context
)
2353 self_adjusted
= self
.adjusted()
2354 if self_adjusted
> context
.Emax
:
2355 return context
._raise
_error
(InvalidOperation
,
2356 'exponent of quantize result too large for current context')
2357 if self_adjusted
- exp
._exp
+ 1 > context
.prec
:
2358 return context
._raise
_error
(InvalidOperation
,
2359 'quantize result has too many digits for current context')
2361 ans
= self
._rescale
(exp
._exp
, rounding
)
2362 if ans
.adjusted() > context
.Emax
:
2363 return context
._raise
_error
(InvalidOperation
,
2364 'exponent of quantize result too large for current context')
2365 if len(ans
._int
) > context
.prec
:
2366 return context
._raise
_error
(InvalidOperation
,
2367 'quantize result has too many digits for current context')
2369 # raise appropriate flags
2370 if ans
._exp
> self
._exp
:
2371 context
._raise
_error
(Rounded
)
2373 context
._raise
_error
(Inexact
)
2374 if ans
and ans
.adjusted() < context
.Emin
:
2375 context
._raise
_error
(Subnormal
)
2377 # call to fix takes care of any necessary folddown
2378 ans
= ans
._fix
(context
)
2381 def same_quantum(self
, other
):
2382 """Return True if self and other have the same exponent; otherwise
2385 If either operand is a special value, the following rules are used:
2386 * return True if both operands are infinities
2387 * return True if both operands are NaNs
2388 * otherwise, return False.
2390 other
= _convert_other(other
, raiseit
=True)
2391 if self
._is
_special
or other
._is
_special
:
2392 return (self
.is_nan() and other
.is_nan() or
2393 self
.is_infinite() and other
.is_infinite())
2394 return self
._exp
== other
._exp
2396 def _rescale(self
, exp
, rounding
):
2397 """Rescale self so that the exponent is exp, either by padding with zeros
2398 or by truncating digits, using the given rounding mode.
2400 Specials are returned without change. This operation is
2401 quiet: it raises no flags, and uses no information from the
2404 exp = exp to scale to (an integer)
2405 rounding = rounding mode
2407 if self
._is
_special
:
2408 return Decimal(self
)
2410 return _dec_from_triple(self
._sign
, '0', exp
)
2412 if self
._exp
>= exp
:
2413 # pad answer with zeros if necessary
2414 return _dec_from_triple(self
._sign
,
2415 self
._int
+ '0'*(self
._exp
- exp
), exp
)
2417 # too many digits; round and lose data. If self.adjusted() <
2418 # exp-1, replace self by 10**(exp-1) before rounding
2419 digits
= len(self
._int
) + self
._exp
- exp
2421 self
= _dec_from_triple(self
._sign
, '1', exp
-1)
2423 this_function
= getattr(self
, self
._pick
_rounding
_function
[rounding
])
2424 changed
= this_function(digits
)
2425 coeff
= self
._int
[:digits
] or '0'
2427 coeff
= str(int(coeff
)+1)
2428 return _dec_from_triple(self
._sign
, coeff
, exp
)
2430 def _round(self
, places
, rounding
):
2431 """Round a nonzero, nonspecial Decimal to a fixed number of
2432 significant figures, using the given rounding mode.
2434 Infinities, NaNs and zeros are returned unaltered.
2436 This operation is quiet: it raises no flags, and uses no
2437 information from the context.
2441 raise ValueError("argument should be at least 1 in _round")
2442 if self
._is
_special
or not self
:
2443 return Decimal(self
)
2444 ans
= self
._rescale
(self
.adjusted()+1-places
, rounding
)
2445 # it can happen that the rescale alters the adjusted exponent;
2446 # for example when rounding 99.97 to 3 significant figures.
2447 # When this happens we end up with an extra 0 at the end of
2448 # the number; a second rescale fixes this.
2449 if ans
.adjusted() != self
.adjusted():
2450 ans
= ans
._rescale
(ans
.adjusted()+1-places
, rounding
)
2453 def to_integral_exact(self
, rounding
=None, context
=None):
2454 """Rounds to a nearby integer.
2456 If no rounding mode is specified, take the rounding mode from
2457 the context. This method raises the Rounded and Inexact flags
2460 See also: to_integral_value, which does exactly the same as
2461 this method except that it doesn't raise Inexact or Rounded.
2463 if self
._is
_special
:
2464 ans
= self
._check
_nans
(context
=context
)
2467 return Decimal(self
)
2469 return Decimal(self
)
2471 return _dec_from_triple(self
._sign
, '0', 0)
2473 context
= getcontext()
2474 if rounding
is None:
2475 rounding
= context
.rounding
2476 context
._raise
_error
(Rounded
)
2477 ans
= self
._rescale
(0, rounding
)
2479 context
._raise
_error
(Inexact
)
2482 def to_integral_value(self
, rounding
=None, context
=None):
2483 """Rounds to the nearest integer, without raising inexact, rounded."""
2485 context
= getcontext()
2486 if rounding
is None:
2487 rounding
= context
.rounding
2488 if self
._is
_special
:
2489 ans
= self
._check
_nans
(context
=context
)
2492 return Decimal(self
)
2494 return Decimal(self
)
2496 return self
._rescale
(0, rounding
)
2498 # the method name changed, but we provide also the old one, for compatibility
2499 to_integral
= to_integral_value
2501 def sqrt(self
, context
=None):
2502 """Return the square root of self."""
2504 context
= getcontext()
2506 if self
._is
_special
:
2507 ans
= self
._check
_nans
(context
=context
)
2511 if self
._isinfinity
() and self
._sign
== 0:
2512 return Decimal(self
)
2515 # exponent = self._exp // 2. sqrt(-0) = -0
2516 ans
= _dec_from_triple(self
._sign
, '0', self
._exp
// 2)
2517 return ans
._fix
(context
)
2520 return context
._raise
_error
(InvalidOperation
, 'sqrt(-x), x > 0')
2522 # At this point self represents a positive number. Let p be
2523 # the desired precision and express self in the form c*100**e
2524 # with c a positive real number and e an integer, c and e
2525 # being chosen so that 100**(p-1) <= c < 100**p. Then the
2526 # (exact) square root of self is sqrt(c)*10**e, and 10**(p-1)
2527 # <= sqrt(c) < 10**p, so the closest representable Decimal at
2528 # precision p is n*10**e where n = round_half_even(sqrt(c)),
2529 # the closest integer to sqrt(c) with the even integer chosen
2530 # in the case of a tie.
2532 # To ensure correct rounding in all cases, we use the
2533 # following trick: we compute the square root to an extra
2534 # place (precision p+1 instead of precision p), rounding down.
2535 # Then, if the result is inexact and its last digit is 0 or 5,
2536 # we increase the last digit to 1 or 6 respectively; if it's
2537 # exact we leave the last digit alone. Now the final round to
2538 # p places (or fewer in the case of underflow) will round
2539 # correctly and raise the appropriate flags.
2541 # use an extra digit of precision
2542 prec
= context
.prec
+1
2544 # write argument in the form c*100**e where e = self._exp//2
2545 # is the 'ideal' exponent, to be used if the square root is
2546 # exactly representable. l is the number of 'digits' of c in
2547 # base 100, so that 100**(l-1) <= c < 100**l.
2552 l
= (len(self
._int
) >> 1) + 1
2555 l
= len(self
._int
)+1 >> 1
2557 # rescale so that c has exactly prec base 100 'digits'
2563 c
, remainder
= divmod(c
, 100**-shift
)
2564 exact
= not remainder
2567 # find n = floor(sqrt(c)) using Newton's method
2575 exact
= exact
and n
*n
== c
2578 # result is exact; rescale to use ideal exponent e
2580 # assert n % 10**shift == 0
2586 # result is not exact; fix last digit as described above
2590 ans
= _dec_from_triple(0, str(n
), e
)
2592 # round, and fit to current context
2593 context
= context
._shallow
_copy
()
2594 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
2595 ans
= ans
._fix
(context
)
2596 context
.rounding
= rounding
2600 def max(self
, other
, context
=None):
2601 """Returns the larger value.
2603 Like max(self, other) except if one is not a number, returns
2604 NaN (and signals if one is sNaN). Also rounds.
2606 other
= _convert_other(other
, raiseit
=True)
2609 context
= getcontext()
2611 if self
._is
_special
or other
._is
_special
:
2612 # If one operand is a quiet NaN and the other is number, then the
2613 # number is always returned
2617 if on
== 1 and sn
== 0:
2618 return self
._fix
(context
)
2619 if sn
== 1 and on
== 0:
2620 return other
._fix
(context
)
2621 return self
._check
_nans
(other
, context
)
2623 c
= self
._cmp
(other
)
2625 # If both operands are finite and equal in numerical value
2626 # then an ordering is applied:
2628 # If the signs differ then max returns the operand with the
2629 # positive sign and min returns the operand with the negative sign
2631 # If the signs are the same then the exponent is used to select
2632 # the result. This is exactly the ordering used in compare_total.
2633 c
= self
.compare_total(other
)
2640 return ans
._fix
(context
)
2642 def min(self
, other
, context
=None):
2643 """Returns the smaller value.
2645 Like min(self, other) except if one is not a number, returns
2646 NaN (and signals if one is sNaN). Also rounds.
2648 other
= _convert_other(other
, raiseit
=True)
2651 context
= getcontext()
2653 if self
._is
_special
or other
._is
_special
:
2654 # If one operand is a quiet NaN and the other is number, then the
2655 # number is always returned
2659 if on
== 1 and sn
== 0:
2660 return self
._fix
(context
)
2661 if sn
== 1 and on
== 0:
2662 return other
._fix
(context
)
2663 return self
._check
_nans
(other
, context
)
2665 c
= self
._cmp
(other
)
2667 c
= self
.compare_total(other
)
2674 return ans
._fix
(context
)
2676 def _isinteger(self
):
2677 """Returns whether self is an integer"""
2678 if self
._is
_special
:
2682 rest
= self
._int
[self
._exp
:]
2683 return rest
== '0'*len(rest
)
2686 """Returns True if self is even. Assumes self is an integer."""
2687 if not self
or self
._exp
> 0:
2689 return self
._int
[-1+self
._exp
] in '02468'
2692 """Return the adjusted exponent of self"""
2694 return self
._exp
+ len(self
._int
) - 1
2695 # If NaN or Infinity, self._exp is string
2699 def canonical(self
, context
=None):
2700 """Returns the same Decimal object.
2702 As we do not have different encodings for the same number, the
2703 received object already is in its canonical form.
2707 def compare_signal(self
, other
, context
=None):
2708 """Compares self to the other operand numerically.
2710 It's pretty much like compare(), but all NaNs signal, with signaling
2711 NaNs taking precedence over quiet NaNs.
2713 other
= _convert_other(other
, raiseit
= True)
2714 ans
= self
._compare
_check
_nans
(other
, context
)
2717 return self
.compare(other
, context
=context
)
2719 def compare_total(self
, other
):
2720 """Compares self to other using the abstract representations.
2722 This is not like the standard compare, which use their numerical
2723 value. Note that a total ordering is defined for all possible abstract
2726 # if one is negative and the other is positive, it's easy
2727 if self
._sign
and not other
._sign
:
2729 if not self
._sign
and other
._sign
:
2733 # let's handle both NaN types
2734 self_nan
= self
._isnan
()
2735 other_nan
= other
._isnan
()
2736 if self_nan
or other_nan
:
2737 if self_nan
== other_nan
:
2738 # compare payloads as though they're integers
2739 self_key
= len(self
._int
), self
._int
2740 other_key
= len(other
._int
), other
._int
2741 if self_key
< other_key
:
2746 if self_key
> other_key
:
2777 if self
._exp
< other
._exp
:
2782 if self
._exp
> other
._exp
:
2790 def compare_total_mag(self
, other
):
2791 """Compares self to other using abstract repr., ignoring sign.
2793 Like compare_total, but with operand's sign ignored and assumed to be 0.
2796 o
= other
.copy_abs()
2797 return s
.compare_total(o
)
2800 """Returns a copy with the sign set to 0. """
2801 return _dec_from_triple(0, self
._int
, self
._exp
, self
._is
_special
)
2803 def copy_negate(self
):
2804 """Returns a copy with the sign inverted."""
2806 return _dec_from_triple(0, self
._int
, self
._exp
, self
._is
_special
)
2808 return _dec_from_triple(1, self
._int
, self
._exp
, self
._is
_special
)
2810 def copy_sign(self
, other
):
2811 """Returns self with the sign of other."""
2812 return _dec_from_triple(other
._sign
, self
._int
,
2813 self
._exp
, self
._is
_special
)
2815 def exp(self
, context
=None):
2816 """Returns e ** self."""
2819 context
= getcontext()
2822 ans
= self
._check
_nans
(context
=context
)
2826 # exp(-Infinity) = 0
2827 if self
._isinfinity
() == -1:
2834 # exp(Infinity) = Infinity
2835 if self
._isinfinity
() == 1:
2836 return Decimal(self
)
2838 # the result is now guaranteed to be inexact (the true
2839 # mathematical result is transcendental). There's no need to
2840 # raise Rounded and Inexact here---they'll always be raised as
2841 # a result of the call to _fix.
2843 adj
= self
.adjusted()
2845 # we only need to do any computation for quite a small range
2846 # of adjusted exponents---for example, -29 <= adj <= 10 for
2847 # the default context. For smaller exponent the result is
2848 # indistinguishable from 1 at the given precision, while for
2849 # larger exponent the result either overflows or underflows.
2850 if self
._sign
== 0 and adj
> len(str((context
.Emax
+1)*3)):
2852 ans
= _dec_from_triple(0, '1', context
.Emax
+1)
2853 elif self
._sign
== 1 and adj
> len(str((-context
.Etiny()+1)*3)):
2855 ans
= _dec_from_triple(0, '1', context
.Etiny()-1)
2856 elif self
._sign
== 0 and adj
< -p
:
2857 # p+1 digits; final round will raise correct flags
2858 ans
= _dec_from_triple(0, '1' + '0'*(p
-1) + '1', -p
)
2859 elif self
._sign
== 1 and adj
< -p
-1:
2860 # p+1 digits; final round will raise correct flags
2861 ans
= _dec_from_triple(0, '9'*(p
+1), -p
-1)
2865 c
, e
= op
.int, op
.exp
2869 # compute correctly rounded result: increase precision by
2870 # 3 digits at a time until we get an unambiguously
2874 coeff
, exp
= _dexp(c
, e
, p
+extra
)
2875 if coeff
% (5*10**(len(str(coeff
))-p
-1)):
2879 ans
= _dec_from_triple(0, str(coeff
), exp
)
2881 # at this stage, ans should round correctly with *any*
2882 # rounding mode, not just with ROUND_HALF_EVEN
2883 context
= context
._shallow
_copy
()
2884 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
2885 ans
= ans
._fix
(context
)
2886 context
.rounding
= rounding
2890 def is_canonical(self
):
2891 """Return True if self is canonical; otherwise return False.
2893 Currently, the encoding of a Decimal instance is always
2894 canonical, so this method returns True for any Decimal.
2898 def is_finite(self
):
2899 """Return True if self is finite; otherwise return False.
2901 A Decimal instance is considered finite if it is neither
2904 return not self
._is
_special
2906 def is_infinite(self
):
2907 """Return True if self is infinite; otherwise return False."""
2908 return self
._exp
== 'F'
2911 """Return True if self is a qNaN or sNaN; otherwise return False."""
2912 return self
._exp
in ('n', 'N')
2914 def is_normal(self
, context
=None):
2915 """Return True if self is a normal number; otherwise return False."""
2916 if self
._is
_special
or not self
:
2919 context
= getcontext()
2920 return context
.Emin
<= self
.adjusted()
2923 """Return True if self is a quiet NaN; otherwise return False."""
2924 return self
._exp
== 'n'
2926 def is_signed(self
):
2927 """Return True if self is negative; otherwise return False."""
2928 return self
._sign
== 1
2931 """Return True if self is a signaling NaN; otherwise return False."""
2932 return self
._exp
== 'N'
2934 def is_subnormal(self
, context
=None):
2935 """Return True if self is subnormal; otherwise return False."""
2936 if self
._is
_special
or not self
:
2939 context
= getcontext()
2940 return self
.adjusted() < context
.Emin
2943 """Return True if self is a zero; otherwise return False."""
2944 return not self
._is
_special
and self
._int
== '0'
2946 def _ln_exp_bound(self
):
2947 """Compute a lower bound for the adjusted exponent of self.ln().
2948 In other words, compute r such that self.ln() >= 10**r. Assumes
2949 that self is finite and positive and that self != 1.
2952 # for 0.1 <= x <= 10 we use the inequalities 1-1/x <= ln(x) <= x-1
2953 adj
= self
._exp
+ len(self
._int
) - 1
2955 # argument >= 10; we use 23/10 = 2.3 as a lower bound for ln(10)
2956 return len(str(adj
*23//10)) - 1
2959 return len(str((-1-adj
)*23//10)) - 1
2961 c
, e
= op
.int, op
.exp
2966 return len(num
) - len(den
) - (num
< den
)
2967 # adj == -1, 0.1 <= self < 1
2968 return e
+ len(str(10**-e
- c
)) - 1
2971 def ln(self
, context
=None):
2972 """Returns the natural (base e) logarithm of self."""
2975 context
= getcontext()
2978 ans
= self
._check
_nans
(context
=context
)
2982 # ln(0.0) == -Infinity
2984 return _NegativeInfinity
2986 # ln(Infinity) = Infinity
2987 if self
._isinfinity
() == 1:
2994 # ln(negative) raises InvalidOperation
2996 return context
._raise
_error
(InvalidOperation
,
2997 'ln of a negative value')
2999 # result is irrational, so necessarily inexact
3001 c
, e
= op
.int, op
.exp
3004 # correctly rounded result: repeatedly increase precision by 3
3005 # until we get an unambiguously roundable result
3006 places
= p
- self
._ln
_exp
_bound
() + 2 # at least p+3 places
3008 coeff
= _dlog(c
, e
, places
)
3009 # assert len(str(abs(coeff)))-p >= 1
3010 if coeff
% (5*10**(len(str(abs(coeff
)))-p
-1)):
3013 ans
= _dec_from_triple(int(coeff
<0), str(abs(coeff
)), -places
)
3015 context
= context
._shallow
_copy
()
3016 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
3017 ans
= ans
._fix
(context
)
3018 context
.rounding
= rounding
3021 def _log10_exp_bound(self
):
3022 """Compute a lower bound for the adjusted exponent of self.log10().
3023 In other words, find r such that self.log10() >= 10**r.
3024 Assumes that self is finite and positive and that self != 1.
3027 # For x >= 10 or x < 0.1 we only need a bound on the integer
3028 # part of log10(self), and this comes directly from the
3029 # exponent of x. For 0.1 <= x <= 10 we use the inequalities
3030 # 1-1/x <= log(x) <= x-1. If x > 1 we have |log10(x)| >
3031 # (1-1/x)/2.31 > 0. If x < 1 then |log10(x)| > (1-x)/2.31 > 0
3033 adj
= self
._exp
+ len(self
._int
) - 1
3036 return len(str(adj
))-1
3039 return len(str(-1-adj
))-1
3041 c
, e
= op
.int, op
.exp
3046 return len(num
) - len(den
) - (num
< den
) + 2
3047 # adj == -1, 0.1 <= self < 1
3049 return len(num
) + e
- (num
< "231") - 1
3051 def log10(self
, context
=None):
3052 """Returns the base 10 logarithm of self."""
3055 context
= getcontext()
3058 ans
= self
._check
_nans
(context
=context
)
3062 # log10(0.0) == -Infinity
3064 return _NegativeInfinity
3066 # log10(Infinity) = Infinity
3067 if self
._isinfinity
() == 1:
3070 # log10(negative or -Infinity) raises InvalidOperation
3072 return context
._raise
_error
(InvalidOperation
,
3073 'log10 of a negative value')
3076 if self
._int
[0] == '1' and self
._int
[1:] == '0'*(len(self
._int
) - 1):
3077 # answer may need rounding
3078 ans
= Decimal(self
._exp
+ len(self
._int
) - 1)
3080 # result is irrational, so necessarily inexact
3082 c
, e
= op
.int, op
.exp
3085 # correctly rounded result: repeatedly increase precision
3086 # until result is unambiguously roundable
3087 places
= p
-self
._log
10_exp
_bound
()+2
3089 coeff
= _dlog10(c
, e
, places
)
3090 # assert len(str(abs(coeff)))-p >= 1
3091 if coeff
% (5*10**(len(str(abs(coeff
)))-p
-1)):
3094 ans
= _dec_from_triple(int(coeff
<0), str(abs(coeff
)), -places
)
3096 context
= context
._shallow
_copy
()
3097 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
3098 ans
= ans
._fix
(context
)
3099 context
.rounding
= rounding
3102 def logb(self
, context
=None):
3103 """ Returns the exponent of the magnitude of self's MSD.
3105 The result is the integer which is the exponent of the magnitude
3106 of the most significant digit of self (as though it were truncated
3107 to a single digit while maintaining the value of that digit and
3108 without limiting the resulting exponent).
3111 ans
= self
._check
_nans
(context
=context
)
3116 context
= getcontext()
3118 # logb(+/-Inf) = +Inf
3119 if self
._isinfinity
():
3122 # logb(0) = -Inf, DivisionByZero
3124 return context
._raise
_error
(DivisionByZero
, 'logb(0)', 1)
3126 # otherwise, simply return the adjusted exponent of self, as a
3127 # Decimal. Note that no attempt is made to fit the result
3128 # into the current context.
3129 ans
= Decimal(self
.adjusted())
3130 return ans
._fix
(context
)
3132 def _islogical(self
):
3133 """Return True if self is a logical operand.
3135 For being logical, it must be a finite number with a sign of 0,
3136 an exponent of 0, and a coefficient whose digits must all be
3139 if self
._sign
!= 0 or self
._exp
!= 0:
3141 for dig
in self
._int
:
3146 def _fill_logical(self
, context
, opa
, opb
):
3147 dif
= context
.prec
- len(opa
)
3151 opa
= opa
[-context
.prec
:]
3152 dif
= context
.prec
- len(opb
)
3156 opb
= opb
[-context
.prec
:]
3159 def logical_and(self
, other
, context
=None):
3160 """Applies an 'and' operation between self and other's digits."""
3162 context
= getcontext()
3163 if not self
._islogical
() or not other
._islogical
():
3164 return context
._raise
_error
(InvalidOperation
)
3166 # fill to context.prec
3167 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3169 # make the operation, and clean starting zeroes
3170 result
= "".join([str(int(a
)&int(b
)) for a
,b
in zip(opa
,opb
)])
3171 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3173 def logical_invert(self
, context
=None):
3174 """Invert all its digits."""
3176 context
= getcontext()
3177 return self
.logical_xor(_dec_from_triple(0,'1'*context
.prec
,0),
3180 def logical_or(self
, other
, context
=None):
3181 """Applies an 'or' operation between self and other's digits."""
3183 context
= getcontext()
3184 if not self
._islogical
() or not other
._islogical
():
3185 return context
._raise
_error
(InvalidOperation
)
3187 # fill to context.prec
3188 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3190 # make the operation, and clean starting zeroes
3191 result
= "".join([str(int(a
)|
int(b
)) for a
,b
in zip(opa
,opb
)])
3192 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3194 def logical_xor(self
, other
, context
=None):
3195 """Applies an 'xor' operation between self and other's digits."""
3197 context
= getcontext()
3198 if not self
._islogical
() or not other
._islogical
():
3199 return context
._raise
_error
(InvalidOperation
)
3201 # fill to context.prec
3202 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3204 # make the operation, and clean starting zeroes
3205 result
= "".join([str(int(a
)^
int(b
)) for a
,b
in zip(opa
,opb
)])
3206 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3208 def max_mag(self
, other
, context
=None):
3209 """Compares the values numerically with their sign ignored."""
3210 other
= _convert_other(other
, raiseit
=True)
3213 context
= getcontext()
3215 if self
._is
_special
or other
._is
_special
:
3216 # If one operand is a quiet NaN and the other is number, then the
3217 # number is always returned
3221 if on
== 1 and sn
== 0:
3222 return self
._fix
(context
)
3223 if sn
== 1 and on
== 0:
3224 return other
._fix
(context
)
3225 return self
._check
_nans
(other
, context
)
3227 c
= self
.copy_abs()._cmp
(other
.copy_abs())
3229 c
= self
.compare_total(other
)
3236 return ans
._fix
(context
)
3238 def min_mag(self
, other
, context
=None):
3239 """Compares the values numerically with their sign ignored."""
3240 other
= _convert_other(other
, raiseit
=True)
3243 context
= getcontext()
3245 if self
._is
_special
or other
._is
_special
:
3246 # If one operand is a quiet NaN and the other is number, then the
3247 # number is always returned
3251 if on
== 1 and sn
== 0:
3252 return self
._fix
(context
)
3253 if sn
== 1 and on
== 0:
3254 return other
._fix
(context
)
3255 return self
._check
_nans
(other
, context
)
3257 c
= self
.copy_abs()._cmp
(other
.copy_abs())
3259 c
= self
.compare_total(other
)
3266 return ans
._fix
(context
)
3268 def next_minus(self
, context
=None):
3269 """Returns the largest representable number smaller than itself."""
3271 context
= getcontext()
3273 ans
= self
._check
_nans
(context
=context
)
3277 if self
._isinfinity
() == -1:
3278 return _NegativeInfinity
3279 if self
._isinfinity
() == 1:
3280 return _dec_from_triple(0, '9'*context
.prec
, context
.Etop())
3282 context
= context
.copy()
3283 context
._set
_rounding
(ROUND_FLOOR
)
3284 context
._ignore
_all
_flags
()
3285 new_self
= self
._fix
(context
)
3286 if new_self
!= self
:
3288 return self
.__sub
__(_dec_from_triple(0, '1', context
.Etiny()-1),
3291 def next_plus(self
, context
=None):
3292 """Returns the smallest representable number larger than itself."""
3294 context
= getcontext()
3296 ans
= self
._check
_nans
(context
=context
)
3300 if self
._isinfinity
() == 1:
3302 if self
._isinfinity
() == -1:
3303 return _dec_from_triple(1, '9'*context
.prec
, context
.Etop())
3305 context
= context
.copy()
3306 context
._set
_rounding
(ROUND_CEILING
)
3307 context
._ignore
_all
_flags
()
3308 new_self
= self
._fix
(context
)
3309 if new_self
!= self
:
3311 return self
.__add
__(_dec_from_triple(0, '1', context
.Etiny()-1),
3314 def next_toward(self
, other
, context
=None):
3315 """Returns the number closest to self, in the direction towards other.
3317 The result is the closest representable number to self
3318 (excluding self) that is in the direction towards other,
3319 unless both have the same value. If the two operands are
3320 numerically equal, then the result is a copy of self with the
3321 sign set to be the same as the sign of other.
3323 other
= _convert_other(other
, raiseit
=True)
3326 context
= getcontext()
3328 ans
= self
._check
_nans
(other
, context
)
3332 comparison
= self
._cmp
(other
)
3334 return self
.copy_sign(other
)
3336 if comparison
== -1:
3337 ans
= self
.next_plus(context
)
3338 else: # comparison == 1
3339 ans
= self
.next_minus(context
)
3341 # decide which flags to raise using value of ans
3342 if ans
._isinfinity
():
3343 context
._raise
_error
(Overflow
,
3344 'Infinite result from next_toward',
3346 context
._raise
_error
(Rounded
)
3347 context
._raise
_error
(Inexact
)
3348 elif ans
.adjusted() < context
.Emin
:
3349 context
._raise
_error
(Underflow
)
3350 context
._raise
_error
(Subnormal
)
3351 context
._raise
_error
(Rounded
)
3352 context
._raise
_error
(Inexact
)
3353 # if precision == 1 then we don't raise Clamped for a
3356 context
._raise
_error
(Clamped
)
3360 def number_class(self
, context
=None):
3361 """Returns an indication of the class of self.
3363 The class is one of the following strings:
3379 inf
= self
._isinfinity
()
3390 context
= getcontext()
3391 if self
.is_subnormal(context
=context
):
3396 # just a normal, regular, boring number, :)
3403 """Just returns 10, as this is Decimal, :)"""
3406 def rotate(self
, other
, context
=None):
3407 """Returns a rotated copy of self, value-of-other times."""
3409 context
= getcontext()
3411 ans
= self
._check
_nans
(other
, context
)
3416 return context
._raise
_error
(InvalidOperation
)
3417 if not (-context
.prec
<= int(other
) <= context
.prec
):
3418 return context
._raise
_error
(InvalidOperation
)
3420 if self
._isinfinity
():
3421 return Decimal(self
)
3423 # get values, pad if necessary
3426 topad
= context
.prec
- len(rotdig
)
3428 rotdig
= '0'*topad
+ rotdig
3431 rotated
= rotdig
[torot
:] + rotdig
[:torot
]
3432 return _dec_from_triple(self
._sign
,
3433 rotated
.lstrip('0') or '0', self
._exp
)
3435 def scaleb (self
, other
, context
=None):
3436 """Returns self operand after adding the second value to its exp."""
3438 context
= getcontext()
3440 ans
= self
._check
_nans
(other
, context
)
3445 return context
._raise
_error
(InvalidOperation
)
3446 liminf
= -2 * (context
.Emax
+ context
.prec
)
3447 limsup
= 2 * (context
.Emax
+ context
.prec
)
3448 if not (liminf
<= int(other
) <= limsup
):
3449 return context
._raise
_error
(InvalidOperation
)
3451 if self
._isinfinity
():
3452 return Decimal(self
)
3454 d
= _dec_from_triple(self
._sign
, self
._int
, self
._exp
+ int(other
))
3458 def shift(self
, other
, context
=None):
3459 """Returns a shifted copy of self, value-of-other times."""
3461 context
= getcontext()
3463 ans
= self
._check
_nans
(other
, context
)
3468 return context
._raise
_error
(InvalidOperation
)
3469 if not (-context
.prec
<= int(other
) <= context
.prec
):
3470 return context
._raise
_error
(InvalidOperation
)
3472 if self
._isinfinity
():
3473 return Decimal(self
)
3475 # get values, pad if necessary
3478 return Decimal(self
)
3480 topad
= context
.prec
- len(rotdig
)
3482 rotdig
= '0'*topad
+ rotdig
3486 rotated
= rotdig
[:torot
]
3488 rotated
= rotdig
+ '0'*torot
3489 rotated
= rotated
[-context
.prec
:]
3491 return _dec_from_triple(self
._sign
,
3492 rotated
.lstrip('0') or '0', self
._exp
)
3494 # Support for pickling, copy, and deepcopy
3495 def __reduce__(self
):
3496 return (self
.__class
__, (str(self
),))
3499 if type(self
) == Decimal
:
3500 return self
# I'm immutable; therefore I am my own clone
3501 return self
.__class
__(str(self
))
3503 def __deepcopy__(self
, memo
):
3504 if type(self
) == Decimal
:
3505 return self
# My components are also immutable
3506 return self
.__class
__(str(self
))
3508 # PEP 3101 support. the _localeconv keyword argument should be
3509 # considered private: it's provided for ease of testing only.
3510 def __format__(self
, specifier
, context
=None, _localeconv
=None):
3511 """Format a Decimal instance according to the given specifier.
3513 The specifier should be a standard format specifier, with the
3514 form described in PEP 3101. Formatting types 'e', 'E', 'f',
3515 'F', 'g', 'G', 'n' and '%' are supported. If the formatting
3516 type is omitted it defaults to 'g' or 'G', depending on the
3517 value of context.capitals.
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
, _localeconv
=_localeconv
)
3530 # special values don't care about the type or precision
3531 if self
._is
_special
:
3532 sign
= _format_sign(self
._sign
, spec
)
3533 body
= str(self
.copy_abs())
3534 return _format_align(sign
, body
, spec
)
3536 # a type of None defaults to 'g' or 'G', depending on context
3537 if spec
['type'] is None:
3538 spec
['type'] = ['g', 'G'][context
.capitals
]
3540 # if type is '%', adjust exponent of self accordingly
3541 if spec
['type'] == '%':
3542 self
= _dec_from_triple(self
._sign
, self
._int
, self
._exp
+2)
3544 # round if necessary, taking rounding mode from the context
3545 rounding
= context
.rounding
3546 precision
= spec
['precision']
3547 if precision
is not None:
3548 if spec
['type'] in 'eE':
3549 self
= self
._round
(precision
+1, rounding
)
3550 elif spec
['type'] in 'fF%':
3551 self
= self
._rescale
(-precision
, rounding
)
3552 elif spec
['type'] in 'gG' and len(self
._int
) > precision
:
3553 self
= self
._round
(precision
, rounding
)
3554 # special case: zeros with a positive exponent can't be
3555 # represented in fixed point; rescale them to 0e0.
3556 if not self
and self
._exp
> 0 and spec
['type'] in 'fF%':
3557 self
= self
._rescale
(0, rounding
)
3559 # figure out placement of the decimal point
3560 leftdigits
= self
._exp
+ len(self
._int
)
3561 if spec
['type'] in 'eE':
3562 if not self
and precision
is not None:
3563 dotplace
= 1 - precision
3566 elif spec
['type'] in 'fF%':
3567 dotplace
= leftdigits
3568 elif spec
['type'] in 'gG':
3569 if self
._exp
<= 0 and leftdigits
> -6:
3570 dotplace
= leftdigits
3574 # find digits before and after decimal point, and get exponent
3577 fracpart
= '0'*(-dotplace
) + self
._int
3578 elif dotplace
> len(self
._int
):
3579 intpart
= self
._int
+ '0'*(dotplace
-len(self
._int
))
3582 intpart
= self
._int
[:dotplace
] or '0'
3583 fracpart
= self
._int
[dotplace
:]
3584 exp
= leftdigits
-dotplace
3586 # done with the decimal-specific stuff; hand over the rest
3587 # of the formatting to the _format_number function
3588 return _format_number(self
._sign
, intpart
, fracpart
, exp
, spec
)
3590 def _dec_from_triple(sign
, coefficient
, exponent
, special
=False):
3591 """Create a decimal instance directly, without any validation,
3592 normalization (e.g. removal of leading zeros) or argument
3595 This function is for *internal use only*.
3598 self
= object.__new
__(Decimal
)
3600 self
._int
= coefficient
3601 self
._exp
= exponent
3602 self
._is
_special
= special
3606 # Register Decimal as a kind of Number (an abstract base class).
3607 # However, do not register it as Real (because Decimals are not
3608 # interoperable with floats).
3609 _numbers
.Number
.register(Decimal
)
3612 ##### Context class #######################################################
3615 # get rounding method function:
3616 rounding_functions
= [name
for name
in Decimal
.__dict
__.keys()
3617 if name
.startswith('_round_')]
3618 for name
in rounding_functions
:
3619 # name is like _round_half_even, goes to the global ROUND_HALF_EVEN value.
3620 globalname
= name
[1:].upper()
3621 val
= globals()[globalname
]
3622 Decimal
._pick
_rounding
_function
[val
] = name
3624 del name
, val
, globalname
, rounding_functions
3626 class _ContextManager(object):
3627 """Context manager class to support localcontext().
3629 Sets a copy of the supplied context in __enter__() and restores
3630 the previous decimal context in __exit__()
3632 def __init__(self
, new_context
):
3633 self
.new_context
= new_context
.copy()
3634 def __enter__(self
):
3635 self
.saved_context
= getcontext()
3636 setcontext(self
.new_context
)
3637 return self
.new_context
3638 def __exit__(self
, t
, v
, tb
):
3639 setcontext(self
.saved_context
)
3641 class Context(object):
3642 """Contains the context for a Decimal instance.
3645 prec - precision (for use in rounding, division, square roots..)
3646 rounding - rounding type (how you round)
3647 traps - If traps[exception] = 1, then the exception is
3648 raised when it is caused. Otherwise, a value is
3650 flags - When an exception is caused, flags[exception] is set.
3651 (Whether or not the trap_enabler is set)
3652 Should be reset by user of Decimal instance.
3653 Emin - Minimum exponent
3654 Emax - Maximum exponent
3655 capitals - If 1, 1*10^1 is printed as 1E+1.
3656 If 0, printed as 1e1
3657 _clamp - If 1, change exponents if too high (Default 0)
3660 def __init__(self
, prec
=None, rounding
=None,
3661 traps
=None, flags
=None,
3662 Emin
=None, Emax
=None,
3663 capitals
=None, _clamp
=0,
3664 _ignored_flags
=None):
3667 if _ignored_flags
is None:
3669 if not isinstance(flags
, dict):
3670 flags
= dict([(s
, int(s
in flags
)) for s
in _signals
])
3672 if traps
is not None and not isinstance(traps
, dict):
3673 traps
= dict([(s
, int(s
in traps
)) for s
in _signals
])
3675 for name
, val
in locals().items():
3677 setattr(self
, name
, _copy
.copy(getattr(DefaultContext
, name
)))
3679 setattr(self
, name
, val
)
3683 """Show the current context."""
3685 s
.append('Context(prec=%(prec)d, rounding=%(rounding)s, '
3686 'Emin=%(Emin)d, Emax=%(Emax)d, capitals=%(capitals)d'
3688 names
= [f
.__name
__ for f
, v
in self
.flags
.items() if v
]
3689 s
.append('flags=[' + ', '.join(names
) + ']')
3690 names
= [t
.__name
__ for t
, v
in self
.traps
.items() if v
]
3691 s
.append('traps=[' + ', '.join(names
) + ']')
3692 return ', '.join(s
) + ')'
3694 def clear_flags(self
):
3695 """Reset all flags to zero"""
3696 for flag
in self
.flags
:
3697 self
.flags
[flag
] = 0
3699 def _shallow_copy(self
):
3700 """Returns a shallow copy from self."""
3701 nc
= Context(self
.prec
, self
.rounding
, self
.traps
,
3702 self
.flags
, self
.Emin
, self
.Emax
,
3703 self
.capitals
, self
._clamp
, self
._ignored
_flags
)
3707 """Returns a deep copy from self."""
3708 nc
= Context(self
.prec
, self
.rounding
, self
.traps
.copy(),
3709 self
.flags
.copy(), self
.Emin
, self
.Emax
,
3710 self
.capitals
, self
._clamp
, self
._ignored
_flags
)
3714 def _raise_error(self
, condition
, explanation
= None, *args
):
3717 If the flag is in _ignored_flags, returns the default response.
3718 Otherwise, it sets the flag, then, if the corresponding
3719 trap_enabler is set, it reaises the exception. Otherwise, it returns
3720 the default value after setting the flag.
3722 error
= _condition_map
.get(condition
, condition
)
3723 if error
in self
._ignored
_flags
:
3724 # Don't touch the flag
3725 return error().handle(self
, *args
)
3727 self
.flags
[error
] = 1
3728 if not self
.traps
[error
]:
3729 # The errors define how to handle themselves.
3730 return condition().handle(self
, *args
)
3732 # Errors should only be risked on copies of the context
3733 # self._ignored_flags = []
3734 raise error(explanation
)
3736 def _ignore_all_flags(self
):
3737 """Ignore all flags, if they are raised"""
3738 return self
._ignore
_flags
(*_signals
)
3740 def _ignore_flags(self
, *flags
):
3741 """Ignore the flags, if they are raised"""
3742 # Do not mutate-- This way, copies of a context leave the original
3744 self
._ignored
_flags
= (self
._ignored
_flags
+ list(flags
))
3747 def _regard_flags(self
, *flags
):
3748 """Stop ignoring the flags, if they are raised"""
3749 if flags
and isinstance(flags
[0], (tuple,list)):
3752 self
._ignored
_flags
.remove(flag
)
3754 # We inherit object.__hash__, so we must deny this explicitly
3758 """Returns Etiny (= Emin - prec + 1)"""
3759 return int(self
.Emin
- self
.prec
+ 1)
3762 """Returns maximum exponent (= Emax - prec + 1)"""
3763 return int(self
.Emax
- self
.prec
+ 1)
3765 def _set_rounding(self
, type):
3766 """Sets the rounding type.
3768 Sets the rounding type, and returns the current (previous)
3769 rounding type. Often used like:
3771 context = context.copy()
3772 # so you don't change the calling context
3773 # if an error occurs in the middle.
3774 rounding = context._set_rounding(ROUND_UP)
3775 val = self.__sub__(other, context=context)
3776 context._set_rounding(rounding)
3778 This will make it round up for that operation.
3780 rounding
= self
.rounding
3784 def create_decimal(self
, num
='0'):
3785 """Creates a new Decimal instance but using self as context.
3787 This method implements the to-number operation of the
3788 IBM Decimal specification."""
3790 if isinstance(num
, basestring
) and num
!= num
.strip():
3791 return self
._raise
_error
(ConversionSyntax
,
3792 "no trailing or leading whitespace is "
3795 d
= Decimal(num
, context
=self
)
3796 if d
._isnan
() and len(d
._int
) > self
.prec
- self
._clamp
:
3797 return self
._raise
_error
(ConversionSyntax
,
3798 "diagnostic info too long in NaN")
3801 def create_decimal_from_float(self
, f
):
3802 """Creates a new Decimal instance from a float but rounding using self
3805 >>> context = Context(prec=5, rounding=ROUND_DOWN)
3806 >>> context.create_decimal_from_float(3.1415926535897932)
3808 >>> context = Context(prec=5, traps=[Inexact])
3809 >>> context.create_decimal_from_float(3.1415926535897932)
3810 Traceback (most recent call last):
3815 d
= Decimal
.from_float(f
) # An exact conversion
3816 return d
._fix
(self
) # Apply the context rounding
3820 """Returns the absolute value of the operand.
3822 If the operand is negative, the result is the same as using the minus
3823 operation on the operand. Otherwise, the result is the same as using
3824 the plus operation on the operand.
3826 >>> ExtendedContext.abs(Decimal('2.1'))
3828 >>> ExtendedContext.abs(Decimal('-100'))
3830 >>> ExtendedContext.abs(Decimal('101.5'))
3832 >>> ExtendedContext.abs(Decimal('-101.5'))
3835 return a
.__abs
__(context
=self
)
3837 def add(self
, a
, b
):
3838 """Return the sum of the two operands.
3840 >>> ExtendedContext.add(Decimal('12'), Decimal('7.00'))
3842 >>> ExtendedContext.add(Decimal('1E+2'), Decimal('1.01E+4'))
3845 return a
.__add
__(b
, context
=self
)
3847 def _apply(self
, a
):
3848 return str(a
._fix
(self
))
3850 def canonical(self
, a
):
3851 """Returns the same Decimal object.
3853 As we do not have different encodings for the same number, the
3854 received object already is in its canonical form.
3856 >>> ExtendedContext.canonical(Decimal('2.50'))
3859 return a
.canonical(context
=self
)
3861 def compare(self
, a
, b
):
3862 """Compares values numerically.
3864 If the signs of the operands differ, a value representing each operand
3865 ('-1' if the operand is less than zero, '0' if the operand is zero or
3866 negative zero, or '1' if the operand is greater than zero) is used in
3867 place of that operand for the comparison instead of the actual
3870 The comparison is then effected by subtracting the second operand from
3871 the first and then returning a value according to the result of the
3872 subtraction: '-1' if the result is less than zero, '0' if the result is
3873 zero or negative zero, or '1' if the result is greater than zero.
3875 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
3877 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
3879 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))
3881 >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))
3883 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))
3885 >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))
3888 return a
.compare(b
, context
=self
)
3890 def compare_signal(self
, a
, b
):
3891 """Compares the values of the two operands numerically.
3893 It's pretty much like compare(), but all NaNs signal, with signaling
3894 NaNs taking precedence over quiet NaNs.
3896 >>> c = ExtendedContext
3897 >>> c.compare_signal(Decimal('2.1'), Decimal('3'))
3899 >>> c.compare_signal(Decimal('2.1'), Decimal('2.1'))
3901 >>> c.flags[InvalidOperation] = 0
3902 >>> print c.flags[InvalidOperation]
3904 >>> c.compare_signal(Decimal('NaN'), Decimal('2.1'))
3906 >>> print c.flags[InvalidOperation]
3908 >>> c.flags[InvalidOperation] = 0
3909 >>> print c.flags[InvalidOperation]
3911 >>> c.compare_signal(Decimal('sNaN'), Decimal('2.1'))
3913 >>> print c.flags[InvalidOperation]
3916 return a
.compare_signal(b
, context
=self
)
3918 def compare_total(self
, a
, b
):
3919 """Compares two operands using their abstract representation.
3921 This is not like the standard compare, which use their numerical
3922 value. Note that a total ordering is defined for all possible abstract
3925 >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
3927 >>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12'))
3929 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))
3931 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))
3933 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300'))
3935 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN'))
3938 return a
.compare_total(b
)
3940 def compare_total_mag(self
, a
, b
):
3941 """Compares two operands using their abstract representation ignoring sign.
3943 Like compare_total, but with operand's sign ignored and assumed to be 0.
3945 return a
.compare_total_mag(b
)
3947 def copy_abs(self
, a
):
3948 """Returns a copy of the operand with the sign set to 0.
3950 >>> ExtendedContext.copy_abs(Decimal('2.1'))
3952 >>> ExtendedContext.copy_abs(Decimal('-100'))
3957 def copy_decimal(self
, a
):
3958 """Returns a copy of the decimal objet.
3960 >>> ExtendedContext.copy_decimal(Decimal('2.1'))
3962 >>> ExtendedContext.copy_decimal(Decimal('-1.00'))
3967 def copy_negate(self
, a
):
3968 """Returns a copy of the operand with the sign inverted.
3970 >>> ExtendedContext.copy_negate(Decimal('101.5'))
3972 >>> ExtendedContext.copy_negate(Decimal('-101.5'))
3975 return a
.copy_negate()
3977 def copy_sign(self
, a
, b
):
3978 """Copies the second operand's sign to the first one.
3980 In detail, it returns a copy of the first operand with the sign
3981 equal to the sign of the second operand.
3983 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))
3985 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))
3987 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))
3989 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))
3992 return a
.copy_sign(b
)
3994 def divide(self
, a
, b
):
3995 """Decimal division in a specified context.
3997 >>> ExtendedContext.divide(Decimal('1'), Decimal('3'))
3998 Decimal('0.333333333')
3999 >>> ExtendedContext.divide(Decimal('2'), Decimal('3'))
4000 Decimal('0.666666667')
4001 >>> ExtendedContext.divide(Decimal('5'), Decimal('2'))
4003 >>> ExtendedContext.divide(Decimal('1'), Decimal('10'))
4005 >>> ExtendedContext.divide(Decimal('12'), Decimal('12'))
4007 >>> ExtendedContext.divide(Decimal('8.00'), Decimal('2'))
4009 >>> ExtendedContext.divide(Decimal('2.400'), Decimal('2.0'))
4011 >>> ExtendedContext.divide(Decimal('1000'), Decimal('100'))
4013 >>> ExtendedContext.divide(Decimal('1000'), Decimal('1'))
4015 >>> ExtendedContext.divide(Decimal('2.40E+6'), Decimal('2'))
4018 return a
.__div
__(b
, context
=self
)
4020 def divide_int(self
, a
, b
):
4021 """Divides two numbers and returns the integer part of the result.
4023 >>> ExtendedContext.divide_int(Decimal('2'), Decimal('3'))
4025 >>> ExtendedContext.divide_int(Decimal('10'), Decimal('3'))
4027 >>> ExtendedContext.divide_int(Decimal('1'), Decimal('0.3'))
4030 return a
.__floordiv
__(b
, context
=self
)
4032 def divmod(self
, a
, b
):
4033 return a
.__divmod
__(b
, context
=self
)
4038 >>> c = ExtendedContext.copy()
4041 >>> c.exp(Decimal('-Infinity'))
4043 >>> c.exp(Decimal('-1'))
4044 Decimal('0.367879441')
4045 >>> c.exp(Decimal('0'))
4047 >>> c.exp(Decimal('1'))
4048 Decimal('2.71828183')
4049 >>> c.exp(Decimal('0.693147181'))
4050 Decimal('2.00000000')
4051 >>> c.exp(Decimal('+Infinity'))
4054 return a
.exp(context
=self
)
4056 def fma(self
, a
, b
, c
):
4057 """Returns a multiplied by b, plus c.
4059 The first two operands are multiplied together, using multiply,
4060 the third operand is then added to the result of that
4061 multiplication, using add, all with only one final rounding.
4063 >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
4065 >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))
4067 >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578'))
4068 Decimal('1.38435736E+12')
4070 return a
.fma(b
, c
, context
=self
)
4072 def is_canonical(self
, a
):
4073 """Return True if the operand is canonical; otherwise return False.
4075 Currently, the encoding of a Decimal instance is always
4076 canonical, so this method returns True for any Decimal.
4078 >>> ExtendedContext.is_canonical(Decimal('2.50'))
4081 return a
.is_canonical()
4083 def is_finite(self
, a
):
4084 """Return True if the operand is finite; otherwise return False.
4086 A Decimal instance is considered finite if it is neither
4089 >>> ExtendedContext.is_finite(Decimal('2.50'))
4091 >>> ExtendedContext.is_finite(Decimal('-0.3'))
4093 >>> ExtendedContext.is_finite(Decimal('0'))
4095 >>> ExtendedContext.is_finite(Decimal('Inf'))
4097 >>> ExtendedContext.is_finite(Decimal('NaN'))
4100 return a
.is_finite()
4102 def is_infinite(self
, a
):
4103 """Return True if the operand is infinite; otherwise return False.
4105 >>> ExtendedContext.is_infinite(Decimal('2.50'))
4107 >>> ExtendedContext.is_infinite(Decimal('-Inf'))
4109 >>> ExtendedContext.is_infinite(Decimal('NaN'))
4112 return a
.is_infinite()
4114 def is_nan(self
, a
):
4115 """Return True if the operand is a qNaN or sNaN;
4116 otherwise return False.
4118 >>> ExtendedContext.is_nan(Decimal('2.50'))
4120 >>> ExtendedContext.is_nan(Decimal('NaN'))
4122 >>> ExtendedContext.is_nan(Decimal('-sNaN'))
4127 def is_normal(self
, a
):
4128 """Return True if the operand is a normal number;
4129 otherwise return False.
4131 >>> c = ExtendedContext.copy()
4134 >>> c.is_normal(Decimal('2.50'))
4136 >>> c.is_normal(Decimal('0.1E-999'))
4138 >>> c.is_normal(Decimal('0.00'))
4140 >>> c.is_normal(Decimal('-Inf'))
4142 >>> c.is_normal(Decimal('NaN'))
4145 return a
.is_normal(context
=self
)
4147 def is_qnan(self
, a
):
4148 """Return True if the operand is a quiet NaN; otherwise return False.
4150 >>> ExtendedContext.is_qnan(Decimal('2.50'))
4152 >>> ExtendedContext.is_qnan(Decimal('NaN'))
4154 >>> ExtendedContext.is_qnan(Decimal('sNaN'))
4159 def is_signed(self
, a
):
4160 """Return True if the operand is negative; otherwise return False.
4162 >>> ExtendedContext.is_signed(Decimal('2.50'))
4164 >>> ExtendedContext.is_signed(Decimal('-12'))
4166 >>> ExtendedContext.is_signed(Decimal('-0'))
4169 return a
.is_signed()
4171 def is_snan(self
, a
):
4172 """Return True if the operand is a signaling NaN;
4173 otherwise return False.
4175 >>> ExtendedContext.is_snan(Decimal('2.50'))
4177 >>> ExtendedContext.is_snan(Decimal('NaN'))
4179 >>> ExtendedContext.is_snan(Decimal('sNaN'))
4184 def is_subnormal(self
, a
):
4185 """Return True if the operand is subnormal; otherwise return False.
4187 >>> c = ExtendedContext.copy()
4190 >>> c.is_subnormal(Decimal('2.50'))
4192 >>> c.is_subnormal(Decimal('0.1E-999'))
4194 >>> c.is_subnormal(Decimal('0.00'))
4196 >>> c.is_subnormal(Decimal('-Inf'))
4198 >>> c.is_subnormal(Decimal('NaN'))
4201 return a
.is_subnormal(context
=self
)
4203 def is_zero(self
, a
):
4204 """Return True if the operand is a zero; otherwise return False.
4206 >>> ExtendedContext.is_zero(Decimal('0'))
4208 >>> ExtendedContext.is_zero(Decimal('2.50'))
4210 >>> ExtendedContext.is_zero(Decimal('-0E+2'))
4216 """Returns the natural (base e) logarithm of the operand.
4218 >>> c = ExtendedContext.copy()
4221 >>> c.ln(Decimal('0'))
4222 Decimal('-Infinity')
4223 >>> c.ln(Decimal('1.000'))
4225 >>> c.ln(Decimal('2.71828183'))
4226 Decimal('1.00000000')
4227 >>> c.ln(Decimal('10'))
4228 Decimal('2.30258509')
4229 >>> c.ln(Decimal('+Infinity'))
4232 return a
.ln(context
=self
)
4235 """Returns the base 10 logarithm of the operand.
4237 >>> c = ExtendedContext.copy()
4240 >>> c.log10(Decimal('0'))
4241 Decimal('-Infinity')
4242 >>> c.log10(Decimal('0.001'))
4244 >>> c.log10(Decimal('1.000'))
4246 >>> c.log10(Decimal('2'))
4247 Decimal('0.301029996')
4248 >>> c.log10(Decimal('10'))
4250 >>> c.log10(Decimal('70'))
4251 Decimal('1.84509804')
4252 >>> c.log10(Decimal('+Infinity'))
4255 return a
.log10(context
=self
)
4258 """ Returns the exponent of the magnitude of the operand's MSD.
4260 The result is the integer which is the exponent of the magnitude
4261 of the most significant digit of the operand (as though the
4262 operand were truncated to a single digit while maintaining the
4263 value of that digit and without limiting the resulting exponent).
4265 >>> ExtendedContext.logb(Decimal('250'))
4267 >>> ExtendedContext.logb(Decimal('2.50'))
4269 >>> ExtendedContext.logb(Decimal('0.03'))
4271 >>> ExtendedContext.logb(Decimal('0'))
4272 Decimal('-Infinity')
4274 return a
.logb(context
=self
)
4276 def logical_and(self
, a
, b
):
4277 """Applies the logical operation 'and' between each operand's digits.
4279 The operands must be both logical numbers.
4281 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))
4283 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))
4285 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))
4287 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))
4289 >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))
4291 >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))
4294 return a
.logical_and(b
, context
=self
)
4296 def logical_invert(self
, a
):
4297 """Invert all the digits in the operand.
4299 The operand must be a logical number.
4301 >>> ExtendedContext.logical_invert(Decimal('0'))
4302 Decimal('111111111')
4303 >>> ExtendedContext.logical_invert(Decimal('1'))
4304 Decimal('111111110')
4305 >>> ExtendedContext.logical_invert(Decimal('111111111'))
4307 >>> ExtendedContext.logical_invert(Decimal('101010101'))
4310 return a
.logical_invert(context
=self
)
4312 def logical_or(self
, a
, b
):
4313 """Applies the logical operation 'or' between each operand's digits.
4315 The operands must be both logical numbers.
4317 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))
4319 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))
4321 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))
4323 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))
4325 >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))
4327 >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))
4330 return a
.logical_or(b
, context
=self
)
4332 def logical_xor(self
, a
, b
):
4333 """Applies the logical operation 'xor' between each operand's digits.
4335 The operands must be both logical numbers.
4337 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))
4339 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))
4341 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))
4343 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))
4345 >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))
4347 >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))
4350 return a
.logical_xor(b
, context
=self
)
4353 """max compares two values numerically and returns the maximum.
4355 If either operand is a NaN then the general rules apply.
4356 Otherwise, the operands are compared as though by the compare
4357 operation. If they are numerically equal then the left-hand operand
4358 is chosen as the result. Otherwise the maximum (closer to positive
4359 infinity) of the two operands is chosen as the result.
4361 >>> ExtendedContext.max(Decimal('3'), Decimal('2'))
4363 >>> ExtendedContext.max(Decimal('-10'), Decimal('3'))
4365 >>> ExtendedContext.max(Decimal('1.0'), Decimal('1'))
4367 >>> ExtendedContext.max(Decimal('7'), Decimal('NaN'))
4370 return a
.max(b
, context
=self
)
4372 def max_mag(self
, a
, b
):
4373 """Compares the values numerically with their sign ignored."""
4374 return a
.max_mag(b
, context
=self
)
4377 """min compares two values numerically and returns the minimum.
4379 If either operand is a NaN then the general rules apply.
4380 Otherwise, the operands are compared as though by the compare
4381 operation. If they are numerically equal then the left-hand operand
4382 is chosen as the result. Otherwise the minimum (closer to negative
4383 infinity) of the two operands is chosen as the result.
4385 >>> ExtendedContext.min(Decimal('3'), Decimal('2'))
4387 >>> ExtendedContext.min(Decimal('-10'), Decimal('3'))
4389 >>> ExtendedContext.min(Decimal('1.0'), Decimal('1'))
4391 >>> ExtendedContext.min(Decimal('7'), Decimal('NaN'))
4394 return a
.min(b
, context
=self
)
4396 def min_mag(self
, a
, b
):
4397 """Compares the values numerically with their sign ignored."""
4398 return a
.min_mag(b
, context
=self
)
4401 """Minus corresponds to unary prefix minus in Python.
4403 The operation is evaluated using the same rules as subtract; the
4404 operation minus(a) is calculated as subtract('0', a) where the '0'
4405 has the same exponent as the operand.
4407 >>> ExtendedContext.minus(Decimal('1.3'))
4409 >>> ExtendedContext.minus(Decimal('-1.3'))
4412 return a
.__neg
__(context
=self
)
4414 def multiply(self
, a
, b
):
4415 """multiply multiplies two operands.
4417 If either operand is a special value then the general rules apply.
4418 Otherwise, the operands are multiplied together ('long multiplication'),
4419 resulting in a number which may be as long as the sum of the lengths
4420 of the two operands.
4422 >>> ExtendedContext.multiply(Decimal('1.20'), Decimal('3'))
4424 >>> ExtendedContext.multiply(Decimal('7'), Decimal('3'))
4426 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('0.8'))
4428 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('-0'))
4430 >>> ExtendedContext.multiply(Decimal('654321'), Decimal('654321'))
4431 Decimal('4.28135971E+11')
4433 return a
.__mul
__(b
, context
=self
)
4435 def next_minus(self
, a
):
4436 """Returns the largest representable number smaller than a.
4438 >>> c = ExtendedContext.copy()
4441 >>> ExtendedContext.next_minus(Decimal('1'))
4442 Decimal('0.999999999')
4443 >>> c.next_minus(Decimal('1E-1007'))
4445 >>> ExtendedContext.next_minus(Decimal('-1.00000003'))
4446 Decimal('-1.00000004')
4447 >>> c.next_minus(Decimal('Infinity'))
4448 Decimal('9.99999999E+999')
4450 return a
.next_minus(context
=self
)
4452 def next_plus(self
, a
):
4453 """Returns the smallest representable number larger than a.
4455 >>> c = ExtendedContext.copy()
4458 >>> ExtendedContext.next_plus(Decimal('1'))
4459 Decimal('1.00000001')
4460 >>> c.next_plus(Decimal('-1E-1007'))
4462 >>> ExtendedContext.next_plus(Decimal('-1.00000003'))
4463 Decimal('-1.00000002')
4464 >>> c.next_plus(Decimal('-Infinity'))
4465 Decimal('-9.99999999E+999')
4467 return a
.next_plus(context
=self
)
4469 def next_toward(self
, a
, b
):
4470 """Returns the number closest to a, in direction towards b.
4472 The result is the closest representable number from the first
4473 operand (but not the first operand) that is in the direction
4474 towards the second operand, unless the operands have the same
4477 >>> c = ExtendedContext.copy()
4480 >>> c.next_toward(Decimal('1'), Decimal('2'))
4481 Decimal('1.00000001')
4482 >>> c.next_toward(Decimal('-1E-1007'), Decimal('1'))
4484 >>> c.next_toward(Decimal('-1.00000003'), Decimal('0'))
4485 Decimal('-1.00000002')
4486 >>> c.next_toward(Decimal('1'), Decimal('0'))
4487 Decimal('0.999999999')
4488 >>> c.next_toward(Decimal('1E-1007'), Decimal('-100'))
4490 >>> c.next_toward(Decimal('-1.00000003'), Decimal('-10'))
4491 Decimal('-1.00000004')
4492 >>> c.next_toward(Decimal('0.00'), Decimal('-0.0000'))
4495 return a
.next_toward(b
, context
=self
)
4497 def normalize(self
, a
):
4498 """normalize reduces an operand to its simplest form.
4500 Essentially a plus operation with all trailing zeros removed from the
4503 >>> ExtendedContext.normalize(Decimal('2.1'))
4505 >>> ExtendedContext.normalize(Decimal('-2.0'))
4507 >>> ExtendedContext.normalize(Decimal('1.200'))
4509 >>> ExtendedContext.normalize(Decimal('-120'))
4511 >>> ExtendedContext.normalize(Decimal('120.00'))
4513 >>> ExtendedContext.normalize(Decimal('0.00'))
4516 return a
.normalize(context
=self
)
4518 def number_class(self
, a
):
4519 """Returns an indication of the class of the operand.
4521 The class is one of the following strings:
4533 >>> c = Context(ExtendedContext)
4536 >>> c.number_class(Decimal('Infinity'))
4538 >>> c.number_class(Decimal('1E-10'))
4540 >>> c.number_class(Decimal('2.50'))
4542 >>> c.number_class(Decimal('0.1E-999'))
4544 >>> c.number_class(Decimal('0'))
4546 >>> c.number_class(Decimal('-0'))
4548 >>> c.number_class(Decimal('-0.1E-999'))
4550 >>> c.number_class(Decimal('-1E-10'))
4552 >>> c.number_class(Decimal('-2.50'))
4554 >>> c.number_class(Decimal('-Infinity'))
4556 >>> c.number_class(Decimal('NaN'))
4558 >>> c.number_class(Decimal('-NaN'))
4560 >>> c.number_class(Decimal('sNaN'))
4563 return a
.number_class(context
=self
)
4566 """Plus corresponds to unary prefix plus in Python.
4568 The operation is evaluated using the same rules as add; the
4569 operation plus(a) is calculated as add('0', a) where the '0'
4570 has the same exponent as the operand.
4572 >>> ExtendedContext.plus(Decimal('1.3'))
4574 >>> ExtendedContext.plus(Decimal('-1.3'))
4577 return a
.__pos
__(context
=self
)
4579 def power(self
, a
, b
, modulo
=None):
4580 """Raises a to the power of b, to modulo if given.
4582 With two arguments, compute a**b. If a is negative then b
4583 must be integral. The result will be inexact unless b is
4584 integral and the result is finite and can be expressed exactly
4585 in 'precision' digits.
4587 With three arguments, compute (a**b) % modulo. For the
4588 three argument form, the following restrictions on the
4591 - all three arguments must be integral
4592 - b must be nonnegative
4593 - at least one of a or b must be nonzero
4594 - modulo must be nonzero and have at most 'precision' digits
4596 The result of pow(a, b, modulo) is identical to the result
4597 that would be obtained by computing (a**b) % modulo with
4598 unbounded precision, but is computed more efficiently. It is
4601 >>> c = ExtendedContext.copy()
4604 >>> c.power(Decimal('2'), Decimal('3'))
4606 >>> c.power(Decimal('-2'), Decimal('3'))
4608 >>> c.power(Decimal('2'), Decimal('-3'))
4610 >>> c.power(Decimal('1.7'), Decimal('8'))
4611 Decimal('69.7575744')
4612 >>> c.power(Decimal('10'), Decimal('0.301029996'))
4613 Decimal('2.00000000')
4614 >>> c.power(Decimal('Infinity'), Decimal('-1'))
4616 >>> c.power(Decimal('Infinity'), Decimal('0'))
4618 >>> c.power(Decimal('Infinity'), Decimal('1'))
4620 >>> c.power(Decimal('-Infinity'), Decimal('-1'))
4622 >>> c.power(Decimal('-Infinity'), Decimal('0'))
4624 >>> c.power(Decimal('-Infinity'), Decimal('1'))
4625 Decimal('-Infinity')
4626 >>> c.power(Decimal('-Infinity'), Decimal('2'))
4628 >>> c.power(Decimal('0'), Decimal('0'))
4631 >>> c.power(Decimal('3'), Decimal('7'), Decimal('16'))
4633 >>> c.power(Decimal('-3'), Decimal('7'), Decimal('16'))
4635 >>> c.power(Decimal('-3'), Decimal('8'), Decimal('16'))
4637 >>> c.power(Decimal('3'), Decimal('7'), Decimal('-16'))
4639 >>> c.power(Decimal('23E12345'), Decimal('67E189'), Decimal('123456789'))
4641 >>> c.power(Decimal('-0'), Decimal('17'), Decimal('1729'))
4643 >>> c.power(Decimal('-23'), Decimal('0'), Decimal('65537'))
4646 return a
.__pow
__(b
, modulo
, context
=self
)
4648 def quantize(self
, a
, b
):
4649 """Returns a value equal to 'a' (rounded), having the exponent of 'b'.
4651 The coefficient of the result is derived from that of the left-hand
4652 operand. It may be rounded using the current rounding setting (if the
4653 exponent is being increased), multiplied by a positive power of ten (if
4654 the exponent is being decreased), or is unchanged (if the exponent is
4655 already equal to that of the right-hand operand).
4657 Unlike other operations, if the length of the coefficient after the
4658 quantize operation would be greater than precision then an Invalid
4659 operation condition is raised. This guarantees that, unless there is
4660 an error condition, the exponent of the result of a quantize is always
4661 equal to that of the right-hand operand.
4663 Also unlike other operations, quantize will never raise Underflow, even
4664 if the result is subnormal and inexact.
4666 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))
4668 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))
4670 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))
4672 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))
4674 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))
4676 >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))
4677 Decimal('-Infinity')
4678 >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))
4680 >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))
4682 >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))
4684 >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))
4686 >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))
4688 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))
4690 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))
4692 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))
4694 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))
4697 return a
.quantize(b
, context
=self
)
4700 """Just returns 10, as this is Decimal, :)
4702 >>> ExtendedContext.radix()
4707 def remainder(self
, a
, b
):
4708 """Returns the remainder from integer division.
4710 The result is the residue of the dividend after the operation of
4711 calculating integer division as described for divide-integer, rounded
4712 to precision digits if necessary. The sign of the result, if
4713 non-zero, is the same as that of the original dividend.
4715 This operation will fail under the same conditions as integer division
4716 (that is, if integer division on the same two operands would fail, the
4717 remainder cannot be calculated).
4719 >>> ExtendedContext.remainder(Decimal('2.1'), Decimal('3'))
4721 >>> ExtendedContext.remainder(Decimal('10'), Decimal('3'))
4723 >>> ExtendedContext.remainder(Decimal('-10'), Decimal('3'))
4725 >>> ExtendedContext.remainder(Decimal('10.2'), Decimal('1'))
4727 >>> ExtendedContext.remainder(Decimal('10'), Decimal('0.3'))
4729 >>> ExtendedContext.remainder(Decimal('3.6'), Decimal('1.3'))
4732 return a
.__mod
__(b
, context
=self
)
4734 def remainder_near(self
, a
, b
):
4735 """Returns to be "a - b * n", where n is the integer nearest the exact
4736 value of "x / b" (if two integers are equally near then the even one
4737 is chosen). If the result is equal to 0 then its sign will be the
4740 This operation will fail under the same conditions as integer division
4741 (that is, if integer division on the same two operands would fail, the
4742 remainder cannot be calculated).
4744 >>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))
4746 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))
4748 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))
4750 >>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))
4752 >>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))
4754 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))
4756 >>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))
4759 return a
.remainder_near(b
, context
=self
)
4761 def rotate(self
, a
, b
):
4762 """Returns a rotated copy of a, b times.
4764 The coefficient of the result is a rotated copy of the digits in
4765 the coefficient of the first operand. The number of places of
4766 rotation is taken from the absolute value of the second operand,
4767 with the rotation being to the left if the second operand is
4768 positive or to the right otherwise.
4770 >>> ExtendedContext.rotate(Decimal('34'), Decimal('8'))
4771 Decimal('400000003')
4772 >>> ExtendedContext.rotate(Decimal('12'), Decimal('9'))
4774 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('-2'))
4775 Decimal('891234567')
4776 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('0'))
4777 Decimal('123456789')
4778 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('+2'))
4779 Decimal('345678912')
4781 return a
.rotate(b
, context
=self
)
4783 def same_quantum(self
, a
, b
):
4784 """Returns True if the two operands have the same exponent.
4786 The result is never affected by either the sign or the coefficient of
4789 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))
4791 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))
4793 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))
4795 >>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))
4798 return a
.same_quantum(b
)
4800 def scaleb (self
, a
, b
):
4801 """Returns the first operand after adding the second value its exp.
4803 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('-2'))
4805 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('0'))
4807 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('3'))
4810 return a
.scaleb (b
, context
=self
)
4812 def shift(self
, a
, b
):
4813 """Returns a shifted copy of a, b times.
4815 The coefficient of the result is a shifted copy of the digits
4816 in the coefficient of the first operand. The number of places
4817 to shift is taken from the absolute value of the second operand,
4818 with the shift being to the left if the second operand is
4819 positive or to the right otherwise. Digits shifted into the
4820 coefficient are zeros.
4822 >>> ExtendedContext.shift(Decimal('34'), Decimal('8'))
4823 Decimal('400000000')
4824 >>> ExtendedContext.shift(Decimal('12'), Decimal('9'))
4826 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('-2'))
4828 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('0'))
4829 Decimal('123456789')
4830 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('+2'))
4831 Decimal('345678900')
4833 return a
.shift(b
, context
=self
)
4836 """Square root of a non-negative number to context precision.
4838 If the result must be inexact, it is rounded using the round-half-even
4841 >>> ExtendedContext.sqrt(Decimal('0'))
4843 >>> ExtendedContext.sqrt(Decimal('-0'))
4845 >>> ExtendedContext.sqrt(Decimal('0.39'))
4846 Decimal('0.624499800')
4847 >>> ExtendedContext.sqrt(Decimal('100'))
4849 >>> ExtendedContext.sqrt(Decimal('1'))
4851 >>> ExtendedContext.sqrt(Decimal('1.0'))
4853 >>> ExtendedContext.sqrt(Decimal('1.00'))
4855 >>> ExtendedContext.sqrt(Decimal('7'))
4856 Decimal('2.64575131')
4857 >>> ExtendedContext.sqrt(Decimal('10'))
4858 Decimal('3.16227766')
4859 >>> ExtendedContext.prec
4862 return a
.sqrt(context
=self
)
4864 def subtract(self
, a
, b
):
4865 """Return the difference between the two operands.
4867 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.07'))
4869 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.30'))
4871 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('2.07'))
4874 return a
.__sub
__(b
, context
=self
)
4876 def to_eng_string(self
, a
):
4877 """Converts a number to a string, using scientific notation.
4879 The operation is not affected by the context.
4881 return a
.to_eng_string(context
=self
)
4883 def to_sci_string(self
, a
):
4884 """Converts a number to a string, using scientific notation.
4886 The operation is not affected by the context.
4888 return a
.__str
__(context
=self
)
4890 def to_integral_exact(self
, a
):
4891 """Rounds to an integer.
4893 When the operand has a negative exponent, the result is the same
4894 as using the quantize() operation using the given operand as the
4895 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
4896 of the operand as the precision setting; Inexact and Rounded flags
4897 are allowed in this operation. The rounding mode is taken from the
4900 >>> ExtendedContext.to_integral_exact(Decimal('2.1'))
4902 >>> ExtendedContext.to_integral_exact(Decimal('100'))
4904 >>> ExtendedContext.to_integral_exact(Decimal('100.0'))
4906 >>> ExtendedContext.to_integral_exact(Decimal('101.5'))
4908 >>> ExtendedContext.to_integral_exact(Decimal('-101.5'))
4910 >>> ExtendedContext.to_integral_exact(Decimal('10E+5'))
4912 >>> ExtendedContext.to_integral_exact(Decimal('7.89E+77'))
4914 >>> ExtendedContext.to_integral_exact(Decimal('-Inf'))
4915 Decimal('-Infinity')
4917 return a
.to_integral_exact(context
=self
)
4919 def to_integral_value(self
, a
):
4920 """Rounds to an integer.
4922 When the operand has a negative exponent, the result is the same
4923 as using the quantize() operation using the given operand as the
4924 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
4925 of the operand as the precision setting, except that no flags will
4926 be set. The rounding mode is taken from the context.
4928 >>> ExtendedContext.to_integral_value(Decimal('2.1'))
4930 >>> ExtendedContext.to_integral_value(Decimal('100'))
4932 >>> ExtendedContext.to_integral_value(Decimal('100.0'))
4934 >>> ExtendedContext.to_integral_value(Decimal('101.5'))
4936 >>> ExtendedContext.to_integral_value(Decimal('-101.5'))
4938 >>> ExtendedContext.to_integral_value(Decimal('10E+5'))
4940 >>> ExtendedContext.to_integral_value(Decimal('7.89E+77'))
4942 >>> ExtendedContext.to_integral_value(Decimal('-Inf'))
4943 Decimal('-Infinity')
4945 return a
.to_integral_value(context
=self
)
4947 # the method name changed, but we provide also the old one, for compatibility
4948 to_integral
= to_integral_value
4950 class _WorkRep(object):
4951 __slots__
= ('sign','int','exp')
4954 # exp: None, int, or string
4956 def __init__(self
, value
=None):
4961 elif isinstance(value
, Decimal
):
4962 self
.sign
= value
._sign
4963 self
.int = int(value
._int
)
4964 self
.exp
= value
._exp
4966 # assert isinstance(value, tuple)
4967 self
.sign
= value
[0]
4972 return "(%r, %r, %r)" % (self
.sign
, self
.int, self
.exp
)
4978 def _normalize(op1
, op2
, prec
= 0):
4979 """Normalizes op1, op2 to have the same exp and length of coefficient.
4981 Done during addition.
4983 if op1
.exp
< op2
.exp
:
4990 # Let exp = min(tmp.exp - 1, tmp.adjusted() - precision - 1).
4991 # Then adding 10**exp to tmp has the same effect (after rounding)
4992 # as adding any positive quantity smaller than 10**exp; similarly
4993 # for subtraction. So if other is smaller than 10**exp we replace
4994 # it with 10**exp. This avoids tmp.exp - other.exp getting too large.
4995 tmp_len
= len(str(tmp
.int))
4996 other_len
= len(str(other
.int))
4997 exp
= tmp
.exp
+ min(-1, tmp_len
- prec
- 2)
4998 if other_len
+ other
.exp
- 1 < exp
:
5002 tmp
.int *= 10 ** (tmp
.exp
- other
.exp
)
5006 ##### Integer arithmetic functions used by ln, log10, exp and __pow__ #####
5008 # This function from Tim Peters was taken from here:
5009 # http://mail.python.org/pipermail/python-list/1999-July/007758.html
5010 # The correction being in the function definition is for speed, and
5011 # the whole function is not resolved with math.log because of avoiding
5012 # the use of floats.
5013 def _nbits(n
, correction
= {
5014 '0': 4, '1': 3, '2': 2, '3': 2,
5015 '4': 1, '5': 1, '6': 1, '7': 1,
5016 '8': 0, '9': 0, 'a': 0, 'b': 0,
5017 'c': 0, 'd': 0, 'e': 0, 'f': 0}):
5018 """Number of bits in binary representation of the positive integer n,
5022 raise ValueError("The argument to _nbits should be nonnegative.")
5024 return 4*len(hex_n
) - correction
[hex_n
[0]]
5026 def _sqrt_nearest(n
, a
):
5027 """Closest integer to the square root of the positive integer n. a is
5028 an initial approximation to the square root. Any positive integer
5029 will do for a, but the closer a is to the square root of n the
5030 faster convergence will be.
5033 if n
<= 0 or a
<= 0:
5034 raise ValueError("Both arguments to _sqrt_nearest should be positive.")
5038 b
, a
= a
, a
--n
//a
>>1
5041 def _rshift_nearest(x
, shift
):
5042 """Given an integer x and a nonnegative integer shift, return closest
5043 integer to x / 2**shift; use round-to-even in case of a tie.
5046 b
, q
= 1L << shift
, x
>> shift
5047 return q
+ (2*(x
& (b
-1)) + (q
&1) > b
)
5049 def _div_nearest(a
, b
):
5050 """Closest integer to a/b, a and b positive integers; rounds to even
5051 in the case of a tie.
5055 return q
+ (2*r
+ (q
&1) > b
)
5057 def _ilog(x
, M
, L
= 8):
5058 """Integer approximation to M*log(x/M), with absolute error boundable
5059 in terms only of x/M.
5061 Given positive integers x and M, return an integer approximation to
5062 M * log(x/M). For L = 8 and 0.1 <= x/M <= 10 the difference
5063 between the approximation and the exact result is at most 22. For
5064 L = 8 and 1.0 <= x/M <= 10.0 the difference is at most 15. In
5065 both cases these are upper bounds on the error; it will usually be
5068 # The basic algorithm is the following: let log1p be the function
5069 # log1p(x) = log(1+x). Then log(x/M) = log1p((x-M)/M). We use
5072 # log1p(y) = 2*log1p(y/(1+sqrt(1+y)))
5074 # repeatedly until the argument to log1p is small (< 2**-L in
5075 # absolute value). For small y we can use the Taylor series
5078 # log1p(y) ~ y - y**2/2 + y**3/3 - ... - (-y)**T/T
5080 # truncating at T such that y**T is small enough. The whole
5081 # computation is carried out in a form of fixed-point arithmetic,
5082 # with a real number z being represented by an integer
5083 # approximation to z*M. To avoid loss of precision, the y below
5084 # is actually an integer approximation to 2**R*y*M, where R is the
5085 # number of reductions performed so far.
5088 # argument reduction; R = number of reductions performed
5090 while (R
<= L
and long(abs(y
)) << L
-R
>= M
or
5091 R
> L
and abs(y
) >> R
-L
>= M
):
5092 y
= _div_nearest(long(M
*y
) << 1,
5093 M
+ _sqrt_nearest(M
*(M
+_rshift_nearest(y
, R
)), M
))
5096 # Taylor series with T terms
5097 T
= -int(-10*len(str(M
))//(3*L
))
5098 yshift
= _rshift_nearest(y
, R
)
5099 w
= _div_nearest(M
, T
)
5100 for k
in xrange(T
-1, 0, -1):
5101 w
= _div_nearest(M
, k
) - _div_nearest(yshift
*w
, M
)
5103 return _div_nearest(w
*y
, M
)
5105 def _dlog10(c
, e
, p
):
5106 """Given integers c, e and p with c > 0, p >= 0, compute an integer
5107 approximation to 10**p * log10(c*10**e), with an absolute error of
5108 at most 1. Assumes that c*10**e is not exactly 1."""
5110 # increase precision by 2; compensate for this by dividing
5111 # final result by 100
5114 # write c*10**e as d*10**f with either:
5115 # f >= 0 and 1 <= d <= 10, or
5116 # f <= 0 and 0.1 <= d <= 1.
5117 # Thus for c*10**e close to 1, f = 0
5119 f
= e
+l
- (e
+l
>= 1)
5127 c
= _div_nearest(c
, 10**-k
)
5129 log_d
= _ilog(c
, M
) # error < 5 + 22 = 27
5130 log_10
= _log10_digits(p
) # error < 1
5131 log_d
= _div_nearest(log_d
*M
, log_10
)
5132 log_tenpower
= f
*M
# exact
5134 log_d
= 0 # error < 2.31
5135 log_tenpower
= _div_nearest(f
, 10**-p
) # error < 0.5
5137 return _div_nearest(log_tenpower
+log_d
, 100)
5140 """Given integers c, e and p with c > 0, compute an integer
5141 approximation to 10**p * log(c*10**e), with an absolute error of
5142 at most 1. Assumes that c*10**e is not exactly 1."""
5144 # Increase precision by 2. The precision increase is compensated
5145 # for at the end with a division by 100.
5148 # rewrite c*10**e as d*10**f with either f >= 0 and 1 <= d <= 10,
5149 # or f <= 0 and 0.1 <= d <= 1. Then we can compute 10**p * log(c*10**e)
5150 # as 10**p * log(d) + 10**p*f * log(10).
5152 f
= e
+l
- (e
+l
>= 1)
5154 # compute approximation to 10**p*log(d), with error < 27
5160 c
= _div_nearest(c
, 10**-k
) # error of <= 0.5 in c
5162 # _ilog magnifies existing error in c by a factor of at most 10
5163 log_d
= _ilog(c
, 10**p
) # error < 5 + 22 = 27
5165 # p <= 0: just approximate the whole thing by 0; error < 2.31
5168 # compute approximation to f*10**p*log(10), with error < 11.
5170 extra
= len(str(abs(f
)))-1
5172 # error in f * _log10_digits(p+extra) < |f| * 1 = |f|
5173 # after division, error < |f|/10**extra + 0.5 < 10 + 0.5 < 11
5174 f_log_ten
= _div_nearest(f
*_log10_digits(p
+extra
), 10**extra
)
5180 # error in sum < 11+27 = 38; error after division < 0.38 + 0.5 < 1
5181 return _div_nearest(f_log_ten
+ log_d
, 100)
5183 class _Log10Memoize(object):
5184 """Class to compute, store, and allow retrieval of, digits of the
5185 constant log(10) = 2.302585.... This constant is needed by
5186 Decimal.ln, Decimal.log10, Decimal.exp and Decimal.__pow__."""
5188 self
.digits
= "23025850929940456840179914546843642076011014886"
5190 def getdigits(self
, p
):
5191 """Given an integer p >= 0, return floor(10**p)*log(10).
5193 For example, self.getdigits(3) returns 2302.
5195 # digits are stored as a string, for quick conversion to
5196 # integer in the case that we've already computed enough
5197 # digits; the stored digits should always be correct
5198 # (truncated, not rounded to nearest).
5200 raise ValueError("p should be nonnegative")
5202 if p
>= len(self
.digits
):
5203 # compute p+3, p+6, p+9, ... digits; continue until at
5204 # least one of the extra digits is nonzero
5207 # compute p+extra digits, correct to within 1ulp
5209 digits
= str(_div_nearest(_ilog(10*M
, M
), 100))
5210 if digits
[-extra
:] != '0'*extra
:
5213 # keep all reliable digits so far; remove trailing zeros
5214 # and next nonzero digit
5215 self
.digits
= digits
.rstrip('0')[:-1]
5216 return int(self
.digits
[:p
+1])
5218 _log10_digits
= _Log10Memoize().getdigits
5220 def _iexp(x
, M
, L
=8):
5221 """Given integers x and M, M > 0, such that x/M is small in absolute
5222 value, compute an integer approximation to M*exp(x/M). For 0 <=
5223 x/M <= 2.4, the absolute error in the result is bounded by 60 (and
5224 is usually much smaller)."""
5226 # Algorithm: to compute exp(z) for a real number z, first divide z
5227 # by a suitable power R of 2 so that |z/2**R| < 2**-L. Then
5228 # compute expm1(z/2**R) = exp(z/2**R) - 1 using the usual Taylor
5231 # expm1(x) = x + x**2/2! + x**3/3! + ...
5233 # Now use the identity
5235 # expm1(2x) = expm1(x)*(expm1(x)+2)
5237 # R times to compute the sequence expm1(z/2**R),
5238 # expm1(z/2**(R-1)), ... , exp(z/2), exp(z).
5240 # Find R such that x/2**R/M <= 2**-L
5241 R
= _nbits((long(x
)<<L
)//M
)
5243 # Taylor series. (2**L)**T > M
5244 T
= -int(-10*len(str(M
))//(3*L
))
5245 y
= _div_nearest(x
, T
)
5247 for i
in xrange(T
-1, 0, -1):
5248 y
= _div_nearest(x
*(Mshift
+ y
), Mshift
* i
)
5251 for k
in xrange(R
-1, -1, -1):
5252 Mshift
= long(M
)<<(k
+2)
5253 y
= _div_nearest(y
*(y
+Mshift
), Mshift
)
5258 """Compute an approximation to exp(c*10**e), with p decimal places of
5261 Returns integers d, f such that:
5263 10**(p-1) <= d <= 10**p, and
5264 (d-1)*10**f < exp(c*10**e) < (d+1)*10**f
5266 In other words, d*10**f is an approximation to exp(c*10**e) with p
5267 digits of precision, and with an error in d of at most 1. This is
5268 almost, but not quite, the same as the error being < 1ulp: when d
5269 = 10**(p-1) the error could be up to 10 ulp."""
5271 # we'll call iexp with M = 10**(p+2), giving p+3 digits of precision
5274 # compute log(10) with extra precision = adjusted exponent of c*10**e
5275 extra
= max(0, e
+ len(str(c
)) - 1)
5278 # compute quotient c*10**e/(log(10)) = c*10**(e+q)/(log(10)*10**q),
5282 cshift
= c
*10**shift
5284 cshift
= c
//10**-shift
5285 quot
, rem
= divmod(cshift
, _log10_digits(q
))
5287 # reduce remainder back to original precision
5288 rem
= _div_nearest(rem
, 10**extra
)
5290 # error in result of _iexp < 120; error after division < 0.62
5291 return _div_nearest(_iexp(rem
, 10**p
), 1000), quot
- p
+ 3
5293 def _dpower(xc
, xe
, yc
, ye
, p
):
5294 """Given integers xc, xe, yc and ye representing Decimals x = xc*10**xe and
5295 y = yc*10**ye, compute x**y. Returns a pair of integers (c, e) such that:
5297 10**(p-1) <= c <= 10**p, and
5298 (c-1)*10**e < x**y < (c+1)*10**e
5300 in other words, c*10**e is an approximation to x**y with p digits
5301 of precision, and with an error in c of at most 1. (This is
5302 almost, but not quite, the same as the error being < 1ulp: when c
5303 == 10**(p-1) we can only guarantee error < 10ulp.)
5305 We assume that: x is positive and not equal to 1, and y is nonzero.
5308 # Find b such that 10**(b-1) <= |y| <= 10**b
5309 b
= len(str(abs(yc
))) + ye
5311 # log(x) = lxc*10**(-p-b-1), to p+b+1 places after the decimal point
5312 lxc
= _dlog(xc
, xe
, p
+b
+1)
5314 # compute product y*log(x) = yc*lxc*10**(-p-b-1+ye) = pc*10**(-p-1)
5317 pc
= lxc
*yc
*10**shift
5319 pc
= _div_nearest(lxc
*yc
, 10**-shift
)
5322 # we prefer a result that isn't exactly 1; this makes it
5323 # easier to compute a correctly rounded result in __pow__
5324 if ((len(str(xc
)) + xe
>= 1) == (yc
> 0)): # if x**y > 1:
5325 coeff
, exp
= 10**(p
-1)+1, 1-p
5327 coeff
, exp
= 10**p
-1, -p
5329 coeff
, exp
= _dexp(pc
, -(p
+1), p
+1)
5330 coeff
= _div_nearest(coeff
, 10)
5335 def _log10_lb(c
, correction
= {
5336 '1': 100, '2': 70, '3': 53, '4': 40, '5': 31,
5337 '6': 23, '7': 16, '8': 10, '9': 5}):
5338 """Compute a lower bound for 100*log10(c) for a positive integer c."""
5340 raise ValueError("The argument to _log10_lb should be nonnegative.")
5342 return 100*len(str_c
) - correction
[str_c
[0]]
5344 ##### Helper Functions ####################################################
5346 def _convert_other(other
, raiseit
=False):
5347 """Convert other to Decimal.
5349 Verifies that it's ok to use in an implicit construction.
5351 if isinstance(other
, Decimal
):
5353 if isinstance(other
, (int, long)):
5354 return Decimal(other
)
5356 raise TypeError("Unable to convert %s to Decimal" % other
)
5357 return NotImplemented
5359 ##### Setup Specific Contexts ############################################
5361 # The default context prototype used by Context()
5362 # Is mutable, so that new contexts can have different default values
5364 DefaultContext
= Context(
5365 prec
=28, rounding
=ROUND_HALF_EVEN
,
5366 traps
=[DivisionByZero
, Overflow
, InvalidOperation
],
5373 # Pre-made alternate contexts offered by the specification
5374 # Don't change these; the user should be able to select these
5375 # contexts and be able to reproduce results from other implementations
5378 BasicContext
= Context(
5379 prec
=9, rounding
=ROUND_HALF_UP
,
5380 traps
=[DivisionByZero
, Overflow
, InvalidOperation
, Clamped
, Underflow
],
5384 ExtendedContext
= Context(
5385 prec
=9, rounding
=ROUND_HALF_EVEN
,
5391 ##### crud for parsing strings #############################################
5393 # Regular expression used for parsing numeric strings. Additional
5396 # 1. Uncomment the two '\s*' lines to allow leading and/or trailing
5397 # whitespace. But note that the specification disallows whitespace in
5400 # 2. For finite numbers (not infinities and NaNs) the body of the
5401 # number between the optional sign and the optional exponent must have
5402 # at least one decimal digit, possibly after the decimal point. The
5403 # lookahead expression '(?=\d|\.\d)' checks this.
5406 _parser
= re
.compile(r
""" # A numeric string consists of:
5408 (?P<sign>[-+])? # an optional sign, followed by either...
5410 (?=\d|\.\d) # ...a number (with at least one digit)
5411 (?P<int>\d*) # having a (possibly empty) integer part
5412 (\.(?P<frac>\d*))? # followed by an optional fractional part
5413 (E(?P<exp>[-+]?\d+))? # followed by an optional exponent, or...
5415 Inf(inity)? # ...an infinity, or...
5417 (?P<signal>s)? # ...an (optionally signaling)
5419 (?P<diag>\d*) # with (possibly empty) diagnostic info.
5423 """, re
.VERBOSE | re
.IGNORECASE | re
.UNICODE
).match
5425 _all_zeros
= re
.compile('0*$').match
5426 _exact_half
= re
.compile('50*$').match
5428 ##### PEP3101 support functions ##############################################
5429 # The functions in this section have little to do with the Decimal
5430 # class, and could potentially be reused or adapted for other pure
5431 # Python numeric classes that want to implement __format__
5433 # A format specifier for Decimal looks like:
5435 # [[fill]align][sign][0][minimumwidth][,][.precision][type]
5437 _parse_format_specifier_regex
= re
.compile(r
"""\A
5444 (?P<minimumwidth>(?!0)\d+)?
5445 (?P<thousands_sep>,)?
5446 (?:\.(?P<precision>0|(?!0)\d+))?
5447 (?P<type>[eEfFgGn%])?
5453 # The locale module is only needed for the 'n' format specifier. The
5454 # rest of the PEP 3101 code functions quite happily without it, so we
5455 # don't care too much if locale isn't present.
5457 import locale
as _locale
5461 def _parse_format_specifier(format_spec
, _localeconv
=None):
5462 """Parse and validate a format specifier.
5464 Turns a standard numeric format specifier into a dict, with the
5467 fill: fill character to pad field to minimum width
5468 align: alignment type, either '<', '>', '=' or '^'
5469 sign: either '+', '-' or ' '
5470 minimumwidth: nonnegative integer giving minimum width
5471 zeropad: boolean, indicating whether to pad with zeros
5472 thousands_sep: string to use as thousands separator, or ''
5473 grouping: grouping for thousands separators, in format
5475 decimal_point: string to use for decimal point
5476 precision: nonnegative integer giving precision, or None
5477 type: one of the characters 'eEfFgG%', or None
5478 unicode: boolean (always True for Python 3.x)
5481 m
= _parse_format_specifier_regex
.match(format_spec
)
5483 raise ValueError("Invalid format specifier: " + format_spec
)
5485 # get the dictionary
5486 format_dict
= m
.groupdict()
5488 # zeropad; defaults for fill and alignment. If zero padding
5489 # is requested, the fill and align fields should be absent.
5490 fill
= format_dict
['fill']
5491 align
= format_dict
['align']
5492 format_dict
['zeropad'] = (format_dict
['zeropad'] is not None)
5493 if format_dict
['zeropad']:
5494 if fill
is not None:
5495 raise ValueError("Fill character conflicts with '0'"
5496 " in format specifier: " + format_spec
)
5497 if align
is not None:
5498 raise ValueError("Alignment conflicts with '0' in "
5499 "format specifier: " + format_spec
)
5500 format_dict
['fill'] = fill
or ' '
5501 # PEP 3101 originally specified that the default alignment should
5502 # be left; it was later agreed that right-aligned makes more sense
5503 # for numeric types. See http://bugs.python.org/issue6857.
5504 format_dict
['align'] = align
or '>'
5506 # default sign handling: '-' for negative, '' for positive
5507 if format_dict
['sign'] is None:
5508 format_dict
['sign'] = '-'
5510 # minimumwidth defaults to 0; precision remains None if not given
5511 format_dict
['minimumwidth'] = int(format_dict
['minimumwidth'] or '0')
5512 if format_dict
['precision'] is not None:
5513 format_dict
['precision'] = int(format_dict
['precision'])
5515 # if format type is 'g' or 'G' then a precision of 0 makes little
5516 # sense; convert it to 1. Same if format type is unspecified.
5517 if format_dict
['precision'] == 0:
5518 if format_dict
['type'] is None or format_dict
['type'] in 'gG':
5519 format_dict
['precision'] = 1
5521 # determine thousands separator, grouping, and decimal separator, and
5522 # add appropriate entries to format_dict
5523 if format_dict
['type'] == 'n':
5524 # apart from separators, 'n' behaves just like 'g'
5525 format_dict
['type'] = 'g'
5526 if _localeconv
is None:
5527 _localeconv
= _locale
.localeconv()
5528 if format_dict
['thousands_sep'] is not None:
5529 raise ValueError("Explicit thousands separator conflicts with "
5530 "'n' type in format specifier: " + format_spec
)
5531 format_dict
['thousands_sep'] = _localeconv
['thousands_sep']
5532 format_dict
['grouping'] = _localeconv
['grouping']
5533 format_dict
['decimal_point'] = _localeconv
['decimal_point']
5535 if format_dict
['thousands_sep'] is None:
5536 format_dict
['thousands_sep'] = ''
5537 format_dict
['grouping'] = [3, 0]
5538 format_dict
['decimal_point'] = '.'
5540 # record whether return type should be str or unicode
5541 format_dict
['unicode'] = isinstance(format_spec
, unicode)
5545 def _format_align(sign
, body
, spec
):
5546 """Given an unpadded, non-aligned numeric string 'body' and sign
5547 string 'sign', add padding and aligment conforming to the given
5548 format specifier dictionary 'spec' (as produced by
5549 parse_format_specifier).
5551 Also converts result to unicode if necessary.
5554 # how much extra space do we have to play with?
5555 minimumwidth
= spec
['minimumwidth']
5557 padding
= fill
*(minimumwidth
- len(sign
) - len(body
))
5559 align
= spec
['align']
5561 result
= sign
+ body
+ padding
5563 result
= padding
+ sign
+ body
5565 result
= sign
+ padding
+ body
5567 half
= len(padding
)//2
5568 result
= padding
[:half
] + sign
+ body
+ padding
[half
:]
5570 raise ValueError('Unrecognised alignment field')
5572 # make sure that result is unicode if necessary
5574 result
= unicode(result
)
5578 def _group_lengths(grouping
):
5579 """Convert a localeconv-style grouping into a (possibly infinite)
5580 iterable of integers representing group lengths.
5583 # The result from localeconv()['grouping'], and the input to this
5584 # function, should be a list of integers in one of the
5585 # following three forms:
5587 # (1) an empty list, or
5588 # (2) nonempty list of positive integers + [0]
5589 # (3) list of positive integers + [locale.CHAR_MAX], or
5591 from itertools
import chain
, repeat
5594 elif grouping
[-1] == 0 and len(grouping
) >= 2:
5595 return chain(grouping
[:-1], repeat(grouping
[-2]))
5596 elif grouping
[-1] == _locale
.CHAR_MAX
:
5597 return grouping
[:-1]
5599 raise ValueError('unrecognised format for grouping')
5601 def _insert_thousands_sep(digits
, spec
, min_width
=1):
5602 """Insert thousands separators into a digit string.
5604 spec is a dictionary whose keys should include 'thousands_sep' and
5605 'grouping'; typically it's the result of parsing the format
5606 specifier using _parse_format_specifier.
5608 The min_width keyword argument gives the minimum length of the
5609 result, which will be padded on the left with zeros if necessary.
5611 If necessary, the zero padding adds an extra '0' on the left to
5612 avoid a leading thousands separator. For example, inserting
5613 commas every three digits in '123456', with min_width=8, gives
5614 '0,123,456', even though that has length 9.
5618 sep
= spec
['thousands_sep']
5619 grouping
= spec
['grouping']
5622 for l
in _group_lengths(grouping
):
5624 raise ValueError("group length should be positive")
5625 # max(..., 1) forces at least 1 digit to the left of a separator
5626 l
= min(max(len(digits
), min_width
, 1), l
)
5627 groups
.append('0'*(l
- len(digits
)) + digits
[-l
:])
5628 digits
= digits
[:-l
]
5630 if not digits
and min_width
<= 0:
5632 min_width
-= len(sep
)
5634 l
= max(len(digits
), min_width
, 1)
5635 groups
.append('0'*(l
- len(digits
)) + digits
[-l
:])
5636 return sep
.join(reversed(groups
))
5638 def _format_sign(is_negative
, spec
):
5639 """Determine sign character."""
5643 elif spec
['sign'] in ' +':
5648 def _format_number(is_negative
, intpart
, fracpart
, exp
, spec
):
5649 """Format a number, given the following data:
5651 is_negative: true if the number is negative, else false
5652 intpart: string of digits that must appear before the decimal point
5653 fracpart: string of digits that must come after the point
5654 exp: exponent, as an integer
5655 spec: dictionary resulting from parsing the format specifier
5657 This function uses the information in spec to:
5658 insert separators (decimal separator and thousands separators)
5661 add trailing '%' for the '%' type
5662 zero-pad if necessary
5663 fill and align if necessary
5666 sign
= _format_sign(is_negative
, spec
)
5669 fracpart
= spec
['decimal_point'] + fracpart
5671 if exp
!= 0 or spec
['type'] in 'eE':
5672 echar
= {'E': 'E', 'e': 'e', 'G': 'E', 'g': 'e'}[spec
['type']]
5673 fracpart
+= "{0}{1:+}".format(echar
, exp
)
5674 if spec
['type'] == '%':
5678 min_width
= spec
['minimumwidth'] - len(fracpart
) - len(sign
)
5681 intpart
= _insert_thousands_sep(intpart
, spec
, min_width
)
5683 return _format_align(sign
, intpart
+fracpart
, spec
)
5686 ##### Useful Constants (internal use only) ################################
5689 _Infinity
= Decimal('Inf')
5690 _NegativeInfinity
= Decimal('-Inf')
5691 _NaN
= Decimal('NaN')
5694 _NegativeOne
= Decimal(-1)
5696 # _SignedInfinity[sign] is infinity w/ that sign
5697 _SignedInfinity
= (_Infinity
, _NegativeInfinity
)
5701 if __name__
== '__main__':
5703 doctest
.testmod(sys
.modules
[__name__
])