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 other
= _convert_other(other
, raiseit
=True)
2728 # if one is negative and the other is positive, it's easy
2729 if self
._sign
and not other
._sign
:
2731 if not self
._sign
and other
._sign
:
2735 # let's handle both NaN types
2736 self_nan
= self
._isnan
()
2737 other_nan
= other
._isnan
()
2738 if self_nan
or other_nan
:
2739 if self_nan
== other_nan
:
2740 # compare payloads as though they're integers
2741 self_key
= len(self
._int
), self
._int
2742 other_key
= len(other
._int
), other
._int
2743 if self_key
< other_key
:
2748 if self_key
> other_key
:
2779 if self
._exp
< other
._exp
:
2784 if self
._exp
> other
._exp
:
2792 def compare_total_mag(self
, other
):
2793 """Compares self to other using abstract repr., ignoring sign.
2795 Like compare_total, but with operand's sign ignored and assumed to be 0.
2797 other
= _convert_other(other
, raiseit
=True)
2800 o
= other
.copy_abs()
2801 return s
.compare_total(o
)
2804 """Returns a copy with the sign set to 0. """
2805 return _dec_from_triple(0, self
._int
, self
._exp
, self
._is
_special
)
2807 def copy_negate(self
):
2808 """Returns a copy with the sign inverted."""
2810 return _dec_from_triple(0, self
._int
, self
._exp
, self
._is
_special
)
2812 return _dec_from_triple(1, self
._int
, self
._exp
, self
._is
_special
)
2814 def copy_sign(self
, other
):
2815 """Returns self with the sign of other."""
2816 return _dec_from_triple(other
._sign
, self
._int
,
2817 self
._exp
, self
._is
_special
)
2819 def exp(self
, context
=None):
2820 """Returns e ** self."""
2823 context
= getcontext()
2826 ans
= self
._check
_nans
(context
=context
)
2830 # exp(-Infinity) = 0
2831 if self
._isinfinity
() == -1:
2838 # exp(Infinity) = Infinity
2839 if self
._isinfinity
() == 1:
2840 return Decimal(self
)
2842 # the result is now guaranteed to be inexact (the true
2843 # mathematical result is transcendental). There's no need to
2844 # raise Rounded and Inexact here---they'll always be raised as
2845 # a result of the call to _fix.
2847 adj
= self
.adjusted()
2849 # we only need to do any computation for quite a small range
2850 # of adjusted exponents---for example, -29 <= adj <= 10 for
2851 # the default context. For smaller exponent the result is
2852 # indistinguishable from 1 at the given precision, while for
2853 # larger exponent the result either overflows or underflows.
2854 if self
._sign
== 0 and adj
> len(str((context
.Emax
+1)*3)):
2856 ans
= _dec_from_triple(0, '1', context
.Emax
+1)
2857 elif self
._sign
== 1 and adj
> len(str((-context
.Etiny()+1)*3)):
2859 ans
= _dec_from_triple(0, '1', context
.Etiny()-1)
2860 elif self
._sign
== 0 and adj
< -p
:
2861 # p+1 digits; final round will raise correct flags
2862 ans
= _dec_from_triple(0, '1' + '0'*(p
-1) + '1', -p
)
2863 elif self
._sign
== 1 and adj
< -p
-1:
2864 # p+1 digits; final round will raise correct flags
2865 ans
= _dec_from_triple(0, '9'*(p
+1), -p
-1)
2869 c
, e
= op
.int, op
.exp
2873 # compute correctly rounded result: increase precision by
2874 # 3 digits at a time until we get an unambiguously
2878 coeff
, exp
= _dexp(c
, e
, p
+extra
)
2879 if coeff
% (5*10**(len(str(coeff
))-p
-1)):
2883 ans
= _dec_from_triple(0, str(coeff
), exp
)
2885 # at this stage, ans should round correctly with *any*
2886 # rounding mode, not just with ROUND_HALF_EVEN
2887 context
= context
._shallow
_copy
()
2888 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
2889 ans
= ans
._fix
(context
)
2890 context
.rounding
= rounding
2894 def is_canonical(self
):
2895 """Return True if self is canonical; otherwise return False.
2897 Currently, the encoding of a Decimal instance is always
2898 canonical, so this method returns True for any Decimal.
2902 def is_finite(self
):
2903 """Return True if self is finite; otherwise return False.
2905 A Decimal instance is considered finite if it is neither
2908 return not self
._is
_special
2910 def is_infinite(self
):
2911 """Return True if self is infinite; otherwise return False."""
2912 return self
._exp
== 'F'
2915 """Return True if self is a qNaN or sNaN; otherwise return False."""
2916 return self
._exp
in ('n', 'N')
2918 def is_normal(self
, context
=None):
2919 """Return True if self is a normal number; otherwise return False."""
2920 if self
._is
_special
or not self
:
2923 context
= getcontext()
2924 return context
.Emin
<= self
.adjusted()
2927 """Return True if self is a quiet NaN; otherwise return False."""
2928 return self
._exp
== 'n'
2930 def is_signed(self
):
2931 """Return True if self is negative; otherwise return False."""
2932 return self
._sign
== 1
2935 """Return True if self is a signaling NaN; otherwise return False."""
2936 return self
._exp
== 'N'
2938 def is_subnormal(self
, context
=None):
2939 """Return True if self is subnormal; otherwise return False."""
2940 if self
._is
_special
or not self
:
2943 context
= getcontext()
2944 return self
.adjusted() < context
.Emin
2947 """Return True if self is a zero; otherwise return False."""
2948 return not self
._is
_special
and self
._int
== '0'
2950 def _ln_exp_bound(self
):
2951 """Compute a lower bound for the adjusted exponent of self.ln().
2952 In other words, compute r such that self.ln() >= 10**r. Assumes
2953 that self is finite and positive and that self != 1.
2956 # for 0.1 <= x <= 10 we use the inequalities 1-1/x <= ln(x) <= x-1
2957 adj
= self
._exp
+ len(self
._int
) - 1
2959 # argument >= 10; we use 23/10 = 2.3 as a lower bound for ln(10)
2960 return len(str(adj
*23//10)) - 1
2963 return len(str((-1-adj
)*23//10)) - 1
2965 c
, e
= op
.int, op
.exp
2970 return len(num
) - len(den
) - (num
< den
)
2971 # adj == -1, 0.1 <= self < 1
2972 return e
+ len(str(10**-e
- c
)) - 1
2975 def ln(self
, context
=None):
2976 """Returns the natural (base e) logarithm of self."""
2979 context
= getcontext()
2982 ans
= self
._check
_nans
(context
=context
)
2986 # ln(0.0) == -Infinity
2988 return _NegativeInfinity
2990 # ln(Infinity) = Infinity
2991 if self
._isinfinity
() == 1:
2998 # ln(negative) raises InvalidOperation
3000 return context
._raise
_error
(InvalidOperation
,
3001 'ln of a negative value')
3003 # result is irrational, so necessarily inexact
3005 c
, e
= op
.int, op
.exp
3008 # correctly rounded result: repeatedly increase precision by 3
3009 # until we get an unambiguously roundable result
3010 places
= p
- self
._ln
_exp
_bound
() + 2 # at least p+3 places
3012 coeff
= _dlog(c
, e
, places
)
3013 # assert len(str(abs(coeff)))-p >= 1
3014 if coeff
% (5*10**(len(str(abs(coeff
)))-p
-1)):
3017 ans
= _dec_from_triple(int(coeff
<0), str(abs(coeff
)), -places
)
3019 context
= context
._shallow
_copy
()
3020 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
3021 ans
= ans
._fix
(context
)
3022 context
.rounding
= rounding
3025 def _log10_exp_bound(self
):
3026 """Compute a lower bound for the adjusted exponent of self.log10().
3027 In other words, find r such that self.log10() >= 10**r.
3028 Assumes that self is finite and positive and that self != 1.
3031 # For x >= 10 or x < 0.1 we only need a bound on the integer
3032 # part of log10(self), and this comes directly from the
3033 # exponent of x. For 0.1 <= x <= 10 we use the inequalities
3034 # 1-1/x <= log(x) <= x-1. If x > 1 we have |log10(x)| >
3035 # (1-1/x)/2.31 > 0. If x < 1 then |log10(x)| > (1-x)/2.31 > 0
3037 adj
= self
._exp
+ len(self
._int
) - 1
3040 return len(str(adj
))-1
3043 return len(str(-1-adj
))-1
3045 c
, e
= op
.int, op
.exp
3050 return len(num
) - len(den
) - (num
< den
) + 2
3051 # adj == -1, 0.1 <= self < 1
3053 return len(num
) + e
- (num
< "231") - 1
3055 def log10(self
, context
=None):
3056 """Returns the base 10 logarithm of self."""
3059 context
= getcontext()
3062 ans
= self
._check
_nans
(context
=context
)
3066 # log10(0.0) == -Infinity
3068 return _NegativeInfinity
3070 # log10(Infinity) = Infinity
3071 if self
._isinfinity
() == 1:
3074 # log10(negative or -Infinity) raises InvalidOperation
3076 return context
._raise
_error
(InvalidOperation
,
3077 'log10 of a negative value')
3080 if self
._int
[0] == '1' and self
._int
[1:] == '0'*(len(self
._int
) - 1):
3081 # answer may need rounding
3082 ans
= Decimal(self
._exp
+ len(self
._int
) - 1)
3084 # result is irrational, so necessarily inexact
3086 c
, e
= op
.int, op
.exp
3089 # correctly rounded result: repeatedly increase precision
3090 # until result is unambiguously roundable
3091 places
= p
-self
._log
10_exp
_bound
()+2
3093 coeff
= _dlog10(c
, e
, places
)
3094 # assert len(str(abs(coeff)))-p >= 1
3095 if coeff
% (5*10**(len(str(abs(coeff
)))-p
-1)):
3098 ans
= _dec_from_triple(int(coeff
<0), str(abs(coeff
)), -places
)
3100 context
= context
._shallow
_copy
()
3101 rounding
= context
._set
_rounding
(ROUND_HALF_EVEN
)
3102 ans
= ans
._fix
(context
)
3103 context
.rounding
= rounding
3106 def logb(self
, context
=None):
3107 """ Returns the exponent of the magnitude of self's MSD.
3109 The result is the integer which is the exponent of the magnitude
3110 of the most significant digit of self (as though it were truncated
3111 to a single digit while maintaining the value of that digit and
3112 without limiting the resulting exponent).
3115 ans
= self
._check
_nans
(context
=context
)
3120 context
= getcontext()
3122 # logb(+/-Inf) = +Inf
3123 if self
._isinfinity
():
3126 # logb(0) = -Inf, DivisionByZero
3128 return context
._raise
_error
(DivisionByZero
, 'logb(0)', 1)
3130 # otherwise, simply return the adjusted exponent of self, as a
3131 # Decimal. Note that no attempt is made to fit the result
3132 # into the current context.
3133 ans
= Decimal(self
.adjusted())
3134 return ans
._fix
(context
)
3136 def _islogical(self
):
3137 """Return True if self is a logical operand.
3139 For being logical, it must be a finite number with a sign of 0,
3140 an exponent of 0, and a coefficient whose digits must all be
3143 if self
._sign
!= 0 or self
._exp
!= 0:
3145 for dig
in self
._int
:
3150 def _fill_logical(self
, context
, opa
, opb
):
3151 dif
= context
.prec
- len(opa
)
3155 opa
= opa
[-context
.prec
:]
3156 dif
= context
.prec
- len(opb
)
3160 opb
= opb
[-context
.prec
:]
3163 def logical_and(self
, other
, context
=None):
3164 """Applies an 'and' operation between self and other's digits."""
3166 context
= getcontext()
3168 other
= _convert_other(other
, raiseit
=True)
3170 if not self
._islogical
() or not other
._islogical
():
3171 return context
._raise
_error
(InvalidOperation
)
3173 # fill to context.prec
3174 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3176 # make the operation, and clean starting zeroes
3177 result
= "".join([str(int(a
)&int(b
)) for a
,b
in zip(opa
,opb
)])
3178 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3180 def logical_invert(self
, context
=None):
3181 """Invert all its digits."""
3183 context
= getcontext()
3184 return self
.logical_xor(_dec_from_triple(0,'1'*context
.prec
,0),
3187 def logical_or(self
, other
, context
=None):
3188 """Applies an 'or' operation between self and other's digits."""
3190 context
= getcontext()
3192 other
= _convert_other(other
, raiseit
=True)
3194 if not self
._islogical
() or not other
._islogical
():
3195 return context
._raise
_error
(InvalidOperation
)
3197 # fill to context.prec
3198 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3200 # make the operation, and clean starting zeroes
3201 result
= "".join([str(int(a
)|
int(b
)) for a
,b
in zip(opa
,opb
)])
3202 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3204 def logical_xor(self
, other
, context
=None):
3205 """Applies an 'xor' operation between self and other's digits."""
3207 context
= getcontext()
3209 other
= _convert_other(other
, raiseit
=True)
3211 if not self
._islogical
() or not other
._islogical
():
3212 return context
._raise
_error
(InvalidOperation
)
3214 # fill to context.prec
3215 (opa
, opb
) = self
._fill
_logical
(context
, self
._int
, other
._int
)
3217 # make the operation, and clean starting zeroes
3218 result
= "".join([str(int(a
)^
int(b
)) for a
,b
in zip(opa
,opb
)])
3219 return _dec_from_triple(0, result
.lstrip('0') or '0', 0)
3221 def max_mag(self
, other
, context
=None):
3222 """Compares the values numerically with their sign ignored."""
3223 other
= _convert_other(other
, raiseit
=True)
3226 context
= getcontext()
3228 if self
._is
_special
or other
._is
_special
:
3229 # If one operand is a quiet NaN and the other is number, then the
3230 # number is always returned
3234 if on
== 1 and sn
== 0:
3235 return self
._fix
(context
)
3236 if sn
== 1 and on
== 0:
3237 return other
._fix
(context
)
3238 return self
._check
_nans
(other
, context
)
3240 c
= self
.copy_abs()._cmp
(other
.copy_abs())
3242 c
= self
.compare_total(other
)
3249 return ans
._fix
(context
)
3251 def min_mag(self
, other
, context
=None):
3252 """Compares the values numerically with their sign ignored."""
3253 other
= _convert_other(other
, raiseit
=True)
3256 context
= getcontext()
3258 if self
._is
_special
or other
._is
_special
:
3259 # If one operand is a quiet NaN and the other is number, then the
3260 # number is always returned
3264 if on
== 1 and sn
== 0:
3265 return self
._fix
(context
)
3266 if sn
== 1 and on
== 0:
3267 return other
._fix
(context
)
3268 return self
._check
_nans
(other
, context
)
3270 c
= self
.copy_abs()._cmp
(other
.copy_abs())
3272 c
= self
.compare_total(other
)
3279 return ans
._fix
(context
)
3281 def next_minus(self
, context
=None):
3282 """Returns the largest representable number smaller than itself."""
3284 context
= getcontext()
3286 ans
= self
._check
_nans
(context
=context
)
3290 if self
._isinfinity
() == -1:
3291 return _NegativeInfinity
3292 if self
._isinfinity
() == 1:
3293 return _dec_from_triple(0, '9'*context
.prec
, context
.Etop())
3295 context
= context
.copy()
3296 context
._set
_rounding
(ROUND_FLOOR
)
3297 context
._ignore
_all
_flags
()
3298 new_self
= self
._fix
(context
)
3299 if new_self
!= self
:
3301 return self
.__sub
__(_dec_from_triple(0, '1', context
.Etiny()-1),
3304 def next_plus(self
, context
=None):
3305 """Returns the smallest representable number larger than itself."""
3307 context
= getcontext()
3309 ans
= self
._check
_nans
(context
=context
)
3313 if self
._isinfinity
() == 1:
3315 if self
._isinfinity
() == -1:
3316 return _dec_from_triple(1, '9'*context
.prec
, context
.Etop())
3318 context
= context
.copy()
3319 context
._set
_rounding
(ROUND_CEILING
)
3320 context
._ignore
_all
_flags
()
3321 new_self
= self
._fix
(context
)
3322 if new_self
!= self
:
3324 return self
.__add
__(_dec_from_triple(0, '1', context
.Etiny()-1),
3327 def next_toward(self
, other
, context
=None):
3328 """Returns the number closest to self, in the direction towards other.
3330 The result is the closest representable number to self
3331 (excluding self) that is in the direction towards other,
3332 unless both have the same value. If the two operands are
3333 numerically equal, then the result is a copy of self with the
3334 sign set to be the same as the sign of other.
3336 other
= _convert_other(other
, raiseit
=True)
3339 context
= getcontext()
3341 ans
= self
._check
_nans
(other
, context
)
3345 comparison
= self
._cmp
(other
)
3347 return self
.copy_sign(other
)
3349 if comparison
== -1:
3350 ans
= self
.next_plus(context
)
3351 else: # comparison == 1
3352 ans
= self
.next_minus(context
)
3354 # decide which flags to raise using value of ans
3355 if ans
._isinfinity
():
3356 context
._raise
_error
(Overflow
,
3357 'Infinite result from next_toward',
3359 context
._raise
_error
(Rounded
)
3360 context
._raise
_error
(Inexact
)
3361 elif ans
.adjusted() < context
.Emin
:
3362 context
._raise
_error
(Underflow
)
3363 context
._raise
_error
(Subnormal
)
3364 context
._raise
_error
(Rounded
)
3365 context
._raise
_error
(Inexact
)
3366 # if precision == 1 then we don't raise Clamped for a
3369 context
._raise
_error
(Clamped
)
3373 def number_class(self
, context
=None):
3374 """Returns an indication of the class of self.
3376 The class is one of the following strings:
3392 inf
= self
._isinfinity
()
3403 context
= getcontext()
3404 if self
.is_subnormal(context
=context
):
3409 # just a normal, regular, boring number, :)
3416 """Just returns 10, as this is Decimal, :)"""
3419 def rotate(self
, other
, context
=None):
3420 """Returns a rotated copy of self, value-of-other times."""
3422 context
= getcontext()
3424 other
= _convert_other(other
, raiseit
=True)
3426 ans
= self
._check
_nans
(other
, context
)
3431 return context
._raise
_error
(InvalidOperation
)
3432 if not (-context
.prec
<= int(other
) <= context
.prec
):
3433 return context
._raise
_error
(InvalidOperation
)
3435 if self
._isinfinity
():
3436 return Decimal(self
)
3438 # get values, pad if necessary
3441 topad
= context
.prec
- len(rotdig
)
3443 rotdig
= '0'*topad
+ rotdig
3445 rotdig
= rotdig
[-topad
:]
3448 rotated
= rotdig
[torot
:] + rotdig
[:torot
]
3449 return _dec_from_triple(self
._sign
,
3450 rotated
.lstrip('0') or '0', self
._exp
)
3452 def scaleb(self
, other
, context
=None):
3453 """Returns self operand after adding the second value to its exp."""
3455 context
= getcontext()
3457 other
= _convert_other(other
, raiseit
=True)
3459 ans
= self
._check
_nans
(other
, context
)
3464 return context
._raise
_error
(InvalidOperation
)
3465 liminf
= -2 * (context
.Emax
+ context
.prec
)
3466 limsup
= 2 * (context
.Emax
+ context
.prec
)
3467 if not (liminf
<= int(other
) <= limsup
):
3468 return context
._raise
_error
(InvalidOperation
)
3470 if self
._isinfinity
():
3471 return Decimal(self
)
3473 d
= _dec_from_triple(self
._sign
, self
._int
, self
._exp
+ int(other
))
3477 def shift(self
, other
, context
=None):
3478 """Returns a shifted copy of self, value-of-other times."""
3480 context
= getcontext()
3482 other
= _convert_other(other
, raiseit
=True)
3484 ans
= self
._check
_nans
(other
, context
)
3489 return context
._raise
_error
(InvalidOperation
)
3490 if not (-context
.prec
<= int(other
) <= context
.prec
):
3491 return context
._raise
_error
(InvalidOperation
)
3493 if self
._isinfinity
():
3494 return Decimal(self
)
3496 # get values, pad if necessary
3499 topad
= context
.prec
- len(rotdig
)
3501 rotdig
= '0'*topad
+ rotdig
3503 rotdig
= rotdig
[-topad
:]
3507 shifted
= rotdig
[:torot
]
3509 shifted
= rotdig
+ '0'*torot
3510 shifted
= shifted
[-context
.prec
:]
3512 return _dec_from_triple(self
._sign
,
3513 shifted
.lstrip('0') or '0', self
._exp
)
3515 # Support for pickling, copy, and deepcopy
3516 def __reduce__(self
):
3517 return (self
.__class
__, (str(self
),))
3520 if type(self
) == Decimal
:
3521 return self
# I'm immutable; therefore I am my own clone
3522 return self
.__class
__(str(self
))
3524 def __deepcopy__(self
, memo
):
3525 if type(self
) == Decimal
:
3526 return self
# My components are also immutable
3527 return self
.__class
__(str(self
))
3529 # PEP 3101 support. the _localeconv keyword argument should be
3530 # considered private: it's provided for ease of testing only.
3531 def __format__(self
, specifier
, context
=None, _localeconv
=None):
3532 """Format a Decimal instance according to the given specifier.
3534 The specifier should be a standard format specifier, with the
3535 form described in PEP 3101. Formatting types 'e', 'E', 'f',
3536 'F', 'g', 'G', 'n' and '%' are supported. If the formatting
3537 type is omitted it defaults to 'g' or 'G', depending on the
3538 value of context.capitals.
3541 # Note: PEP 3101 says that if the type is not present then
3542 # there should be at least one digit after the decimal point.
3543 # We take the liberty of ignoring this requirement for
3544 # Decimal---it's presumably there to make sure that
3545 # format(float, '') behaves similarly to str(float).
3547 context
= getcontext()
3549 spec
= _parse_format_specifier(specifier
, _localeconv
=_localeconv
)
3551 # special values don't care about the type or precision
3552 if self
._is
_special
:
3553 sign
= _format_sign(self
._sign
, spec
)
3554 body
= str(self
.copy_abs())
3555 return _format_align(sign
, body
, spec
)
3557 # a type of None defaults to 'g' or 'G', depending on context
3558 if spec
['type'] is None:
3559 spec
['type'] = ['g', 'G'][context
.capitals
]
3561 # if type is '%', adjust exponent of self accordingly
3562 if spec
['type'] == '%':
3563 self
= _dec_from_triple(self
._sign
, self
._int
, self
._exp
+2)
3565 # round if necessary, taking rounding mode from the context
3566 rounding
= context
.rounding
3567 precision
= spec
['precision']
3568 if precision
is not None:
3569 if spec
['type'] in 'eE':
3570 self
= self
._round
(precision
+1, rounding
)
3571 elif spec
['type'] in 'fF%':
3572 self
= self
._rescale
(-precision
, rounding
)
3573 elif spec
['type'] in 'gG' and len(self
._int
) > precision
:
3574 self
= self
._round
(precision
, rounding
)
3575 # special case: zeros with a positive exponent can't be
3576 # represented in fixed point; rescale them to 0e0.
3577 if not self
and self
._exp
> 0 and spec
['type'] in 'fF%':
3578 self
= self
._rescale
(0, rounding
)
3580 # figure out placement of the decimal point
3581 leftdigits
= self
._exp
+ len(self
._int
)
3582 if spec
['type'] in 'eE':
3583 if not self
and precision
is not None:
3584 dotplace
= 1 - precision
3587 elif spec
['type'] in 'fF%':
3588 dotplace
= leftdigits
3589 elif spec
['type'] in 'gG':
3590 if self
._exp
<= 0 and leftdigits
> -6:
3591 dotplace
= leftdigits
3595 # find digits before and after decimal point, and get exponent
3598 fracpart
= '0'*(-dotplace
) + self
._int
3599 elif dotplace
> len(self
._int
):
3600 intpart
= self
._int
+ '0'*(dotplace
-len(self
._int
))
3603 intpart
= self
._int
[:dotplace
] or '0'
3604 fracpart
= self
._int
[dotplace
:]
3605 exp
= leftdigits
-dotplace
3607 # done with the decimal-specific stuff; hand over the rest
3608 # of the formatting to the _format_number function
3609 return _format_number(self
._sign
, intpart
, fracpart
, exp
, spec
)
3611 def _dec_from_triple(sign
, coefficient
, exponent
, special
=False):
3612 """Create a decimal instance directly, without any validation,
3613 normalization (e.g. removal of leading zeros) or argument
3616 This function is for *internal use only*.
3619 self
= object.__new
__(Decimal
)
3621 self
._int
= coefficient
3622 self
._exp
= exponent
3623 self
._is
_special
= special
3627 # Register Decimal as a kind of Number (an abstract base class).
3628 # However, do not register it as Real (because Decimals are not
3629 # interoperable with floats).
3630 _numbers
.Number
.register(Decimal
)
3633 ##### Context class #######################################################
3636 # get rounding method function:
3637 rounding_functions
= [name
for name
in Decimal
.__dict
__.keys()
3638 if name
.startswith('_round_')]
3639 for name
in rounding_functions
:
3640 # name is like _round_half_even, goes to the global ROUND_HALF_EVEN value.
3641 globalname
= name
[1:].upper()
3642 val
= globals()[globalname
]
3643 Decimal
._pick
_rounding
_function
[val
] = name
3645 del name
, val
, globalname
, rounding_functions
3647 class _ContextManager(object):
3648 """Context manager class to support localcontext().
3650 Sets a copy of the supplied context in __enter__() and restores
3651 the previous decimal context in __exit__()
3653 def __init__(self
, new_context
):
3654 self
.new_context
= new_context
.copy()
3655 def __enter__(self
):
3656 self
.saved_context
= getcontext()
3657 setcontext(self
.new_context
)
3658 return self
.new_context
3659 def __exit__(self
, t
, v
, tb
):
3660 setcontext(self
.saved_context
)
3662 class Context(object):
3663 """Contains the context for a Decimal instance.
3666 prec - precision (for use in rounding, division, square roots..)
3667 rounding - rounding type (how you round)
3668 traps - If traps[exception] = 1, then the exception is
3669 raised when it is caused. Otherwise, a value is
3671 flags - When an exception is caused, flags[exception] is set.
3672 (Whether or not the trap_enabler is set)
3673 Should be reset by user of Decimal instance.
3674 Emin - Minimum exponent
3675 Emax - Maximum exponent
3676 capitals - If 1, 1*10^1 is printed as 1E+1.
3677 If 0, printed as 1e1
3678 _clamp - If 1, change exponents if too high (Default 0)
3681 def __init__(self
, prec
=None, rounding
=None,
3682 traps
=None, flags
=None,
3683 Emin
=None, Emax
=None,
3684 capitals
=None, _clamp
=0,
3685 _ignored_flags
=None):
3688 if _ignored_flags
is None:
3690 if not isinstance(flags
, dict):
3691 flags
= dict([(s
, int(s
in flags
)) for s
in _signals
])
3693 if traps
is not None and not isinstance(traps
, dict):
3694 traps
= dict([(s
, int(s
in traps
)) for s
in _signals
])
3696 for name
, val
in locals().items():
3698 setattr(self
, name
, _copy
.copy(getattr(DefaultContext
, name
)))
3700 setattr(self
, name
, val
)
3704 """Show the current context."""
3706 s
.append('Context(prec=%(prec)d, rounding=%(rounding)s, '
3707 'Emin=%(Emin)d, Emax=%(Emax)d, capitals=%(capitals)d'
3709 names
= [f
.__name
__ for f
, v
in self
.flags
.items() if v
]
3710 s
.append('flags=[' + ', '.join(names
) + ']')
3711 names
= [t
.__name
__ for t
, v
in self
.traps
.items() if v
]
3712 s
.append('traps=[' + ', '.join(names
) + ']')
3713 return ', '.join(s
) + ')'
3715 def clear_flags(self
):
3716 """Reset all flags to zero"""
3717 for flag
in self
.flags
:
3718 self
.flags
[flag
] = 0
3720 def _shallow_copy(self
):
3721 """Returns a shallow copy from self."""
3722 nc
= Context(self
.prec
, self
.rounding
, self
.traps
,
3723 self
.flags
, self
.Emin
, self
.Emax
,
3724 self
.capitals
, self
._clamp
, self
._ignored
_flags
)
3728 """Returns a deep copy from self."""
3729 nc
= Context(self
.prec
, self
.rounding
, self
.traps
.copy(),
3730 self
.flags
.copy(), self
.Emin
, self
.Emax
,
3731 self
.capitals
, self
._clamp
, self
._ignored
_flags
)
3735 def _raise_error(self
, condition
, explanation
= None, *args
):
3738 If the flag is in _ignored_flags, returns the default response.
3739 Otherwise, it sets the flag, then, if the corresponding
3740 trap_enabler is set, it reaises the exception. Otherwise, it returns
3741 the default value after setting the flag.
3743 error
= _condition_map
.get(condition
, condition
)
3744 if error
in self
._ignored
_flags
:
3745 # Don't touch the flag
3746 return error().handle(self
, *args
)
3748 self
.flags
[error
] = 1
3749 if not self
.traps
[error
]:
3750 # The errors define how to handle themselves.
3751 return condition().handle(self
, *args
)
3753 # Errors should only be risked on copies of the context
3754 # self._ignored_flags = []
3755 raise error(explanation
)
3757 def _ignore_all_flags(self
):
3758 """Ignore all flags, if they are raised"""
3759 return self
._ignore
_flags
(*_signals
)
3761 def _ignore_flags(self
, *flags
):
3762 """Ignore the flags, if they are raised"""
3763 # Do not mutate-- This way, copies of a context leave the original
3765 self
._ignored
_flags
= (self
._ignored
_flags
+ list(flags
))
3768 def _regard_flags(self
, *flags
):
3769 """Stop ignoring the flags, if they are raised"""
3770 if flags
and isinstance(flags
[0], (tuple,list)):
3773 self
._ignored
_flags
.remove(flag
)
3775 # We inherit object.__hash__, so we must deny this explicitly
3779 """Returns Etiny (= Emin - prec + 1)"""
3780 return int(self
.Emin
- self
.prec
+ 1)
3783 """Returns maximum exponent (= Emax - prec + 1)"""
3784 return int(self
.Emax
- self
.prec
+ 1)
3786 def _set_rounding(self
, type):
3787 """Sets the rounding type.
3789 Sets the rounding type, and returns the current (previous)
3790 rounding type. Often used like:
3792 context = context.copy()
3793 # so you don't change the calling context
3794 # if an error occurs in the middle.
3795 rounding = context._set_rounding(ROUND_UP)
3796 val = self.__sub__(other, context=context)
3797 context._set_rounding(rounding)
3799 This will make it round up for that operation.
3801 rounding
= self
.rounding
3805 def create_decimal(self
, num
='0'):
3806 """Creates a new Decimal instance but using self as context.
3808 This method implements the to-number operation of the
3809 IBM Decimal specification."""
3811 if isinstance(num
, basestring
) and num
!= num
.strip():
3812 return self
._raise
_error
(ConversionSyntax
,
3813 "no trailing or leading whitespace is "
3816 d
= Decimal(num
, context
=self
)
3817 if d
._isnan
() and len(d
._int
) > self
.prec
- self
._clamp
:
3818 return self
._raise
_error
(ConversionSyntax
,
3819 "diagnostic info too long in NaN")
3822 def create_decimal_from_float(self
, f
):
3823 """Creates a new Decimal instance from a float but rounding using self
3826 >>> context = Context(prec=5, rounding=ROUND_DOWN)
3827 >>> context.create_decimal_from_float(3.1415926535897932)
3829 >>> context = Context(prec=5, traps=[Inexact])
3830 >>> context.create_decimal_from_float(3.1415926535897932)
3831 Traceback (most recent call last):
3836 d
= Decimal
.from_float(f
) # An exact conversion
3837 return d
._fix
(self
) # Apply the context rounding
3841 """Returns the absolute value of the operand.
3843 If the operand is negative, the result is the same as using the minus
3844 operation on the operand. Otherwise, the result is the same as using
3845 the plus operation on the operand.
3847 >>> ExtendedContext.abs(Decimal('2.1'))
3849 >>> ExtendedContext.abs(Decimal('-100'))
3851 >>> ExtendedContext.abs(Decimal('101.5'))
3853 >>> ExtendedContext.abs(Decimal('-101.5'))
3856 return a
.__abs
__(context
=self
)
3858 def add(self
, a
, b
):
3859 """Return the sum of the two operands.
3861 >>> ExtendedContext.add(Decimal('12'), Decimal('7.00'))
3863 >>> ExtendedContext.add(Decimal('1E+2'), Decimal('1.01E+4'))
3866 return a
.__add
__(b
, context
=self
)
3868 def _apply(self
, a
):
3869 return str(a
._fix
(self
))
3871 def canonical(self
, a
):
3872 """Returns the same Decimal object.
3874 As we do not have different encodings for the same number, the
3875 received object already is in its canonical form.
3877 >>> ExtendedContext.canonical(Decimal('2.50'))
3880 return a
.canonical(context
=self
)
3882 def compare(self
, a
, b
):
3883 """Compares values numerically.
3885 If the signs of the operands differ, a value representing each operand
3886 ('-1' if the operand is less than zero, '0' if the operand is zero or
3887 negative zero, or '1' if the operand is greater than zero) is used in
3888 place of that operand for the comparison instead of the actual
3891 The comparison is then effected by subtracting the second operand from
3892 the first and then returning a value according to the result of the
3893 subtraction: '-1' if the result is less than zero, '0' if the result is
3894 zero or negative zero, or '1' if the result is greater than zero.
3896 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
3898 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
3900 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))
3902 >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))
3904 >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))
3906 >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))
3909 return a
.compare(b
, context
=self
)
3911 def compare_signal(self
, a
, b
):
3912 """Compares the values of the two operands numerically.
3914 It's pretty much like compare(), but all NaNs signal, with signaling
3915 NaNs taking precedence over quiet NaNs.
3917 >>> c = ExtendedContext
3918 >>> c.compare_signal(Decimal('2.1'), Decimal('3'))
3920 >>> c.compare_signal(Decimal('2.1'), Decimal('2.1'))
3922 >>> c.flags[InvalidOperation] = 0
3923 >>> print c.flags[InvalidOperation]
3925 >>> c.compare_signal(Decimal('NaN'), Decimal('2.1'))
3927 >>> print c.flags[InvalidOperation]
3929 >>> c.flags[InvalidOperation] = 0
3930 >>> print c.flags[InvalidOperation]
3932 >>> c.compare_signal(Decimal('sNaN'), Decimal('2.1'))
3934 >>> print c.flags[InvalidOperation]
3937 return a
.compare_signal(b
, context
=self
)
3939 def compare_total(self
, a
, b
):
3940 """Compares two operands using their abstract representation.
3942 This is not like the standard compare, which use their numerical
3943 value. Note that a total ordering is defined for all possible abstract
3946 >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
3948 >>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12'))
3950 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))
3952 >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))
3954 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300'))
3956 >>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN'))
3959 return a
.compare_total(b
)
3961 def compare_total_mag(self
, a
, b
):
3962 """Compares two operands using their abstract representation ignoring sign.
3964 Like compare_total, but with operand's sign ignored and assumed to be 0.
3966 return a
.compare_total_mag(b
)
3968 def copy_abs(self
, a
):
3969 """Returns a copy of the operand with the sign set to 0.
3971 >>> ExtendedContext.copy_abs(Decimal('2.1'))
3973 >>> ExtendedContext.copy_abs(Decimal('-100'))
3978 def copy_decimal(self
, a
):
3979 """Returns a copy of the decimal objet.
3981 >>> ExtendedContext.copy_decimal(Decimal('2.1'))
3983 >>> ExtendedContext.copy_decimal(Decimal('-1.00'))
3988 def copy_negate(self
, a
):
3989 """Returns a copy of the operand with the sign inverted.
3991 >>> ExtendedContext.copy_negate(Decimal('101.5'))
3993 >>> ExtendedContext.copy_negate(Decimal('-101.5'))
3996 return a
.copy_negate()
3998 def copy_sign(self
, a
, b
):
3999 """Copies the second operand's sign to the first one.
4001 In detail, it returns a copy of the first operand with the sign
4002 equal to the sign of the second operand.
4004 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))
4006 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))
4008 >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))
4010 >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))
4013 return a
.copy_sign(b
)
4015 def divide(self
, a
, b
):
4016 """Decimal division in a specified context.
4018 >>> ExtendedContext.divide(Decimal('1'), Decimal('3'))
4019 Decimal('0.333333333')
4020 >>> ExtendedContext.divide(Decimal('2'), Decimal('3'))
4021 Decimal('0.666666667')
4022 >>> ExtendedContext.divide(Decimal('5'), Decimal('2'))
4024 >>> ExtendedContext.divide(Decimal('1'), Decimal('10'))
4026 >>> ExtendedContext.divide(Decimal('12'), Decimal('12'))
4028 >>> ExtendedContext.divide(Decimal('8.00'), Decimal('2'))
4030 >>> ExtendedContext.divide(Decimal('2.400'), Decimal('2.0'))
4032 >>> ExtendedContext.divide(Decimal('1000'), Decimal('100'))
4034 >>> ExtendedContext.divide(Decimal('1000'), Decimal('1'))
4036 >>> ExtendedContext.divide(Decimal('2.40E+6'), Decimal('2'))
4039 return a
.__div
__(b
, context
=self
)
4041 def divide_int(self
, a
, b
):
4042 """Divides two numbers and returns the integer part of the result.
4044 >>> ExtendedContext.divide_int(Decimal('2'), Decimal('3'))
4046 >>> ExtendedContext.divide_int(Decimal('10'), Decimal('3'))
4048 >>> ExtendedContext.divide_int(Decimal('1'), Decimal('0.3'))
4051 return a
.__floordiv
__(b
, context
=self
)
4053 def divmod(self
, a
, b
):
4054 return a
.__divmod
__(b
, context
=self
)
4059 >>> c = ExtendedContext.copy()
4062 >>> c.exp(Decimal('-Infinity'))
4064 >>> c.exp(Decimal('-1'))
4065 Decimal('0.367879441')
4066 >>> c.exp(Decimal('0'))
4068 >>> c.exp(Decimal('1'))
4069 Decimal('2.71828183')
4070 >>> c.exp(Decimal('0.693147181'))
4071 Decimal('2.00000000')
4072 >>> c.exp(Decimal('+Infinity'))
4075 return a
.exp(context
=self
)
4077 def fma(self
, a
, b
, c
):
4078 """Returns a multiplied by b, plus c.
4080 The first two operands are multiplied together, using multiply,
4081 the third operand is then added to the result of that
4082 multiplication, using add, all with only one final rounding.
4084 >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
4086 >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))
4088 >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578'))
4089 Decimal('1.38435736E+12')
4091 return a
.fma(b
, c
, context
=self
)
4093 def is_canonical(self
, a
):
4094 """Return True if the operand is canonical; otherwise return False.
4096 Currently, the encoding of a Decimal instance is always
4097 canonical, so this method returns True for any Decimal.
4099 >>> ExtendedContext.is_canonical(Decimal('2.50'))
4102 return a
.is_canonical()
4104 def is_finite(self
, a
):
4105 """Return True if the operand is finite; otherwise return False.
4107 A Decimal instance is considered finite if it is neither
4110 >>> ExtendedContext.is_finite(Decimal('2.50'))
4112 >>> ExtendedContext.is_finite(Decimal('-0.3'))
4114 >>> ExtendedContext.is_finite(Decimal('0'))
4116 >>> ExtendedContext.is_finite(Decimal('Inf'))
4118 >>> ExtendedContext.is_finite(Decimal('NaN'))
4121 return a
.is_finite()
4123 def is_infinite(self
, a
):
4124 """Return True if the operand is infinite; otherwise return False.
4126 >>> ExtendedContext.is_infinite(Decimal('2.50'))
4128 >>> ExtendedContext.is_infinite(Decimal('-Inf'))
4130 >>> ExtendedContext.is_infinite(Decimal('NaN'))
4133 return a
.is_infinite()
4135 def is_nan(self
, a
):
4136 """Return True if the operand is a qNaN or sNaN;
4137 otherwise return False.
4139 >>> ExtendedContext.is_nan(Decimal('2.50'))
4141 >>> ExtendedContext.is_nan(Decimal('NaN'))
4143 >>> ExtendedContext.is_nan(Decimal('-sNaN'))
4148 def is_normal(self
, a
):
4149 """Return True if the operand is a normal number;
4150 otherwise return False.
4152 >>> c = ExtendedContext.copy()
4155 >>> c.is_normal(Decimal('2.50'))
4157 >>> c.is_normal(Decimal('0.1E-999'))
4159 >>> c.is_normal(Decimal('0.00'))
4161 >>> c.is_normal(Decimal('-Inf'))
4163 >>> c.is_normal(Decimal('NaN'))
4166 return a
.is_normal(context
=self
)
4168 def is_qnan(self
, a
):
4169 """Return True if the operand is a quiet NaN; otherwise return False.
4171 >>> ExtendedContext.is_qnan(Decimal('2.50'))
4173 >>> ExtendedContext.is_qnan(Decimal('NaN'))
4175 >>> ExtendedContext.is_qnan(Decimal('sNaN'))
4180 def is_signed(self
, a
):
4181 """Return True if the operand is negative; otherwise return False.
4183 >>> ExtendedContext.is_signed(Decimal('2.50'))
4185 >>> ExtendedContext.is_signed(Decimal('-12'))
4187 >>> ExtendedContext.is_signed(Decimal('-0'))
4190 return a
.is_signed()
4192 def is_snan(self
, a
):
4193 """Return True if the operand is a signaling NaN;
4194 otherwise return False.
4196 >>> ExtendedContext.is_snan(Decimal('2.50'))
4198 >>> ExtendedContext.is_snan(Decimal('NaN'))
4200 >>> ExtendedContext.is_snan(Decimal('sNaN'))
4205 def is_subnormal(self
, a
):
4206 """Return True if the operand is subnormal; otherwise return False.
4208 >>> c = ExtendedContext.copy()
4211 >>> c.is_subnormal(Decimal('2.50'))
4213 >>> c.is_subnormal(Decimal('0.1E-999'))
4215 >>> c.is_subnormal(Decimal('0.00'))
4217 >>> c.is_subnormal(Decimal('-Inf'))
4219 >>> c.is_subnormal(Decimal('NaN'))
4222 return a
.is_subnormal(context
=self
)
4224 def is_zero(self
, a
):
4225 """Return True if the operand is a zero; otherwise return False.
4227 >>> ExtendedContext.is_zero(Decimal('0'))
4229 >>> ExtendedContext.is_zero(Decimal('2.50'))
4231 >>> ExtendedContext.is_zero(Decimal('-0E+2'))
4237 """Returns the natural (base e) logarithm of the operand.
4239 >>> c = ExtendedContext.copy()
4242 >>> c.ln(Decimal('0'))
4243 Decimal('-Infinity')
4244 >>> c.ln(Decimal('1.000'))
4246 >>> c.ln(Decimal('2.71828183'))
4247 Decimal('1.00000000')
4248 >>> c.ln(Decimal('10'))
4249 Decimal('2.30258509')
4250 >>> c.ln(Decimal('+Infinity'))
4253 return a
.ln(context
=self
)
4256 """Returns the base 10 logarithm of the operand.
4258 >>> c = ExtendedContext.copy()
4261 >>> c.log10(Decimal('0'))
4262 Decimal('-Infinity')
4263 >>> c.log10(Decimal('0.001'))
4265 >>> c.log10(Decimal('1.000'))
4267 >>> c.log10(Decimal('2'))
4268 Decimal('0.301029996')
4269 >>> c.log10(Decimal('10'))
4271 >>> c.log10(Decimal('70'))
4272 Decimal('1.84509804')
4273 >>> c.log10(Decimal('+Infinity'))
4276 return a
.log10(context
=self
)
4279 """ Returns the exponent of the magnitude of the operand's MSD.
4281 The result is the integer which is the exponent of the magnitude
4282 of the most significant digit of the operand (as though the
4283 operand were truncated to a single digit while maintaining the
4284 value of that digit and without limiting the resulting exponent).
4286 >>> ExtendedContext.logb(Decimal('250'))
4288 >>> ExtendedContext.logb(Decimal('2.50'))
4290 >>> ExtendedContext.logb(Decimal('0.03'))
4292 >>> ExtendedContext.logb(Decimal('0'))
4293 Decimal('-Infinity')
4295 return a
.logb(context
=self
)
4297 def logical_and(self
, a
, b
):
4298 """Applies the logical operation 'and' between each operand's digits.
4300 The operands must be both logical numbers.
4302 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))
4304 >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))
4306 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))
4308 >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))
4310 >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))
4312 >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))
4315 return a
.logical_and(b
, context
=self
)
4317 def logical_invert(self
, a
):
4318 """Invert all the digits in the operand.
4320 The operand must be a logical number.
4322 >>> ExtendedContext.logical_invert(Decimal('0'))
4323 Decimal('111111111')
4324 >>> ExtendedContext.logical_invert(Decimal('1'))
4325 Decimal('111111110')
4326 >>> ExtendedContext.logical_invert(Decimal('111111111'))
4328 >>> ExtendedContext.logical_invert(Decimal('101010101'))
4331 return a
.logical_invert(context
=self
)
4333 def logical_or(self
, a
, b
):
4334 """Applies the logical operation 'or' between each operand's digits.
4336 The operands must be both logical numbers.
4338 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))
4340 >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))
4342 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))
4344 >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))
4346 >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))
4348 >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))
4351 return a
.logical_or(b
, context
=self
)
4353 def logical_xor(self
, a
, b
):
4354 """Applies the logical operation 'xor' between each operand's digits.
4356 The operands must be both logical numbers.
4358 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))
4360 >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))
4362 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))
4364 >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))
4366 >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))
4368 >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))
4371 return a
.logical_xor(b
, context
=self
)
4374 """max compares two values numerically and returns the maximum.
4376 If either operand is a NaN then the general rules apply.
4377 Otherwise, the operands are compared as though by the compare
4378 operation. If they are numerically equal then the left-hand operand
4379 is chosen as the result. Otherwise the maximum (closer to positive
4380 infinity) of the two operands is chosen as the result.
4382 >>> ExtendedContext.max(Decimal('3'), Decimal('2'))
4384 >>> ExtendedContext.max(Decimal('-10'), Decimal('3'))
4386 >>> ExtendedContext.max(Decimal('1.0'), Decimal('1'))
4388 >>> ExtendedContext.max(Decimal('7'), Decimal('NaN'))
4391 return a
.max(b
, context
=self
)
4393 def max_mag(self
, a
, b
):
4394 """Compares the values numerically with their sign ignored."""
4395 return a
.max_mag(b
, context
=self
)
4398 """min compares two values numerically and returns the minimum.
4400 If either operand is a NaN then the general rules apply.
4401 Otherwise, the operands are compared as though by the compare
4402 operation. If they are numerically equal then the left-hand operand
4403 is chosen as the result. Otherwise the minimum (closer to negative
4404 infinity) of the two operands is chosen as the result.
4406 >>> ExtendedContext.min(Decimal('3'), Decimal('2'))
4408 >>> ExtendedContext.min(Decimal('-10'), Decimal('3'))
4410 >>> ExtendedContext.min(Decimal('1.0'), Decimal('1'))
4412 >>> ExtendedContext.min(Decimal('7'), Decimal('NaN'))
4415 return a
.min(b
, context
=self
)
4417 def min_mag(self
, a
, b
):
4418 """Compares the values numerically with their sign ignored."""
4419 return a
.min_mag(b
, context
=self
)
4422 """Minus corresponds to unary prefix minus in Python.
4424 The operation is evaluated using the same rules as subtract; the
4425 operation minus(a) is calculated as subtract('0', a) where the '0'
4426 has the same exponent as the operand.
4428 >>> ExtendedContext.minus(Decimal('1.3'))
4430 >>> ExtendedContext.minus(Decimal('-1.3'))
4433 return a
.__neg
__(context
=self
)
4435 def multiply(self
, a
, b
):
4436 """multiply multiplies two operands.
4438 If either operand is a special value then the general rules apply.
4439 Otherwise, the operands are multiplied together ('long multiplication'),
4440 resulting in a number which may be as long as the sum of the lengths
4441 of the two operands.
4443 >>> ExtendedContext.multiply(Decimal('1.20'), Decimal('3'))
4445 >>> ExtendedContext.multiply(Decimal('7'), Decimal('3'))
4447 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('0.8'))
4449 >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('-0'))
4451 >>> ExtendedContext.multiply(Decimal('654321'), Decimal('654321'))
4452 Decimal('4.28135971E+11')
4454 return a
.__mul
__(b
, context
=self
)
4456 def next_minus(self
, a
):
4457 """Returns the largest representable number smaller than a.
4459 >>> c = ExtendedContext.copy()
4462 >>> ExtendedContext.next_minus(Decimal('1'))
4463 Decimal('0.999999999')
4464 >>> c.next_minus(Decimal('1E-1007'))
4466 >>> ExtendedContext.next_minus(Decimal('-1.00000003'))
4467 Decimal('-1.00000004')
4468 >>> c.next_minus(Decimal('Infinity'))
4469 Decimal('9.99999999E+999')
4471 return a
.next_minus(context
=self
)
4473 def next_plus(self
, a
):
4474 """Returns the smallest representable number larger than a.
4476 >>> c = ExtendedContext.copy()
4479 >>> ExtendedContext.next_plus(Decimal('1'))
4480 Decimal('1.00000001')
4481 >>> c.next_plus(Decimal('-1E-1007'))
4483 >>> ExtendedContext.next_plus(Decimal('-1.00000003'))
4484 Decimal('-1.00000002')
4485 >>> c.next_plus(Decimal('-Infinity'))
4486 Decimal('-9.99999999E+999')
4488 return a
.next_plus(context
=self
)
4490 def next_toward(self
, a
, b
):
4491 """Returns the number closest to a, in direction towards b.
4493 The result is the closest representable number from the first
4494 operand (but not the first operand) that is in the direction
4495 towards the second operand, unless the operands have the same
4498 >>> c = ExtendedContext.copy()
4501 >>> c.next_toward(Decimal('1'), Decimal('2'))
4502 Decimal('1.00000001')
4503 >>> c.next_toward(Decimal('-1E-1007'), Decimal('1'))
4505 >>> c.next_toward(Decimal('-1.00000003'), Decimal('0'))
4506 Decimal('-1.00000002')
4507 >>> c.next_toward(Decimal('1'), Decimal('0'))
4508 Decimal('0.999999999')
4509 >>> c.next_toward(Decimal('1E-1007'), Decimal('-100'))
4511 >>> c.next_toward(Decimal('-1.00000003'), Decimal('-10'))
4512 Decimal('-1.00000004')
4513 >>> c.next_toward(Decimal('0.00'), Decimal('-0.0000'))
4516 return a
.next_toward(b
, context
=self
)
4518 def normalize(self
, a
):
4519 """normalize reduces an operand to its simplest form.
4521 Essentially a plus operation with all trailing zeros removed from the
4524 >>> ExtendedContext.normalize(Decimal('2.1'))
4526 >>> ExtendedContext.normalize(Decimal('-2.0'))
4528 >>> ExtendedContext.normalize(Decimal('1.200'))
4530 >>> ExtendedContext.normalize(Decimal('-120'))
4532 >>> ExtendedContext.normalize(Decimal('120.00'))
4534 >>> ExtendedContext.normalize(Decimal('0.00'))
4537 return a
.normalize(context
=self
)
4539 def number_class(self
, a
):
4540 """Returns an indication of the class of the operand.
4542 The class is one of the following strings:
4554 >>> c = Context(ExtendedContext)
4557 >>> c.number_class(Decimal('Infinity'))
4559 >>> c.number_class(Decimal('1E-10'))
4561 >>> c.number_class(Decimal('2.50'))
4563 >>> c.number_class(Decimal('0.1E-999'))
4565 >>> c.number_class(Decimal('0'))
4567 >>> c.number_class(Decimal('-0'))
4569 >>> c.number_class(Decimal('-0.1E-999'))
4571 >>> c.number_class(Decimal('-1E-10'))
4573 >>> c.number_class(Decimal('-2.50'))
4575 >>> c.number_class(Decimal('-Infinity'))
4577 >>> c.number_class(Decimal('NaN'))
4579 >>> c.number_class(Decimal('-NaN'))
4581 >>> c.number_class(Decimal('sNaN'))
4584 return a
.number_class(context
=self
)
4587 """Plus corresponds to unary prefix plus in Python.
4589 The operation is evaluated using the same rules as add; the
4590 operation plus(a) is calculated as add('0', a) where the '0'
4591 has the same exponent as the operand.
4593 >>> ExtendedContext.plus(Decimal('1.3'))
4595 >>> ExtendedContext.plus(Decimal('-1.3'))
4598 return a
.__pos
__(context
=self
)
4600 def power(self
, a
, b
, modulo
=None):
4601 """Raises a to the power of b, to modulo if given.
4603 With two arguments, compute a**b. If a is negative then b
4604 must be integral. The result will be inexact unless b is
4605 integral and the result is finite and can be expressed exactly
4606 in 'precision' digits.
4608 With three arguments, compute (a**b) % modulo. For the
4609 three argument form, the following restrictions on the
4612 - all three arguments must be integral
4613 - b must be nonnegative
4614 - at least one of a or b must be nonzero
4615 - modulo must be nonzero and have at most 'precision' digits
4617 The result of pow(a, b, modulo) is identical to the result
4618 that would be obtained by computing (a**b) % modulo with
4619 unbounded precision, but is computed more efficiently. It is
4622 >>> c = ExtendedContext.copy()
4625 >>> c.power(Decimal('2'), Decimal('3'))
4627 >>> c.power(Decimal('-2'), Decimal('3'))
4629 >>> c.power(Decimal('2'), Decimal('-3'))
4631 >>> c.power(Decimal('1.7'), Decimal('8'))
4632 Decimal('69.7575744')
4633 >>> c.power(Decimal('10'), Decimal('0.301029996'))
4634 Decimal('2.00000000')
4635 >>> c.power(Decimal('Infinity'), Decimal('-1'))
4637 >>> c.power(Decimal('Infinity'), Decimal('0'))
4639 >>> c.power(Decimal('Infinity'), Decimal('1'))
4641 >>> c.power(Decimal('-Infinity'), Decimal('-1'))
4643 >>> c.power(Decimal('-Infinity'), Decimal('0'))
4645 >>> c.power(Decimal('-Infinity'), Decimal('1'))
4646 Decimal('-Infinity')
4647 >>> c.power(Decimal('-Infinity'), Decimal('2'))
4649 >>> c.power(Decimal('0'), Decimal('0'))
4652 >>> c.power(Decimal('3'), Decimal('7'), Decimal('16'))
4654 >>> c.power(Decimal('-3'), Decimal('7'), Decimal('16'))
4656 >>> c.power(Decimal('-3'), Decimal('8'), Decimal('16'))
4658 >>> c.power(Decimal('3'), Decimal('7'), Decimal('-16'))
4660 >>> c.power(Decimal('23E12345'), Decimal('67E189'), Decimal('123456789'))
4662 >>> c.power(Decimal('-0'), Decimal('17'), Decimal('1729'))
4664 >>> c.power(Decimal('-23'), Decimal('0'), Decimal('65537'))
4667 return a
.__pow
__(b
, modulo
, context
=self
)
4669 def quantize(self
, a
, b
):
4670 """Returns a value equal to 'a' (rounded), having the exponent of 'b'.
4672 The coefficient of the result is derived from that of the left-hand
4673 operand. It may be rounded using the current rounding setting (if the
4674 exponent is being increased), multiplied by a positive power of ten (if
4675 the exponent is being decreased), or is unchanged (if the exponent is
4676 already equal to that of the right-hand operand).
4678 Unlike other operations, if the length of the coefficient after the
4679 quantize operation would be greater than precision then an Invalid
4680 operation condition is raised. This guarantees that, unless there is
4681 an error condition, the exponent of the result of a quantize is always
4682 equal to that of the right-hand operand.
4684 Also unlike other operations, quantize will never raise Underflow, even
4685 if the result is subnormal and inexact.
4687 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))
4689 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))
4691 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))
4693 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))
4695 >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))
4697 >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))
4698 Decimal('-Infinity')
4699 >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))
4701 >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))
4703 >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))
4705 >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))
4707 >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))
4709 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))
4711 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))
4713 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))
4715 >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))
4718 return a
.quantize(b
, context
=self
)
4721 """Just returns 10, as this is Decimal, :)
4723 >>> ExtendedContext.radix()
4728 def remainder(self
, a
, b
):
4729 """Returns the remainder from integer division.
4731 The result is the residue of the dividend after the operation of
4732 calculating integer division as described for divide-integer, rounded
4733 to precision digits if necessary. The sign of the result, if
4734 non-zero, is the same as that of the original dividend.
4736 This operation will fail under the same conditions as integer division
4737 (that is, if integer division on the same two operands would fail, the
4738 remainder cannot be calculated).
4740 >>> ExtendedContext.remainder(Decimal('2.1'), Decimal('3'))
4742 >>> ExtendedContext.remainder(Decimal('10'), Decimal('3'))
4744 >>> ExtendedContext.remainder(Decimal('-10'), Decimal('3'))
4746 >>> ExtendedContext.remainder(Decimal('10.2'), Decimal('1'))
4748 >>> ExtendedContext.remainder(Decimal('10'), Decimal('0.3'))
4750 >>> ExtendedContext.remainder(Decimal('3.6'), Decimal('1.3'))
4753 return a
.__mod
__(b
, context
=self
)
4755 def remainder_near(self
, a
, b
):
4756 """Returns to be "a - b * n", where n is the integer nearest the exact
4757 value of "x / b" (if two integers are equally near then the even one
4758 is chosen). If the result is equal to 0 then its sign will be the
4761 This operation will fail under the same conditions as integer division
4762 (that is, if integer division on the same two operands would fail, the
4763 remainder cannot be calculated).
4765 >>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))
4767 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))
4769 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))
4771 >>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))
4773 >>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))
4775 >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))
4777 >>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))
4780 return a
.remainder_near(b
, context
=self
)
4782 def rotate(self
, a
, b
):
4783 """Returns a rotated copy of a, b times.
4785 The coefficient of the result is a rotated copy of the digits in
4786 the coefficient of the first operand. The number of places of
4787 rotation is taken from the absolute value of the second operand,
4788 with the rotation being to the left if the second operand is
4789 positive or to the right otherwise.
4791 >>> ExtendedContext.rotate(Decimal('34'), Decimal('8'))
4792 Decimal('400000003')
4793 >>> ExtendedContext.rotate(Decimal('12'), Decimal('9'))
4795 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('-2'))
4796 Decimal('891234567')
4797 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('0'))
4798 Decimal('123456789')
4799 >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('+2'))
4800 Decimal('345678912')
4802 return a
.rotate(b
, context
=self
)
4804 def same_quantum(self
, a
, b
):
4805 """Returns True if the two operands have the same exponent.
4807 The result is never affected by either the sign or the coefficient of
4810 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))
4812 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))
4814 >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))
4816 >>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))
4819 return a
.same_quantum(b
)
4821 def scaleb (self
, a
, b
):
4822 """Returns the first operand after adding the second value its exp.
4824 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('-2'))
4826 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('0'))
4828 >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('3'))
4831 return a
.scaleb (b
, context
=self
)
4833 def shift(self
, a
, b
):
4834 """Returns a shifted copy of a, b times.
4836 The coefficient of the result is a shifted copy of the digits
4837 in the coefficient of the first operand. The number of places
4838 to shift is taken from the absolute value of the second operand,
4839 with the shift being to the left if the second operand is
4840 positive or to the right otherwise. Digits shifted into the
4841 coefficient are zeros.
4843 >>> ExtendedContext.shift(Decimal('34'), Decimal('8'))
4844 Decimal('400000000')
4845 >>> ExtendedContext.shift(Decimal('12'), Decimal('9'))
4847 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('-2'))
4849 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('0'))
4850 Decimal('123456789')
4851 >>> ExtendedContext.shift(Decimal('123456789'), Decimal('+2'))
4852 Decimal('345678900')
4854 return a
.shift(b
, context
=self
)
4857 """Square root of a non-negative number to context precision.
4859 If the result must be inexact, it is rounded using the round-half-even
4862 >>> ExtendedContext.sqrt(Decimal('0'))
4864 >>> ExtendedContext.sqrt(Decimal('-0'))
4866 >>> ExtendedContext.sqrt(Decimal('0.39'))
4867 Decimal('0.624499800')
4868 >>> ExtendedContext.sqrt(Decimal('100'))
4870 >>> ExtendedContext.sqrt(Decimal('1'))
4872 >>> ExtendedContext.sqrt(Decimal('1.0'))
4874 >>> ExtendedContext.sqrt(Decimal('1.00'))
4876 >>> ExtendedContext.sqrt(Decimal('7'))
4877 Decimal('2.64575131')
4878 >>> ExtendedContext.sqrt(Decimal('10'))
4879 Decimal('3.16227766')
4880 >>> ExtendedContext.prec
4883 return a
.sqrt(context
=self
)
4885 def subtract(self
, a
, b
):
4886 """Return the difference between the two operands.
4888 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.07'))
4890 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.30'))
4892 >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('2.07'))
4895 return a
.__sub
__(b
, context
=self
)
4897 def to_eng_string(self
, a
):
4898 """Converts a number to a string, using scientific notation.
4900 The operation is not affected by the context.
4902 return a
.to_eng_string(context
=self
)
4904 def to_sci_string(self
, a
):
4905 """Converts a number to a string, using scientific notation.
4907 The operation is not affected by the context.
4909 return a
.__str
__(context
=self
)
4911 def to_integral_exact(self
, a
):
4912 """Rounds to an integer.
4914 When the operand has a negative exponent, the result is the same
4915 as using the quantize() operation using the given operand as the
4916 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
4917 of the operand as the precision setting; Inexact and Rounded flags
4918 are allowed in this operation. The rounding mode is taken from the
4921 >>> ExtendedContext.to_integral_exact(Decimal('2.1'))
4923 >>> ExtendedContext.to_integral_exact(Decimal('100'))
4925 >>> ExtendedContext.to_integral_exact(Decimal('100.0'))
4927 >>> ExtendedContext.to_integral_exact(Decimal('101.5'))
4929 >>> ExtendedContext.to_integral_exact(Decimal('-101.5'))
4931 >>> ExtendedContext.to_integral_exact(Decimal('10E+5'))
4933 >>> ExtendedContext.to_integral_exact(Decimal('7.89E+77'))
4935 >>> ExtendedContext.to_integral_exact(Decimal('-Inf'))
4936 Decimal('-Infinity')
4938 return a
.to_integral_exact(context
=self
)
4940 def to_integral_value(self
, a
):
4941 """Rounds to an integer.
4943 When the operand has a negative exponent, the result is the same
4944 as using the quantize() operation using the given operand as the
4945 left-hand-operand, 1E+0 as the right-hand-operand, and the precision
4946 of the operand as the precision setting, except that no flags will
4947 be set. The rounding mode is taken from the context.
4949 >>> ExtendedContext.to_integral_value(Decimal('2.1'))
4951 >>> ExtendedContext.to_integral_value(Decimal('100'))
4953 >>> ExtendedContext.to_integral_value(Decimal('100.0'))
4955 >>> ExtendedContext.to_integral_value(Decimal('101.5'))
4957 >>> ExtendedContext.to_integral_value(Decimal('-101.5'))
4959 >>> ExtendedContext.to_integral_value(Decimal('10E+5'))
4961 >>> ExtendedContext.to_integral_value(Decimal('7.89E+77'))
4963 >>> ExtendedContext.to_integral_value(Decimal('-Inf'))
4964 Decimal('-Infinity')
4966 return a
.to_integral_value(context
=self
)
4968 # the method name changed, but we provide also the old one, for compatibility
4969 to_integral
= to_integral_value
4971 class _WorkRep(object):
4972 __slots__
= ('sign','int','exp')
4975 # exp: None, int, or string
4977 def __init__(self
, value
=None):
4982 elif isinstance(value
, Decimal
):
4983 self
.sign
= value
._sign
4984 self
.int = int(value
._int
)
4985 self
.exp
= value
._exp
4987 # assert isinstance(value, tuple)
4988 self
.sign
= value
[0]
4993 return "(%r, %r, %r)" % (self
.sign
, self
.int, self
.exp
)
4999 def _normalize(op1
, op2
, prec
= 0):
5000 """Normalizes op1, op2 to have the same exp and length of coefficient.
5002 Done during addition.
5004 if op1
.exp
< op2
.exp
:
5011 # Let exp = min(tmp.exp - 1, tmp.adjusted() - precision - 1).
5012 # Then adding 10**exp to tmp has the same effect (after rounding)
5013 # as adding any positive quantity smaller than 10**exp; similarly
5014 # for subtraction. So if other is smaller than 10**exp we replace
5015 # it with 10**exp. This avoids tmp.exp - other.exp getting too large.
5016 tmp_len
= len(str(tmp
.int))
5017 other_len
= len(str(other
.int))
5018 exp
= tmp
.exp
+ min(-1, tmp_len
- prec
- 2)
5019 if other_len
+ other
.exp
- 1 < exp
:
5023 tmp
.int *= 10 ** (tmp
.exp
- other
.exp
)
5027 ##### Integer arithmetic functions used by ln, log10, exp and __pow__ #####
5029 # This function from Tim Peters was taken from here:
5030 # http://mail.python.org/pipermail/python-list/1999-July/007758.html
5031 # The correction being in the function definition is for speed, and
5032 # the whole function is not resolved with math.log because of avoiding
5033 # the use of floats.
5034 def _nbits(n
, correction
= {
5035 '0': 4, '1': 3, '2': 2, '3': 2,
5036 '4': 1, '5': 1, '6': 1, '7': 1,
5037 '8': 0, '9': 0, 'a': 0, 'b': 0,
5038 'c': 0, 'd': 0, 'e': 0, 'f': 0}):
5039 """Number of bits in binary representation of the positive integer n,
5043 raise ValueError("The argument to _nbits should be nonnegative.")
5045 return 4*len(hex_n
) - correction
[hex_n
[0]]
5047 def _sqrt_nearest(n
, a
):
5048 """Closest integer to the square root of the positive integer n. a is
5049 an initial approximation to the square root. Any positive integer
5050 will do for a, but the closer a is to the square root of n the
5051 faster convergence will be.
5054 if n
<= 0 or a
<= 0:
5055 raise ValueError("Both arguments to _sqrt_nearest should be positive.")
5059 b
, a
= a
, a
--n
//a
>>1
5062 def _rshift_nearest(x
, shift
):
5063 """Given an integer x and a nonnegative integer shift, return closest
5064 integer to x / 2**shift; use round-to-even in case of a tie.
5067 b
, q
= 1L << shift
, x
>> shift
5068 return q
+ (2*(x
& (b
-1)) + (q
&1) > b
)
5070 def _div_nearest(a
, b
):
5071 """Closest integer to a/b, a and b positive integers; rounds to even
5072 in the case of a tie.
5076 return q
+ (2*r
+ (q
&1) > b
)
5078 def _ilog(x
, M
, L
= 8):
5079 """Integer approximation to M*log(x/M), with absolute error boundable
5080 in terms only of x/M.
5082 Given positive integers x and M, return an integer approximation to
5083 M * log(x/M). For L = 8 and 0.1 <= x/M <= 10 the difference
5084 between the approximation and the exact result is at most 22. For
5085 L = 8 and 1.0 <= x/M <= 10.0 the difference is at most 15. In
5086 both cases these are upper bounds on the error; it will usually be
5089 # The basic algorithm is the following: let log1p be the function
5090 # log1p(x) = log(1+x). Then log(x/M) = log1p((x-M)/M). We use
5093 # log1p(y) = 2*log1p(y/(1+sqrt(1+y)))
5095 # repeatedly until the argument to log1p is small (< 2**-L in
5096 # absolute value). For small y we can use the Taylor series
5099 # log1p(y) ~ y - y**2/2 + y**3/3 - ... - (-y)**T/T
5101 # truncating at T such that y**T is small enough. The whole
5102 # computation is carried out in a form of fixed-point arithmetic,
5103 # with a real number z being represented by an integer
5104 # approximation to z*M. To avoid loss of precision, the y below
5105 # is actually an integer approximation to 2**R*y*M, where R is the
5106 # number of reductions performed so far.
5109 # argument reduction; R = number of reductions performed
5111 while (R
<= L
and long(abs(y
)) << L
-R
>= M
or
5112 R
> L
and abs(y
) >> R
-L
>= M
):
5113 y
= _div_nearest(long(M
*y
) << 1,
5114 M
+ _sqrt_nearest(M
*(M
+_rshift_nearest(y
, R
)), M
))
5117 # Taylor series with T terms
5118 T
= -int(-10*len(str(M
))//(3*L
))
5119 yshift
= _rshift_nearest(y
, R
)
5120 w
= _div_nearest(M
, T
)
5121 for k
in xrange(T
-1, 0, -1):
5122 w
= _div_nearest(M
, k
) - _div_nearest(yshift
*w
, M
)
5124 return _div_nearest(w
*y
, M
)
5126 def _dlog10(c
, e
, p
):
5127 """Given integers c, e and p with c > 0, p >= 0, compute an integer
5128 approximation to 10**p * log10(c*10**e), with an absolute error of
5129 at most 1. Assumes that c*10**e is not exactly 1."""
5131 # increase precision by 2; compensate for this by dividing
5132 # final result by 100
5135 # write c*10**e as d*10**f with either:
5136 # f >= 0 and 1 <= d <= 10, or
5137 # f <= 0 and 0.1 <= d <= 1.
5138 # Thus for c*10**e close to 1, f = 0
5140 f
= e
+l
- (e
+l
>= 1)
5148 c
= _div_nearest(c
, 10**-k
)
5150 log_d
= _ilog(c
, M
) # error < 5 + 22 = 27
5151 log_10
= _log10_digits(p
) # error < 1
5152 log_d
= _div_nearest(log_d
*M
, log_10
)
5153 log_tenpower
= f
*M
# exact
5155 log_d
= 0 # error < 2.31
5156 log_tenpower
= _div_nearest(f
, 10**-p
) # error < 0.5
5158 return _div_nearest(log_tenpower
+log_d
, 100)
5161 """Given integers c, e and p with c > 0, compute an integer
5162 approximation to 10**p * log(c*10**e), with an absolute error of
5163 at most 1. Assumes that c*10**e is not exactly 1."""
5165 # Increase precision by 2. The precision increase is compensated
5166 # for at the end with a division by 100.
5169 # rewrite c*10**e as d*10**f with either f >= 0 and 1 <= d <= 10,
5170 # or f <= 0 and 0.1 <= d <= 1. Then we can compute 10**p * log(c*10**e)
5171 # as 10**p * log(d) + 10**p*f * log(10).
5173 f
= e
+l
- (e
+l
>= 1)
5175 # compute approximation to 10**p*log(d), with error < 27
5181 c
= _div_nearest(c
, 10**-k
) # error of <= 0.5 in c
5183 # _ilog magnifies existing error in c by a factor of at most 10
5184 log_d
= _ilog(c
, 10**p
) # error < 5 + 22 = 27
5186 # p <= 0: just approximate the whole thing by 0; error < 2.31
5189 # compute approximation to f*10**p*log(10), with error < 11.
5191 extra
= len(str(abs(f
)))-1
5193 # error in f * _log10_digits(p+extra) < |f| * 1 = |f|
5194 # after division, error < |f|/10**extra + 0.5 < 10 + 0.5 < 11
5195 f_log_ten
= _div_nearest(f
*_log10_digits(p
+extra
), 10**extra
)
5201 # error in sum < 11+27 = 38; error after division < 0.38 + 0.5 < 1
5202 return _div_nearest(f_log_ten
+ log_d
, 100)
5204 class _Log10Memoize(object):
5205 """Class to compute, store, and allow retrieval of, digits of the
5206 constant log(10) = 2.302585.... This constant is needed by
5207 Decimal.ln, Decimal.log10, Decimal.exp and Decimal.__pow__."""
5209 self
.digits
= "23025850929940456840179914546843642076011014886"
5211 def getdigits(self
, p
):
5212 """Given an integer p >= 0, return floor(10**p)*log(10).
5214 For example, self.getdigits(3) returns 2302.
5216 # digits are stored as a string, for quick conversion to
5217 # integer in the case that we've already computed enough
5218 # digits; the stored digits should always be correct
5219 # (truncated, not rounded to nearest).
5221 raise ValueError("p should be nonnegative")
5223 if p
>= len(self
.digits
):
5224 # compute p+3, p+6, p+9, ... digits; continue until at
5225 # least one of the extra digits is nonzero
5228 # compute p+extra digits, correct to within 1ulp
5230 digits
= str(_div_nearest(_ilog(10*M
, M
), 100))
5231 if digits
[-extra
:] != '0'*extra
:
5234 # keep all reliable digits so far; remove trailing zeros
5235 # and next nonzero digit
5236 self
.digits
= digits
.rstrip('0')[:-1]
5237 return int(self
.digits
[:p
+1])
5239 _log10_digits
= _Log10Memoize().getdigits
5241 def _iexp(x
, M
, L
=8):
5242 """Given integers x and M, M > 0, such that x/M is small in absolute
5243 value, compute an integer approximation to M*exp(x/M). For 0 <=
5244 x/M <= 2.4, the absolute error in the result is bounded by 60 (and
5245 is usually much smaller)."""
5247 # Algorithm: to compute exp(z) for a real number z, first divide z
5248 # by a suitable power R of 2 so that |z/2**R| < 2**-L. Then
5249 # compute expm1(z/2**R) = exp(z/2**R) - 1 using the usual Taylor
5252 # expm1(x) = x + x**2/2! + x**3/3! + ...
5254 # Now use the identity
5256 # expm1(2x) = expm1(x)*(expm1(x)+2)
5258 # R times to compute the sequence expm1(z/2**R),
5259 # expm1(z/2**(R-1)), ... , exp(z/2), exp(z).
5261 # Find R such that x/2**R/M <= 2**-L
5262 R
= _nbits((long(x
)<<L
)//M
)
5264 # Taylor series. (2**L)**T > M
5265 T
= -int(-10*len(str(M
))//(3*L
))
5266 y
= _div_nearest(x
, T
)
5268 for i
in xrange(T
-1, 0, -1):
5269 y
= _div_nearest(x
*(Mshift
+ y
), Mshift
* i
)
5272 for k
in xrange(R
-1, -1, -1):
5273 Mshift
= long(M
)<<(k
+2)
5274 y
= _div_nearest(y
*(y
+Mshift
), Mshift
)
5279 """Compute an approximation to exp(c*10**e), with p decimal places of
5282 Returns integers d, f such that:
5284 10**(p-1) <= d <= 10**p, and
5285 (d-1)*10**f < exp(c*10**e) < (d+1)*10**f
5287 In other words, d*10**f is an approximation to exp(c*10**e) with p
5288 digits of precision, and with an error in d of at most 1. This is
5289 almost, but not quite, the same as the error being < 1ulp: when d
5290 = 10**(p-1) the error could be up to 10 ulp."""
5292 # we'll call iexp with M = 10**(p+2), giving p+3 digits of precision
5295 # compute log(10) with extra precision = adjusted exponent of c*10**e
5296 extra
= max(0, e
+ len(str(c
)) - 1)
5299 # compute quotient c*10**e/(log(10)) = c*10**(e+q)/(log(10)*10**q),
5303 cshift
= c
*10**shift
5305 cshift
= c
//10**-shift
5306 quot
, rem
= divmod(cshift
, _log10_digits(q
))
5308 # reduce remainder back to original precision
5309 rem
= _div_nearest(rem
, 10**extra
)
5311 # error in result of _iexp < 120; error after division < 0.62
5312 return _div_nearest(_iexp(rem
, 10**p
), 1000), quot
- p
+ 3
5314 def _dpower(xc
, xe
, yc
, ye
, p
):
5315 """Given integers xc, xe, yc and ye representing Decimals x = xc*10**xe and
5316 y = yc*10**ye, compute x**y. Returns a pair of integers (c, e) such that:
5318 10**(p-1) <= c <= 10**p, and
5319 (c-1)*10**e < x**y < (c+1)*10**e
5321 in other words, c*10**e is an approximation to x**y with p digits
5322 of precision, and with an error in c of at most 1. (This is
5323 almost, but not quite, the same as the error being < 1ulp: when c
5324 == 10**(p-1) we can only guarantee error < 10ulp.)
5326 We assume that: x is positive and not equal to 1, and y is nonzero.
5329 # Find b such that 10**(b-1) <= |y| <= 10**b
5330 b
= len(str(abs(yc
))) + ye
5332 # log(x) = lxc*10**(-p-b-1), to p+b+1 places after the decimal point
5333 lxc
= _dlog(xc
, xe
, p
+b
+1)
5335 # compute product y*log(x) = yc*lxc*10**(-p-b-1+ye) = pc*10**(-p-1)
5338 pc
= lxc
*yc
*10**shift
5340 pc
= _div_nearest(lxc
*yc
, 10**-shift
)
5343 # we prefer a result that isn't exactly 1; this makes it
5344 # easier to compute a correctly rounded result in __pow__
5345 if ((len(str(xc
)) + xe
>= 1) == (yc
> 0)): # if x**y > 1:
5346 coeff
, exp
= 10**(p
-1)+1, 1-p
5348 coeff
, exp
= 10**p
-1, -p
5350 coeff
, exp
= _dexp(pc
, -(p
+1), p
+1)
5351 coeff
= _div_nearest(coeff
, 10)
5356 def _log10_lb(c
, correction
= {
5357 '1': 100, '2': 70, '3': 53, '4': 40, '5': 31,
5358 '6': 23, '7': 16, '8': 10, '9': 5}):
5359 """Compute a lower bound for 100*log10(c) for a positive integer c."""
5361 raise ValueError("The argument to _log10_lb should be nonnegative.")
5363 return 100*len(str_c
) - correction
[str_c
[0]]
5365 ##### Helper Functions ####################################################
5367 def _convert_other(other
, raiseit
=False):
5368 """Convert other to Decimal.
5370 Verifies that it's ok to use in an implicit construction.
5372 if isinstance(other
, Decimal
):
5374 if isinstance(other
, (int, long)):
5375 return Decimal(other
)
5377 raise TypeError("Unable to convert %s to Decimal" % other
)
5378 return NotImplemented
5380 ##### Setup Specific Contexts ############################################
5382 # The default context prototype used by Context()
5383 # Is mutable, so that new contexts can have different default values
5385 DefaultContext
= Context(
5386 prec
=28, rounding
=ROUND_HALF_EVEN
,
5387 traps
=[DivisionByZero
, Overflow
, InvalidOperation
],
5394 # Pre-made alternate contexts offered by the specification
5395 # Don't change these; the user should be able to select these
5396 # contexts and be able to reproduce results from other implementations
5399 BasicContext
= Context(
5400 prec
=9, rounding
=ROUND_HALF_UP
,
5401 traps
=[DivisionByZero
, Overflow
, InvalidOperation
, Clamped
, Underflow
],
5405 ExtendedContext
= Context(
5406 prec
=9, rounding
=ROUND_HALF_EVEN
,
5412 ##### crud for parsing strings #############################################
5414 # Regular expression used for parsing numeric strings. Additional
5417 # 1. Uncomment the two '\s*' lines to allow leading and/or trailing
5418 # whitespace. But note that the specification disallows whitespace in
5421 # 2. For finite numbers (not infinities and NaNs) the body of the
5422 # number between the optional sign and the optional exponent must have
5423 # at least one decimal digit, possibly after the decimal point. The
5424 # lookahead expression '(?=\d|\.\d)' checks this.
5427 _parser
= re
.compile(r
""" # A numeric string consists of:
5429 (?P<sign>[-+])? # an optional sign, followed by either...
5431 (?=\d|\.\d) # ...a number (with at least one digit)
5432 (?P<int>\d*) # having a (possibly empty) integer part
5433 (\.(?P<frac>\d*))? # followed by an optional fractional part
5434 (E(?P<exp>[-+]?\d+))? # followed by an optional exponent, or...
5436 Inf(inity)? # ...an infinity, or...
5438 (?P<signal>s)? # ...an (optionally signaling)
5440 (?P<diag>\d*) # with (possibly empty) diagnostic info.
5444 """, re
.VERBOSE | re
.IGNORECASE | re
.UNICODE
).match
5446 _all_zeros
= re
.compile('0*$').match
5447 _exact_half
= re
.compile('50*$').match
5449 ##### PEP3101 support functions ##############################################
5450 # The functions in this section have little to do with the Decimal
5451 # class, and could potentially be reused or adapted for other pure
5452 # Python numeric classes that want to implement __format__
5454 # A format specifier for Decimal looks like:
5456 # [[fill]align][sign][0][minimumwidth][,][.precision][type]
5458 _parse_format_specifier_regex
= re
.compile(r
"""\A
5465 (?P<minimumwidth>(?!0)\d+)?
5466 (?P<thousands_sep>,)?
5467 (?:\.(?P<precision>0|(?!0)\d+))?
5468 (?P<type>[eEfFgGn%])?
5474 # The locale module is only needed for the 'n' format specifier. The
5475 # rest of the PEP 3101 code functions quite happily without it, so we
5476 # don't care too much if locale isn't present.
5478 import locale
as _locale
5482 def _parse_format_specifier(format_spec
, _localeconv
=None):
5483 """Parse and validate a format specifier.
5485 Turns a standard numeric format specifier into a dict, with the
5488 fill: fill character to pad field to minimum width
5489 align: alignment type, either '<', '>', '=' or '^'
5490 sign: either '+', '-' or ' '
5491 minimumwidth: nonnegative integer giving minimum width
5492 zeropad: boolean, indicating whether to pad with zeros
5493 thousands_sep: string to use as thousands separator, or ''
5494 grouping: grouping for thousands separators, in format
5496 decimal_point: string to use for decimal point
5497 precision: nonnegative integer giving precision, or None
5498 type: one of the characters 'eEfFgG%', or None
5499 unicode: boolean (always True for Python 3.x)
5502 m
= _parse_format_specifier_regex
.match(format_spec
)
5504 raise ValueError("Invalid format specifier: " + format_spec
)
5506 # get the dictionary
5507 format_dict
= m
.groupdict()
5509 # zeropad; defaults for fill and alignment. If zero padding
5510 # is requested, the fill and align fields should be absent.
5511 fill
= format_dict
['fill']
5512 align
= format_dict
['align']
5513 format_dict
['zeropad'] = (format_dict
['zeropad'] is not None)
5514 if format_dict
['zeropad']:
5515 if fill
is not None:
5516 raise ValueError("Fill character conflicts with '0'"
5517 " in format specifier: " + format_spec
)
5518 if align
is not None:
5519 raise ValueError("Alignment conflicts with '0' in "
5520 "format specifier: " + format_spec
)
5521 format_dict
['fill'] = fill
or ' '
5522 # PEP 3101 originally specified that the default alignment should
5523 # be left; it was later agreed that right-aligned makes more sense
5524 # for numeric types. See http://bugs.python.org/issue6857.
5525 format_dict
['align'] = align
or '>'
5527 # default sign handling: '-' for negative, '' for positive
5528 if format_dict
['sign'] is None:
5529 format_dict
['sign'] = '-'
5531 # minimumwidth defaults to 0; precision remains None if not given
5532 format_dict
['minimumwidth'] = int(format_dict
['minimumwidth'] or '0')
5533 if format_dict
['precision'] is not None:
5534 format_dict
['precision'] = int(format_dict
['precision'])
5536 # if format type is 'g' or 'G' then a precision of 0 makes little
5537 # sense; convert it to 1. Same if format type is unspecified.
5538 if format_dict
['precision'] == 0:
5539 if format_dict
['type'] is None or format_dict
['type'] in 'gG':
5540 format_dict
['precision'] = 1
5542 # determine thousands separator, grouping, and decimal separator, and
5543 # add appropriate entries to format_dict
5544 if format_dict
['type'] == 'n':
5545 # apart from separators, 'n' behaves just like 'g'
5546 format_dict
['type'] = 'g'
5547 if _localeconv
is None:
5548 _localeconv
= _locale
.localeconv()
5549 if format_dict
['thousands_sep'] is not None:
5550 raise ValueError("Explicit thousands separator conflicts with "
5551 "'n' type in format specifier: " + format_spec
)
5552 format_dict
['thousands_sep'] = _localeconv
['thousands_sep']
5553 format_dict
['grouping'] = _localeconv
['grouping']
5554 format_dict
['decimal_point'] = _localeconv
['decimal_point']
5556 if format_dict
['thousands_sep'] is None:
5557 format_dict
['thousands_sep'] = ''
5558 format_dict
['grouping'] = [3, 0]
5559 format_dict
['decimal_point'] = '.'
5561 # record whether return type should be str or unicode
5562 format_dict
['unicode'] = isinstance(format_spec
, unicode)
5566 def _format_align(sign
, body
, spec
):
5567 """Given an unpadded, non-aligned numeric string 'body' and sign
5568 string 'sign', add padding and aligment conforming to the given
5569 format specifier dictionary 'spec' (as produced by
5570 parse_format_specifier).
5572 Also converts result to unicode if necessary.
5575 # how much extra space do we have to play with?
5576 minimumwidth
= spec
['minimumwidth']
5578 padding
= fill
*(minimumwidth
- len(sign
) - len(body
))
5580 align
= spec
['align']
5582 result
= sign
+ body
+ padding
5584 result
= padding
+ sign
+ body
5586 result
= sign
+ padding
+ body
5588 half
= len(padding
)//2
5589 result
= padding
[:half
] + sign
+ body
+ padding
[half
:]
5591 raise ValueError('Unrecognised alignment field')
5593 # make sure that result is unicode if necessary
5595 result
= unicode(result
)
5599 def _group_lengths(grouping
):
5600 """Convert a localeconv-style grouping into a (possibly infinite)
5601 iterable of integers representing group lengths.
5604 # The result from localeconv()['grouping'], and the input to this
5605 # function, should be a list of integers in one of the
5606 # following three forms:
5608 # (1) an empty list, or
5609 # (2) nonempty list of positive integers + [0]
5610 # (3) list of positive integers + [locale.CHAR_MAX], or
5612 from itertools
import chain
, repeat
5615 elif grouping
[-1] == 0 and len(grouping
) >= 2:
5616 return chain(grouping
[:-1], repeat(grouping
[-2]))
5617 elif grouping
[-1] == _locale
.CHAR_MAX
:
5618 return grouping
[:-1]
5620 raise ValueError('unrecognised format for grouping')
5622 def _insert_thousands_sep(digits
, spec
, min_width
=1):
5623 """Insert thousands separators into a digit string.
5625 spec is a dictionary whose keys should include 'thousands_sep' and
5626 'grouping'; typically it's the result of parsing the format
5627 specifier using _parse_format_specifier.
5629 The min_width keyword argument gives the minimum length of the
5630 result, which will be padded on the left with zeros if necessary.
5632 If necessary, the zero padding adds an extra '0' on the left to
5633 avoid a leading thousands separator. For example, inserting
5634 commas every three digits in '123456', with min_width=8, gives
5635 '0,123,456', even though that has length 9.
5639 sep
= spec
['thousands_sep']
5640 grouping
= spec
['grouping']
5643 for l
in _group_lengths(grouping
):
5645 raise ValueError("group length should be positive")
5646 # max(..., 1) forces at least 1 digit to the left of a separator
5647 l
= min(max(len(digits
), min_width
, 1), l
)
5648 groups
.append('0'*(l
- len(digits
)) + digits
[-l
:])
5649 digits
= digits
[:-l
]
5651 if not digits
and min_width
<= 0:
5653 min_width
-= len(sep
)
5655 l
= max(len(digits
), min_width
, 1)
5656 groups
.append('0'*(l
- len(digits
)) + digits
[-l
:])
5657 return sep
.join(reversed(groups
))
5659 def _format_sign(is_negative
, spec
):
5660 """Determine sign character."""
5664 elif spec
['sign'] in ' +':
5669 def _format_number(is_negative
, intpart
, fracpart
, exp
, spec
):
5670 """Format a number, given the following data:
5672 is_negative: true if the number is negative, else false
5673 intpart: string of digits that must appear before the decimal point
5674 fracpart: string of digits that must come after the point
5675 exp: exponent, as an integer
5676 spec: dictionary resulting from parsing the format specifier
5678 This function uses the information in spec to:
5679 insert separators (decimal separator and thousands separators)
5682 add trailing '%' for the '%' type
5683 zero-pad if necessary
5684 fill and align if necessary
5687 sign
= _format_sign(is_negative
, spec
)
5690 fracpart
= spec
['decimal_point'] + fracpart
5692 if exp
!= 0 or spec
['type'] in 'eE':
5693 echar
= {'E': 'E', 'e': 'e', 'G': 'E', 'g': 'e'}[spec
['type']]
5694 fracpart
+= "{0}{1:+}".format(echar
, exp
)
5695 if spec
['type'] == '%':
5699 min_width
= spec
['minimumwidth'] - len(fracpart
) - len(sign
)
5702 intpart
= _insert_thousands_sep(intpart
, spec
, min_width
)
5704 return _format_align(sign
, intpart
+fracpart
, spec
)
5707 ##### Useful Constants (internal use only) ################################
5710 _Infinity
= Decimal('Inf')
5711 _NegativeInfinity
= Decimal('-Inf')
5712 _NaN
= Decimal('NaN')
5715 _NegativeOne
= Decimal(-1)
5717 # _SignedInfinity[sign] is infinity w/ that sign
5718 _SignedInfinity
= (_Infinity
, _NegativeInfinity
)
5722 if __name__
== '__main__':
5724 doctest
.testmod(sys
.modules
[__name__
])