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 should be kept in sync with the latest updates of the
11
# IBM specification as it evolves. Those updates will be treated
12
# as bug fixes (deviation from the spec is a compatibility, usability
13
# bug) and will be backported. At this point the spec is stabilizing
14
# and the updates are becoming fewer, smaller, and less significant.
17
This is an implementation of decimal floating point arithmetic based on
18
the General Decimal Arithmetic Specification:
20
www2.hursley.ibm.com/decimal/decarith.html
22
and IEEE standard 854-1987:
24
www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html
26
Decimal floating point has finite precision with arbitrarily large bounds.
28
The purpose of this module is to support arithmetic using familiar
29
"schoolhouse" rules and to avoid some of the tricky representation
30
issues associated with binary floating point. The package is especially
31
useful for financial applications or for contexts where users have
32
expectations that are at odds with binary floating point (for instance,
33
in binary floating point, 1.00 % 0.1 gives 0.09999999999999995 instead
34
of the expected Decimal('0.00') returned by decimal floating point).
36
Here are some examples of using the decimal module:
38
>>> from decimal import *
39
>>> setcontext(ExtendedContext)
48
>>> Decimal('123.45e12345678901234567890')
49
Decimal('1.2345E+12345678901234567892')
50
>>> Decimal('1.33') + Decimal('1.27')
52
>>> Decimal('12.34') + Decimal('3.87') - Decimal('18.41')
55
>>> print(dig / Decimal(3))
57
>>> getcontext().prec = 18
58
>>> print(dig / Decimal(3))
62
>>> print(Decimal(3).sqrt())
64
>>> print(Decimal(3) ** 123)
65
4.85192780976896427E+58
66
>>> inf = Decimal(1) / Decimal(0)
69
>>> neginf = Decimal(-1) / Decimal(0)
72
>>> print(neginf + inf)
74
>>> print(neginf * inf)
78
>>> getcontext().traps[DivisionByZero] = 1
80
Traceback (most recent call last):
84
decimal.DivisionByZero: x / 0
86
>>> c.traps[InvalidOperation] = 0
87
>>> print(c.flags[InvalidOperation])
89
>>> c.divide(Decimal(0), Decimal(0))
91
>>> c.traps[InvalidOperation] = 1
92
>>> print(c.flags[InvalidOperation])
94
>>> c.flags[InvalidOperation] = 0
95
>>> print(c.flags[InvalidOperation])
97
>>> print(c.divide(Decimal(0), Decimal(0)))
98
Traceback (most recent call last):
102
decimal.InvalidOperation: 0 / 0
103
>>> print(c.flags[InvalidOperation])
105
>>> c.flags[InvalidOperation] = 0
106
>>> c.traps[InvalidOperation] = 0
107
>>> print(c.divide(Decimal(0), Decimal(0)))
109
>>> print(c.flags[InvalidOperation])
116
'Decimal', 'Context',
119
'DefaultContext', 'BasicContext', 'ExtendedContext',
122
'DecimalException', 'Clamped', 'InvalidOperation', 'DivisionByZero',
123
'Inexact', 'Rounded', 'Subnormal', 'Overflow', 'Underflow',
125
# Constants for use in setting up contexts
126
'ROUND_DOWN', 'ROUND_HALF_UP', 'ROUND_HALF_EVEN', 'ROUND_CEILING',
127
'ROUND_FLOOR', 'ROUND_UP', 'ROUND_HALF_DOWN', 'ROUND_05UP',
129
# Functions for manipulating contexts
130
'setcontext', 'getcontext', 'localcontext'
135
import numbers as _numbers
138
from collections import namedtuple as _namedtuple
139
DecimalTuple = _namedtuple('DecimalTuple', 'sign digits exponent')
141
DecimalTuple = lambda *args: args
144
ROUND_DOWN = 'ROUND_DOWN'
145
ROUND_HALF_UP = 'ROUND_HALF_UP'
146
ROUND_HALF_EVEN = 'ROUND_HALF_EVEN'
147
ROUND_CEILING = 'ROUND_CEILING'
148
ROUND_FLOOR = 'ROUND_FLOOR'
149
ROUND_UP = 'ROUND_UP'
150
ROUND_HALF_DOWN = 'ROUND_HALF_DOWN'
151
ROUND_05UP = 'ROUND_05UP'
155
class DecimalException(ArithmeticError):
156
"""Base exception class.
158
Used exceptions derive from this.
159
If an exception derives from another exception besides this (such as
160
Underflow (Inexact, Rounded, Subnormal) that indicates that it is only
161
called if the others are present. This isn't actually used for
164
handle -- Called when context._raise_error is called and the
165
trap_enabler is set. First argument is self, second is the
166
context. More arguments can be given, those being after
167
the explanation in _raise_error (For example,
168
context._raise_error(NewError, '(-x)!', self._sign) would
169
call NewError().handle(context, self._sign).)
171
To define a new exception, it should be sufficient to have it derive
172
from DecimalException.
174
def handle(self, context, *args):
178
class Clamped(DecimalException):
179
"""Exponent of a 0 changed to fit bounds.
181
This occurs and signals clamped if the exponent of a result has been
182
altered in order to fit the constraints of a specific concrete
183
representation. This may occur when the exponent of a zero result would
184
be outside the bounds of a representation, or when a large normal
185
number would have an encoded exponent that cannot be represented. In
186
this latter case, the exponent is reduced to fit and the corresponding
187
number of zero digits are appended to the coefficient ("fold-down").
190
class InvalidOperation(DecimalException):
191
"""An invalid operation was performed.
193
Various bad things cause this:
195
Something creates a signaling NaN
201
x._rescale( non-integer )
206
An operand is invalid
208
The result of the operation after these is a quiet positive NaN,
209
except when the cause is a signaling NaN, in which case the result is
210
also a quiet NaN, but with the original sign, and an optional
211
diagnostic information.
213
def handle(self, context, *args):
215
ans = _dec_from_triple(args[0]._sign, args[0]._int, 'n', True)
216
return ans._fix_nan(context)
219
class ConversionSyntax(InvalidOperation):
220
"""Trying to convert badly formed string.
222
This occurs and signals invalid-operation if an string is being
223
converted to a number and it does not conform to the numeric string
224
syntax. The result is [0,qNaN].
226
def handle(self, context, *args):
229
class DivisionByZero(DecimalException, ZeroDivisionError):
232
This occurs and signals division-by-zero if division of a finite number
233
by zero was attempted (during a divide-integer or divide operation, or a
234
power operation with negative right-hand operand), and the dividend was
237
The result of the operation is [sign,inf], where sign is the exclusive
238
or of the signs of the operands for divide, or is 1 for an odd power of
242
def handle(self, context, sign, *args):
243
return _SignedInfinity[sign]
245
class DivisionImpossible(InvalidOperation):
246
"""Cannot perform the division adequately.
248
This occurs and signals invalid-operation if the integer result of a
249
divide-integer or remainder operation had too many digits (would be
250
longer than precision). The result is [0,qNaN].
253
def handle(self, context, *args):
256
class DivisionUndefined(InvalidOperation, ZeroDivisionError):
257
"""Undefined result of division.
259
This occurs and signals invalid-operation if division by zero was
260
attempted (during a divide-integer, divide, or remainder operation), and
261
the dividend is also zero. The result is [0,qNaN].
264
def handle(self, context, *args):
267
class Inexact(DecimalException):
268
"""Had to round, losing information.
270
This occurs and signals inexact whenever the result of an operation is
271
not exact (that is, it needed to be rounded and any discarded digits
272
were non-zero), or if an overflow or underflow condition occurs. The
273
result in all cases is unchanged.
275
The inexact signal may be tested (or trapped) to determine if a given
276
operation (or sequence of operations) was inexact.
279
class InvalidContext(InvalidOperation):
280
"""Invalid context. Unknown rounding, for example.
282
This occurs and signals invalid-operation if an invalid context was
283
detected during an operation. This can occur if contexts are not checked
284
on creation and either the precision exceeds the capability of the
285
underlying concrete representation or an unknown or unsupported rounding
286
was specified. These aspects of the context need only be checked when
287
the values are required to be used. The result is [0,qNaN].
290
def handle(self, context, *args):
293
class Rounded(DecimalException):
294
"""Number got rounded (not necessarily changed during rounding).
296
This occurs and signals rounded whenever the result of an operation is
297
rounded (that is, some zero or non-zero digits were discarded from the
298
coefficient), or if an overflow or underflow condition occurs. The
299
result in all cases is unchanged.
301
The rounded signal may be tested (or trapped) to determine if a given
302
operation (or sequence of operations) caused a loss of precision.
305
class Subnormal(DecimalException):
306
"""Exponent < Emin before rounding.
308
This occurs and signals subnormal whenever the result of a conversion or
309
operation is subnormal (that is, its adjusted exponent is less than
310
Emin, before any rounding). The result in all cases is unchanged.
312
The subnormal signal may be tested (or trapped) to determine if a given
313
or operation (or sequence of operations) yielded a subnormal result.
316
class Overflow(Inexact, Rounded):
317
"""Numerical overflow.
319
This occurs and signals overflow if the adjusted exponent of a result
320
(from a conversion or from an operation that is not an attempt to divide
321
by zero), after rounding, would be greater than the largest value that
322
can be handled by the implementation (the value Emax).
324
The result depends on the rounding mode:
326
For round-half-up and round-half-even (and for round-half-down and
327
round-up, if implemented), the result of the operation is [sign,inf],
328
where sign is the sign of the intermediate result. For round-down, the
329
result is the largest finite number that can be represented in the
330
current precision, with the sign of the intermediate result. For
331
round-ceiling, the result is the same as for round-down if the sign of
332
the intermediate result is 1, or is [0,inf] otherwise. For round-floor,
333
the result is the same as for round-down if the sign of the intermediate
334
result is 0, or is [1,inf] otherwise. In all cases, Inexact and Rounded
338
def handle(self, context, sign, *args):
339
if context.rounding in (ROUND_HALF_UP, ROUND_HALF_EVEN,
340
ROUND_HALF_DOWN, ROUND_UP):
341
return _SignedInfinity[sign]
343
if context.rounding == ROUND_CEILING:
344
return _SignedInfinity[sign]
345
return _dec_from_triple(sign, '9'*context.prec,
346
context.Emax-context.prec+1)
348
if context.rounding == ROUND_FLOOR:
349
return _SignedInfinity[sign]
350
return _dec_from_triple(sign, '9'*context.prec,
351
context.Emax-context.prec+1)
354
class Underflow(Inexact, Rounded, Subnormal):
355
"""Numerical underflow with result rounded to 0.
357
This occurs and signals underflow if a result is inexact and the
358
adjusted exponent of the result would be smaller (more negative) than
359
the smallest value that can be handled by the implementation (the value
360
Emin). That is, the result is both inexact and subnormal.
362
The result after an underflow will be a subnormal number rounded, if
363
necessary, so that its exponent is not less than Etiny. This may result
364
in 0 with the sign of the intermediate result and an exponent of Etiny.
366
In all cases, Inexact, Rounded, and Subnormal will also be raised.
369
# List of public traps and flags
370
_signals = [Clamped, DivisionByZero, Inexact, Overflow, Rounded,
371
Underflow, InvalidOperation, Subnormal]
373
# Map conditions (per the spec) to signals
374
_condition_map = {ConversionSyntax:InvalidOperation,
375
DivisionImpossible:InvalidOperation,
376
DivisionUndefined:InvalidOperation,
377
InvalidContext:InvalidOperation}
379
##### Context Functions ##################################################
381
# The getcontext() and setcontext() function manage access to a thread-local
382
# current context. Py2.4 offers direct support for thread locals. If that
383
# is not available, use threading.current_thread() which is slower but will
384
# work for older Pythons. If threads are not part of the build, create a
385
# mock threading object with threading.local() returning the module namespace.
390
# Python was compiled without threads; create a mock object instead
392
class MockThreading(object):
393
def local(self, sys=sys):
394
return sys.modules[__name__]
395
threading = MockThreading()
396
del sys, MockThreading
401
except AttributeError:
403
# To fix reloading, force it to create a new context
404
# Old contexts have different exceptions in their dicts, making problems.
405
if hasattr(threading.current_thread(), '__decimal_context__'):
406
del threading.current_thread().__decimal_context__
408
def setcontext(context):
409
"""Set this thread's context to context."""
410
if context in (DefaultContext, BasicContext, ExtendedContext):
411
context = context.copy()
412
context.clear_flags()
413
threading.current_thread().__decimal_context__ = context
416
"""Returns this thread's context.
418
If this thread does not yet have a context, returns
419
a new context and sets this thread's context.
420
New contexts are copies of DefaultContext.
423
return threading.current_thread().__decimal_context__
424
except AttributeError:
426
threading.current_thread().__decimal_context__ = context
431
local = threading.local()
432
if hasattr(local, '__decimal_context__'):
433
del local.__decimal_context__
435
def getcontext(_local=local):
436
"""Returns this thread's context.
438
If this thread does not yet have a context, returns
439
a new context and sets this thread's context.
440
New contexts are copies of DefaultContext.
443
return _local.__decimal_context__
444
except AttributeError:
446
_local.__decimal_context__ = context
449
def setcontext(context, _local=local):
450
"""Set this thread's context to context."""
451
if context in (DefaultContext, BasicContext, ExtendedContext):
452
context = context.copy()
453
context.clear_flags()
454
_local.__decimal_context__ = context
456
del threading, local # Don't contaminate the namespace
458
def localcontext(ctx=None):
459
"""Return a context manager for a copy of the supplied context
461
Uses a copy of the current context if no context is specified
462
The returned context manager creates a local decimal context
465
with localcontext() as ctx:
467
# Rest of sin calculation algorithm
468
# uses a precision 2 greater than normal
469
return +s # Convert result to normal precision
472
with localcontext(ExtendedContext):
473
# Rest of sin calculation algorithm
474
# uses the Extended Context from the
475
# General Decimal Arithmetic Specification
476
return +s # Convert result to normal context
478
>>> setcontext(DefaultContext)
479
>>> print(getcontext().prec)
481
>>> with localcontext():
482
... ctx = getcontext()
487
>>> with localcontext(ExtendedContext):
488
... print(getcontext().prec)
491
>>> print(getcontext().prec)
494
if ctx is None: ctx = getcontext()
495
return _ContextManager(ctx)
498
##### Decimal class #######################################################
500
# Do not subclass Decimal from numbers.Real and do not register it as such
501
# (because Decimals are not interoperable with floats). See the notes in
502
# numbers.py for more detail.
504
class Decimal(object):
505
"""Floating point class for decimal arithmetic."""
507
__slots__ = ('_exp','_int','_sign', '_is_special')
508
# Generally, the value of the Decimal instance is given by
509
# (-1)**_sign * _int * 10**_exp
510
# Special values are signified by _is_special == True
512
# We're immutable, so use __new__ not __init__
513
def __new__(cls, value="0", context=None):
514
"""Create a decimal point instance.
516
>>> Decimal('3.14') # string input
518
>>> Decimal((0, (3, 1, 4), -2)) # tuple (sign, digit_tuple, exponent)
520
>>> Decimal(314) # int
522
>>> Decimal(Decimal(314)) # another decimal instance
524
>>> Decimal(' 3.14 \\n') # leading and trailing whitespace okay
528
# Note that the coefficient, self._int, is actually stored as
529
# a string rather than as a tuple of digits. This speeds up
530
# the "digits to integer" and "integer to digits" conversions
531
# that are used in almost every arithmetic operation on
532
# Decimals. This is an internal detail: the as_tuple function
533
# and the Decimal constructor still deal with tuples of
536
self = object.__new__(cls)
539
# REs insist on real strings, so we can too.
540
if isinstance(value, str):
541
m = _parser(value.strip())
544
context = getcontext()
545
return context._raise_error(ConversionSyntax,
546
"Invalid literal for Decimal: %r" % value)
548
if m.group('sign') == "-":
552
intpart = m.group('int')
553
if intpart is not None:
555
fracpart = m.group('frac')
556
exp = int(m.group('exp') or '0')
557
if fracpart is not None:
558
self._int = (intpart+fracpart).lstrip('0') or '0'
559
self._exp = exp - len(fracpart)
561
self._int = intpart.lstrip('0') or '0'
563
self._is_special = False
565
diag = m.group('diag')
568
self._int = diag.lstrip('0')
569
if m.group('signal'):
577
self._is_special = True
581
if isinstance(value, int):
587
self._int = str(abs(value))
588
self._is_special = False
591
# From another decimal
592
if isinstance(value, Decimal):
593
self._exp = value._exp
594
self._sign = value._sign
595
self._int = value._int
596
self._is_special = value._is_special
599
# From an internal working value
600
if isinstance(value, _WorkRep):
601
self._sign = value.sign
602
self._int = str(value.int)
603
self._exp = int(value.exp)
604
self._is_special = False
607
# tuple/list conversion (possibly from as_tuple())
608
if isinstance(value, (list,tuple)):
610
raise ValueError('Invalid tuple size in creation of Decimal '
611
'from list or tuple. The list or tuple '
612
'should have exactly three elements.')
613
# process sign. The isinstance test rejects floats
614
if not (isinstance(value[0], int) and value[0] in (0,1)):
615
raise ValueError("Invalid sign. The first value in the tuple "
616
"should be an integer; either 0 for a "
617
"positive number or 1 for a negative number.")
618
self._sign = value[0]
620
# infinity: value[1] is ignored
623
self._is_special = True
625
# process and validate the digits in value[1]
627
for digit in value[1]:
628
if isinstance(digit, int) and 0 <= digit <= 9:
630
if digits or digit != 0:
633
raise ValueError("The second value in the tuple must "
634
"be composed of integers in the range "
636
if value[2] in ('n', 'N'):
637
# NaN: digits form the diagnostic
638
self._int = ''.join(map(str, digits))
640
self._is_special = True
641
elif isinstance(value[2], int):
642
# finite number: digits give the coefficient
643
self._int = ''.join(map(str, digits or [0]))
645
self._is_special = False
647
raise ValueError("The third value in the tuple must "
648
"be an integer, or one of the "
649
"strings 'F', 'n', 'N'.")
652
if isinstance(value, float):
653
raise TypeError("Cannot convert float to Decimal. " +
654
"First convert the float to a string")
656
raise TypeError("Cannot convert %r to Decimal" % value)
658
# @classmethod, but @decorator is not valid Python 2.3 syntax, so
659
# don't use it (see notes on Py2.3 compatibility at top of file)
660
def from_float(cls, f):
661
"""Converts a float to a decimal number, exactly.
663
Note that Decimal.from_float(0.1) is not the same as Decimal('0.1').
664
Since 0.1 is not exactly representable in binary floating point, the
665
value is stored as the nearest representable value which is
666
0x1.999999999999ap-4. The exact equivalent of the value in decimal
667
is 0.1000000000000000055511151231257827021181583404541015625.
669
>>> Decimal.from_float(0.1)
670
Decimal('0.1000000000000000055511151231257827021181583404541015625')
671
>>> Decimal.from_float(float('nan'))
673
>>> Decimal.from_float(float('inf'))
675
>>> Decimal.from_float(-float('inf'))
677
>>> Decimal.from_float(-0.0)
681
if isinstance(f, int): # handle integer inputs
683
if _math.isinf(f) or _math.isnan(f): # raises TypeError if not a float
685
if _math.copysign(1.0, f) == 1.0:
689
n, d = abs(f).as_integer_ratio()
690
k = d.bit_length() - 1
691
result = _dec_from_triple(sign, str(n*5**k), -k)
696
from_float = classmethod(from_float)
699
"""Returns whether the number is not actually one.
713
def _isinfinity(self):
714
"""Returns whether the number is infinite
716
0 if finite or not a number
726
def _check_nans(self, other=None, context=None):
727
"""Returns whether the number is not actually one.
729
if self, other are sNaN, signal
730
if self, other are NaN return nan
733
Done before operations.
736
self_is_nan = self._isnan()
740
other_is_nan = other._isnan()
742
if self_is_nan or other_is_nan:
744
context = getcontext()
747
return context._raise_error(InvalidOperation, 'sNaN',
749
if other_is_nan == 2:
750
return context._raise_error(InvalidOperation, 'sNaN',
753
return self._fix_nan(context)
755
return other._fix_nan(context)
758
def _compare_check_nans(self, other, context):
759
"""Version of _check_nans used for the signaling comparisons
760
compare_signal, __le__, __lt__, __ge__, __gt__.
762
Signal InvalidOperation if either self or other is a (quiet
763
or signaling) NaN. Signaling NaNs take precedence over quiet
766
Return 0 if neither operand is a NaN.
770
context = getcontext()
772
if self._is_special or other._is_special:
774
return context._raise_error(InvalidOperation,
775
'comparison involving sNaN',
777
elif other.is_snan():
778
return context._raise_error(InvalidOperation,
779
'comparison involving sNaN',
782
return context._raise_error(InvalidOperation,
783
'comparison involving NaN',
785
elif other.is_qnan():
786
return context._raise_error(InvalidOperation,
787
'comparison involving NaN',
792
"""Return True if self is nonzero; otherwise return False.
794
NaNs and infinities are considered nonzero.
796
return self._is_special or self._int != '0'
798
def _cmp(self, other):
799
"""Compare the two non-NaN decimal instances self and other.
801
Returns -1 if self < other, 0 if self == other and 1
802
if self > other. This routine is for internal use only."""
804
if self._is_special or other._is_special:
805
self_inf = self._isinfinity()
806
other_inf = other._isinfinity()
807
if self_inf == other_inf:
809
elif self_inf < other_inf:
814
# check for zeros; Decimal('0') == Decimal('-0')
819
return -((-1)**other._sign)
821
return (-1)**self._sign
823
# If different signs, neg one is less
824
if other._sign < self._sign:
826
if self._sign < other._sign:
829
self_adjusted = self.adjusted()
830
other_adjusted = other.adjusted()
831
if self_adjusted == other_adjusted:
832
self_padded = self._int + '0'*(self._exp - other._exp)
833
other_padded = other._int + '0'*(other._exp - self._exp)
834
if self_padded == other_padded:
836
elif self_padded < other_padded:
837
return -(-1)**self._sign
839
return (-1)**self._sign
840
elif self_adjusted > other_adjusted:
841
return (-1)**self._sign
842
else: # self_adjusted < other_adjusted
843
return -((-1)**self._sign)
845
# Note: The Decimal standard doesn't cover rich comparisons for
846
# Decimals. In particular, the specification is silent on the
847
# subject of what should happen for a comparison involving a NaN.
848
# We take the following approach:
850
# == comparisons involving a NaN always return False
851
# != comparisons involving a NaN always return True
852
# <, >, <= and >= comparisons involving a (quiet or signaling)
853
# NaN signal InvalidOperation, and return False if the
854
# InvalidOperation is not trapped.
856
# This behavior is designed to conform as closely as possible to
857
# that specified by IEEE 754.
859
def __eq__(self, other):
860
other = _convert_other(other)
861
if other is NotImplemented:
863
if self.is_nan() or other.is_nan():
865
return self._cmp(other) == 0
867
def __ne__(self, other):
868
other = _convert_other(other)
869
if other is NotImplemented:
871
if self.is_nan() or other.is_nan():
873
return self._cmp(other) != 0
876
def __lt__(self, other, context=None):
877
other = _convert_other(other)
878
if other is NotImplemented:
880
ans = self._compare_check_nans(other, context)
883
return self._cmp(other) < 0
885
def __le__(self, other, context=None):
886
other = _convert_other(other)
887
if other is NotImplemented:
889
ans = self._compare_check_nans(other, context)
892
return self._cmp(other) <= 0
894
def __gt__(self, other, context=None):
895
other = _convert_other(other)
896
if other is NotImplemented:
898
ans = self._compare_check_nans(other, context)
901
return self._cmp(other) > 0
903
def __ge__(self, other, context=None):
904
other = _convert_other(other)
905
if other is NotImplemented:
907
ans = self._compare_check_nans(other, context)
910
return self._cmp(other) >= 0
912
def compare(self, other, context=None):
913
"""Compares one to another.
919
Like __cmp__, but returns Decimal instances.
921
other = _convert_other(other, raiseit=True)
923
# Compare(NaN, NaN) = NaN
924
if (self._is_special or other and other._is_special):
925
ans = self._check_nans(other, context)
929
return Decimal(self._cmp(other))
932
"""x.__hash__() <==> hash(x)"""
933
# Decimal integers must hash the same as the ints
935
# The hash of a nonspecial noninteger Decimal must depend only
936
# on the value of that Decimal, and not on its representation.
937
# For example: hash(Decimal('100E-1')) == hash(Decimal('10')).
940
raise TypeError('Cannot hash a NaN value.')
941
return hash(str(self))
944
if self._isinteger():
945
op = _WorkRep(self.to_integral_value())
946
# to make computation feasible for Decimals with large
947
# exponent, we use the fact that hash(n) == hash(m) for
948
# any two nonzero integers n and m such that (i) n and m
949
# have the same sign, and (ii) n is congruent to m modulo
950
# 2**64-1. So we can replace hash((-1)**s*c*10**e) with
951
# hash((-1)**s*c*pow(10, e, 2**64-1).
952
return hash((-1)**op.sign*op.int*pow(10, op.exp, 2**64-1))
953
# The value of a nonzero nonspecial Decimal instance is
954
# faithfully represented by the triple consisting of its sign,
955
# its adjusted exponent, and its coefficient with trailing
957
return hash((self._sign,
958
self._exp+len(self._int),
959
self._int.rstrip('0')))
962
"""Represents the number as a triple tuple.
964
To show the internals exactly as they are.
966
return DecimalTuple(self._sign, tuple(map(int, self._int)), self._exp)
969
"""Represents the number as an instance of Decimal."""
970
# Invariant: eval(repr(d)) == d
971
return "Decimal('%s')" % str(self)
973
def __str__(self, eng=False, context=None):
974
"""Return string representation of the number in scientific notation.
976
Captures all of the information in the underlying representation.
979
sign = ['', '-'][self._sign]
982
return sign + 'Infinity'
983
elif self._exp == 'n':
984
return sign + 'NaN' + self._int
985
else: # self._exp == 'N'
986
return sign + 'sNaN' + self._int
988
# number of digits of self._int to left of decimal point
989
leftdigits = self._exp + len(self._int)
991
# dotplace is number of digits of self._int to the left of the
992
# decimal point in the mantissa of the output string (that is,
993
# after adjusting the exponent)
994
if self._exp <= 0 and leftdigits > -6:
995
# no exponent required
996
dotplace = leftdigits
998
# usual scientific notation: 1 digit on left of the point
1000
elif self._int == '0':
1001
# engineering notation, zero
1002
dotplace = (leftdigits + 1) % 3 - 1
1004
# engineering notation, nonzero
1005
dotplace = (leftdigits - 1) % 3 + 1
1009
fracpart = '.' + '0'*(-dotplace) + self._int
1010
elif dotplace >= len(self._int):
1011
intpart = self._int+'0'*(dotplace-len(self._int))
1014
intpart = self._int[:dotplace]
1015
fracpart = '.' + self._int[dotplace:]
1016
if leftdigits == dotplace:
1020
context = getcontext()
1021
exp = ['e', 'E'][context.capitals] + "%+d" % (leftdigits-dotplace)
1023
return sign + intpart + fracpart + exp
1025
def to_eng_string(self, context=None):
1026
"""Convert to engineering-type string.
1028
Engineering notation has an exponent which is a multiple of 3, so there
1029
are up to 3 digits left of the decimal place.
1031
Same rules for when in exponential and when as a value as in __str__.
1033
return self.__str__(eng=True, context=context)
1035
def __neg__(self, context=None):
1036
"""Returns a copy with the sign switched.
1038
Rounds, if it has reason.
1040
if self._is_special:
1041
ans = self._check_nans(context=context)
1046
# -Decimal('0') is Decimal('0'), not Decimal('-0')
1047
ans = self.copy_abs()
1049
ans = self.copy_negate()
1052
context = getcontext()
1053
return ans._fix(context)
1055
def __pos__(self, context=None):
1056
"""Returns a copy, unless it is a sNaN.
1058
Rounds the number (if more then precision digits)
1060
if self._is_special:
1061
ans = self._check_nans(context=context)
1067
ans = self.copy_abs()
1072
context = getcontext()
1073
return ans._fix(context)
1075
def __abs__(self, round=True, context=None):
1076
"""Returns the absolute value of self.
1078
If the keyword argument 'round' is false, do not round. The
1079
expression self.__abs__(round=False) is equivalent to
1083
return self.copy_abs()
1085
if self._is_special:
1086
ans = self._check_nans(context=context)
1091
ans = self.__neg__(context=context)
1093
ans = self.__pos__(context=context)
1097
def __add__(self, other, context=None):
1098
"""Returns self + other.
1100
-INF + INF (or the reverse) cause InvalidOperation errors.
1102
other = _convert_other(other)
1103
if other is NotImplemented:
1107
context = getcontext()
1109
if self._is_special or other._is_special:
1110
ans = self._check_nans(other, context)
1114
if self._isinfinity():
1115
# If both INF, same sign => same as both, opposite => error.
1116
if self._sign != other._sign and other._isinfinity():
1117
return context._raise_error(InvalidOperation, '-INF + INF')
1118
return Decimal(self)
1119
if other._isinfinity():
1120
return Decimal(other) # Can't both be infinity here
1122
exp = min(self._exp, other._exp)
1124
if context.rounding == ROUND_FLOOR and self._sign != other._sign:
1125
# If the answer is 0, the sign should be negative, in this case.
1128
if not self and not other:
1129
sign = min(self._sign, other._sign)
1132
ans = _dec_from_triple(sign, '0', exp)
1133
ans = ans._fix(context)
1136
exp = max(exp, other._exp - context.prec-1)
1137
ans = other._rescale(exp, context.rounding)
1138
ans = ans._fix(context)
1141
exp = max(exp, self._exp - context.prec-1)
1142
ans = self._rescale(exp, context.rounding)
1143
ans = ans._fix(context)
1146
op1 = _WorkRep(self)
1147
op2 = _WorkRep(other)
1148
op1, op2 = _normalize(op1, op2, context.prec)
1151
if op1.sign != op2.sign:
1152
# Equal and opposite
1153
if op1.int == op2.int:
1154
ans = _dec_from_triple(negativezero, '0', exp)
1155
ans = ans._fix(context)
1157
if op1.int < op2.int:
1159
# OK, now abs(op1) > abs(op2)
1162
op1.sign, op2.sign = op2.sign, op1.sign
1165
# So we know the sign, and op1 > 0.
1168
op1.sign, op2.sign = (0, 0)
1171
# Now, op1 > abs(op2) > 0
1174
result.int = op1.int + op2.int
1176
result.int = op1.int - op2.int
1178
result.exp = op1.exp
1179
ans = Decimal(result)
1180
ans = ans._fix(context)
1185
def __sub__(self, other, context=None):
1186
"""Return self - other"""
1187
other = _convert_other(other)
1188
if other is NotImplemented:
1191
if self._is_special or other._is_special:
1192
ans = self._check_nans(other, context=context)
1196
# self - other is computed as self + other.copy_negate()
1197
return self.__add__(other.copy_negate(), context=context)
1199
def __rsub__(self, other, context=None):
1200
"""Return other - self"""
1201
other = _convert_other(other)
1202
if other is NotImplemented:
1205
return other.__sub__(self, context=context)
1207
def __mul__(self, other, context=None):
1208
"""Return self * other.
1210
(+-) INF * 0 (or its reverse) raise InvalidOperation.
1212
other = _convert_other(other)
1213
if other is NotImplemented:
1217
context = getcontext()
1219
resultsign = self._sign ^ other._sign
1221
if self._is_special or other._is_special:
1222
ans = self._check_nans(other, context)
1226
if self._isinfinity():
1228
return context._raise_error(InvalidOperation, '(+-)INF * 0')
1229
return _SignedInfinity[resultsign]
1231
if other._isinfinity():
1233
return context._raise_error(InvalidOperation, '0 * (+-)INF')
1234
return _SignedInfinity[resultsign]
1236
resultexp = self._exp + other._exp
1238
# Special case for multiplying by zero
1239
if not self or not other:
1240
ans = _dec_from_triple(resultsign, '0', resultexp)
1241
# Fixing in case the exponent is out of bounds
1242
ans = ans._fix(context)
1245
# Special case for multiplying by power of 10
1246
if self._int == '1':
1247
ans = _dec_from_triple(resultsign, other._int, resultexp)
1248
ans = ans._fix(context)
1250
if other._int == '1':
1251
ans = _dec_from_triple(resultsign, self._int, resultexp)
1252
ans = ans._fix(context)
1255
op1 = _WorkRep(self)
1256
op2 = _WorkRep(other)
1258
ans = _dec_from_triple(resultsign, str(op1.int * op2.int), resultexp)
1259
ans = ans._fix(context)
1264
def __truediv__(self, other, context=None):
1265
"""Return self / other."""
1266
other = _convert_other(other)
1267
if other is NotImplemented:
1268
return NotImplemented
1271
context = getcontext()
1273
sign = self._sign ^ other._sign
1275
if self._is_special or other._is_special:
1276
ans = self._check_nans(other, context)
1280
if self._isinfinity() and other._isinfinity():
1281
return context._raise_error(InvalidOperation, '(+-)INF/(+-)INF')
1283
if self._isinfinity():
1284
return _SignedInfinity[sign]
1286
if other._isinfinity():
1287
context._raise_error(Clamped, 'Division by infinity')
1288
return _dec_from_triple(sign, '0', context.Etiny())
1290
# Special cases for zeroes
1293
return context._raise_error(DivisionUndefined, '0 / 0')
1294
return context._raise_error(DivisionByZero, 'x / 0', sign)
1297
exp = self._exp - other._exp
1300
# OK, so neither = 0, INF or NaN
1301
shift = len(other._int) - len(self._int) + context.prec + 1
1302
exp = self._exp - other._exp - shift
1303
op1 = _WorkRep(self)
1304
op2 = _WorkRep(other)
1306
coeff, remainder = divmod(op1.int * 10**shift, op2.int)
1308
coeff, remainder = divmod(op1.int, op2.int * 10**-shift)
1310
# result is not exact; adjust to ensure correct rounding
1314
# result is exact; get as close to ideal exponent as possible
1315
ideal_exp = self._exp - other._exp
1316
while exp < ideal_exp and coeff % 10 == 0:
1320
ans = _dec_from_triple(sign, str(coeff), exp)
1321
return ans._fix(context)
1323
def _divide(self, other, context):
1324
"""Return (self // other, self % other), to context.prec precision.
1326
Assumes that neither self nor other is a NaN, that self is not
1327
infinite and that other is nonzero.
1329
sign = self._sign ^ other._sign
1330
if other._isinfinity():
1331
ideal_exp = self._exp
1333
ideal_exp = min(self._exp, other._exp)
1335
expdiff = self.adjusted() - other.adjusted()
1336
if not self or other._isinfinity() or expdiff <= -2:
1337
return (_dec_from_triple(sign, '0', 0),
1338
self._rescale(ideal_exp, context.rounding))
1339
if expdiff <= context.prec:
1340
op1 = _WorkRep(self)
1341
op2 = _WorkRep(other)
1342
if op1.exp >= op2.exp:
1343
op1.int *= 10**(op1.exp - op2.exp)
1345
op2.int *= 10**(op2.exp - op1.exp)
1346
q, r = divmod(op1.int, op2.int)
1347
if q < 10**context.prec:
1348
return (_dec_from_triple(sign, str(q), 0),
1349
_dec_from_triple(self._sign, str(r), ideal_exp))
1351
# Here the quotient is too large to be representable
1352
ans = context._raise_error(DivisionImpossible,
1353
'quotient too large in //, % or divmod')
1356
def __rtruediv__(self, other, context=None):
1357
"""Swaps self/other and returns __truediv__."""
1358
other = _convert_other(other)
1359
if other is NotImplemented:
1361
return other.__truediv__(self, context=context)
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
context = getcontext()
1559
return context._raise_error(InvalidContext)
1560
elif self._isinfinity():
1561
raise OverflowError("Cannot convert infinity to int")
1562
s = (-1)**self._sign
1564
return s*int(self._int)*10**self._exp
1566
return s*int(self._int[:self._exp] or '0')
1572
real = property(real)
1576
imag = property(imag)
1578
def conjugate(self):
1581
def __complex__(self):
1582
return complex(float(self))
1584
def _fix_nan(self, context):
1585
"""Decapitate the payload of a NaN to fit the context"""
1588
# maximum length of payload is precision if _clamp=0,
1589
# precision-1 if _clamp=1.
1590
max_payload_len = context.prec - context._clamp
1591
if len(payload) > max_payload_len:
1592
payload = payload[len(payload)-max_payload_len:].lstrip('0')
1593
return _dec_from_triple(self._sign, payload, self._exp, True)
1594
return Decimal(self)
1596
def _fix(self, context):
1597
"""Round if it is necessary to keep self within prec precision.
1599
Rounds and fixes the exponent. Does not raise on a sNaN.
1602
self - Decimal instance
1603
context - context used.
1606
if self._is_special:
1608
# decapitate payload if necessary
1609
return self._fix_nan(context)
1611
# self is +/-Infinity; return unaltered
1612
return Decimal(self)
1614
# if self is zero then exponent should be between Etiny and
1615
# Emax if _clamp==0, and between Etiny and Etop if _clamp==1.
1616
Etiny = context.Etiny()
1617
Etop = context.Etop()
1619
exp_max = [context.Emax, Etop][context._clamp]
1620
new_exp = min(max(self._exp, Etiny), exp_max)
1621
if new_exp != self._exp:
1622
context._raise_error(Clamped)
1623
return _dec_from_triple(self._sign, '0', new_exp)
1625
return Decimal(self)
1627
# exp_min is the smallest allowable exponent of the result,
1628
# equal to max(self.adjusted()-context.prec+1, Etiny)
1629
exp_min = len(self._int) + self._exp - context.prec
1631
# overflow: exp_min > Etop iff self.adjusted() > Emax
1632
context._raise_error(Inexact)
1633
context._raise_error(Rounded)
1634
return context._raise_error(Overflow, 'above Emax', self._sign)
1635
self_is_subnormal = exp_min < Etiny
1636
if self_is_subnormal:
1637
context._raise_error(Subnormal)
1640
# round if self has too many digits
1641
if self._exp < exp_min:
1642
context._raise_error(Rounded)
1643
digits = len(self._int) + self._exp - exp_min
1645
self = _dec_from_triple(self._sign, '1', exp_min-1)
1647
this_function = getattr(self, self._pick_rounding_function[context.rounding])
1648
changed = this_function(digits)
1649
coeff = self._int[:digits] or '0'
1651
coeff = str(int(coeff)+1)
1652
ans = _dec_from_triple(self._sign, coeff, exp_min)
1655
context._raise_error(Inexact)
1656
if self_is_subnormal:
1657
context._raise_error(Underflow)
1659
# raise Clamped on underflow to 0
1660
context._raise_error(Clamped)
1661
elif len(ans._int) == context.prec+1:
1662
# we get here only if rescaling rounds the
1663
# cofficient up to exactly 10**context.prec
1665
ans = _dec_from_triple(ans._sign,
1666
ans._int[:-1], ans._exp+1)
1668
# Inexact and Rounded have already been raised
1669
ans = context._raise_error(Overflow, 'above Emax',
1673
# fold down if _clamp == 1 and self has too few digits
1674
if context._clamp == 1 and self._exp > Etop:
1675
context._raise_error(Clamped)
1676
self_padded = self._int + '0'*(self._exp - Etop)
1677
return _dec_from_triple(self._sign, self_padded, Etop)
1679
# here self was representable to begin with; return unchanged
1680
return Decimal(self)
1682
_pick_rounding_function = {}
1684
# for each of the rounding functions below:
1685
# self is a finite, nonzero Decimal
1686
# prec is an integer satisfying 0 <= prec < len(self._int)
1688
# each function returns either -1, 0, or 1, as follows:
1689
# 1 indicates that self should be rounded up (away from zero)
1690
# 0 indicates that self should be truncated, and that all the
1691
# digits to be truncated are zeros (so the value is unchanged)
1692
# -1 indicates that there are nonzero digits to be truncated
1694
def _round_down(self, prec):
1695
"""Also known as round-towards-0, truncate."""
1696
if _all_zeros(self._int, prec):
1701
def _round_up(self, prec):
1702
"""Rounds away from 0."""
1703
return -self._round_down(prec)
1705
def _round_half_up(self, prec):
1706
"""Rounds 5 up (away from 0)"""
1707
if self._int[prec] in '56789':
1709
elif _all_zeros(self._int, prec):
1714
def _round_half_down(self, prec):
1716
if _exact_half(self._int, prec):
1719
return self._round_half_up(prec)
1721
def _round_half_even(self, prec):
1722
"""Round 5 to even, rest to nearest."""
1723
if _exact_half(self._int, prec) and \
1724
(prec == 0 or self._int[prec-1] in '02468'):
1727
return self._round_half_up(prec)
1729
def _round_ceiling(self, prec):
1730
"""Rounds up (not away from 0 if negative.)"""
1732
return self._round_down(prec)
1734
return -self._round_down(prec)
1736
def _round_floor(self, prec):
1737
"""Rounds down (not towards 0 if negative)"""
1739
return self._round_down(prec)
1741
return -self._round_down(prec)
1743
def _round_05up(self, prec):
1744
"""Round down unless digit prec-1 is 0 or 5."""
1745
if prec and self._int[prec-1] not in '05':
1746
return self._round_down(prec)
1748
return -self._round_down(prec)
1750
def __round__(self, n=None):
1751
"""Round self to the nearest integer, or to a given precision.
1753
If only one argument is supplied, round a finite Decimal
1754
instance self to the nearest integer. If self is infinite or
1755
a NaN then a Python exception is raised. If self is finite
1756
and lies exactly halfway between two integers then it is
1757
rounded to the integer with even last digit.
1759
>>> round(Decimal('123.456'))
1761
>>> round(Decimal('-456.789'))
1763
>>> round(Decimal('-3.0'))
1765
>>> round(Decimal('2.5'))
1767
>>> round(Decimal('3.5'))
1769
>>> round(Decimal('Inf'))
1770
Traceback (most recent call last):
1772
OverflowError: cannot round an infinity
1773
>>> round(Decimal('NaN'))
1774
Traceback (most recent call last):
1776
ValueError: cannot round a NaN
1778
If a second argument n is supplied, self is rounded to n
1779
decimal places using the rounding mode for the current
1782
For an integer n, round(self, -n) is exactly equivalent to
1783
self.quantize(Decimal('1En')).
1785
>>> round(Decimal('123.456'), 0)
1787
>>> round(Decimal('123.456'), 2)
1789
>>> round(Decimal('123.456'), -2)
1791
>>> round(Decimal('-Infinity'), 37)
1793
>>> round(Decimal('sNaN123'), 0)
1798
# two-argument form: use the equivalent quantize call
1799
if not isinstance(n, int):
1800
raise TypeError('Second argument to round should be integral')
1801
exp = _dec_from_triple(0, '1', -n)
1802
return self.quantize(exp)
1805
if self._is_special:
1807
raise ValueError("cannot round a NaN")
1809
raise OverflowError("cannot round an infinity")
1810
return int(self._rescale(0, ROUND_HALF_EVEN))
1812
def __floor__(self):
1813
"""Return the floor of self, as an integer.
1815
For a finite Decimal instance self, return the greatest
1816
integer n such that n <= self. If self is infinite or a NaN
1817
then a Python exception is raised.
1820
if self._is_special:
1822
raise ValueError("cannot round a NaN")
1824
raise OverflowError("cannot round an infinity")
1825
return int(self._rescale(0, ROUND_FLOOR))
1828
"""Return the ceiling of self, as an integer.
1830
For a finite Decimal instance self, return the least integer n
1831
such that n >= self. If self is infinite or a NaN then a
1832
Python exception is raised.
1835
if self._is_special:
1837
raise ValueError("cannot round a NaN")
1839
raise OverflowError("cannot round an infinity")
1840
return int(self._rescale(0, ROUND_CEILING))
1842
def fma(self, other, third, context=None):
1843
"""Fused multiply-add.
1845
Returns self*other+third with no rounding of the intermediate
1848
self and other are multiplied together, with no rounding of
1849
the result. The third operand is then added to the result,
1850
and a single final rounding is performed.
1853
other = _convert_other(other, raiseit=True)
1855
# compute product; raise InvalidOperation if either operand is
1856
# a signaling NaN or if the product is zero times infinity.
1857
if self._is_special or other._is_special:
1859
context = getcontext()
1860
if self._exp == 'N':
1861
return context._raise_error(InvalidOperation, 'sNaN', self)
1862
if other._exp == 'N':
1863
return context._raise_error(InvalidOperation, 'sNaN', other)
1864
if self._exp == 'n':
1866
elif other._exp == 'n':
1868
elif self._exp == 'F':
1870
return context._raise_error(InvalidOperation,
1872
product = _SignedInfinity[self._sign ^ other._sign]
1873
elif other._exp == 'F':
1875
return context._raise_error(InvalidOperation,
1877
product = _SignedInfinity[self._sign ^ other._sign]
1879
product = _dec_from_triple(self._sign ^ other._sign,
1880
str(int(self._int) * int(other._int)),
1881
self._exp + other._exp)
1883
third = _convert_other(third, raiseit=True)
1884
return product.__add__(third, context)
1886
def _power_modulo(self, other, modulo, context=None):
1887
"""Three argument version of __pow__"""
1889
# if can't convert other and modulo to Decimal, raise
1890
# TypeError; there's no point returning NotImplemented (no
1891
# equivalent of __rpow__ for three argument pow)
1892
other = _convert_other(other, raiseit=True)
1893
modulo = _convert_other(modulo, raiseit=True)
1896
context = getcontext()
1898
# deal with NaNs: if there are any sNaNs then first one wins,
1899
# (i.e. behaviour for NaNs is identical to that of fma)
1900
self_is_nan = self._isnan()
1901
other_is_nan = other._isnan()
1902
modulo_is_nan = modulo._isnan()
1903
if self_is_nan or other_is_nan or modulo_is_nan:
1904
if self_is_nan == 2:
1905
return context._raise_error(InvalidOperation, 'sNaN',
1907
if other_is_nan == 2:
1908
return context._raise_error(InvalidOperation, 'sNaN',
1910
if modulo_is_nan == 2:
1911
return context._raise_error(InvalidOperation, 'sNaN',
1914
return self._fix_nan(context)
1916
return other._fix_nan(context)
1917
return modulo._fix_nan(context)
1919
# check inputs: we apply same restrictions as Python's pow()
1920
if not (self._isinteger() and
1921
other._isinteger() and
1922
modulo._isinteger()):
1923
return context._raise_error(InvalidOperation,
1924
'pow() 3rd argument not allowed '
1925
'unless all arguments are integers')
1927
return context._raise_error(InvalidOperation,
1928
'pow() 2nd argument cannot be '
1929
'negative when 3rd argument specified')
1931
return context._raise_error(InvalidOperation,
1932
'pow() 3rd argument cannot be 0')
1934
# additional restriction for decimal: the modulus must be less
1935
# than 10**prec in absolute value
1936
if modulo.adjusted() >= context.prec:
1937
return context._raise_error(InvalidOperation,
1938
'insufficient precision: pow() 3rd '
1939
'argument must not have more than '
1942
# define 0**0 == NaN, for consistency with two-argument pow
1943
# (even though it hurts!)
1944
if not other and not self:
1945
return context._raise_error(InvalidOperation,
1946
'at least one of pow() 1st argument '
1947
'and 2nd argument must be nonzero ;'
1948
'0**0 is not defined')
1950
# compute sign of result
1956
# convert modulo to a Python integer, and self and other to
1957
# Decimal integers (i.e. force their exponents to be >= 0)
1958
modulo = abs(int(modulo))
1959
base = _WorkRep(self.to_integral_value())
1960
exponent = _WorkRep(other.to_integral_value())
1962
# compute result using integer pow()
1963
base = (base.int % modulo * pow(10, base.exp, modulo)) % modulo
1964
for i in range(exponent.exp):
1965
base = pow(base, 10, modulo)
1966
base = pow(base, exponent.int, modulo)
1968
return _dec_from_triple(sign, str(base), 0)
1970
def _power_exact(self, other, p):
1971
"""Attempt to compute self**other exactly.
1973
Given Decimals self and other and an integer p, attempt to
1974
compute an exact result for the power self**other, with p
1975
digits of precision. Return None if self**other is not
1976
exactly representable in p digits.
1978
Assumes that elimination of special cases has already been
1979
performed: self and other must both be nonspecial; self must
1980
be positive and not numerically equal to 1; other must be
1981
nonzero. For efficiency, other._exp should not be too large,
1982
so that 10**abs(other._exp) is a feasible calculation."""
1984
# In the comments below, we write x for the value of self and
1985
# y for the value of other. Write x = xc*10**xe and y =
1988
# The main purpose of this method is to identify the *failure*
1989
# of x**y to be exactly representable with as little effort as
1990
# possible. So we look for cheap and easy tests that
1991
# eliminate the possibility of x**y being exact. Only if all
1992
# these tests are passed do we go on to actually compute x**y.
1994
# Here's the main idea. First normalize both x and y. We
1995
# express y as a rational m/n, with m and n relatively prime
1996
# and n>0. Then for x**y to be exactly representable (at
1997
# *any* precision), xc must be the nth power of a positive
1998
# integer and xe must be divisible by n. If m is negative
1999
# then additionally xc must be a power of either 2 or 5, hence
2000
# a power of 2**n or 5**n.
2002
# There's a limit to how small |y| can be: if y=m/n as above
2005
# (1) if xc != 1 then for the result to be representable we
2006
# need xc**(1/n) >= 2, and hence also xc**|y| >= 2. So
2007
# if |y| <= 1/nbits(xc) then xc < 2**nbits(xc) <=
2008
# 2**(1/|y|), hence xc**|y| < 2 and the result is not
2011
# (2) if xe != 0, |xe|*(1/n) >= 1, so |xe|*|y| >= 1. Hence if
2012
# |y| < 1/|xe| then the result is not representable.
2014
# Note that since x is not equal to 1, at least one of (1) and
2015
# (2) must apply. Now |y| < 1/nbits(xc) iff |yc|*nbits(xc) <
2016
# 10**-ye iff len(str(|yc|*nbits(xc)) <= -ye.
2018
# There's also a limit to how large y can be, at least if it's
2019
# positive: the normalized result will have coefficient xc**y,
2020
# so if it's representable then xc**y < 10**p, and y <
2021
# p/log10(xc). Hence if y*log10(xc) >= p then the result is
2022
# not exactly representable.
2024
# if len(str(abs(yc*xe)) <= -ye then abs(yc*xe) < 10**-ye,
2025
# so |y| < 1/xe and the result is not representable.
2026
# Similarly, len(str(abs(yc)*xc_bits)) <= -ye implies |y|
2030
xc, xe = x.int, x.exp
2036
yc, ye = y.int, y.exp
2041
# case where xc == 1: result is 10**(xe*y), with xe*y
2042
# required to be an integer
2045
exponent = xe*yc*10**ye
2047
exponent, remainder = divmod(xe*yc, 10**-ye)
2051
exponent = -exponent
2052
# if other is a nonnegative integer, use ideal exponent
2053
if other._isinteger() and other._sign == 0:
2054
ideal_exponent = self._exp*int(other)
2055
zeros = min(exponent-ideal_exponent, p-1)
2058
return _dec_from_triple(0, '1' + '0'*zeros, exponent-zeros)
2060
# case where y is negative: xc must be either a power
2061
# of 2 or a power of 5.
2063
last_digit = xc % 10
2064
if last_digit in (2,4,6,8):
2065
# quick test for power of 2
2068
# now xc is a power of 2; e is its exponent
2070
# find e*y and xe*y; both must be integers
2072
y_as_int = yc*10**ye
2077
e, remainder = divmod(e*yc, ten_pow)
2080
xe, remainder = divmod(xe*yc, ten_pow)
2084
if e*65 >= p*93: # 93/65 > log(10)/log(5)
2088
elif last_digit == 5:
2089
# e >= log_5(xc) if xc is a power of 5; we have
2090
# equality all the way up to xc=5**2658
2091
e = _nbits(xc)*28//65
2092
xc, remainder = divmod(5**e, xc)
2099
y_as_integer = yc*10**ye
2101
xe = xe*y_as_integer
2104
e, remainder = divmod(e*yc, ten_pow)
2107
xe, remainder = divmod(xe*yc, ten_pow)
2110
if e*3 >= p*10: # 10/3 > log(10)/log(2)
2119
return _dec_from_triple(0, str(xc), xe)
2121
# now y is positive; find m and n such that y = m/n
2125
if xe != 0 and len(str(abs(yc*xe))) <= -ye:
2127
xc_bits = _nbits(xc)
2128
if xc != 1 and len(str(abs(yc)*xc_bits)) <= -ye:
2130
m, n = yc, 10**(-ye)
2131
while m % 2 == n % 2 == 0:
2134
while m % 5 == n % 5 == 0:
2138
# compute nth root of xc*10**xe
2140
# if 1 < xc < 2**n then xc isn't an nth power
2141
if xc != 1 and xc_bits <= n:
2144
xe, rem = divmod(xe, n)
2148
# compute nth root of xc using Newton's method
2149
a = 1 << -(-_nbits(xc)//n) # initial estimate
2151
q, r = divmod(xc, a**(n-1))
2155
a = (a*(n-1) + q)//n
2156
if not (a == q and r == 0):
2160
# now xc*10**xe is the nth root of the original xc*10**xe
2161
# compute mth power of xc*10**xe
2163
# if m > p*100//_log10_lb(xc) then m > p/log10(xc), hence xc**m >
2164
# 10**p and the result is not representable.
2165
if xc > 1 and m > p*100//_log10_lb(xc):
2172
# by this point the result *is* exactly representable
2173
# adjust the exponent to get as close as possible to the ideal
2174
# exponent, if necessary
2176
if other._isinteger() and other._sign == 0:
2177
ideal_exponent = self._exp*int(other)
2178
zeros = min(xe-ideal_exponent, p-len(str_xc))
2181
return _dec_from_triple(0, str_xc+'0'*zeros, xe-zeros)
2183
def __pow__(self, other, modulo=None, context=None):
2184
"""Return self ** other [ % modulo].
2186
With two arguments, compute self**other.
2188
With three arguments, compute (self**other) % modulo. For the
2189
three argument form, the following restrictions on the
2192
- all three arguments must be integral
2193
- other must be nonnegative
2194
- either self or other (or both) must be nonzero
2195
- modulo must be nonzero and must have at most p digits,
2196
where p is the context precision.
2198
If any of these restrictions is violated the InvalidOperation
2201
The result of pow(self, other, modulo) is identical to the
2202
result that would be obtained by computing (self**other) %
2203
modulo with unbounded precision, but is computed more
2204
efficiently. It is always exact.
2207
if modulo is not None:
2208
return self._power_modulo(other, modulo, context)
2210
other = _convert_other(other)
2211
if other is NotImplemented:
2215
context = getcontext()
2217
# either argument is a NaN => result is NaN
2218
ans = self._check_nans(other, context)
2222
# 0**0 = NaN (!), x**0 = 1 for nonzero x (including +/-Infinity)
2225
return context._raise_error(InvalidOperation, '0 ** 0')
2229
# result has sign 1 iff self._sign is 1 and other is an odd integer
2232
if other._isinteger():
2233
if not other._iseven():
2236
# -ve**noninteger = NaN
2237
# (-0)**noninteger = 0**noninteger
2239
return context._raise_error(InvalidOperation,
2240
'x ** y with x negative and y not an integer')
2241
# negate self, without doing any unwanted rounding
2242
self = self.copy_negate()
2244
# 0**(+ve or Inf)= 0; 0**(-ve or -Inf) = Infinity
2246
if other._sign == 0:
2247
return _dec_from_triple(result_sign, '0', 0)
2249
return _SignedInfinity[result_sign]
2251
# Inf**(+ve or Inf) = Inf; Inf**(-ve or -Inf) = 0
2252
if self._isinfinity():
2253
if other._sign == 0:
2254
return _SignedInfinity[result_sign]
2256
return _dec_from_triple(result_sign, '0', 0)
2258
# 1**other = 1, but the choice of exponent and the flags
2259
# depend on the exponent of self, and on whether other is a
2260
# positive integer, a negative integer, or neither
2262
if other._isinteger():
2263
# exp = max(self._exp*max(int(other), 0),
2264
# 1-context.prec) but evaluating int(other) directly
2265
# is dangerous until we know other is small (other
2266
# could be 1e999999999)
2267
if other._sign == 1:
2269
elif other > context.prec:
2270
multiplier = context.prec
2272
multiplier = int(other)
2274
exp = self._exp * multiplier
2275
if exp < 1-context.prec:
2276
exp = 1-context.prec
2277
context._raise_error(Rounded)
2279
context._raise_error(Inexact)
2280
context._raise_error(Rounded)
2281
exp = 1-context.prec
2283
return _dec_from_triple(result_sign, '1'+'0'*-exp, exp)
2285
# compute adjusted exponent of self
2286
self_adj = self.adjusted()
2288
# self ** infinity is infinity if self > 1, 0 if self < 1
2289
# self ** -infinity is infinity if self < 1, 0 if self > 1
2290
if other._isinfinity():
2291
if (other._sign == 0) == (self_adj < 0):
2292
return _dec_from_triple(result_sign, '0', 0)
2294
return _SignedInfinity[result_sign]
2296
# from here on, the result always goes through the call
2297
# to _fix at the end of this function.
2300
# crude test to catch cases of extreme overflow/underflow. If
2301
# log10(self)*other >= 10**bound and bound >= len(str(Emax))
2302
# then 10**bound >= 10**len(str(Emax)) >= Emax+1 and hence
2303
# self**other >= 10**(Emax+1), so overflow occurs. The test
2304
# for underflow is similar.
2305
bound = self._log10_exp_bound() + other.adjusted()
2306
if (self_adj >= 0) == (other._sign == 0):
2307
# self > 1 and other +ve, or self < 1 and other -ve
2308
# possibility of overflow
2309
if bound >= len(str(context.Emax)):
2310
ans = _dec_from_triple(result_sign, '1', context.Emax+1)
2312
# self > 1 and other -ve, or self < 1 and other +ve
2313
# possibility of underflow to 0
2314
Etiny = context.Etiny()
2315
if bound >= len(str(-Etiny)):
2316
ans = _dec_from_triple(result_sign, '1', Etiny-1)
2318
# try for an exact result with precision +1
2320
ans = self._power_exact(other, context.prec + 1)
2321
if ans is not None and result_sign == 1:
2322
ans = _dec_from_triple(1, ans._int, ans._exp)
2324
# usual case: inexact result, x**y computed directly as exp(y*log(x))
2328
xc, xe = x.int, x.exp
2330
yc, ye = y.int, y.exp
2334
# compute correctly rounded result: start with precision +3,
2335
# then increase precision until result is unambiguously roundable
2338
coeff, exp = _dpower(xc, xe, yc, ye, p+extra)
2339
if coeff % (5*10**(len(str(coeff))-p-1)):
2343
ans = _dec_from_triple(result_sign, str(coeff), exp)
2345
# the specification says that for non-integer other we need to
2346
# raise Inexact, even when the result is actually exact. In
2347
# the same way, we need to raise Underflow here if the result
2348
# is subnormal. (The call to _fix will take care of raising
2349
# Rounded and Subnormal, as usual.)
2350
if not other._isinteger():
2351
context._raise_error(Inexact)
2352
# pad with zeros up to length context.prec+1 if necessary
2353
if len(ans._int) <= context.prec:
2354
expdiff = context.prec+1 - len(ans._int)
2355
ans = _dec_from_triple(ans._sign, ans._int+'0'*expdiff,
2357
if ans.adjusted() < context.Emin:
2358
context._raise_error(Underflow)
2360
# unlike exp, ln and log10, the power function respects the
2361
# rounding mode; no need to use ROUND_HALF_EVEN here
2362
ans = ans._fix(context)
2365
def __rpow__(self, other, context=None):
2366
"""Swaps self/other and returns __pow__."""
2367
other = _convert_other(other)
2368
if other is NotImplemented:
2370
return other.__pow__(self, context=context)
2372
def normalize(self, context=None):
2373
"""Normalize- strip trailing 0s, change anything equal to 0 to 0e0"""
2376
context = getcontext()
2378
if self._is_special:
2379
ans = self._check_nans(context=context)
2383
dup = self._fix(context)
2384
if dup._isinfinity():
2388
return _dec_from_triple(dup._sign, '0', 0)
2389
exp_max = [context.Emax, context.Etop()][context._clamp]
2392
while dup._int[end-1] == '0' and exp < exp_max:
2395
return _dec_from_triple(dup._sign, dup._int[:end], exp)
2397
def quantize(self, exp, rounding=None, context=None, watchexp=True):
2398
"""Quantize self so its exponent is the same as that of exp.
2400
Similar to self._rescale(exp._exp) but with error checking.
2402
exp = _convert_other(exp, raiseit=True)
2405
context = getcontext()
2406
if rounding is None:
2407
rounding = context.rounding
2409
if self._is_special or exp._is_special:
2410
ans = self._check_nans(exp, context)
2414
if exp._isinfinity() or self._isinfinity():
2415
if exp._isinfinity() and self._isinfinity():
2416
return Decimal(self) # if both are inf, it is OK
2417
return context._raise_error(InvalidOperation,
2418
'quantize with one INF')
2420
# if we're not watching exponents, do a simple rescale
2422
ans = self._rescale(exp._exp, rounding)
2423
# raise Inexact and Rounded where appropriate
2424
if ans._exp > self._exp:
2425
context._raise_error(Rounded)
2427
context._raise_error(Inexact)
2430
# exp._exp should be between Etiny and Emax
2431
if not (context.Etiny() <= exp._exp <= context.Emax):
2432
return context._raise_error(InvalidOperation,
2433
'target exponent out of bounds in quantize')
2436
ans = _dec_from_triple(self._sign, '0', exp._exp)
2437
return ans._fix(context)
2439
self_adjusted = self.adjusted()
2440
if self_adjusted > context.Emax:
2441
return context._raise_error(InvalidOperation,
2442
'exponent of quantize result too large for current context')
2443
if self_adjusted - exp._exp + 1 > context.prec:
2444
return context._raise_error(InvalidOperation,
2445
'quantize result has too many digits for current context')
2447
ans = self._rescale(exp._exp, rounding)
2448
if ans.adjusted() > context.Emax:
2449
return context._raise_error(InvalidOperation,
2450
'exponent of quantize result too large for current context')
2451
if len(ans._int) > context.prec:
2452
return context._raise_error(InvalidOperation,
2453
'quantize result has too many digits for current context')
2455
# raise appropriate flags
2456
if ans._exp > self._exp:
2457
context._raise_error(Rounded)
2459
context._raise_error(Inexact)
2460
if ans and ans.adjusted() < context.Emin:
2461
context._raise_error(Subnormal)
2463
# call to fix takes care of any necessary folddown
2464
ans = ans._fix(context)
2467
def same_quantum(self, other):
2468
"""Return True if self and other have the same exponent; otherwise
2471
If either operand is a special value, the following rules are used:
2472
* return True if both operands are infinities
2473
* return True if both operands are NaNs
2474
* otherwise, return False.
2476
other = _convert_other(other, raiseit=True)
2477
if self._is_special or other._is_special:
2478
return (self.is_nan() and other.is_nan() or
2479
self.is_infinite() and other.is_infinite())
2480
return self._exp == other._exp
2482
def _rescale(self, exp, rounding):
2483
"""Rescale self so that the exponent is exp, either by padding with zeros
2484
or by truncating digits, using the given rounding mode.
2486
Specials are returned without change. This operation is
2487
quiet: it raises no flags, and uses no information from the
2490
exp = exp to scale to (an integer)
2491
rounding = rounding mode
2493
if self._is_special:
2494
return Decimal(self)
2496
return _dec_from_triple(self._sign, '0', exp)
2498
if self._exp >= exp:
2499
# pad answer with zeros if necessary
2500
return _dec_from_triple(self._sign,
2501
self._int + '0'*(self._exp - exp), exp)
2503
# too many digits; round and lose data. If self.adjusted() <
2504
# exp-1, replace self by 10**(exp-1) before rounding
2505
digits = len(self._int) + self._exp - exp
2507
self = _dec_from_triple(self._sign, '1', exp-1)
2509
this_function = getattr(self, self._pick_rounding_function[rounding])
2510
changed = this_function(digits)
2511
coeff = self._int[:digits] or '0'
2513
coeff = str(int(coeff)+1)
2514
return _dec_from_triple(self._sign, coeff, exp)
2516
def _round(self, places, rounding):
2517
"""Round a nonzero, nonspecial Decimal to a fixed number of
2518
significant figures, using the given rounding mode.
2520
Infinities, NaNs and zeros are returned unaltered.
2522
This operation is quiet: it raises no flags, and uses no
2523
information from the context.
2527
raise ValueError("argument should be at least 1 in _round")
2528
if self._is_special or not self:
2529
return Decimal(self)
2530
ans = self._rescale(self.adjusted()+1-places, rounding)
2531
# it can happen that the rescale alters the adjusted exponent;
2532
# for example when rounding 99.97 to 3 significant figures.
2533
# When this happens we end up with an extra 0 at the end of
2534
# the number; a second rescale fixes this.
2535
if ans.adjusted() != self.adjusted():
2536
ans = ans._rescale(ans.adjusted()+1-places, rounding)
2539
def to_integral_exact(self, rounding=None, context=None):
2540
"""Rounds to a nearby integer.
2542
If no rounding mode is specified, take the rounding mode from
2543
the context. This method raises the Rounded and Inexact flags
2546
See also: to_integral_value, which does exactly the same as
2547
this method except that it doesn't raise Inexact or Rounded.
2549
if self._is_special:
2550
ans = self._check_nans(context=context)
2553
return Decimal(self)
2555
return Decimal(self)
2557
return _dec_from_triple(self._sign, '0', 0)
2559
context = getcontext()
2560
if rounding is None:
2561
rounding = context.rounding
2562
context._raise_error(Rounded)
2563
ans = self._rescale(0, rounding)
2565
context._raise_error(Inexact)
2568
def to_integral_value(self, rounding=None, context=None):
2569
"""Rounds to the nearest integer, without raising inexact, rounded."""
2571
context = getcontext()
2572
if rounding is None:
2573
rounding = context.rounding
2574
if self._is_special:
2575
ans = self._check_nans(context=context)
2578
return Decimal(self)
2580
return Decimal(self)
2582
return self._rescale(0, rounding)
2584
# the method name changed, but we provide also the old one, for compatibility
2585
to_integral = to_integral_value
2587
def sqrt(self, context=None):
2588
"""Return the square root of self."""
2590
context = getcontext()
2592
if self._is_special:
2593
ans = self._check_nans(context=context)
2597
if self._isinfinity() and self._sign == 0:
2598
return Decimal(self)
2601
# exponent = self._exp // 2. sqrt(-0) = -0
2602
ans = _dec_from_triple(self._sign, '0', self._exp // 2)
2603
return ans._fix(context)
2606
return context._raise_error(InvalidOperation, 'sqrt(-x), x > 0')
2608
# At this point self represents a positive number. Let p be
2609
# the desired precision and express self in the form c*100**e
2610
# with c a positive real number and e an integer, c and e
2611
# being chosen so that 100**(p-1) <= c < 100**p. Then the
2612
# (exact) square root of self is sqrt(c)*10**e, and 10**(p-1)
2613
# <= sqrt(c) < 10**p, so the closest representable Decimal at
2614
# precision p is n*10**e where n = round_half_even(sqrt(c)),
2615
# the closest integer to sqrt(c) with the even integer chosen
2616
# in the case of a tie.
2618
# To ensure correct rounding in all cases, we use the
2619
# following trick: we compute the square root to an extra
2620
# place (precision p+1 instead of precision p), rounding down.
2621
# Then, if the result is inexact and its last digit is 0 or 5,
2622
# we increase the last digit to 1 or 6 respectively; if it's
2623
# exact we leave the last digit alone. Now the final round to
2624
# p places (or fewer in the case of underflow) will round
2625
# correctly and raise the appropriate flags.
2627
# use an extra digit of precision
2628
prec = context.prec+1
2630
# write argument in the form c*100**e where e = self._exp//2
2631
# is the 'ideal' exponent, to be used if the square root is
2632
# exactly representable. l is the number of 'digits' of c in
2633
# base 100, so that 100**(l-1) <= c < 100**l.
2638
l = (len(self._int) >> 1) + 1
2641
l = len(self._int)+1 >> 1
2643
# rescale so that c has exactly prec base 100 'digits'
2649
c, remainder = divmod(c, 100**-shift)
2650
exact = not remainder
2653
# find n = floor(sqrt(c)) using Newton's method
2661
exact = exact and n*n == c
2664
# result is exact; rescale to use ideal exponent e
2666
# assert n % 10**shift == 0
2672
# result is not exact; fix last digit as described above
2676
ans = _dec_from_triple(0, str(n), e)
2678
# round, and fit to current context
2679
context = context._shallow_copy()
2680
rounding = context._set_rounding(ROUND_HALF_EVEN)
2681
ans = ans._fix(context)
2682
context.rounding = rounding
2686
def max(self, other, context=None):
2687
"""Returns the larger value.
2689
Like max(self, other) except if one is not a number, returns
2690
NaN (and signals if one is sNaN). Also rounds.
2692
other = _convert_other(other, raiseit=True)
2695
context = getcontext()
2697
if self._is_special or other._is_special:
2698
# If one operand is a quiet NaN and the other is number, then the
2699
# number is always returned
2703
if on == 1 and sn == 0:
2704
return self._fix(context)
2705
if sn == 1 and on == 0:
2706
return other._fix(context)
2707
return self._check_nans(other, context)
2709
c = self._cmp(other)
2711
# If both operands are finite and equal in numerical value
2712
# then an ordering is applied:
2714
# If the signs differ then max returns the operand with the
2715
# positive sign and min returns the operand with the negative sign
2717
# If the signs are the same then the exponent is used to select
2718
# the result. This is exactly the ordering used in compare_total.
2719
c = self.compare_total(other)
2726
return ans._fix(context)
2728
def min(self, other, context=None):
2729
"""Returns the smaller value.
2731
Like min(self, other) except if one is not a number, returns
2732
NaN (and signals if one is sNaN). Also rounds.
2734
other = _convert_other(other, raiseit=True)
2737
context = getcontext()
2739
if self._is_special or other._is_special:
2740
# If one operand is a quiet NaN and the other is number, then the
2741
# number is always returned
2745
if on == 1 and sn == 0:
2746
return self._fix(context)
2747
if sn == 1 and on == 0:
2748
return other._fix(context)
2749
return self._check_nans(other, context)
2751
c = self._cmp(other)
2753
c = self.compare_total(other)
2760
return ans._fix(context)
2762
def _isinteger(self):
2763
"""Returns whether self is an integer"""
2764
if self._is_special:
2768
rest = self._int[self._exp:]
2769
return rest == '0'*len(rest)
2772
"""Returns True if self is even. Assumes self is an integer."""
2773
if not self or self._exp > 0:
2775
return self._int[-1+self._exp] in '02468'
2778
"""Return the adjusted exponent of self"""
2780
return self._exp + len(self._int) - 1
2781
# If NaN or Infinity, self._exp is string
2785
def canonical(self, context=None):
2786
"""Returns the same Decimal object.
2788
As we do not have different encodings for the same number, the
2789
received object already is in its canonical form.
2793
def compare_signal(self, other, context=None):
2794
"""Compares self to the other operand numerically.
2796
It's pretty much like compare(), but all NaNs signal, with signaling
2797
NaNs taking precedence over quiet NaNs.
2799
other = _convert_other(other, raiseit = True)
2800
ans = self._compare_check_nans(other, context)
2803
return self.compare(other, context=context)
2805
def compare_total(self, other):
2806
"""Compares self to other using the abstract representations.
2808
This is not like the standard compare, which use their numerical
2809
value. Note that a total ordering is defined for all possible abstract
2812
# if one is negative and the other is positive, it's easy
2813
if self._sign and not other._sign:
2815
if not self._sign and other._sign:
2819
# let's handle both NaN types
2820
self_nan = self._isnan()
2821
other_nan = other._isnan()
2822
if self_nan or other_nan:
2823
if self_nan == other_nan:
2824
if self._int < other._int:
2829
if self._int > other._int:
2860
if self._exp < other._exp:
2865
if self._exp > other._exp:
2873
def compare_total_mag(self, other):
2874
"""Compares self to other using abstract repr., ignoring sign.
2876
Like compare_total, but with operand's sign ignored and assumed to be 0.
2879
o = other.copy_abs()
2880
return s.compare_total(o)
2883
"""Returns a copy with the sign set to 0. """
2884
return _dec_from_triple(0, self._int, self._exp, self._is_special)
2886
def copy_negate(self):
2887
"""Returns a copy with the sign inverted."""
2889
return _dec_from_triple(0, self._int, self._exp, self._is_special)
2891
return _dec_from_triple(1, self._int, self._exp, self._is_special)
2893
def copy_sign(self, other):
2894
"""Returns self with the sign of other."""
2895
return _dec_from_triple(other._sign, self._int,
2896
self._exp, self._is_special)
2898
def exp(self, context=None):
2899
"""Returns e ** self."""
2902
context = getcontext()
2905
ans = self._check_nans(context=context)
2909
# exp(-Infinity) = 0
2910
if self._isinfinity() == -1:
2917
# exp(Infinity) = Infinity
2918
if self._isinfinity() == 1:
2919
return Decimal(self)
2921
# the result is now guaranteed to be inexact (the true
2922
# mathematical result is transcendental). There's no need to
2923
# raise Rounded and Inexact here---they'll always be raised as
2924
# a result of the call to _fix.
2926
adj = self.adjusted()
2928
# we only need to do any computation for quite a small range
2929
# of adjusted exponents---for example, -29 <= adj <= 10 for
2930
# the default context. For smaller exponent the result is
2931
# indistinguishable from 1 at the given precision, while for
2932
# larger exponent the result either overflows or underflows.
2933
if self._sign == 0 and adj > len(str((context.Emax+1)*3)):
2935
ans = _dec_from_triple(0, '1', context.Emax+1)
2936
elif self._sign == 1 and adj > len(str((-context.Etiny()+1)*3)):
2938
ans = _dec_from_triple(0, '1', context.Etiny()-1)
2939
elif self._sign == 0 and adj < -p:
2940
# p+1 digits; final round will raise correct flags
2941
ans = _dec_from_triple(0, '1' + '0'*(p-1) + '1', -p)
2942
elif self._sign == 1 and adj < -p-1:
2943
# p+1 digits; final round will raise correct flags
2944
ans = _dec_from_triple(0, '9'*(p+1), -p-1)
2948
c, e = op.int, op.exp
2952
# compute correctly rounded result: increase precision by
2953
# 3 digits at a time until we get an unambiguously
2957
coeff, exp = _dexp(c, e, p+extra)
2958
if coeff % (5*10**(len(str(coeff))-p-1)):
2962
ans = _dec_from_triple(0, str(coeff), exp)
2964
# at this stage, ans should round correctly with *any*
2965
# rounding mode, not just with ROUND_HALF_EVEN
2966
context = context._shallow_copy()
2967
rounding = context._set_rounding(ROUND_HALF_EVEN)
2968
ans = ans._fix(context)
2969
context.rounding = rounding
2973
def is_canonical(self):
2974
"""Return True if self is canonical; otherwise return False.
2976
Currently, the encoding of a Decimal instance is always
2977
canonical, so this method returns True for any Decimal.
2981
def is_finite(self):
2982
"""Return True if self is finite; otherwise return False.
2984
A Decimal instance is considered finite if it is neither
2987
return not self._is_special
2989
def is_infinite(self):
2990
"""Return True if self is infinite; otherwise return False."""
2991
return self._exp == 'F'
2994
"""Return True if self is a qNaN or sNaN; otherwise return False."""
2995
return self._exp in ('n', 'N')
2997
def is_normal(self, context=None):
2998
"""Return True if self is a normal number; otherwise return False."""
2999
if self._is_special or not self:
3002
context = getcontext()
3003
return context.Emin <= self.adjusted() <= context.Emax
3006
"""Return True if self is a quiet NaN; otherwise return False."""
3007
return self._exp == 'n'
3009
def is_signed(self):
3010
"""Return True if self is negative; otherwise return False."""
3011
return self._sign == 1
3014
"""Return True if self is a signaling NaN; otherwise return False."""
3015
return self._exp == 'N'
3017
def is_subnormal(self, context=None):
3018
"""Return True if self is subnormal; otherwise return False."""
3019
if self._is_special or not self:
3022
context = getcontext()
3023
return self.adjusted() < context.Emin
3026
"""Return True if self is a zero; otherwise return False."""
3027
return not self._is_special and self._int == '0'
3029
def _ln_exp_bound(self):
3030
"""Compute a lower bound for the adjusted exponent of self.ln().
3031
In other words, compute r such that self.ln() >= 10**r. Assumes
3032
that self is finite and positive and that self != 1.
3035
# for 0.1 <= x <= 10 we use the inequalities 1-1/x <= ln(x) <= x-1
3036
adj = self._exp + len(self._int) - 1
3038
# argument >= 10; we use 23/10 = 2.3 as a lower bound for ln(10)
3039
return len(str(adj*23//10)) - 1
3042
return len(str((-1-adj)*23//10)) - 1
3044
c, e = op.int, op.exp
3049
return len(num) - len(den) - (num < den)
3050
# adj == -1, 0.1 <= self < 1
3051
return e + len(str(10**-e - c)) - 1
3054
def ln(self, context=None):
3055
"""Returns the natural (base e) logarithm of self."""
3058
context = getcontext()
3061
ans = self._check_nans(context=context)
3065
# ln(0.0) == -Infinity
3067
return _NegativeInfinity
3069
# ln(Infinity) = Infinity
3070
if self._isinfinity() == 1:
3077
# ln(negative) raises InvalidOperation
3079
return context._raise_error(InvalidOperation,
3080
'ln of a negative value')
3082
# result is irrational, so necessarily inexact
3084
c, e = op.int, op.exp
3087
# correctly rounded result: repeatedly increase precision by 3
3088
# until we get an unambiguously roundable result
3089
places = p - self._ln_exp_bound() + 2 # at least p+3 places
3091
coeff = _dlog(c, e, places)
3092
# assert len(str(abs(coeff)))-p >= 1
3093
if coeff % (5*10**(len(str(abs(coeff)))-p-1)):
3096
ans = _dec_from_triple(int(coeff<0), str(abs(coeff)), -places)
3098
context = context._shallow_copy()
3099
rounding = context._set_rounding(ROUND_HALF_EVEN)
3100
ans = ans._fix(context)
3101
context.rounding = rounding
3104
def _log10_exp_bound(self):
3105
"""Compute a lower bound for the adjusted exponent of self.log10().
3106
In other words, find r such that self.log10() >= 10**r.
3107
Assumes that self is finite and positive and that self != 1.
3110
# For x >= 10 or x < 0.1 we only need a bound on the integer
3111
# part of log10(self), and this comes directly from the
3112
# exponent of x. For 0.1 <= x <= 10 we use the inequalities
3113
# 1-1/x <= log(x) <= x-1. If x > 1 we have |log10(x)| >
3114
# (1-1/x)/2.31 > 0. If x < 1 then |log10(x)| > (1-x)/2.31 > 0
3116
adj = self._exp + len(self._int) - 1
3119
return len(str(adj))-1
3122
return len(str(-1-adj))-1
3124
c, e = op.int, op.exp
3129
return len(num) - len(den) - (num < den) + 2
3130
# adj == -1, 0.1 <= self < 1
3132
return len(num) + e - (num < "231") - 1
3134
def log10(self, context=None):
3135
"""Returns the base 10 logarithm of self."""
3138
context = getcontext()
3141
ans = self._check_nans(context=context)
3145
# log10(0.0) == -Infinity
3147
return _NegativeInfinity
3149
# log10(Infinity) = Infinity
3150
if self._isinfinity() == 1:
3153
# log10(negative or -Infinity) raises InvalidOperation
3155
return context._raise_error(InvalidOperation,
3156
'log10 of a negative value')
3159
if self._int[0] == '1' and self._int[1:] == '0'*(len(self._int) - 1):
3160
# answer may need rounding
3161
ans = Decimal(self._exp + len(self._int) - 1)
3163
# result is irrational, so necessarily inexact
3165
c, e = op.int, op.exp
3168
# correctly rounded result: repeatedly increase precision
3169
# until result is unambiguously roundable
3170
places = p-self._log10_exp_bound()+2
3172
coeff = _dlog10(c, e, places)
3173
# assert len(str(abs(coeff)))-p >= 1
3174
if coeff % (5*10**(len(str(abs(coeff)))-p-1)):
3177
ans = _dec_from_triple(int(coeff<0), str(abs(coeff)), -places)
3179
context = context._shallow_copy()
3180
rounding = context._set_rounding(ROUND_HALF_EVEN)
3181
ans = ans._fix(context)
3182
context.rounding = rounding
3185
def logb(self, context=None):
3186
""" Returns the exponent of the magnitude of self's MSD.
3188
The result is the integer which is the exponent of the magnitude
3189
of the most significant digit of self (as though it were truncated
3190
to a single digit while maintaining the value of that digit and
3191
without limiting the resulting exponent).
3194
ans = self._check_nans(context=context)
3199
context = getcontext()
3201
# logb(+/-Inf) = +Inf
3202
if self._isinfinity():
3205
# logb(0) = -Inf, DivisionByZero
3207
return context._raise_error(DivisionByZero, 'logb(0)', 1)
3209
# otherwise, simply return the adjusted exponent of self, as a
3210
# Decimal. Note that no attempt is made to fit the result
3211
# into the current context.
3212
return Decimal(self.adjusted())
3214
def _islogical(self):
3215
"""Return True if self is a logical operand.
3217
For being logical, it must be a finite number with a sign of 0,
3218
an exponent of 0, and a coefficient whose digits must all be
3221
if self._sign != 0 or self._exp != 0:
3223
for dig in self._int:
3228
def _fill_logical(self, context, opa, opb):
3229
dif = context.prec - len(opa)
3233
opa = opa[-context.prec:]
3234
dif = context.prec - len(opb)
3238
opb = opb[-context.prec:]
3241
def logical_and(self, other, context=None):
3242
"""Applies an 'and' operation between self and other's digits."""
3244
context = getcontext()
3245
if not self._islogical() or not other._islogical():
3246
return context._raise_error(InvalidOperation)
3248
# fill to context.prec
3249
(opa, opb) = self._fill_logical(context, self._int, other._int)
3251
# make the operation, and clean starting zeroes
3252
result = "".join([str(int(a)&int(b)) for a,b in zip(opa,opb)])
3253
return _dec_from_triple(0, result.lstrip('0') or '0', 0)
3255
def logical_invert(self, context=None):
3256
"""Invert all its digits."""
3258
context = getcontext()
3259
return self.logical_xor(_dec_from_triple(0,'1'*context.prec,0),
3262
def logical_or(self, other, context=None):
3263
"""Applies an 'or' operation between self and other's digits."""
3265
context = getcontext()
3266
if not self._islogical() or not other._islogical():
3267
return context._raise_error(InvalidOperation)
3269
# fill to context.prec
3270
(opa, opb) = self._fill_logical(context, self._int, other._int)
3272
# make the operation, and clean starting zeroes
3273
result = "".join([str(int(a)|int(b)) for a,b in zip(opa,opb)])
3274
return _dec_from_triple(0, result.lstrip('0') or '0', 0)
3276
def logical_xor(self, other, context=None):
3277
"""Applies an 'xor' operation between self and other's digits."""
3279
context = getcontext()
3280
if not self._islogical() or not other._islogical():
3281
return context._raise_error(InvalidOperation)
3283
# fill to context.prec
3284
(opa, opb) = self._fill_logical(context, self._int, other._int)
3286
# make the operation, and clean starting zeroes
3287
result = "".join([str(int(a)^int(b)) for a,b in zip(opa,opb)])
3288
return _dec_from_triple(0, result.lstrip('0') or '0', 0)
3290
def max_mag(self, other, context=None):
3291
"""Compares the values numerically with their sign ignored."""
3292
other = _convert_other(other, raiseit=True)
3295
context = getcontext()
3297
if self._is_special or other._is_special:
3298
# If one operand is a quiet NaN and the other is number, then the
3299
# number is always returned
3303
if on == 1 and sn == 0:
3304
return self._fix(context)
3305
if sn == 1 and on == 0:
3306
return other._fix(context)
3307
return self._check_nans(other, context)
3309
c = self.copy_abs()._cmp(other.copy_abs())
3311
c = self.compare_total(other)
3318
return ans._fix(context)
3320
def min_mag(self, other, context=None):
3321
"""Compares the values numerically with their sign ignored."""
3322
other = _convert_other(other, raiseit=True)
3325
context = getcontext()
3327
if self._is_special or other._is_special:
3328
# If one operand is a quiet NaN and the other is number, then the
3329
# number is always returned
3333
if on == 1 and sn == 0:
3334
return self._fix(context)
3335
if sn == 1 and on == 0:
3336
return other._fix(context)
3337
return self._check_nans(other, context)
3339
c = self.copy_abs()._cmp(other.copy_abs())
3341
c = self.compare_total(other)
3348
return ans._fix(context)
3350
def next_minus(self, context=None):
3351
"""Returns the largest representable number smaller than itself."""
3353
context = getcontext()
3355
ans = self._check_nans(context=context)
3359
if self._isinfinity() == -1:
3360
return _NegativeInfinity
3361
if self._isinfinity() == 1:
3362
return _dec_from_triple(0, '9'*context.prec, context.Etop())
3364
context = context.copy()
3365
context._set_rounding(ROUND_FLOOR)
3366
context._ignore_all_flags()
3367
new_self = self._fix(context)
3368
if new_self != self:
3370
return self.__sub__(_dec_from_triple(0, '1', context.Etiny()-1),
3373
def next_plus(self, context=None):
3374
"""Returns the smallest representable number larger than itself."""
3376
context = getcontext()
3378
ans = self._check_nans(context=context)
3382
if self._isinfinity() == 1:
3384
if self._isinfinity() == -1:
3385
return _dec_from_triple(1, '9'*context.prec, context.Etop())
3387
context = context.copy()
3388
context._set_rounding(ROUND_CEILING)
3389
context._ignore_all_flags()
3390
new_self = self._fix(context)
3391
if new_self != self:
3393
return self.__add__(_dec_from_triple(0, '1', context.Etiny()-1),
3396
def next_toward(self, other, context=None):
3397
"""Returns the number closest to self, in the direction towards other.
3399
The result is the closest representable number to self
3400
(excluding self) that is in the direction towards other,
3401
unless both have the same value. If the two operands are
3402
numerically equal, then the result is a copy of self with the
3403
sign set to be the same as the sign of other.
3405
other = _convert_other(other, raiseit=True)
3408
context = getcontext()
3410
ans = self._check_nans(other, context)
3414
comparison = self._cmp(other)
3416
return self.copy_sign(other)
3418
if comparison == -1:
3419
ans = self.next_plus(context)
3420
else: # comparison == 1
3421
ans = self.next_minus(context)
3423
# decide which flags to raise using value of ans
3424
if ans._isinfinity():
3425
context._raise_error(Overflow,
3426
'Infinite result from next_toward',
3428
context._raise_error(Rounded)
3429
context._raise_error(Inexact)
3430
elif ans.adjusted() < context.Emin:
3431
context._raise_error(Underflow)
3432
context._raise_error(Subnormal)
3433
context._raise_error(Rounded)
3434
context._raise_error(Inexact)
3435
# if precision == 1 then we don't raise Clamped for a
3438
context._raise_error(Clamped)
3442
def number_class(self, context=None):
3443
"""Returns an indication of the class of self.
3445
The class is one of the following strings:
3461
inf = self._isinfinity()
3472
context = getcontext()
3473
if self.is_subnormal(context=context):
3478
# just a normal, regular, boring number, :)
3485
"""Just returns 10, as this is Decimal, :)"""
3488
def rotate(self, other, context=None):
3489
"""Returns a rotated copy of self, value-of-other times."""
3491
context = getcontext()
3493
ans = self._check_nans(other, context)
3498
return context._raise_error(InvalidOperation)
3499
if not (-context.prec <= int(other) <= context.prec):
3500
return context._raise_error(InvalidOperation)
3502
if self._isinfinity():
3503
return Decimal(self)
3505
# get values, pad if necessary
3508
topad = context.prec - len(rotdig)
3510
rotdig = '0'*topad + rotdig
3513
rotated = rotdig[torot:] + rotdig[:torot]
3514
return _dec_from_triple(self._sign,
3515
rotated.lstrip('0') or '0', self._exp)
3517
def scaleb (self, other, context=None):
3518
"""Returns self operand after adding the second value to its exp."""
3520
context = getcontext()
3522
ans = self._check_nans(other, context)
3527
return context._raise_error(InvalidOperation)
3528
liminf = -2 * (context.Emax + context.prec)
3529
limsup = 2 * (context.Emax + context.prec)
3530
if not (liminf <= int(other) <= limsup):
3531
return context._raise_error(InvalidOperation)
3533
if self._isinfinity():
3534
return Decimal(self)
3536
d = _dec_from_triple(self._sign, self._int, self._exp + int(other))
3540
def shift(self, other, context=None):
3541
"""Returns a shifted copy of self, value-of-other times."""
3543
context = getcontext()
3545
ans = self._check_nans(other, context)
3550
return context._raise_error(InvalidOperation)
3551
if not (-context.prec <= int(other) <= context.prec):
3552
return context._raise_error(InvalidOperation)
3554
if self._isinfinity():
3555
return Decimal(self)
3557
# get values, pad if necessary
3560
return Decimal(self)
3562
topad = context.prec - len(rotdig)
3564
rotdig = '0'*topad + rotdig
3568
rotated = rotdig[:torot]
3570
rotated = rotdig + '0'*torot
3571
rotated = rotated[-context.prec:]
3573
return _dec_from_triple(self._sign,
3574
rotated.lstrip('0') or '0', self._exp)
3576
# Support for pickling, copy, and deepcopy
3577
def __reduce__(self):
3578
return (self.__class__, (str(self),))
3581
if type(self) == Decimal:
3582
return self # I'm immutable; therefore I am my own clone
3583
return self.__class__(str(self))
3585
def __deepcopy__(self, memo):
3586
if type(self) == Decimal:
3587
return self # My components are also immutable
3588
return self.__class__(str(self))
3590
# PEP 3101 support. the _localeconv keyword argument should be
3591
# considered private: it's provided for ease of testing only.
3592
def __format__(self, specifier, context=None, _localeconv=None):
3593
"""Format a Decimal instance according to the given specifier.
3595
The specifier should be a standard format specifier, with the
3596
form described in PEP 3101. Formatting types 'e', 'E', 'f',
3597
'F', 'g', 'G', 'n' and '%' are supported. If the formatting
3598
type is omitted it defaults to 'g' or 'G', depending on the
3599
value of context.capitals.
3602
# Note: PEP 3101 says that if the type is not present then
3603
# there should be at least one digit after the decimal point.
3604
# We take the liberty of ignoring this requirement for
3605
# Decimal---it's presumably there to make sure that
3606
# format(float, '') behaves similarly to str(float).
3608
context = getcontext()
3610
spec = _parse_format_specifier(specifier, _localeconv=_localeconv)
3612
# special values don't care about the type or precision
3613
if self._is_special:
3614
sign = _format_sign(self._sign, spec)
3615
body = str(self.copy_abs())
3616
return _format_align(sign, body, spec)
3618
# a type of None defaults to 'g' or 'G', depending on context
3619
if spec['type'] is None:
3620
spec['type'] = ['g', 'G'][context.capitals]
3622
# if type is '%', adjust exponent of self accordingly
3623
if spec['type'] == '%':
3624
self = _dec_from_triple(self._sign, self._int, self._exp+2)
3626
# round if necessary, taking rounding mode from the context
3627
rounding = context.rounding
3628
precision = spec['precision']
3629
if precision is not None:
3630
if spec['type'] in 'eE':
3631
self = self._round(precision+1, rounding)
3632
elif spec['type'] in 'fF%':
3633
self = self._rescale(-precision, rounding)
3634
elif spec['type'] in 'gG' and len(self._int) > precision:
3635
self = self._round(precision, rounding)
3636
# special case: zeros with a positive exponent can't be
3637
# represented in fixed point; rescale them to 0e0.
3638
if not self and self._exp > 0 and spec['type'] in 'fF%':
3639
self = self._rescale(0, rounding)
3641
# figure out placement of the decimal point
3642
leftdigits = self._exp + len(self._int)
3643
if spec['type'] in 'eE':
3644
if not self and precision is not None:
3645
dotplace = 1 - precision
3648
elif spec['type'] in 'fF%':
3649
dotplace = leftdigits
3650
elif spec['type'] in 'gG':
3651
if self._exp <= 0 and leftdigits > -6:
3652
dotplace = leftdigits
3656
# find digits before and after decimal point, and get exponent
3659
fracpart = '0'*(-dotplace) + self._int
3660
elif dotplace > len(self._int):
3661
intpart = self._int + '0'*(dotplace-len(self._int))
3664
intpart = self._int[:dotplace] or '0'
3665
fracpart = self._int[dotplace:]
3666
exp = leftdigits-dotplace
3668
# done with the decimal-specific stuff; hand over the rest
3669
# of the formatting to the _format_number function
3670
return _format_number(self._sign, intpart, fracpart, exp, spec)
3672
def _dec_from_triple(sign, coefficient, exponent, special=False):
3673
"""Create a decimal instance directly, without any validation,
3674
normalization (e.g. removal of leading zeros) or argument
3677
This function is for *internal use only*.
3680
self = object.__new__(Decimal)
3682
self._int = coefficient
3683
self._exp = exponent
3684
self._is_special = special
3688
# Register Decimal as a kind of Number (an abstract base class).
3689
# However, do not register it as Real (because Decimals are not
3690
# interoperable with floats).
3691
_numbers.Number.register(Decimal)
3694
##### Context class #######################################################
3697
# get rounding method function:
3698
rounding_functions = [name for name in Decimal.__dict__.keys()
3699
if name.startswith('_round_')]
3700
for name in rounding_functions:
3701
# name is like _round_half_even, goes to the global ROUND_HALF_EVEN value.
3702
globalname = name[1:].upper()
3703
val = globals()[globalname]
3704
Decimal._pick_rounding_function[val] = name
3706
del name, val, globalname, rounding_functions
3708
class _ContextManager(object):
3709
"""Context manager class to support localcontext().
3711
Sets a copy of the supplied context in __enter__() and restores
3712
the previous decimal context in __exit__()
3714
def __init__(self, new_context):
3715
self.new_context = new_context.copy()
3716
def __enter__(self):
3717
self.saved_context = getcontext()
3718
setcontext(self.new_context)
3719
return self.new_context
3720
def __exit__(self, t, v, tb):
3721
setcontext(self.saved_context)
3723
class Context(object):
3724
"""Contains the context for a Decimal instance.
3727
prec - precision (for use in rounding, division, square roots..)
3728
rounding - rounding type (how you round)
3729
traps - If traps[exception] = 1, then the exception is
3730
raised when it is caused. Otherwise, a value is
3732
flags - When an exception is caused, flags[exception] is set.
3733
(Whether or not the trap_enabler is set)
3734
Should be reset by user of Decimal instance.
3735
Emin - Minimum exponent
3736
Emax - Maximum exponent
3737
capitals - If 1, 1*10^1 is printed as 1E+1.
3738
If 0, printed as 1e1
3739
_clamp - If 1, change exponents if too high (Default 0)
3742
def __init__(self, prec=None, rounding=None,
3743
traps=None, flags=None,
3744
Emin=None, Emax=None,
3745
capitals=None, _clamp=0,
3746
_ignored_flags=None):
3749
if _ignored_flags is None:
3751
if not isinstance(flags, dict):
3752
flags = dict([(s, int(s in flags)) for s in _signals])
3753
if traps is not None and not isinstance(traps, dict):
3754
traps = dict([(s, int(s in traps)) for s in _signals])
3755
for name, val in locals().items():
3757
setattr(self, name, _copy.copy(getattr(DefaultContext, name)))
3759
setattr(self, name, val)
3763
"""Show the current context."""
3765
s.append('Context(prec=%(prec)d, rounding=%(rounding)s, '
3766
'Emin=%(Emin)d, Emax=%(Emax)d, capitals=%(capitals)d'
3768
names = [f.__name__ for f, v in self.flags.items() if v]
3769
s.append('flags=[' + ', '.join(names) + ']')
3770
names = [t.__name__ for t, v in self.traps.items() if v]
3771
s.append('traps=[' + ', '.join(names) + ']')
3772
return ', '.join(s) + ')'
3774
def clear_flags(self):
3775
"""Reset all flags to zero"""
3776
for flag in self.flags:
3777
self.flags[flag] = 0
3779
def _shallow_copy(self):
3780
"""Returns a shallow copy from self."""
3781
nc = Context(self.prec, self.rounding, self.traps,
3782
self.flags, self.Emin, self.Emax,
3783
self.capitals, self._clamp, self._ignored_flags)
3787
"""Returns a deep copy from self."""
3788
nc = Context(self.prec, self.rounding, self.traps.copy(),
3789
self.flags.copy(), self.Emin, self.Emax,
3790
self.capitals, self._clamp, self._ignored_flags)
3794
def _raise_error(self, condition, explanation = None, *args):
3797
If the flag is in _ignored_flags, returns the default response.
3798
Otherwise, it sets the flag, then, if the corresponding
3799
trap_enabler is set, it reaises the exception. Otherwise, it returns
3800
the default value after setting the flag.
3802
error = _condition_map.get(condition, condition)
3803
if error in self._ignored_flags:
3804
# Don't touch the flag
3805
return error().handle(self, *args)
3807
self.flags[error] = 1
3808
if not self.traps[error]:
3809
# The errors define how to handle themselves.
3810
return condition().handle(self, *args)
3812
# Errors should only be risked on copies of the context
3813
# self._ignored_flags = []
3814
raise error(explanation)
3816
def _ignore_all_flags(self):
3817
"""Ignore all flags, if they are raised"""
3818
return self._ignore_flags(*_signals)
3820
def _ignore_flags(self, *flags):
3821
"""Ignore the flags, if they are raised"""
3822
# Do not mutate-- This way, copies of a context leave the original
3824
self._ignored_flags = (self._ignored_flags + list(flags))
3827
def _regard_flags(self, *flags):
3828
"""Stop ignoring the flags, if they are raised"""
3829
if flags and isinstance(flags[0], (tuple,list)):
3832
self._ignored_flags.remove(flag)
3834
# We inherit object.__hash__, so we must deny this explicitly
3838
"""Returns Etiny (= Emin - prec + 1)"""
3839
return int(self.Emin - self.prec + 1)
3842
"""Returns maximum exponent (= Emax - prec + 1)"""
3843
return int(self.Emax - self.prec + 1)
3845
def _set_rounding(self, type):
3846
"""Sets the rounding type.
3848
Sets the rounding type, and returns the current (previous)
3849
rounding type. Often used like:
3851
context = context.copy()
3852
# so you don't change the calling context
3853
# if an error occurs in the middle.
3854
rounding = context._set_rounding(ROUND_UP)
3855
val = self.__sub__(other, context=context)
3856
context._set_rounding(rounding)
3858
This will make it round up for that operation.
3860
rounding = self.rounding
3864
def create_decimal(self, num='0'):
3865
"""Creates a new Decimal instance but using self as context.
3867
This method implements the to-number operation of the
3868
IBM Decimal specification."""
3870
if isinstance(num, str) and num != num.strip():
3871
return self._raise_error(ConversionSyntax,
3872
"no trailing or leading whitespace is "
3875
d = Decimal(num, context=self)
3876
if d._isnan() and len(d._int) > self.prec - self._clamp:
3877
return self._raise_error(ConversionSyntax,
3878
"diagnostic info too long in NaN")
3881
def create_decimal_from_float(self, f):
3882
"""Creates a new Decimal instance from a float but rounding using self
3885
>>> context = Context(prec=5, rounding=ROUND_DOWN)
3886
>>> context.create_decimal_from_float(3.1415926535897932)
3888
>>> context = Context(prec=5, traps=[Inexact])
3889
>>> context.create_decimal_from_float(3.1415926535897932)
3890
Traceback (most recent call last):
3892
decimal.Inexact: None
3895
d = Decimal.from_float(f) # An exact conversion
3896
return d._fix(self) # Apply the context rounding
3900
"""Returns the absolute value of the operand.
3902
If the operand is negative, the result is the same as using the minus
3903
operation on the operand. Otherwise, the result is the same as using
3904
the plus operation on the operand.
3906
>>> ExtendedContext.abs(Decimal('2.1'))
3908
>>> ExtendedContext.abs(Decimal('-100'))
3910
>>> ExtendedContext.abs(Decimal('101.5'))
3912
>>> ExtendedContext.abs(Decimal('-101.5'))
3915
return a.__abs__(context=self)
3917
def add(self, a, b):
3918
"""Return the sum of the two operands.
3920
>>> ExtendedContext.add(Decimal('12'), Decimal('7.00'))
3922
>>> ExtendedContext.add(Decimal('1E+2'), Decimal('1.01E+4'))
3925
return a.__add__(b, context=self)
3927
def _apply(self, a):
3928
return str(a._fix(self))
3930
def canonical(self, a):
3931
"""Returns the same Decimal object.
3933
As we do not have different encodings for the same number, the
3934
received object already is in its canonical form.
3936
>>> ExtendedContext.canonical(Decimal('2.50'))
3939
return a.canonical(context=self)
3941
def compare(self, a, b):
3942
"""Compares values numerically.
3944
If the signs of the operands differ, a value representing each operand
3945
('-1' if the operand is less than zero, '0' if the operand is zero or
3946
negative zero, or '1' if the operand is greater than zero) is used in
3947
place of that operand for the comparison instead of the actual
3950
The comparison is then effected by subtracting the second operand from
3951
the first and then returning a value according to the result of the
3952
subtraction: '-1' if the result is less than zero, '0' if the result is
3953
zero or negative zero, or '1' if the result is greater than zero.
3955
>>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
3957
>>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
3959
>>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))
3961
>>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))
3963
>>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))
3965
>>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))
3968
return a.compare(b, context=self)
3970
def compare_signal(self, a, b):
3971
"""Compares the values of the two operands numerically.
3973
It's pretty much like compare(), but all NaNs signal, with signaling
3974
NaNs taking precedence over quiet NaNs.
3976
>>> c = ExtendedContext
3977
>>> c.compare_signal(Decimal('2.1'), Decimal('3'))
3979
>>> c.compare_signal(Decimal('2.1'), Decimal('2.1'))
3981
>>> c.flags[InvalidOperation] = 0
3982
>>> print(c.flags[InvalidOperation])
3984
>>> c.compare_signal(Decimal('NaN'), Decimal('2.1'))
3986
>>> print(c.flags[InvalidOperation])
3988
>>> c.flags[InvalidOperation] = 0
3989
>>> print(c.flags[InvalidOperation])
3991
>>> c.compare_signal(Decimal('sNaN'), Decimal('2.1'))
3993
>>> print(c.flags[InvalidOperation])
3996
return a.compare_signal(b, context=self)
3998
def compare_total(self, a, b):
3999
"""Compares two operands using their abstract representation.
4001
This is not like the standard compare, which use their numerical
4002
value. Note that a total ordering is defined for all possible abstract
4005
>>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
4007
>>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12'))
4009
>>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))
4011
>>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))
4013
>>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300'))
4015
>>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN'))
4018
return a.compare_total(b)
4020
def compare_total_mag(self, a, b):
4021
"""Compares two operands using their abstract representation ignoring sign.
4023
Like compare_total, but with operand's sign ignored and assumed to be 0.
4025
return a.compare_total_mag(b)
4027
def copy_abs(self, a):
4028
"""Returns a copy of the operand with the sign set to 0.
4030
>>> ExtendedContext.copy_abs(Decimal('2.1'))
4032
>>> ExtendedContext.copy_abs(Decimal('-100'))
4037
def copy_decimal(self, a):
4038
"""Returns a copy of the decimal objet.
4040
>>> ExtendedContext.copy_decimal(Decimal('2.1'))
4042
>>> ExtendedContext.copy_decimal(Decimal('-1.00'))
4047
def copy_negate(self, a):
4048
"""Returns a copy of the operand with the sign inverted.
4050
>>> ExtendedContext.copy_negate(Decimal('101.5'))
4052
>>> ExtendedContext.copy_negate(Decimal('-101.5'))
4055
return a.copy_negate()
4057
def copy_sign(self, a, b):
4058
"""Copies the second operand's sign to the first one.
4060
In detail, it returns a copy of the first operand with the sign
4061
equal to the sign of the second operand.
4063
>>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))
4065
>>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))
4067
>>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))
4069
>>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))
4072
return a.copy_sign(b)
4074
def divide(self, a, b):
4075
"""Decimal division in a specified context.
4077
>>> ExtendedContext.divide(Decimal('1'), Decimal('3'))
4078
Decimal('0.333333333')
4079
>>> ExtendedContext.divide(Decimal('2'), Decimal('3'))
4080
Decimal('0.666666667')
4081
>>> ExtendedContext.divide(Decimal('5'), Decimal('2'))
4083
>>> ExtendedContext.divide(Decimal('1'), Decimal('10'))
4085
>>> ExtendedContext.divide(Decimal('12'), Decimal('12'))
4087
>>> ExtendedContext.divide(Decimal('8.00'), Decimal('2'))
4089
>>> ExtendedContext.divide(Decimal('2.400'), Decimal('2.0'))
4091
>>> ExtendedContext.divide(Decimal('1000'), Decimal('100'))
4093
>>> ExtendedContext.divide(Decimal('1000'), Decimal('1'))
4095
>>> ExtendedContext.divide(Decimal('2.40E+6'), Decimal('2'))
4098
return a.__truediv__(b, context=self)
4100
def divide_int(self, a, b):
4101
"""Divides two numbers and returns the integer part of the result.
4103
>>> ExtendedContext.divide_int(Decimal('2'), Decimal('3'))
4105
>>> ExtendedContext.divide_int(Decimal('10'), Decimal('3'))
4107
>>> ExtendedContext.divide_int(Decimal('1'), Decimal('0.3'))
4110
return a.__floordiv__(b, context=self)
4112
def divmod(self, a, b):
4113
return a.__divmod__(b, context=self)
4118
>>> c = ExtendedContext.copy()
4121
>>> c.exp(Decimal('-Infinity'))
4123
>>> c.exp(Decimal('-1'))
4124
Decimal('0.367879441')
4125
>>> c.exp(Decimal('0'))
4127
>>> c.exp(Decimal('1'))
4128
Decimal('2.71828183')
4129
>>> c.exp(Decimal('0.693147181'))
4130
Decimal('2.00000000')
4131
>>> c.exp(Decimal('+Infinity'))
4134
return a.exp(context=self)
4136
def fma(self, a, b, c):
4137
"""Returns a multiplied by b, plus c.
4139
The first two operands are multiplied together, using multiply,
4140
the third operand is then added to the result of that
4141
multiplication, using add, all with only one final rounding.
4143
>>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
4145
>>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))
4147
>>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578'))
4148
Decimal('1.38435736E+12')
4150
return a.fma(b, c, context=self)
4152
def is_canonical(self, a):
4153
"""Return True if the operand is canonical; otherwise return False.
4155
Currently, the encoding of a Decimal instance is always
4156
canonical, so this method returns True for any Decimal.
4158
>>> ExtendedContext.is_canonical(Decimal('2.50'))
4161
return a.is_canonical()
4163
def is_finite(self, a):
4164
"""Return True if the operand is finite; otherwise return False.
4166
A Decimal instance is considered finite if it is neither
4169
>>> ExtendedContext.is_finite(Decimal('2.50'))
4171
>>> ExtendedContext.is_finite(Decimal('-0.3'))
4173
>>> ExtendedContext.is_finite(Decimal('0'))
4175
>>> ExtendedContext.is_finite(Decimal('Inf'))
4177
>>> ExtendedContext.is_finite(Decimal('NaN'))
4180
return a.is_finite()
4182
def is_infinite(self, a):
4183
"""Return True if the operand is infinite; otherwise return False.
4185
>>> ExtendedContext.is_infinite(Decimal('2.50'))
4187
>>> ExtendedContext.is_infinite(Decimal('-Inf'))
4189
>>> ExtendedContext.is_infinite(Decimal('NaN'))
4192
return a.is_infinite()
4194
def is_nan(self, a):
4195
"""Return True if the operand is a qNaN or sNaN;
4196
otherwise return False.
4198
>>> ExtendedContext.is_nan(Decimal('2.50'))
4200
>>> ExtendedContext.is_nan(Decimal('NaN'))
4202
>>> ExtendedContext.is_nan(Decimal('-sNaN'))
4207
def is_normal(self, a):
4208
"""Return True if the operand is a normal number;
4209
otherwise return False.
4211
>>> c = ExtendedContext.copy()
4214
>>> c.is_normal(Decimal('2.50'))
4216
>>> c.is_normal(Decimal('0.1E-999'))
4218
>>> c.is_normal(Decimal('0.00'))
4220
>>> c.is_normal(Decimal('-Inf'))
4222
>>> c.is_normal(Decimal('NaN'))
4225
return a.is_normal(context=self)
4227
def is_qnan(self, a):
4228
"""Return True if the operand is a quiet NaN; otherwise return False.
4230
>>> ExtendedContext.is_qnan(Decimal('2.50'))
4232
>>> ExtendedContext.is_qnan(Decimal('NaN'))
4234
>>> ExtendedContext.is_qnan(Decimal('sNaN'))
4239
def is_signed(self, a):
4240
"""Return True if the operand is negative; otherwise return False.
4242
>>> ExtendedContext.is_signed(Decimal('2.50'))
4244
>>> ExtendedContext.is_signed(Decimal('-12'))
4246
>>> ExtendedContext.is_signed(Decimal('-0'))
4249
return a.is_signed()
4251
def is_snan(self, a):
4252
"""Return True if the operand is a signaling NaN;
4253
otherwise return False.
4255
>>> ExtendedContext.is_snan(Decimal('2.50'))
4257
>>> ExtendedContext.is_snan(Decimal('NaN'))
4259
>>> ExtendedContext.is_snan(Decimal('sNaN'))
4264
def is_subnormal(self, a):
4265
"""Return True if the operand is subnormal; otherwise return False.
4267
>>> c = ExtendedContext.copy()
4270
>>> c.is_subnormal(Decimal('2.50'))
4272
>>> c.is_subnormal(Decimal('0.1E-999'))
4274
>>> c.is_subnormal(Decimal('0.00'))
4276
>>> c.is_subnormal(Decimal('-Inf'))
4278
>>> c.is_subnormal(Decimal('NaN'))
4281
return a.is_subnormal(context=self)
4283
def is_zero(self, a):
4284
"""Return True if the operand is a zero; otherwise return False.
4286
>>> ExtendedContext.is_zero(Decimal('0'))
4288
>>> ExtendedContext.is_zero(Decimal('2.50'))
4290
>>> ExtendedContext.is_zero(Decimal('-0E+2'))
4296
"""Returns the natural (base e) logarithm of the operand.
4298
>>> c = ExtendedContext.copy()
4301
>>> c.ln(Decimal('0'))
4302
Decimal('-Infinity')
4303
>>> c.ln(Decimal('1.000'))
4305
>>> c.ln(Decimal('2.71828183'))
4306
Decimal('1.00000000')
4307
>>> c.ln(Decimal('10'))
4308
Decimal('2.30258509')
4309
>>> c.ln(Decimal('+Infinity'))
4312
return a.ln(context=self)
4315
"""Returns the base 10 logarithm of the operand.
4317
>>> c = ExtendedContext.copy()
4320
>>> c.log10(Decimal('0'))
4321
Decimal('-Infinity')
4322
>>> c.log10(Decimal('0.001'))
4324
>>> c.log10(Decimal('1.000'))
4326
>>> c.log10(Decimal('2'))
4327
Decimal('0.301029996')
4328
>>> c.log10(Decimal('10'))
4330
>>> c.log10(Decimal('70'))
4331
Decimal('1.84509804')
4332
>>> c.log10(Decimal('+Infinity'))
4335
return a.log10(context=self)
4338
""" Returns the exponent of the magnitude of the operand's MSD.
4340
The result is the integer which is the exponent of the magnitude
4341
of the most significant digit of the operand (as though the
4342
operand were truncated to a single digit while maintaining the
4343
value of that digit and without limiting the resulting exponent).
4345
>>> ExtendedContext.logb(Decimal('250'))
4347
>>> ExtendedContext.logb(Decimal('2.50'))
4349
>>> ExtendedContext.logb(Decimal('0.03'))
4351
>>> ExtendedContext.logb(Decimal('0'))
4352
Decimal('-Infinity')
4354
return a.logb(context=self)
4356
def logical_and(self, a, b):
4357
"""Applies the logical operation 'and' between each operand's digits.
4359
The operands must be both logical numbers.
4361
>>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))
4363
>>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))
4365
>>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))
4367
>>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))
4369
>>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))
4371
>>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))
4374
return a.logical_and(b, context=self)
4376
def logical_invert(self, a):
4377
"""Invert all the digits in the operand.
4379
The operand must be a logical number.
4381
>>> ExtendedContext.logical_invert(Decimal('0'))
4382
Decimal('111111111')
4383
>>> ExtendedContext.logical_invert(Decimal('1'))
4384
Decimal('111111110')
4385
>>> ExtendedContext.logical_invert(Decimal('111111111'))
4387
>>> ExtendedContext.logical_invert(Decimal('101010101'))
4390
return a.logical_invert(context=self)
4392
def logical_or(self, a, b):
4393
"""Applies the logical operation 'or' between each operand's digits.
4395
The operands must be both logical numbers.
4397
>>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))
4399
>>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))
4401
>>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))
4403
>>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))
4405
>>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))
4407
>>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))
4410
return a.logical_or(b, context=self)
4412
def logical_xor(self, a, b):
4413
"""Applies the logical operation 'xor' between each operand's digits.
4415
The operands must be both logical numbers.
4417
>>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))
4419
>>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))
4421
>>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))
4423
>>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))
4425
>>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))
4427
>>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))
4430
return a.logical_xor(b, context=self)
4433
"""max compares two values numerically and returns the maximum.
4435
If either operand is a NaN then the general rules apply.
4436
Otherwise, the operands are compared as though by the compare
4437
operation. If they are numerically equal then the left-hand operand
4438
is chosen as the result. Otherwise the maximum (closer to positive
4439
infinity) of the two operands is chosen as the result.
4441
>>> ExtendedContext.max(Decimal('3'), Decimal('2'))
4443
>>> ExtendedContext.max(Decimal('-10'), Decimal('3'))
4445
>>> ExtendedContext.max(Decimal('1.0'), Decimal('1'))
4447
>>> ExtendedContext.max(Decimal('7'), Decimal('NaN'))
4450
return a.max(b, context=self)
4452
def max_mag(self, a, b):
4453
"""Compares the values numerically with their sign ignored."""
4454
return a.max_mag(b, context=self)
4457
"""min compares two values numerically and returns the minimum.
4459
If either operand is a NaN then the general rules apply.
4460
Otherwise, the operands are compared as though by the compare
4461
operation. If they are numerically equal then the left-hand operand
4462
is chosen as the result. Otherwise the minimum (closer to negative
4463
infinity) of the two operands is chosen as the result.
4465
>>> ExtendedContext.min(Decimal('3'), Decimal('2'))
4467
>>> ExtendedContext.min(Decimal('-10'), Decimal('3'))
4469
>>> ExtendedContext.min(Decimal('1.0'), Decimal('1'))
4471
>>> ExtendedContext.min(Decimal('7'), Decimal('NaN'))
4474
return a.min(b, context=self)
4476
def min_mag(self, a, b):
4477
"""Compares the values numerically with their sign ignored."""
4478
return a.min_mag(b, context=self)
4481
"""Minus corresponds to unary prefix minus in Python.
4483
The operation is evaluated using the same rules as subtract; the
4484
operation minus(a) is calculated as subtract('0', a) where the '0'
4485
has the same exponent as the operand.
4487
>>> ExtendedContext.minus(Decimal('1.3'))
4489
>>> ExtendedContext.minus(Decimal('-1.3'))
4492
return a.__neg__(context=self)
4494
def multiply(self, a, b):
4495
"""multiply multiplies two operands.
4497
If either operand is a special value then the general rules apply.
4498
Otherwise, the operands are multiplied together ('long multiplication'),
4499
resulting in a number which may be as long as the sum of the lengths
4500
of the two operands.
4502
>>> ExtendedContext.multiply(Decimal('1.20'), Decimal('3'))
4504
>>> ExtendedContext.multiply(Decimal('7'), Decimal('3'))
4506
>>> ExtendedContext.multiply(Decimal('0.9'), Decimal('0.8'))
4508
>>> ExtendedContext.multiply(Decimal('0.9'), Decimal('-0'))
4510
>>> ExtendedContext.multiply(Decimal('654321'), Decimal('654321'))
4511
Decimal('4.28135971E+11')
4513
return a.__mul__(b, context=self)
4515
def next_minus(self, a):
4516
"""Returns the largest representable number smaller than a.
4518
>>> c = ExtendedContext.copy()
4521
>>> ExtendedContext.next_minus(Decimal('1'))
4522
Decimal('0.999999999')
4523
>>> c.next_minus(Decimal('1E-1007'))
4525
>>> ExtendedContext.next_minus(Decimal('-1.00000003'))
4526
Decimal('-1.00000004')
4527
>>> c.next_minus(Decimal('Infinity'))
4528
Decimal('9.99999999E+999')
4530
return a.next_minus(context=self)
4532
def next_plus(self, a):
4533
"""Returns the smallest representable number larger than a.
4535
>>> c = ExtendedContext.copy()
4538
>>> ExtendedContext.next_plus(Decimal('1'))
4539
Decimal('1.00000001')
4540
>>> c.next_plus(Decimal('-1E-1007'))
4542
>>> ExtendedContext.next_plus(Decimal('-1.00000003'))
4543
Decimal('-1.00000002')
4544
>>> c.next_plus(Decimal('-Infinity'))
4545
Decimal('-9.99999999E+999')
4547
return a.next_plus(context=self)
4549
def next_toward(self, a, b):
4550
"""Returns the number closest to a, in direction towards b.
4552
The result is the closest representable number from the first
4553
operand (but not the first operand) that is in the direction
4554
towards the second operand, unless the operands have the same
4557
>>> c = ExtendedContext.copy()
4560
>>> c.next_toward(Decimal('1'), Decimal('2'))
4561
Decimal('1.00000001')
4562
>>> c.next_toward(Decimal('-1E-1007'), Decimal('1'))
4564
>>> c.next_toward(Decimal('-1.00000003'), Decimal('0'))
4565
Decimal('-1.00000002')
4566
>>> c.next_toward(Decimal('1'), Decimal('0'))
4567
Decimal('0.999999999')
4568
>>> c.next_toward(Decimal('1E-1007'), Decimal('-100'))
4570
>>> c.next_toward(Decimal('-1.00000003'), Decimal('-10'))
4571
Decimal('-1.00000004')
4572
>>> c.next_toward(Decimal('0.00'), Decimal('-0.0000'))
4575
return a.next_toward(b, context=self)
4577
def normalize(self, a):
4578
"""normalize reduces an operand to its simplest form.
4580
Essentially a plus operation with all trailing zeros removed from the
4583
>>> ExtendedContext.normalize(Decimal('2.1'))
4585
>>> ExtendedContext.normalize(Decimal('-2.0'))
4587
>>> ExtendedContext.normalize(Decimal('1.200'))
4589
>>> ExtendedContext.normalize(Decimal('-120'))
4591
>>> ExtendedContext.normalize(Decimal('120.00'))
4593
>>> ExtendedContext.normalize(Decimal('0.00'))
4596
return a.normalize(context=self)
4598
def number_class(self, a):
4599
"""Returns an indication of the class of the operand.
4601
The class is one of the following strings:
4613
>>> c = Context(ExtendedContext)
4616
>>> c.number_class(Decimal('Infinity'))
4618
>>> c.number_class(Decimal('1E-10'))
4620
>>> c.number_class(Decimal('2.50'))
4622
>>> c.number_class(Decimal('0.1E-999'))
4624
>>> c.number_class(Decimal('0'))
4626
>>> c.number_class(Decimal('-0'))
4628
>>> c.number_class(Decimal('-0.1E-999'))
4630
>>> c.number_class(Decimal('-1E-10'))
4632
>>> c.number_class(Decimal('-2.50'))
4634
>>> c.number_class(Decimal('-Infinity'))
4636
>>> c.number_class(Decimal('NaN'))
4638
>>> c.number_class(Decimal('-NaN'))
4640
>>> c.number_class(Decimal('sNaN'))
4643
return a.number_class(context=self)
4646
"""Plus corresponds to unary prefix plus in Python.
4648
The operation is evaluated using the same rules as add; the
4649
operation plus(a) is calculated as add('0', a) where the '0'
4650
has the same exponent as the operand.
4652
>>> ExtendedContext.plus(Decimal('1.3'))
4654
>>> ExtendedContext.plus(Decimal('-1.3'))
4657
return a.__pos__(context=self)
4659
def power(self, a, b, modulo=None):
4660
"""Raises a to the power of b, to modulo if given.
4662
With two arguments, compute a**b. If a is negative then b
4663
must be integral. The result will be inexact unless b is
4664
integral and the result is finite and can be expressed exactly
4665
in 'precision' digits.
4667
With three arguments, compute (a**b) % modulo. For the
4668
three argument form, the following restrictions on the
4671
- all three arguments must be integral
4672
- b must be nonnegative
4673
- at least one of a or b must be nonzero
4674
- modulo must be nonzero and have at most 'precision' digits
4676
The result of pow(a, b, modulo) is identical to the result
4677
that would be obtained by computing (a**b) % modulo with
4678
unbounded precision, but is computed more efficiently. It is
4681
>>> c = ExtendedContext.copy()
4684
>>> c.power(Decimal('2'), Decimal('3'))
4686
>>> c.power(Decimal('-2'), Decimal('3'))
4688
>>> c.power(Decimal('2'), Decimal('-3'))
4690
>>> c.power(Decimal('1.7'), Decimal('8'))
4691
Decimal('69.7575744')
4692
>>> c.power(Decimal('10'), Decimal('0.301029996'))
4693
Decimal('2.00000000')
4694
>>> c.power(Decimal('Infinity'), Decimal('-1'))
4696
>>> c.power(Decimal('Infinity'), Decimal('0'))
4698
>>> c.power(Decimal('Infinity'), Decimal('1'))
4700
>>> c.power(Decimal('-Infinity'), Decimal('-1'))
4702
>>> c.power(Decimal('-Infinity'), Decimal('0'))
4704
>>> c.power(Decimal('-Infinity'), Decimal('1'))
4705
Decimal('-Infinity')
4706
>>> c.power(Decimal('-Infinity'), Decimal('2'))
4708
>>> c.power(Decimal('0'), Decimal('0'))
4711
>>> c.power(Decimal('3'), Decimal('7'), Decimal('16'))
4713
>>> c.power(Decimal('-3'), Decimal('7'), Decimal('16'))
4715
>>> c.power(Decimal('-3'), Decimal('8'), Decimal('16'))
4717
>>> c.power(Decimal('3'), Decimal('7'), Decimal('-16'))
4719
>>> c.power(Decimal('23E12345'), Decimal('67E189'), Decimal('123456789'))
4721
>>> c.power(Decimal('-0'), Decimal('17'), Decimal('1729'))
4723
>>> c.power(Decimal('-23'), Decimal('0'), Decimal('65537'))
4726
return a.__pow__(b, modulo, context=self)
4728
def quantize(self, a, b):
4729
"""Returns a value equal to 'a' (rounded), having the exponent of 'b'.
4731
The coefficient of the result is derived from that of the left-hand
4732
operand. It may be rounded using the current rounding setting (if the
4733
exponent is being increased), multiplied by a positive power of ten (if
4734
the exponent is being decreased), or is unchanged (if the exponent is
4735
already equal to that of the right-hand operand).
4737
Unlike other operations, if the length of the coefficient after the
4738
quantize operation would be greater than precision then an Invalid
4739
operation condition is raised. This guarantees that, unless there is
4740
an error condition, the exponent of the result of a quantize is always
4741
equal to that of the right-hand operand.
4743
Also unlike other operations, quantize will never raise Underflow, even
4744
if the result is subnormal and inexact.
4746
>>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))
4748
>>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))
4750
>>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))
4752
>>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))
4754
>>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))
4756
>>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))
4757
Decimal('-Infinity')
4758
>>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))
4760
>>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))
4762
>>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))
4764
>>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))
4766
>>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))
4768
>>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))
4770
>>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))
4772
>>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))
4774
>>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))
4777
return a.quantize(b, context=self)
4780
"""Just returns 10, as this is Decimal, :)
4782
>>> ExtendedContext.radix()
4787
def remainder(self, a, b):
4788
"""Returns the remainder from integer division.
4790
The result is the residue of the dividend after the operation of
4791
calculating integer division as described for divide-integer, rounded
4792
to precision digits if necessary. The sign of the result, if
4793
non-zero, is the same as that of the original dividend.
4795
This operation will fail under the same conditions as integer division
4796
(that is, if integer division on the same two operands would fail, the
4797
remainder cannot be calculated).
4799
>>> ExtendedContext.remainder(Decimal('2.1'), Decimal('3'))
4801
>>> ExtendedContext.remainder(Decimal('10'), Decimal('3'))
4803
>>> ExtendedContext.remainder(Decimal('-10'), Decimal('3'))
4805
>>> ExtendedContext.remainder(Decimal('10.2'), Decimal('1'))
4807
>>> ExtendedContext.remainder(Decimal('10'), Decimal('0.3'))
4809
>>> ExtendedContext.remainder(Decimal('3.6'), Decimal('1.3'))
4812
return a.__mod__(b, context=self)
4814
def remainder_near(self, a, b):
4815
"""Returns to be "a - b * n", where n is the integer nearest the exact
4816
value of "x / b" (if two integers are equally near then the even one
4817
is chosen). If the result is equal to 0 then its sign will be the
4820
This operation will fail under the same conditions as integer division
4821
(that is, if integer division on the same two operands would fail, the
4822
remainder cannot be calculated).
4824
>>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))
4826
>>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))
4828
>>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))
4830
>>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))
4832
>>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))
4834
>>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))
4836
>>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))
4839
return a.remainder_near(b, context=self)
4841
def rotate(self, a, b):
4842
"""Returns a rotated copy of a, b times.
4844
The coefficient of the result is a rotated copy of the digits in
4845
the coefficient of the first operand. The number of places of
4846
rotation is taken from the absolute value of the second operand,
4847
with the rotation being to the left if the second operand is
4848
positive or to the right otherwise.
4850
>>> ExtendedContext.rotate(Decimal('34'), Decimal('8'))
4851
Decimal('400000003')
4852
>>> ExtendedContext.rotate(Decimal('12'), Decimal('9'))
4854
>>> ExtendedContext.rotate(Decimal('123456789'), Decimal('-2'))
4855
Decimal('891234567')
4856
>>> ExtendedContext.rotate(Decimal('123456789'), Decimal('0'))
4857
Decimal('123456789')
4858
>>> ExtendedContext.rotate(Decimal('123456789'), Decimal('+2'))
4859
Decimal('345678912')
4861
return a.rotate(b, context=self)
4863
def same_quantum(self, a, b):
4864
"""Returns True if the two operands have the same exponent.
4866
The result is never affected by either the sign or the coefficient of
4869
>>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))
4871
>>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))
4873
>>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))
4875
>>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))
4878
return a.same_quantum(b)
4880
def scaleb (self, a, b):
4881
"""Returns the first operand after adding the second value its exp.
4883
>>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('-2'))
4885
>>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('0'))
4887
>>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('3'))
4890
return a.scaleb (b, context=self)
4892
def shift(self, a, b):
4893
"""Returns a shifted copy of a, b times.
4895
The coefficient of the result is a shifted copy of the digits
4896
in the coefficient of the first operand. The number of places
4897
to shift is taken from the absolute value of the second operand,
4898
with the shift being to the left if the second operand is
4899
positive or to the right otherwise. Digits shifted into the
4900
coefficient are zeros.
4902
>>> ExtendedContext.shift(Decimal('34'), Decimal('8'))
4903
Decimal('400000000')
4904
>>> ExtendedContext.shift(Decimal('12'), Decimal('9'))
4906
>>> ExtendedContext.shift(Decimal('123456789'), Decimal('-2'))
4908
>>> ExtendedContext.shift(Decimal('123456789'), Decimal('0'))
4909
Decimal('123456789')
4910
>>> ExtendedContext.shift(Decimal('123456789'), Decimal('+2'))
4911
Decimal('345678900')
4913
return a.shift(b, context=self)
4916
"""Square root of a non-negative number to context precision.
4918
If the result must be inexact, it is rounded using the round-half-even
4921
>>> ExtendedContext.sqrt(Decimal('0'))
4923
>>> ExtendedContext.sqrt(Decimal('-0'))
4925
>>> ExtendedContext.sqrt(Decimal('0.39'))
4926
Decimal('0.624499800')
4927
>>> ExtendedContext.sqrt(Decimal('100'))
4929
>>> ExtendedContext.sqrt(Decimal('1'))
4931
>>> ExtendedContext.sqrt(Decimal('1.0'))
4933
>>> ExtendedContext.sqrt(Decimal('1.00'))
4935
>>> ExtendedContext.sqrt(Decimal('7'))
4936
Decimal('2.64575131')
4937
>>> ExtendedContext.sqrt(Decimal('10'))
4938
Decimal('3.16227766')
4939
>>> ExtendedContext.prec
4942
return a.sqrt(context=self)
4944
def subtract(self, a, b):
4945
"""Return the difference between the two operands.
4947
>>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.07'))
4949
>>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.30'))
4951
>>> ExtendedContext.subtract(Decimal('1.3'), Decimal('2.07'))
4954
return a.__sub__(b, context=self)
4956
def to_eng_string(self, a):
4957
"""Converts a number to a string, using scientific notation.
4959
The operation is not affected by the context.
4961
return a.to_eng_string(context=self)
4963
def to_sci_string(self, a):
4964
"""Converts a number to a string, using scientific notation.
4966
The operation is not affected by the context.
4968
return a.__str__(context=self)
4970
def to_integral_exact(self, a):
4971
"""Rounds to an integer.
4973
When the operand has a negative exponent, the result is the same
4974
as using the quantize() operation using the given operand as the
4975
left-hand-operand, 1E+0 as the right-hand-operand, and the precision
4976
of the operand as the precision setting; Inexact and Rounded flags
4977
are allowed in this operation. The rounding mode is taken from the
4980
>>> ExtendedContext.to_integral_exact(Decimal('2.1'))
4982
>>> ExtendedContext.to_integral_exact(Decimal('100'))
4984
>>> ExtendedContext.to_integral_exact(Decimal('100.0'))
4986
>>> ExtendedContext.to_integral_exact(Decimal('101.5'))
4988
>>> ExtendedContext.to_integral_exact(Decimal('-101.5'))
4990
>>> ExtendedContext.to_integral_exact(Decimal('10E+5'))
4992
>>> ExtendedContext.to_integral_exact(Decimal('7.89E+77'))
4994
>>> ExtendedContext.to_integral_exact(Decimal('-Inf'))
4995
Decimal('-Infinity')
4997
return a.to_integral_exact(context=self)
4999
def to_integral_value(self, a):
5000
"""Rounds to an integer.
5002
When the operand has a negative exponent, the result is the same
5003
as using the quantize() operation using the given operand as the
5004
left-hand-operand, 1E+0 as the right-hand-operand, and the precision
5005
of the operand as the precision setting, except that no flags will
5006
be set. The rounding mode is taken from the context.
5008
>>> ExtendedContext.to_integral_value(Decimal('2.1'))
5010
>>> ExtendedContext.to_integral_value(Decimal('100'))
5012
>>> ExtendedContext.to_integral_value(Decimal('100.0'))
5014
>>> ExtendedContext.to_integral_value(Decimal('101.5'))
5016
>>> ExtendedContext.to_integral_value(Decimal('-101.5'))
5018
>>> ExtendedContext.to_integral_value(Decimal('10E+5'))
5020
>>> ExtendedContext.to_integral_value(Decimal('7.89E+77'))
5022
>>> ExtendedContext.to_integral_value(Decimal('-Inf'))
5023
Decimal('-Infinity')
5025
return a.to_integral_value(context=self)
5027
# the method name changed, but we provide also the old one, for compatibility
5028
to_integral = to_integral_value
5030
class _WorkRep(object):
5031
__slots__ = ('sign','int','exp')
5034
# exp: None, int, or string
5036
def __init__(self, value=None):
5041
elif isinstance(value, Decimal):
5042
self.sign = value._sign
5043
self.int = int(value._int)
5044
self.exp = value._exp
5046
# assert isinstance(value, tuple)
5047
self.sign = value[0]
5052
return "(%r, %r, %r)" % (self.sign, self.int, self.exp)
5058
def _normalize(op1, op2, prec = 0):
5059
"""Normalizes op1, op2 to have the same exp and length of coefficient.
5061
Done during addition.
5063
if op1.exp < op2.exp:
5070
# Let exp = min(tmp.exp - 1, tmp.adjusted() - precision - 1).
5071
# Then adding 10**exp to tmp has the same effect (after rounding)
5072
# as adding any positive quantity smaller than 10**exp; similarly
5073
# for subtraction. So if other is smaller than 10**exp we replace
5074
# it with 10**exp. This avoids tmp.exp - other.exp getting too large.
5075
tmp_len = len(str(tmp.int))
5076
other_len = len(str(other.int))
5077
exp = tmp.exp + min(-1, tmp_len - prec - 2)
5078
if other_len + other.exp - 1 < exp:
5082
tmp.int *= 10 ** (tmp.exp - other.exp)
5086
##### Integer arithmetic functions used by ln, log10, exp and __pow__ #####
5088
# This function from Tim Peters was taken from here:
5089
# http://mail.python.org/pipermail/python-list/1999-July/007758.html
5090
# The correction being in the function definition is for speed, and
5091
# the whole function is not resolved with math.log because of avoiding
5092
# the use of floats.
5093
def _nbits(n, correction = {
5094
'0': 4, '1': 3, '2': 2, '3': 2,
5095
'4': 1, '5': 1, '6': 1, '7': 1,
5096
'8': 0, '9': 0, 'a': 0, 'b': 0,
5097
'c': 0, 'd': 0, 'e': 0, 'f': 0}):
5098
"""Number of bits in binary representation of the positive integer n,
5102
raise ValueError("The argument to _nbits should be nonnegative.")
5104
return 4*len(hex_n) - correction[hex_n[0]]
5106
def _sqrt_nearest(n, a):
5107
"""Closest integer to the square root of the positive integer n. a is
5108
an initial approximation to the square root. Any positive integer
5109
will do for a, but the closer a is to the square root of n the
5110
faster convergence will be.
5113
if n <= 0 or a <= 0:
5114
raise ValueError("Both arguments to _sqrt_nearest should be positive.")
5118
b, a = a, a--n//a>>1
5121
def _rshift_nearest(x, shift):
5122
"""Given an integer x and a nonnegative integer shift, return closest
5123
integer to x / 2**shift; use round-to-even in case of a tie.
5126
b, q = 1 << shift, x >> shift
5127
return q + (2*(x & (b-1)) + (q&1) > b)
5129
def _div_nearest(a, b):
5130
"""Closest integer to a/b, a and b positive integers; rounds to even
5131
in the case of a tie.
5135
return q + (2*r + (q&1) > b)
5137
def _ilog(x, M, L = 8):
5138
"""Integer approximation to M*log(x/M), with absolute error boundable
5139
in terms only of x/M.
5141
Given positive integers x and M, return an integer approximation to
5142
M * log(x/M). For L = 8 and 0.1 <= x/M <= 10 the difference
5143
between the approximation and the exact result is at most 22. For
5144
L = 8 and 1.0 <= x/M <= 10.0 the difference is at most 15. In
5145
both cases these are upper bounds on the error; it will usually be
5148
# The basic algorithm is the following: let log1p be the function
5149
# log1p(x) = log(1+x). Then log(x/M) = log1p((x-M)/M). We use
5152
# log1p(y) = 2*log1p(y/(1+sqrt(1+y)))
5154
# repeatedly until the argument to log1p is small (< 2**-L in
5155
# absolute value). For small y we can use the Taylor series
5158
# log1p(y) ~ y - y**2/2 + y**3/3 - ... - (-y)**T/T
5160
# truncating at T such that y**T is small enough. The whole
5161
# computation is carried out in a form of fixed-point arithmetic,
5162
# with a real number z being represented by an integer
5163
# approximation to z*M. To avoid loss of precision, the y below
5164
# is actually an integer approximation to 2**R*y*M, where R is the
5165
# number of reductions performed so far.
5168
# argument reduction; R = number of reductions performed
5170
while (R <= L and abs(y) << L-R >= M or
5171
R > L and abs(y) >> R-L >= M):
5172
y = _div_nearest((M*y) << 1,
5173
M + _sqrt_nearest(M*(M+_rshift_nearest(y, R)), M))
5176
# Taylor series with T terms
5177
T = -int(-10*len(str(M))//(3*L))
5178
yshift = _rshift_nearest(y, R)
5179
w = _div_nearest(M, T)
5180
for k in range(T-1, 0, -1):
5181
w = _div_nearest(M, k) - _div_nearest(yshift*w, M)
5183
return _div_nearest(w*y, M)
5185
def _dlog10(c, e, p):
5186
"""Given integers c, e and p with c > 0, p >= 0, compute an integer
5187
approximation to 10**p * log10(c*10**e), with an absolute error of
5188
at most 1. Assumes that c*10**e is not exactly 1."""
5190
# increase precision by 2; compensate for this by dividing
5191
# final result by 100
5194
# write c*10**e as d*10**f with either:
5195
# f >= 0 and 1 <= d <= 10, or
5196
# f <= 0 and 0.1 <= d <= 1.
5197
# Thus for c*10**e close to 1, f = 0
5199
f = e+l - (e+l >= 1)
5207
c = _div_nearest(c, 10**-k)
5209
log_d = _ilog(c, M) # error < 5 + 22 = 27
5210
log_10 = _log10_digits(p) # error < 1
5211
log_d = _div_nearest(log_d*M, log_10)
5212
log_tenpower = f*M # exact
5214
log_d = 0 # error < 2.31
5215
log_tenpower = _div_nearest(f, 10**-p) # error < 0.5
5217
return _div_nearest(log_tenpower+log_d, 100)
5220
"""Given integers c, e and p with c > 0, compute an integer
5221
approximation to 10**p * log(c*10**e), with an absolute error of
5222
at most 1. Assumes that c*10**e is not exactly 1."""
5224
# Increase precision by 2. The precision increase is compensated
5225
# for at the end with a division by 100.
5228
# rewrite c*10**e as d*10**f with either f >= 0 and 1 <= d <= 10,
5229
# or f <= 0 and 0.1 <= d <= 1. Then we can compute 10**p * log(c*10**e)
5230
# as 10**p * log(d) + 10**p*f * log(10).
5232
f = e+l - (e+l >= 1)
5234
# compute approximation to 10**p*log(d), with error < 27
5240
c = _div_nearest(c, 10**-k) # error of <= 0.5 in c
5242
# _ilog magnifies existing error in c by a factor of at most 10
5243
log_d = _ilog(c, 10**p) # error < 5 + 22 = 27
5245
# p <= 0: just approximate the whole thing by 0; error < 2.31
5248
# compute approximation to f*10**p*log(10), with error < 11.
5250
extra = len(str(abs(f)))-1
5252
# error in f * _log10_digits(p+extra) < |f| * 1 = |f|
5253
# after division, error < |f|/10**extra + 0.5 < 10 + 0.5 < 11
5254
f_log_ten = _div_nearest(f*_log10_digits(p+extra), 10**extra)
5260
# error in sum < 11+27 = 38; error after division < 0.38 + 0.5 < 1
5261
return _div_nearest(f_log_ten + log_d, 100)
5263
class _Log10Memoize(object):
5264
"""Class to compute, store, and allow retrieval of, digits of the
5265
constant log(10) = 2.302585.... This constant is needed by
5266
Decimal.ln, Decimal.log10, Decimal.exp and Decimal.__pow__."""
5268
self.digits = "23025850929940456840179914546843642076011014886"
5270
def getdigits(self, p):
5271
"""Given an integer p >= 0, return floor(10**p)*log(10).
5273
For example, self.getdigits(3) returns 2302.
5275
# digits are stored as a string, for quick conversion to
5276
# integer in the case that we've already computed enough
5277
# digits; the stored digits should always be correct
5278
# (truncated, not rounded to nearest).
5280
raise ValueError("p should be nonnegative")
5282
if p >= len(self.digits):
5283
# compute p+3, p+6, p+9, ... digits; continue until at
5284
# least one of the extra digits is nonzero
5287
# compute p+extra digits, correct to within 1ulp
5289
digits = str(_div_nearest(_ilog(10*M, M), 100))
5290
if digits[-extra:] != '0'*extra:
5293
# keep all reliable digits so far; remove trailing zeros
5294
# and next nonzero digit
5295
self.digits = digits.rstrip('0')[:-1]
5296
return int(self.digits[:p+1])
5298
_log10_digits = _Log10Memoize().getdigits
5300
def _iexp(x, M, L=8):
5301
"""Given integers x and M, M > 0, such that x/M is small in absolute
5302
value, compute an integer approximation to M*exp(x/M). For 0 <=
5303
x/M <= 2.4, the absolute error in the result is bounded by 60 (and
5304
is usually much smaller)."""
5306
# Algorithm: to compute exp(z) for a real number z, first divide z
5307
# by a suitable power R of 2 so that |z/2**R| < 2**-L. Then
5308
# compute expm1(z/2**R) = exp(z/2**R) - 1 using the usual Taylor
5311
# expm1(x) = x + x**2/2! + x**3/3! + ...
5313
# Now use the identity
5315
# expm1(2x) = expm1(x)*(expm1(x)+2)
5317
# R times to compute the sequence expm1(z/2**R),
5318
# expm1(z/2**(R-1)), ... , exp(z/2), exp(z).
5320
# Find R such that x/2**R/M <= 2**-L
5321
R = _nbits((x<<L)//M)
5323
# Taylor series. (2**L)**T > M
5324
T = -int(-10*len(str(M))//(3*L))
5325
y = _div_nearest(x, T)
5327
for i in range(T-1, 0, -1):
5328
y = _div_nearest(x*(Mshift + y), Mshift * i)
5331
for k in range(R-1, -1, -1):
5333
y = _div_nearest(y*(y+Mshift), Mshift)
5338
"""Compute an approximation to exp(c*10**e), with p decimal places of
5341
Returns integers d, f such that:
5343
10**(p-1) <= d <= 10**p, and
5344
(d-1)*10**f < exp(c*10**e) < (d+1)*10**f
5346
In other words, d*10**f is an approximation to exp(c*10**e) with p
5347
digits of precision, and with an error in d of at most 1. This is
5348
almost, but not quite, the same as the error being < 1ulp: when d
5349
= 10**(p-1) the error could be up to 10 ulp."""
5351
# we'll call iexp with M = 10**(p+2), giving p+3 digits of precision
5354
# compute log(10) with extra precision = adjusted exponent of c*10**e
5355
extra = max(0, e + len(str(c)) - 1)
5358
# compute quotient c*10**e/(log(10)) = c*10**(e+q)/(log(10)*10**q),
5362
cshift = c*10**shift
5364
cshift = c//10**-shift
5365
quot, rem = divmod(cshift, _log10_digits(q))
5367
# reduce remainder back to original precision
5368
rem = _div_nearest(rem, 10**extra)
5370
# error in result of _iexp < 120; error after division < 0.62
5371
return _div_nearest(_iexp(rem, 10**p), 1000), quot - p + 3
5373
def _dpower(xc, xe, yc, ye, p):
5374
"""Given integers xc, xe, yc and ye representing Decimals x = xc*10**xe and
5375
y = yc*10**ye, compute x**y. Returns a pair of integers (c, e) such that:
5377
10**(p-1) <= c <= 10**p, and
5378
(c-1)*10**e < x**y < (c+1)*10**e
5380
in other words, c*10**e is an approximation to x**y with p digits
5381
of precision, and with an error in c of at most 1. (This is
5382
almost, but not quite, the same as the error being < 1ulp: when c
5383
== 10**(p-1) we can only guarantee error < 10ulp.)
5385
We assume that: x is positive and not equal to 1, and y is nonzero.
5388
# Find b such that 10**(b-1) <= |y| <= 10**b
5389
b = len(str(abs(yc))) + ye
5391
# log(x) = lxc*10**(-p-b-1), to p+b+1 places after the decimal point
5392
lxc = _dlog(xc, xe, p+b+1)
5394
# compute product y*log(x) = yc*lxc*10**(-p-b-1+ye) = pc*10**(-p-1)
5397
pc = lxc*yc*10**shift
5399
pc = _div_nearest(lxc*yc, 10**-shift)
5402
# we prefer a result that isn't exactly 1; this makes it
5403
# easier to compute a correctly rounded result in __pow__
5404
if ((len(str(xc)) + xe >= 1) == (yc > 0)): # if x**y > 1:
5405
coeff, exp = 10**(p-1)+1, 1-p
5407
coeff, exp = 10**p-1, -p
5409
coeff, exp = _dexp(pc, -(p+1), p+1)
5410
coeff = _div_nearest(coeff, 10)
5415
def _log10_lb(c, correction = {
5416
'1': 100, '2': 70, '3': 53, '4': 40, '5': 31,
5417
'6': 23, '7': 16, '8': 10, '9': 5}):
5418
"""Compute a lower bound for 100*log10(c) for a positive integer c."""
5420
raise ValueError("The argument to _log10_lb should be nonnegative.")
5422
return 100*len(str_c) - correction[str_c[0]]
5424
##### Helper Functions ####################################################
5426
def _convert_other(other, raiseit=False):
5427
"""Convert other to Decimal.
5429
Verifies that it's ok to use in an implicit construction.
5431
if isinstance(other, Decimal):
5433
if isinstance(other, int):
5434
return Decimal(other)
5436
raise TypeError("Unable to convert %s to Decimal" % other)
5437
return NotImplemented
5439
##### Setup Specific Contexts ############################################
5441
# The default context prototype used by Context()
5442
# Is mutable, so that new contexts can have different default values
5444
DefaultContext = Context(
5445
prec=28, rounding=ROUND_HALF_EVEN,
5446
traps=[DivisionByZero, Overflow, InvalidOperation],
5453
# Pre-made alternate contexts offered by the specification
5454
# Don't change these; the user should be able to select these
5455
# contexts and be able to reproduce results from other implementations
5458
BasicContext = Context(
5459
prec=9, rounding=ROUND_HALF_UP,
5460
traps=[DivisionByZero, Overflow, InvalidOperation, Clamped, Underflow],
5464
ExtendedContext = Context(
5465
prec=9, rounding=ROUND_HALF_EVEN,
5471
##### crud for parsing strings #############################################
5473
# Regular expression used for parsing numeric strings. Additional
5476
# 1. Uncomment the two '\s*' lines to allow leading and/or trailing
5477
# whitespace. But note that the specification disallows whitespace in
5480
# 2. For finite numbers (not infinities and NaNs) the body of the
5481
# number between the optional sign and the optional exponent must have
5482
# at least one decimal digit, possibly after the decimal point. The
5483
# lookahead expression '(?=[0-9]|\.[0-9])' checks this.
5485
# As the flag UNICODE is not enabled here, we're explicitly avoiding any
5486
# other meaning for \d than the numbers [0-9].
5489
_parser = re.compile(r""" # A numeric string consists of:
5491
(?P<sign>[-+])? # an optional sign, followed by either...
5493
(?=[0-9]|\.[0-9]) # ...a number (with at least one digit)
5494
(?P<int>[0-9]*) # having a (possibly empty) integer part
5495
(\.(?P<frac>[0-9]*))? # followed by an optional fractional part
5496
(E(?P<exp>[-+]?[0-9]+))? # followed by an optional exponent, or...
5498
Inf(inity)? # ...an infinity, or...
5500
(?P<signal>s)? # ...an (optionally signaling)
5502
(?P<diag>[0-9]*) # with (possibly empty) diagnostic info.
5506
""", re.VERBOSE | re.IGNORECASE).match
5508
_all_zeros = re.compile('0*$').match
5509
_exact_half = re.compile('50*$').match
5511
##### PEP3101 support functions ##############################################
5512
# The functions in this section have little to do with the Decimal
5513
# class, and could potentially be reused or adapted for other pure
5514
# Python numeric classes that want to implement __format__
5516
# A format specifier for Decimal looks like:
5518
# [[fill]align][sign][0][minimumwidth][,][.precision][type]
5520
_parse_format_specifier_regex = re.compile(r"""\A
5527
(?P<minimumwidth>(?!0)\d+)?
5528
(?P<thousands_sep>,)?
5529
(?:\.(?P<precision>0|(?!0)\d+))?
5530
(?P<type>[eEfFgGn%])?
5536
# The locale module is only needed for the 'n' format specifier. The
5537
# rest of the PEP 3101 code functions quite happily without it, so we
5538
# don't care too much if locale isn't present.
5540
import locale as _locale
5544
def _parse_format_specifier(format_spec, _localeconv=None):
5545
"""Parse and validate a format specifier.
5547
Turns a standard numeric format specifier into a dict, with the
5550
fill: fill character to pad field to minimum width
5551
align: alignment type, either '<', '>', '=' or '^'
5552
sign: either '+', '-' or ' '
5553
minimumwidth: nonnegative integer giving minimum width
5554
zeropad: boolean, indicating whether to pad with zeros
5555
thousands_sep: string to use as thousands separator, or ''
5556
grouping: grouping for thousands separators, in format
5558
decimal_point: string to use for decimal point
5559
precision: nonnegative integer giving precision, or None
5560
type: one of the characters 'eEfFgG%', or None
5563
m = _parse_format_specifier_regex.match(format_spec)
5565
raise ValueError("Invalid format specifier: " + format_spec)
5567
# get the dictionary
5568
format_dict = m.groupdict()
5570
# zeropad; defaults for fill and alignment. If zero padding
5571
# is requested, the fill and align fields should be absent.
5572
fill = format_dict['fill']
5573
align = format_dict['align']
5574
format_dict['zeropad'] = (format_dict['zeropad'] is not None)
5575
if format_dict['zeropad']:
5576
if fill is not None:
5577
raise ValueError("Fill character conflicts with '0'"
5578
" in format specifier: " + format_spec)
5579
if align is not None:
5580
raise ValueError("Alignment conflicts with '0' in "
5581
"format specifier: " + format_spec)
5582
format_dict['fill'] = fill or ' '
5583
format_dict['align'] = align or '<'
5585
# default sign handling: '-' for negative, '' for positive
5586
if format_dict['sign'] is None:
5587
format_dict['sign'] = '-'
5589
# minimumwidth defaults to 0; precision remains None if not given
5590
format_dict['minimumwidth'] = int(format_dict['minimumwidth'] or '0')
5591
if format_dict['precision'] is not None:
5592
format_dict['precision'] = int(format_dict['precision'])
5594
# if format type is 'g' or 'G' then a precision of 0 makes little
5595
# sense; convert it to 1. Same if format type is unspecified.
5596
if format_dict['precision'] == 0:
5597
if format_dict['type'] in 'gG' or format_dict['type'] is None:
5598
format_dict['precision'] = 1
5600
# determine thousands separator, grouping, and decimal separator, and
5601
# add appropriate entries to format_dict
5602
if format_dict['type'] == 'n':
5603
# apart from separators, 'n' behaves just like 'g'
5604
format_dict['type'] = 'g'
5605
if _localeconv is None:
5606
_localeconv = _locale.localeconv()
5607
if format_dict['thousands_sep'] is not None:
5608
raise ValueError("Explicit thousands separator conflicts with "
5609
"'n' type in format specifier: " + format_spec)
5610
format_dict['thousands_sep'] = _localeconv['thousands_sep']
5611
format_dict['grouping'] = _localeconv['grouping']
5612
format_dict['decimal_point'] = _localeconv['decimal_point']
5614
if format_dict['thousands_sep'] is None:
5615
format_dict['thousands_sep'] = ''
5616
format_dict['grouping'] = [3, 0]
5617
format_dict['decimal_point'] = '.'
5621
def _format_align(sign, body, spec):
5622
"""Given an unpadded, non-aligned numeric string 'body' and sign
5623
string 'sign', add padding and aligment conforming to the given
5624
format specifier dictionary 'spec' (as produced by
5625
parse_format_specifier).
5628
# how much extra space do we have to play with?
5629
minimumwidth = spec['minimumwidth']
5631
padding = fill*(minimumwidth - len(sign) - len(body))
5633
align = spec['align']
5635
result = sign + body + padding
5637
result = padding + sign + body
5639
result = sign + padding + body
5641
half = len(padding)//2
5642
result = padding[:half] + sign + body + padding[half:]
5644
raise ValueError('Unrecognised alignment field')
5648
def _group_lengths(grouping):
5649
"""Convert a localeconv-style grouping into a (possibly infinite)
5650
iterable of integers representing group lengths.
5653
# The result from localeconv()['grouping'], and the input to this
5654
# function, should be a list of integers in one of the
5655
# following three forms:
5657
# (1) an empty list, or
5658
# (2) nonempty list of positive integers + [0]
5659
# (3) list of positive integers + [locale.CHAR_MAX], or
5661
from itertools import chain, repeat
5664
elif grouping[-1] == 0 and len(grouping) >= 2:
5665
return chain(grouping[:-1], repeat(grouping[-2]))
5666
elif grouping[-1] == _locale.CHAR_MAX:
5667
return grouping[:-1]
5669
raise ValueError('unrecognised format for grouping')
5671
def _insert_thousands_sep(digits, spec, min_width=1):
5672
"""Insert thousands separators into a digit string.
5674
spec is a dictionary whose keys should include 'thousands_sep' and
5675
'grouping'; typically it's the result of parsing the format
5676
specifier using _parse_format_specifier.
5678
The min_width keyword argument gives the minimum length of the
5679
result, which will be padded on the left with zeros if necessary.
5681
If necessary, the zero padding adds an extra '0' on the left to
5682
avoid a leading thousands separator. For example, inserting
5683
commas every three digits in '123456', with min_width=8, gives
5684
'0,123,456', even though that has length 9.
5688
sep = spec['thousands_sep']
5689
grouping = spec['grouping']
5692
for l in _group_lengths(grouping):
5694
raise ValueError("group length should be positive")
5695
# max(..., 1) forces at least 1 digit to the left of a separator
5696
l = min(max(len(digits), min_width, 1), l)
5697
groups.append('0'*(l - len(digits)) + digits[-l:])
5698
digits = digits[:-l]
5700
if not digits and min_width <= 0:
5702
min_width -= len(sep)
5704
l = max(len(digits), min_width, 1)
5705
groups.append('0'*(l - len(digits)) + digits[-l:])
5706
return sep.join(reversed(groups))
5708
def _format_sign(is_negative, spec):
5709
"""Determine sign character."""
5713
elif spec['sign'] in ' +':
5718
def _format_number(is_negative, intpart, fracpart, exp, spec):
5719
"""Format a number, given the following data:
5721
is_negative: true if the number is negative, else false
5722
intpart: string of digits that must appear before the decimal point
5723
fracpart: string of digits that must come after the point
5724
exp: exponent, as an integer
5725
spec: dictionary resulting from parsing the format specifier
5727
This function uses the information in spec to:
5728
insert separators (decimal separator and thousands separators)
5731
add trailing '%' for the '%' type
5732
zero-pad if necessary
5733
fill and align if necessary
5736
sign = _format_sign(is_negative, spec)
5739
fracpart = spec['decimal_point'] + fracpart
5741
if exp != 0 or spec['type'] in 'eE':
5742
echar = {'E': 'E', 'e': 'e', 'G': 'E', 'g': 'e'}[spec['type']]
5743
fracpart += "{0}{1:+}".format(echar, exp)
5744
if spec['type'] == '%':
5748
min_width = spec['minimumwidth'] - len(fracpart) - len(sign)
5751
intpart = _insert_thousands_sep(intpart, spec, min_width)
5753
return _format_align(sign, intpart+fracpart, spec)
5756
##### Useful Constants (internal use only) ################################
5759
_Infinity = Decimal('Inf')
5760
_NegativeInfinity = Decimal('-Inf')
5761
_NaN = Decimal('NaN')
5764
_NegativeOne = Decimal(-1)
5766
# _SignedInfinity[sign] is infinity w/ that sign
5767
_SignedInfinity = (_Infinity, _NegativeInfinity)
5771
if __name__ == '__main__':
5773
doctest.testmod(sys.modules[__name__])
added
removed
Lib/decimal.py
