• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright (c) 2004 Python Software Foundation.
2# All rights reserved.
3
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>
8#    and Tim Peters
9
10# This module is currently Py2.3 compatible and should be kept that way
11# unless a major compelling advantage arises.  IOW, 2.3 compatibility is
12# strongly preferred, but not guaranteed.
13
14# Also, this module should be kept in sync with the latest updates of
15# the IBM specification as it evolves.  Those updates will be treated
16# as bug fixes (deviation from the spec is a compatibility, usability
17# bug) and will be backported.  At this point the spec is stabilizing
18# and the updates are becoming fewer, smaller, and less significant.
19
20"""
21This is a Py2.3 implementation of decimal floating point arithmetic based on
22the General Decimal Arithmetic Specification:
23
24    http://speleotrove.com/decimal/decarith.html
25
26and IEEE standard 854-1987:
27
28    http://en.wikipedia.org/wiki/IEEE_854-1987
29
30Decimal floating point has finite precision with arbitrarily large bounds.
31
32The purpose of this module is to support arithmetic using familiar
33"schoolhouse" rules and to avoid some of the tricky representation
34issues associated with binary floating point.  The package is especially
35useful for financial applications or for contexts where users have
36expectations that are at odds with binary floating point (for instance,
37in binary floating point, 1.00 % 0.1 gives 0.09999999999999995 instead
38of the expected Decimal('0.00') returned by decimal floating point).
39
40Here are some examples of using the decimal module:
41
42>>> from decimal import *
43>>> setcontext(ExtendedContext)
44>>> Decimal(0)
45Decimal('0')
46>>> Decimal('1')
47Decimal('1')
48>>> Decimal('-.0123')
49Decimal('-0.0123')
50>>> Decimal(123456)
51Decimal('123456')
52>>> Decimal('123.45e12345678901234567890')
53Decimal('1.2345E+12345678901234567892')
54>>> Decimal('1.33') + Decimal('1.27')
55Decimal('2.60')
56>>> Decimal('12.34') + Decimal('3.87') - Decimal('18.41')
57Decimal('-2.20')
58>>> dig = Decimal(1)
59>>> print dig / Decimal(3)
600.333333333
61>>> getcontext().prec = 18
62>>> print dig / Decimal(3)
630.333333333333333333
64>>> print dig.sqrt()
651
66>>> print Decimal(3).sqrt()
671.73205080756887729
68>>> print Decimal(3) ** 123
694.85192780976896427E+58
70>>> inf = Decimal(1) / Decimal(0)
71>>> print inf
72Infinity
73>>> neginf = Decimal(-1) / Decimal(0)
74>>> print neginf
75-Infinity
76>>> print neginf + inf
77NaN
78>>> print neginf * inf
79-Infinity
80>>> print dig / 0
81Infinity
82>>> getcontext().traps[DivisionByZero] = 1
83>>> print dig / 0
84Traceback (most recent call last):
85  ...
86  ...
87  ...
88DivisionByZero: x / 0
89>>> c = Context()
90>>> c.traps[InvalidOperation] = 0
91>>> print c.flags[InvalidOperation]
920
93>>> c.divide(Decimal(0), Decimal(0))
94Decimal('NaN')
95>>> c.traps[InvalidOperation] = 1
96>>> print c.flags[InvalidOperation]
971
98>>> c.flags[InvalidOperation] = 0
99>>> print c.flags[InvalidOperation]
1000
101>>> print c.divide(Decimal(0), Decimal(0))
102Traceback (most recent call last):
103  ...
104  ...
105  ...
106InvalidOperation: 0 / 0
107>>> print c.flags[InvalidOperation]
1081
109>>> c.flags[InvalidOperation] = 0
110>>> c.traps[InvalidOperation] = 0
111>>> print c.divide(Decimal(0), Decimal(0))
112NaN
113>>> print c.flags[InvalidOperation]
1141
115>>>
116"""
117
118__all__ = [
119    # Two major classes
120    'Decimal', 'Context',
121
122    # Contexts
123    'DefaultContext', 'BasicContext', 'ExtendedContext',
124
125    # Exceptions
126    'DecimalException', 'Clamped', 'InvalidOperation', 'DivisionByZero',
127    'Inexact', 'Rounded', 'Subnormal', 'Overflow', 'Underflow',
128
129    # Constants for use in setting up contexts
130    'ROUND_DOWN', 'ROUND_HALF_UP', 'ROUND_HALF_EVEN', 'ROUND_CEILING',
131    'ROUND_FLOOR', 'ROUND_UP', 'ROUND_HALF_DOWN', 'ROUND_05UP',
132
133    # Functions for manipulating contexts
134    'setcontext', 'getcontext', 'localcontext'
135]
136
137__version__ = '1.70'    # Highest version of the spec this complies with
138
139import math as _math
140import numbers as _numbers
141
142try:
143    from collections import namedtuple as _namedtuple
144    DecimalTuple = _namedtuple('DecimalTuple', 'sign digits exponent')
145except ImportError:
146    DecimalTuple = lambda *args: args
147
148# Rounding
149ROUND_DOWN = 'ROUND_DOWN'
150ROUND_HALF_UP = 'ROUND_HALF_UP'
151ROUND_HALF_EVEN = 'ROUND_HALF_EVEN'
152ROUND_CEILING = 'ROUND_CEILING'
153ROUND_FLOOR = 'ROUND_FLOOR'
154ROUND_UP = 'ROUND_UP'
155ROUND_HALF_DOWN = 'ROUND_HALF_DOWN'
156ROUND_05UP = 'ROUND_05UP'
157
158# Errors
159
160class DecimalException(ArithmeticError):
161    """Base exception class.
162
163    Used exceptions derive from this.
164    If an exception derives from another exception besides this (such as
165    Underflow (Inexact, Rounded, Subnormal) that indicates that it is only
166    called if the others are present.  This isn't actually used for
167    anything, though.
168
169    handle  -- Called when context._raise_error is called and the
170               trap_enabler is not set.  First argument is self, second is the
171               context.  More arguments can be given, those being after
172               the explanation in _raise_error (For example,
173               context._raise_error(NewError, '(-x)!', self._sign) would
174               call NewError().handle(context, self._sign).)
175
176    To define a new exception, it should be sufficient to have it derive
177    from DecimalException.
178    """
179    def handle(self, context, *args):
180        pass
181
182
183class Clamped(DecimalException):
184    """Exponent of a 0 changed to fit bounds.
185
186    This occurs and signals clamped if the exponent of a result has been
187    altered in order to fit the constraints of a specific concrete
188    representation.  This may occur when the exponent of a zero result would
189    be outside the bounds of a representation, or when a large normal
190    number would have an encoded exponent that cannot be represented.  In
191    this latter case, the exponent is reduced to fit and the corresponding
192    number of zero digits are appended to the coefficient ("fold-down").
193    """
194
195class InvalidOperation(DecimalException):
196    """An invalid operation was performed.
197
198    Various bad things cause this:
199
200    Something creates a signaling NaN
201    -INF + INF
202    0 * (+-)INF
203    (+-)INF / (+-)INF
204    x % 0
205    (+-)INF % x
206    x._rescale( non-integer )
207    sqrt(-x) , x > 0
208    0 ** 0
209    x ** (non-integer)
210    x ** (+-)INF
211    An operand is invalid
212
213    The result of the operation after these is a quiet positive NaN,
214    except when the cause is a signaling NaN, in which case the result is
215    also a quiet NaN, but with the original sign, and an optional
216    diagnostic information.
217    """
218    def handle(self, context, *args):
219        if args:
220            ans = _dec_from_triple(args[0]._sign, args[0]._int, 'n', True)
221            return ans._fix_nan(context)
222        return _NaN
223
224class ConversionSyntax(InvalidOperation):
225    """Trying to convert badly formed string.
226
227    This occurs and signals invalid-operation if a string is being
228    converted to a number and it does not conform to the numeric string
229    syntax.  The result is [0,qNaN].
230    """
231    def handle(self, context, *args):
232        return _NaN
233
234class DivisionByZero(DecimalException, ZeroDivisionError):
235    """Division by 0.
236
237    This occurs and signals division-by-zero if division of a finite number
238    by zero was attempted (during a divide-integer or divide operation, or a
239    power operation with negative right-hand operand), and the dividend was
240    not zero.
241
242    The result of the operation is [sign,inf], where sign is the exclusive
243    or of the signs of the operands for divide, or is 1 for an odd power of
244    -0, for power.
245    """
246
247    def handle(self, context, sign, *args):
248        return _SignedInfinity[sign]
249
250class DivisionImpossible(InvalidOperation):
251    """Cannot perform the division adequately.
252
253    This occurs and signals invalid-operation if the integer result of a
254    divide-integer or remainder operation had too many digits (would be
255    longer than precision).  The result is [0,qNaN].
256    """
257
258    def handle(self, context, *args):
259        return _NaN
260
261class DivisionUndefined(InvalidOperation, ZeroDivisionError):
262    """Undefined result of division.
263
264    This occurs and signals invalid-operation if division by zero was
265    attempted (during a divide-integer, divide, or remainder operation), and
266    the dividend is also zero.  The result is [0,qNaN].
267    """
268
269    def handle(self, context, *args):
270        return _NaN
271
272class Inexact(DecimalException):
273    """Had to round, losing information.
274
275    This occurs and signals inexact whenever the result of an operation is
276    not exact (that is, it needed to be rounded and any discarded digits
277    were non-zero), or if an overflow or underflow condition occurs.  The
278    result in all cases is unchanged.
279
280    The inexact signal may be tested (or trapped) to determine if a given
281    operation (or sequence of operations) was inexact.
282    """
283
284class InvalidContext(InvalidOperation):
285    """Invalid context.  Unknown rounding, for example.
286
287    This occurs and signals invalid-operation if an invalid context was
288    detected during an operation.  This can occur if contexts are not checked
289    on creation and either the precision exceeds the capability of the
290    underlying concrete representation or an unknown or unsupported rounding
291    was specified.  These aspects of the context need only be checked when
292    the values are required to be used.  The result is [0,qNaN].
293    """
294
295    def handle(self, context, *args):
296        return _NaN
297
298class Rounded(DecimalException):
299    """Number got rounded (not  necessarily changed during rounding).
300
301    This occurs and signals rounded whenever the result of an operation is
302    rounded (that is, some zero or non-zero digits were discarded from the
303    coefficient), or if an overflow or underflow condition occurs.  The
304    result in all cases is unchanged.
305
306    The rounded signal may be tested (or trapped) to determine if a given
307    operation (or sequence of operations) caused a loss of precision.
308    """
309
310class Subnormal(DecimalException):
311    """Exponent < Emin before rounding.
312
313    This occurs and signals subnormal whenever the result of a conversion or
314    operation is subnormal (that is, its adjusted exponent is less than
315    Emin, before any rounding).  The result in all cases is unchanged.
316
317    The subnormal signal may be tested (or trapped) to determine if a given
318    or operation (or sequence of operations) yielded a subnormal result.
319    """
320
321class Overflow(Inexact, Rounded):
322    """Numerical overflow.
323
324    This occurs and signals overflow if the adjusted exponent of a result
325    (from a conversion or from an operation that is not an attempt to divide
326    by zero), after rounding, would be greater than the largest value that
327    can be handled by the implementation (the value Emax).
328
329    The result depends on the rounding mode:
330
331    For round-half-up and round-half-even (and for round-half-down and
332    round-up, if implemented), the result of the operation is [sign,inf],
333    where sign is the sign of the intermediate result.  For round-down, the
334    result is the largest finite number that can be represented in the
335    current precision, with the sign of the intermediate result.  For
336    round-ceiling, the result is the same as for round-down if the sign of
337    the intermediate result is 1, or is [0,inf] otherwise.  For round-floor,
338    the result is the same as for round-down if the sign of the intermediate
339    result is 0, or is [1,inf] otherwise.  In all cases, Inexact and Rounded
340    will also be raised.
341    """
342
343    def handle(self, context, sign, *args):
344        if context.rounding in (ROUND_HALF_UP, ROUND_HALF_EVEN,
345                                ROUND_HALF_DOWN, ROUND_UP):
346            return _SignedInfinity[sign]
347        if sign == 0:
348            if context.rounding == ROUND_CEILING:
349                return _SignedInfinity[sign]
350            return _dec_from_triple(sign, '9'*context.prec,
351                            context.Emax-context.prec+1)
352        if sign == 1:
353            if context.rounding == ROUND_FLOOR:
354                return _SignedInfinity[sign]
355            return _dec_from_triple(sign, '9'*context.prec,
356                             context.Emax-context.prec+1)
357
358
359class Underflow(Inexact, Rounded, Subnormal):
360    """Numerical underflow with result rounded to 0.
361
362    This occurs and signals underflow if a result is inexact and the
363    adjusted exponent of the result would be smaller (more negative) than
364    the smallest value that can be handled by the implementation (the value
365    Emin).  That is, the result is both inexact and subnormal.
366
367    The result after an underflow will be a subnormal number rounded, if
368    necessary, so that its exponent is not less than Etiny.  This may result
369    in 0 with the sign of the intermediate result and an exponent of Etiny.
370
371    In all cases, Inexact, Rounded, and Subnormal will also be raised.
372    """
373
374# List of public traps and flags
375_signals = [Clamped, DivisionByZero, Inexact, Overflow, Rounded,
376           Underflow, InvalidOperation, Subnormal]
377
378# Map conditions (per the spec) to signals
379_condition_map = {ConversionSyntax:InvalidOperation,
380                  DivisionImpossible:InvalidOperation,
381                  DivisionUndefined:InvalidOperation,
382                  InvalidContext:InvalidOperation}
383
384##### Context Functions ##################################################
385
386# The getcontext() and setcontext() function manage access to a thread-local
387# current context.  Py2.4 offers direct support for thread locals.  If that
388# is not available, use threading.currentThread() which is slower but will
389# work for older Pythons.  If threads are not part of the build, create a
390# mock threading object with threading.local() returning the module namespace.
391
392try:
393    import threading
394except ImportError:
395    # Python was compiled without threads; create a mock object instead
396    import sys
397    class MockThreading(object):
398        def local(self, sys=sys):
399            return sys.modules[__name__]
400    threading = MockThreading()
401    del sys, MockThreading
402
403try:
404    threading.local
405
406except AttributeError:
407
408    # To fix reloading, force it to create a new context
409    # Old contexts have different exceptions in their dicts, making problems.
410    if hasattr(threading.currentThread(), '__decimal_context__'):
411        del threading.currentThread().__decimal_context__
412
413    def setcontext(context):
414        """Set this thread's context to context."""
415        if context in (DefaultContext, BasicContext, ExtendedContext):
416            context = context.copy()
417            context.clear_flags()
418        threading.currentThread().__decimal_context__ = context
419
420    def getcontext():
421        """Returns this thread's context.
422
423        If this thread does not yet have a context, returns
424        a new context and sets this thread's context.
425        New contexts are copies of DefaultContext.
426        """
427        try:
428            return threading.currentThread().__decimal_context__
429        except AttributeError:
430            context = Context()
431            threading.currentThread().__decimal_context__ = context
432            return context
433
434else:
435
436    local = threading.local()
437    if hasattr(local, '__decimal_context__'):
438        del local.__decimal_context__
439
440    def getcontext(_local=local):
441        """Returns this thread's context.
442
443        If this thread does not yet have a context, returns
444        a new context and sets this thread's context.
445        New contexts are copies of DefaultContext.
446        """
447        try:
448            return _local.__decimal_context__
449        except AttributeError:
450            context = Context()
451            _local.__decimal_context__ = context
452            return context
453
454    def setcontext(context, _local=local):
455        """Set this thread's context to context."""
456        if context in (DefaultContext, BasicContext, ExtendedContext):
457            context = context.copy()
458            context.clear_flags()
459        _local.__decimal_context__ = context
460
461    del threading, local        # Don't contaminate the namespace
462
463def localcontext(ctx=None):
464    """Return a context manager for a copy of the supplied context
465
466    Uses a copy of the current context if no context is specified
467    The returned context manager creates a local decimal context
468    in a with statement:
469        def sin(x):
470             with localcontext() as ctx:
471                 ctx.prec += 2
472                 # Rest of sin calculation algorithm
473                 # uses a precision 2 greater than normal
474             return +s  # Convert result to normal precision
475
476         def sin(x):
477             with localcontext(ExtendedContext):
478                 # Rest of sin calculation algorithm
479                 # uses the Extended Context from the
480                 # General Decimal Arithmetic Specification
481             return +s  # Convert result to normal context
482
483    >>> setcontext(DefaultContext)
484    >>> print getcontext().prec
485    28
486    >>> with localcontext():
487    ...     ctx = getcontext()
488    ...     ctx.prec += 2
489    ...     print ctx.prec
490    ...
491    30
492    >>> with localcontext(ExtendedContext):
493    ...     print getcontext().prec
494    ...
495    9
496    >>> print getcontext().prec
497    28
498    """
499    if ctx is None: ctx = getcontext()
500    return _ContextManager(ctx)
501
502
503##### Decimal class #######################################################
504
505class Decimal(object):
506    """Floating point class for decimal arithmetic."""
507
508    __slots__ = ('_exp','_int','_sign', '_is_special')
509    # Generally, the value of the Decimal instance is given by
510    #  (-1)**_sign * _int * 10**_exp
511    # Special values are signified by _is_special == True
512
513    # We're immutable, so use __new__ not __init__
514    def __new__(cls, value="0", context=None):
515        """Create a decimal point instance.
516
517        >>> Decimal('3.14')              # string input
518        Decimal('3.14')
519        >>> Decimal((0, (3, 1, 4), -2))  # tuple (sign, digit_tuple, exponent)
520        Decimal('3.14')
521        >>> Decimal(314)                 # int or long
522        Decimal('314')
523        >>> Decimal(Decimal(314))        # another decimal instance
524        Decimal('314')
525        >>> Decimal('  3.14  \\n')        # leading and trailing whitespace okay
526        Decimal('3.14')
527        """
528
529        # Note that the coefficient, self._int, is actually stored as
530        # a string rather than as a tuple of digits.  This speeds up
531        # the "digits to integer" and "integer to digits" conversions
532        # that are used in almost every arithmetic operation on
533        # Decimals.  This is an internal detail: the as_tuple function
534        # and the Decimal constructor still deal with tuples of
535        # digits.
536
537        self = object.__new__(cls)
538
539        # From a string
540        # REs insist on real strings, so we can too.
541        if isinstance(value, basestring):
542            m = _parser(value.strip())
543            if m is None:
544                if context is None:
545                    context = getcontext()
546                return context._raise_error(ConversionSyntax,
547                                "Invalid literal for Decimal: %r" % value)
548
549            if m.group('sign') == "-":
550                self._sign = 1
551            else:
552                self._sign = 0
553            intpart = m.group('int')
554            if intpart is not None:
555                # finite number
556                fracpart = m.group('frac') or ''
557                exp = int(m.group('exp') or '0')
558                self._int = str(int(intpart+fracpart))
559                self._exp = exp - len(fracpart)
560                self._is_special = False
561            else:
562                diag = m.group('diag')
563                if diag is not None:
564                    # NaN
565                    self._int = str(int(diag or '0')).lstrip('0')
566                    if m.group('signal'):
567                        self._exp = 'N'
568                    else:
569                        self._exp = 'n'
570                else:
571                    # infinity
572                    self._int = '0'
573                    self._exp = 'F'
574                self._is_special = True
575            return self
576
577        # From an integer
578        if isinstance(value, (int,long)):
579            if value >= 0:
580                self._sign = 0
581            else:
582                self._sign = 1
583            self._exp = 0
584            self._int = str(abs(value))
585            self._is_special = False
586            return self
587
588        # From another decimal
589        if isinstance(value, Decimal):
590            self._exp  = value._exp
591            self._sign = value._sign
592            self._int  = value._int
593            self._is_special  = value._is_special
594            return self
595
596        # From an internal working value
597        if isinstance(value, _WorkRep):
598            self._sign = value.sign
599            self._int = str(value.int)
600            self._exp = int(value.exp)
601            self._is_special = False
602            return self
603
604        # tuple/list conversion (possibly from as_tuple())
605        if isinstance(value, (list,tuple)):
606            if len(value) != 3:
607                raise ValueError('Invalid tuple size in creation of Decimal '
608                                 'from list or tuple.  The list or tuple '
609                                 'should have exactly three elements.')
610            # process sign.  The isinstance test rejects floats
611            if not (isinstance(value[0], (int, long)) and value[0] in (0,1)):
612                raise ValueError("Invalid sign.  The first value in the tuple "
613                                 "should be an integer; either 0 for a "
614                                 "positive number or 1 for a negative number.")
615            self._sign = value[0]
616            if value[2] == 'F':
617                # infinity: value[1] is ignored
618                self._int = '0'
619                self._exp = value[2]
620                self._is_special = True
621            else:
622                # process and validate the digits in value[1]
623                digits = []
624                for digit in value[1]:
625                    if isinstance(digit, (int, long)) and 0 <= digit <= 9:
626                        # skip leading zeros
627                        if digits or digit != 0:
628                            digits.append(digit)
629                    else:
630                        raise ValueError("The second value in the tuple must "
631                                         "be composed of integers in the range "
632                                         "0 through 9.")
633                if value[2] in ('n', 'N'):
634                    # NaN: digits form the diagnostic
635                    self._int = ''.join(map(str, digits))
636                    self._exp = value[2]
637                    self._is_special = True
638                elif isinstance(value[2], (int, long)):
639                    # finite number: digits give the coefficient
640                    self._int = ''.join(map(str, digits or [0]))
641                    self._exp = value[2]
642                    self._is_special = False
643                else:
644                    raise ValueError("The third value in the tuple must "
645                                     "be an integer, or one of the "
646                                     "strings 'F', 'n', 'N'.")
647            return self
648
649        if isinstance(value, float):
650            value = Decimal.from_float(value)
651            self._exp  = value._exp
652            self._sign = value._sign
653            self._int  = value._int
654            self._is_special  = value._is_special
655            return self
656
657        raise TypeError("Cannot convert %r to Decimal" % value)
658
659    # @classmethod, but @decorator is not valid Python 2.3 syntax, so
660    # don't use it (see notes on Py2.3 compatibility at top of file)
661    def from_float(cls, f):
662        """Converts a float to a decimal number, exactly.
663
664        Note that Decimal.from_float(0.1) is not the same as Decimal('0.1').
665        Since 0.1 is not exactly representable in binary floating point, the
666        value is stored as the nearest representable value which is
667        0x1.999999999999ap-4.  The exact equivalent of the value in decimal
668        is 0.1000000000000000055511151231257827021181583404541015625.
669
670        >>> Decimal.from_float(0.1)
671        Decimal('0.1000000000000000055511151231257827021181583404541015625')
672        >>> Decimal.from_float(float('nan'))
673        Decimal('NaN')
674        >>> Decimal.from_float(float('inf'))
675        Decimal('Infinity')
676        >>> Decimal.from_float(-float('inf'))
677        Decimal('-Infinity')
678        >>> Decimal.from_float(-0.0)
679        Decimal('-0')
680
681        """
682        if isinstance(f, (int, long)):        # handle integer inputs
683            return cls(f)
684        if _math.isinf(f) or _math.isnan(f):  # raises TypeError if not a float
685            return cls(repr(f))
686        if _math.copysign(1.0, f) == 1.0:
687            sign = 0
688        else:
689            sign = 1
690        n, d = abs(f).as_integer_ratio()
691        k = d.bit_length() - 1
692        result = _dec_from_triple(sign, str(n*5**k), -k)
693        if cls is Decimal:
694            return result
695        else:
696            return cls(result)
697    from_float = classmethod(from_float)
698
699    def _isnan(self):
700        """Returns whether the number is not actually one.
701
702        0 if a number
703        1 if NaN
704        2 if sNaN
705        """
706        if self._is_special:
707            exp = self._exp
708            if exp == 'n':
709                return 1
710            elif exp == 'N':
711                return 2
712        return 0
713
714    def _isinfinity(self):
715        """Returns whether the number is infinite
716
717        0 if finite or not a number
718        1 if +INF
719        -1 if -INF
720        """
721        if self._exp == 'F':
722            if self._sign:
723                return -1
724            return 1
725        return 0
726
727    def _check_nans(self, other=None, context=None):
728        """Returns whether the number is not actually one.
729
730        if self, other are sNaN, signal
731        if self, other are NaN return nan
732        return 0
733
734        Done before operations.
735        """
736
737        self_is_nan = self._isnan()
738        if other is None:
739            other_is_nan = False
740        else:
741            other_is_nan = other._isnan()
742
743        if self_is_nan or other_is_nan:
744            if context is None:
745                context = getcontext()
746
747            if self_is_nan == 2:
748                return context._raise_error(InvalidOperation, 'sNaN',
749                                        self)
750            if other_is_nan == 2:
751                return context._raise_error(InvalidOperation, 'sNaN',
752                                        other)
753            if self_is_nan:
754                return self._fix_nan(context)
755
756            return other._fix_nan(context)
757        return 0
758
759    def _compare_check_nans(self, other, context):
760        """Version of _check_nans used for the signaling comparisons
761        compare_signal, __le__, __lt__, __ge__, __gt__.
762
763        Signal InvalidOperation if either self or other is a (quiet
764        or signaling) NaN.  Signaling NaNs take precedence over quiet
765        NaNs.
766
767        Return 0 if neither operand is a NaN.
768
769        """
770        if context is None:
771            context = getcontext()
772
773        if self._is_special or other._is_special:
774            if self.is_snan():
775                return context._raise_error(InvalidOperation,
776                                            'comparison involving sNaN',
777                                            self)
778            elif other.is_snan():
779                return context._raise_error(InvalidOperation,
780                                            'comparison involving sNaN',
781                                            other)
782            elif self.is_qnan():
783                return context._raise_error(InvalidOperation,
784                                            'comparison involving NaN',
785                                            self)
786            elif other.is_qnan():
787                return context._raise_error(InvalidOperation,
788                                            'comparison involving NaN',
789                                            other)
790        return 0
791
792    def __nonzero__(self):
793        """Return True if self is nonzero; otherwise return False.
794
795        NaNs and infinities are considered nonzero.
796        """
797        return self._is_special or self._int != '0'
798
799    def _cmp(self, other):
800        """Compare the two non-NaN decimal instances self and other.
801
802        Returns -1 if self < other, 0 if self == other and 1
803        if self > other.  This routine is for internal use only."""
804
805        if self._is_special or other._is_special:
806            self_inf = self._isinfinity()
807            other_inf = other._isinfinity()
808            if self_inf == other_inf:
809                return 0
810            elif self_inf < other_inf:
811                return -1
812            else:
813                return 1
814
815        # check for zeros;  Decimal('0') == Decimal('-0')
816        if not self:
817            if not other:
818                return 0
819            else:
820                return -((-1)**other._sign)
821        if not other:
822            return (-1)**self._sign
823
824        # If different signs, neg one is less
825        if other._sign < self._sign:
826            return -1
827        if self._sign < other._sign:
828            return 1
829
830        self_adjusted = self.adjusted()
831        other_adjusted = other.adjusted()
832        if self_adjusted == other_adjusted:
833            self_padded = self._int + '0'*(self._exp - other._exp)
834            other_padded = other._int + '0'*(other._exp - self._exp)
835            if self_padded == other_padded:
836                return 0
837            elif self_padded < other_padded:
838                return -(-1)**self._sign
839            else:
840                return (-1)**self._sign
841        elif self_adjusted > other_adjusted:
842            return (-1)**self._sign
843        else: # self_adjusted < other_adjusted
844            return -((-1)**self._sign)
845
846    # Note: The Decimal standard doesn't cover rich comparisons for
847    # Decimals.  In particular, the specification is silent on the
848    # subject of what should happen for a comparison involving a NaN.
849    # We take the following approach:
850    #
851    #   == comparisons involving a quiet NaN always return False
852    #   != comparisons involving a quiet NaN always return True
853    #   == or != comparisons involving a signaling NaN signal
854    #      InvalidOperation, and return False or True as above if the
855    #      InvalidOperation is not trapped.
856    #   <, >, <= and >= comparisons involving a (quiet or signaling)
857    #      NaN signal InvalidOperation, and return False if the
858    #      InvalidOperation is not trapped.
859    #
860    # This behavior is designed to conform as closely as possible to
861    # that specified by IEEE 754.
862
863    def __eq__(self, other, context=None):
864        other = _convert_other(other, allow_float=True)
865        if other is NotImplemented:
866            return other
867        if self._check_nans(other, context):
868            return False
869        return self._cmp(other) == 0
870
871    def __ne__(self, other, context=None):
872        other = _convert_other(other, allow_float=True)
873        if other is NotImplemented:
874            return other
875        if self._check_nans(other, context):
876            return True
877        return self._cmp(other) != 0
878
879    def __lt__(self, other, context=None):
880        other = _convert_other(other, allow_float=True)
881        if other is NotImplemented:
882            return other
883        ans = self._compare_check_nans(other, context)
884        if ans:
885            return False
886        return self._cmp(other) < 0
887
888    def __le__(self, other, context=None):
889        other = _convert_other(other, allow_float=True)
890        if other is NotImplemented:
891            return other
892        ans = self._compare_check_nans(other, context)
893        if ans:
894            return False
895        return self._cmp(other) <= 0
896
897    def __gt__(self, other, context=None):
898        other = _convert_other(other, allow_float=True)
899        if other is NotImplemented:
900            return other
901        ans = self._compare_check_nans(other, context)
902        if ans:
903            return False
904        return self._cmp(other) > 0
905
906    def __ge__(self, other, context=None):
907        other = _convert_other(other, allow_float=True)
908        if other is NotImplemented:
909            return other
910        ans = self._compare_check_nans(other, context)
911        if ans:
912            return False
913        return self._cmp(other) >= 0
914
915    def compare(self, other, context=None):
916        """Compares one to another.
917
918        -1 => a < b
919        0  => a = b
920        1  => a > b
921        NaN => one is NaN
922        Like __cmp__, but returns Decimal instances.
923        """
924        other = _convert_other(other, raiseit=True)
925
926        # Compare(NaN, NaN) = NaN
927        if (self._is_special or other and other._is_special):
928            ans = self._check_nans(other, context)
929            if ans:
930                return ans
931
932        return Decimal(self._cmp(other))
933
934    def __hash__(self):
935        """x.__hash__() <==> hash(x)"""
936        # Decimal integers must hash the same as the ints
937        #
938        # The hash of a nonspecial noninteger Decimal must depend only
939        # on the value of that Decimal, and not on its representation.
940        # For example: hash(Decimal('100E-1')) == hash(Decimal('10')).
941
942        # Equality comparisons involving signaling nans can raise an
943        # exception; since equality checks are implicitly and
944        # unpredictably used when checking set and dict membership, we
945        # prevent signaling nans from being used as set elements or
946        # dict keys by making __hash__ raise an exception.
947        if self._is_special:
948            if self.is_snan():
949                raise TypeError('Cannot hash a signaling NaN value.')
950            elif self.is_nan():
951                # 0 to match hash(float('nan'))
952                return 0
953            else:
954                # values chosen to match hash(float('inf')) and
955                # hash(float('-inf')).
956                if self._sign:
957                    return -271828
958                else:
959                    return 314159
960
961        # In Python 2.7, we're allowing comparisons (but not
962        # arithmetic operations) between floats and Decimals;  so if
963        # a Decimal instance is exactly representable as a float then
964        # its hash should match that of the float.
965        self_as_float = float(self)
966        if Decimal.from_float(self_as_float) == self:
967            return hash(self_as_float)
968
969        if self._isinteger():
970            op = _WorkRep(self.to_integral_value())
971            # to make computation feasible for Decimals with large
972            # exponent, we use the fact that hash(n) == hash(m) for
973            # any two nonzero integers n and m such that (i) n and m
974            # have the same sign, and (ii) n is congruent to m modulo
975            # 2**64-1.  So we can replace hash((-1)**s*c*10**e) with
976            # hash((-1)**s*c*pow(10, e, 2**64-1).
977            return hash((-1)**op.sign*op.int*pow(10, op.exp, 2**64-1))
978        # The value of a nonzero nonspecial Decimal instance is
979        # faithfully represented by the triple consisting of its sign,
980        # its adjusted exponent, and its coefficient with trailing
981        # zeros removed.
982        return hash((self._sign,
983                     self._exp+len(self._int),
984                     self._int.rstrip('0')))
985
986    def as_tuple(self):
987        """Represents the number as a triple tuple.
988
989        To show the internals exactly as they are.
990        """
991        return DecimalTuple(self._sign, tuple(map(int, self._int)), self._exp)
992
993    def __repr__(self):
994        """Represents the number as an instance of Decimal."""
995        # Invariant:  eval(repr(d)) == d
996        return "Decimal('%s')" % str(self)
997
998    def __str__(self, eng=False, context=None):
999        """Return string representation of the number in scientific notation.
1000
1001        Captures all of the information in the underlying representation.
1002        """
1003
1004        sign = ['', '-'][self._sign]
1005        if self._is_special:
1006            if self._exp == 'F':
1007                return sign + 'Infinity'
1008            elif self._exp == 'n':
1009                return sign + 'NaN' + self._int
1010            else: # self._exp == 'N'
1011                return sign + 'sNaN' + self._int
1012
1013        # number of digits of self._int to left of decimal point
1014        leftdigits = self._exp + len(self._int)
1015
1016        # dotplace is number of digits of self._int to the left of the
1017        # decimal point in the mantissa of the output string (that is,
1018        # after adjusting the exponent)
1019        if self._exp <= 0 and leftdigits > -6:
1020            # no exponent required
1021            dotplace = leftdigits
1022        elif not eng:
1023            # usual scientific notation: 1 digit on left of the point
1024            dotplace = 1
1025        elif self._int == '0':
1026            # engineering notation, zero
1027            dotplace = (leftdigits + 1) % 3 - 1
1028        else:
1029            # engineering notation, nonzero
1030            dotplace = (leftdigits - 1) % 3 + 1
1031
1032        if dotplace <= 0:
1033            intpart = '0'
1034            fracpart = '.' + '0'*(-dotplace) + self._int
1035        elif dotplace >= len(self._int):
1036            intpart = self._int+'0'*(dotplace-len(self._int))
1037            fracpart = ''
1038        else:
1039            intpart = self._int[:dotplace]
1040            fracpart = '.' + self._int[dotplace:]
1041        if leftdigits == dotplace:
1042            exp = ''
1043        else:
1044            if context is None:
1045                context = getcontext()
1046            exp = ['e', 'E'][context.capitals] + "%+d" % (leftdigits-dotplace)
1047
1048        return sign + intpart + fracpart + exp
1049
1050    def to_eng_string(self, context=None):
1051        """Convert to a string, using engineering notation if an exponent is needed.
1052
1053        Engineering notation has an exponent which is a multiple of 3.  This
1054        can leave up to 3 digits to the left of the decimal place and may
1055        require the addition of either one or two trailing zeros.
1056        """
1057        return self.__str__(eng=True, context=context)
1058
1059    def __neg__(self, context=None):
1060        """Returns a copy with the sign switched.
1061
1062        Rounds, if it has reason.
1063        """
1064        if self._is_special:
1065            ans = self._check_nans(context=context)
1066            if ans:
1067                return ans
1068
1069        if context is None:
1070            context = getcontext()
1071
1072        if not self and context.rounding != ROUND_FLOOR:
1073            # -Decimal('0') is Decimal('0'), not Decimal('-0'), except
1074            # in ROUND_FLOOR rounding mode.
1075            ans = self.copy_abs()
1076        else:
1077            ans = self.copy_negate()
1078
1079        return ans._fix(context)
1080
1081    def __pos__(self, context=None):
1082        """Returns a copy, unless it is a sNaN.
1083
1084        Rounds the number (if more than precision digits)
1085        """
1086        if self._is_special:
1087            ans = self._check_nans(context=context)
1088            if ans:
1089                return ans
1090
1091        if context is None:
1092            context = getcontext()
1093
1094        if not self and context.rounding != ROUND_FLOOR:
1095            # + (-0) = 0, except in ROUND_FLOOR rounding mode.
1096            ans = self.copy_abs()
1097        else:
1098            ans = Decimal(self)
1099
1100        return ans._fix(context)
1101
1102    def __abs__(self, round=True, context=None):
1103        """Returns the absolute value of self.
1104
1105        If the keyword argument 'round' is false, do not round.  The
1106        expression self.__abs__(round=False) is equivalent to
1107        self.copy_abs().
1108        """
1109        if not round:
1110            return self.copy_abs()
1111
1112        if self._is_special:
1113            ans = self._check_nans(context=context)
1114            if ans:
1115                return ans
1116
1117        if self._sign:
1118            ans = self.__neg__(context=context)
1119        else:
1120            ans = self.__pos__(context=context)
1121
1122        return ans
1123
1124    def __add__(self, other, context=None):
1125        """Returns self + other.
1126
1127        -INF + INF (or the reverse) cause InvalidOperation errors.
1128        """
1129        other = _convert_other(other)
1130        if other is NotImplemented:
1131            return other
1132
1133        if context is None:
1134            context = getcontext()
1135
1136        if self._is_special or other._is_special:
1137            ans = self._check_nans(other, context)
1138            if ans:
1139                return ans
1140
1141            if self._isinfinity():
1142                # If both INF, same sign => same as both, opposite => error.
1143                if self._sign != other._sign and other._isinfinity():
1144                    return context._raise_error(InvalidOperation, '-INF + INF')
1145                return Decimal(self)
1146            if other._isinfinity():
1147                return Decimal(other)  # Can't both be infinity here
1148
1149        exp = min(self._exp, other._exp)
1150        negativezero = 0
1151        if context.rounding == ROUND_FLOOR and self._sign != other._sign:
1152            # If the answer is 0, the sign should be negative, in this case.
1153            negativezero = 1
1154
1155        if not self and not other:
1156            sign = min(self._sign, other._sign)
1157            if negativezero:
1158                sign = 1
1159            ans = _dec_from_triple(sign, '0', exp)
1160            ans = ans._fix(context)
1161            return ans
1162        if not self:
1163            exp = max(exp, other._exp - context.prec-1)
1164            ans = other._rescale(exp, context.rounding)
1165            ans = ans._fix(context)
1166            return ans
1167        if not other:
1168            exp = max(exp, self._exp - context.prec-1)
1169            ans = self._rescale(exp, context.rounding)
1170            ans = ans._fix(context)
1171            return ans
1172
1173        op1 = _WorkRep(self)
1174        op2 = _WorkRep(other)
1175        op1, op2 = _normalize(op1, op2, context.prec)
1176
1177        result = _WorkRep()
1178        if op1.sign != op2.sign:
1179            # Equal and opposite
1180            if op1.int == op2.int:
1181                ans = _dec_from_triple(negativezero, '0', exp)
1182                ans = ans._fix(context)
1183                return ans
1184            if op1.int < op2.int:
1185                op1, op2 = op2, op1
1186                # OK, now abs(op1) > abs(op2)
1187            if op1.sign == 1:
1188                result.sign = 1
1189                op1.sign, op2.sign = op2.sign, op1.sign
1190            else:
1191                result.sign = 0
1192                # So we know the sign, and op1 > 0.
1193        elif op1.sign == 1:
1194            result.sign = 1
1195            op1.sign, op2.sign = (0, 0)
1196        else:
1197            result.sign = 0
1198        # Now, op1 > abs(op2) > 0
1199
1200        if op2.sign == 0:
1201            result.int = op1.int + op2.int
1202        else:
1203            result.int = op1.int - op2.int
1204
1205        result.exp = op1.exp
1206        ans = Decimal(result)
1207        ans = ans._fix(context)
1208        return ans
1209
1210    __radd__ = __add__
1211
1212    def __sub__(self, other, context=None):
1213        """Return self - other"""
1214        other = _convert_other(other)
1215        if other is NotImplemented:
1216            return other
1217
1218        if self._is_special or other._is_special:
1219            ans = self._check_nans(other, context=context)
1220            if ans:
1221                return ans
1222
1223        # self - other is computed as self + other.copy_negate()
1224        return self.__add__(other.copy_negate(), context=context)
1225
1226    def __rsub__(self, other, context=None):
1227        """Return other - self"""
1228        other = _convert_other(other)
1229        if other is NotImplemented:
1230            return other
1231
1232        return other.__sub__(self, context=context)
1233
1234    def __mul__(self, other, context=None):
1235        """Return self * other.
1236
1237        (+-) INF * 0 (or its reverse) raise InvalidOperation.
1238        """
1239        other = _convert_other(other)
1240        if other is NotImplemented:
1241            return other
1242
1243        if context is None:
1244            context = getcontext()
1245
1246        resultsign = self._sign ^ other._sign
1247
1248        if self._is_special or other._is_special:
1249            ans = self._check_nans(other, context)
1250            if ans:
1251                return ans
1252
1253            if self._isinfinity():
1254                if not other:
1255                    return context._raise_error(InvalidOperation, '(+-)INF * 0')
1256                return _SignedInfinity[resultsign]
1257
1258            if other._isinfinity():
1259                if not self:
1260                    return context._raise_error(InvalidOperation, '0 * (+-)INF')
1261                return _SignedInfinity[resultsign]
1262
1263        resultexp = self._exp + other._exp
1264
1265        # Special case for multiplying by zero
1266        if not self or not other:
1267            ans = _dec_from_triple(resultsign, '0', resultexp)
1268            # Fixing in case the exponent is out of bounds
1269            ans = ans._fix(context)
1270            return ans
1271
1272        # Special case for multiplying by power of 10
1273        if self._int == '1':
1274            ans = _dec_from_triple(resultsign, other._int, resultexp)
1275            ans = ans._fix(context)
1276            return ans
1277        if other._int == '1':
1278            ans = _dec_from_triple(resultsign, self._int, resultexp)
1279            ans = ans._fix(context)
1280            return ans
1281
1282        op1 = _WorkRep(self)
1283        op2 = _WorkRep(other)
1284
1285        ans = _dec_from_triple(resultsign, str(op1.int * op2.int), resultexp)
1286        ans = ans._fix(context)
1287
1288        return ans
1289    __rmul__ = __mul__
1290
1291    def __truediv__(self, other, context=None):
1292        """Return self / other."""
1293        other = _convert_other(other)
1294        if other is NotImplemented:
1295            return NotImplemented
1296
1297        if context is None:
1298            context = getcontext()
1299
1300        sign = self._sign ^ other._sign
1301
1302        if self._is_special or other._is_special:
1303            ans = self._check_nans(other, context)
1304            if ans:
1305                return ans
1306
1307            if self._isinfinity() and other._isinfinity():
1308                return context._raise_error(InvalidOperation, '(+-)INF/(+-)INF')
1309
1310            if self._isinfinity():
1311                return _SignedInfinity[sign]
1312
1313            if other._isinfinity():
1314                context._raise_error(Clamped, 'Division by infinity')
1315                return _dec_from_triple(sign, '0', context.Etiny())
1316
1317        # Special cases for zeroes
1318        if not other:
1319            if not self:
1320                return context._raise_error(DivisionUndefined, '0 / 0')
1321            return context._raise_error(DivisionByZero, 'x / 0', sign)
1322
1323        if not self:
1324            exp = self._exp - other._exp
1325            coeff = 0
1326        else:
1327            # OK, so neither = 0, INF or NaN
1328            shift = len(other._int) - len(self._int) + context.prec + 1
1329            exp = self._exp - other._exp - shift
1330            op1 = _WorkRep(self)
1331            op2 = _WorkRep(other)
1332            if shift >= 0:
1333                coeff, remainder = divmod(op1.int * 10**shift, op2.int)
1334            else:
1335                coeff, remainder = divmod(op1.int, op2.int * 10**-shift)
1336            if remainder:
1337                # result is not exact; adjust to ensure correct rounding
1338                if coeff % 5 == 0:
1339                    coeff += 1
1340            else:
1341                # result is exact; get as close to ideal exponent as possible
1342                ideal_exp = self._exp - other._exp
1343                while exp < ideal_exp and coeff % 10 == 0:
1344                    coeff //= 10
1345                    exp += 1
1346
1347        ans = _dec_from_triple(sign, str(coeff), exp)
1348        return ans._fix(context)
1349
1350    def _divide(self, other, context):
1351        """Return (self // other, self % other), to context.prec precision.
1352
1353        Assumes that neither self nor other is a NaN, that self is not
1354        infinite and that other is nonzero.
1355        """
1356        sign = self._sign ^ other._sign
1357        if other._isinfinity():
1358            ideal_exp = self._exp
1359        else:
1360            ideal_exp = min(self._exp, other._exp)
1361
1362        expdiff = self.adjusted() - other.adjusted()
1363        if not self or other._isinfinity() or expdiff <= -2:
1364            return (_dec_from_triple(sign, '0', 0),
1365                    self._rescale(ideal_exp, context.rounding))
1366        if expdiff <= context.prec:
1367            op1 = _WorkRep(self)
1368            op2 = _WorkRep(other)
1369            if op1.exp >= op2.exp:
1370                op1.int *= 10**(op1.exp - op2.exp)
1371            else:
1372                op2.int *= 10**(op2.exp - op1.exp)
1373            q, r = divmod(op1.int, op2.int)
1374            if q < 10**context.prec:
1375                return (_dec_from_triple(sign, str(q), 0),
1376                        _dec_from_triple(self._sign, str(r), ideal_exp))
1377
1378        # Here the quotient is too large to be representable
1379        ans = context._raise_error(DivisionImpossible,
1380                                   'quotient too large in //, % or divmod')
1381        return ans, ans
1382
1383    def __rtruediv__(self, other, context=None):
1384        """Swaps self/other and returns __truediv__."""
1385        other = _convert_other(other)
1386        if other is NotImplemented:
1387            return other
1388        return other.__truediv__(self, context=context)
1389
1390    __div__ = __truediv__
1391    __rdiv__ = __rtruediv__
1392
1393    def __divmod__(self, other, context=None):
1394        """
1395        Return (self // other, self % other)
1396        """
1397        other = _convert_other(other)
1398        if other is NotImplemented:
1399            return other
1400
1401        if context is None:
1402            context = getcontext()
1403
1404        ans = self._check_nans(other, context)
1405        if ans:
1406            return (ans, ans)
1407
1408        sign = self._sign ^ other._sign
1409        if self._isinfinity():
1410            if other._isinfinity():
1411                ans = context._raise_error(InvalidOperation, 'divmod(INF, INF)')
1412                return ans, ans
1413            else:
1414                return (_SignedInfinity[sign],
1415                        context._raise_error(InvalidOperation, 'INF % x'))
1416
1417        if not other:
1418            if not self:
1419                ans = context._raise_error(DivisionUndefined, 'divmod(0, 0)')
1420                return ans, ans
1421            else:
1422                return (context._raise_error(DivisionByZero, 'x // 0', sign),
1423                        context._raise_error(InvalidOperation, 'x % 0'))
1424
1425        quotient, remainder = self._divide(other, context)
1426        remainder = remainder._fix(context)
1427        return quotient, remainder
1428
1429    def __rdivmod__(self, other, context=None):
1430        """Swaps self/other and returns __divmod__."""
1431        other = _convert_other(other)
1432        if other is NotImplemented:
1433            return other
1434        return other.__divmod__(self, context=context)
1435
1436    def __mod__(self, other, context=None):
1437        """
1438        self % other
1439        """
1440        other = _convert_other(other)
1441        if other is NotImplemented:
1442            return other
1443
1444        if context is None:
1445            context = getcontext()
1446
1447        ans = self._check_nans(other, context)
1448        if ans:
1449            return ans
1450
1451        if self._isinfinity():
1452            return context._raise_error(InvalidOperation, 'INF % x')
1453        elif not other:
1454            if self:
1455                return context._raise_error(InvalidOperation, 'x % 0')
1456            else:
1457                return context._raise_error(DivisionUndefined, '0 % 0')
1458
1459        remainder = self._divide(other, context)[1]
1460        remainder = remainder._fix(context)
1461        return remainder
1462
1463    def __rmod__(self, other, context=None):
1464        """Swaps self/other and returns __mod__."""
1465        other = _convert_other(other)
1466        if other is NotImplemented:
1467            return other
1468        return other.__mod__(self, context=context)
1469
1470    def remainder_near(self, other, context=None):
1471        """
1472        Remainder nearest to 0-  abs(remainder-near) <= other/2
1473        """
1474        if context is None:
1475            context = getcontext()
1476
1477        other = _convert_other(other, raiseit=True)
1478
1479        ans = self._check_nans(other, context)
1480        if ans:
1481            return ans
1482
1483        # self == +/-infinity -> InvalidOperation
1484        if self._isinfinity():
1485            return context._raise_error(InvalidOperation,
1486                                        'remainder_near(infinity, x)')
1487
1488        # other == 0 -> either InvalidOperation or DivisionUndefined
1489        if not other:
1490            if self:
1491                return context._raise_error(InvalidOperation,
1492                                            'remainder_near(x, 0)')
1493            else:
1494                return context._raise_error(DivisionUndefined,
1495                                            'remainder_near(0, 0)')
1496
1497        # other = +/-infinity -> remainder = self
1498        if other._isinfinity():
1499            ans = Decimal(self)
1500            return ans._fix(context)
1501
1502        # self = 0 -> remainder = self, with ideal exponent
1503        ideal_exponent = min(self._exp, other._exp)
1504        if not self:
1505            ans = _dec_from_triple(self._sign, '0', ideal_exponent)
1506            return ans._fix(context)
1507
1508        # catch most cases of large or small quotient
1509        expdiff = self.adjusted() - other.adjusted()
1510        if expdiff >= context.prec + 1:
1511            # expdiff >= prec+1 => abs(self/other) > 10**prec
1512            return context._raise_error(DivisionImpossible)
1513        if expdiff <= -2:
1514            # expdiff <= -2 => abs(self/other) < 0.1
1515            ans = self._rescale(ideal_exponent, context.rounding)
1516            return ans._fix(context)
1517
1518        # adjust both arguments to have the same exponent, then divide
1519        op1 = _WorkRep(self)
1520        op2 = _WorkRep(other)
1521        if op1.exp >= op2.exp:
1522            op1.int *= 10**(op1.exp - op2.exp)
1523        else:
1524            op2.int *= 10**(op2.exp - op1.exp)
1525        q, r = divmod(op1.int, op2.int)
1526        # remainder is r*10**ideal_exponent; other is +/-op2.int *
1527        # 10**ideal_exponent.   Apply correction to ensure that
1528        # abs(remainder) <= abs(other)/2
1529        if 2*r + (q&1) > op2.int:
1530            r -= op2.int
1531            q += 1
1532
1533        if q >= 10**context.prec:
1534            return context._raise_error(DivisionImpossible)
1535
1536        # result has same sign as self unless r is negative
1537        sign = self._sign
1538        if r < 0:
1539            sign = 1-sign
1540            r = -r
1541
1542        ans = _dec_from_triple(sign, str(r), ideal_exponent)
1543        return ans._fix(context)
1544
1545    def __floordiv__(self, other, context=None):
1546        """self // other"""
1547        other = _convert_other(other)
1548        if other is NotImplemented:
1549            return other
1550
1551        if context is None:
1552            context = getcontext()
1553
1554        ans = self._check_nans(other, context)
1555        if ans:
1556            return ans
1557
1558        if self._isinfinity():
1559            if other._isinfinity():
1560                return context._raise_error(InvalidOperation, 'INF // INF')
1561            else:
1562                return _SignedInfinity[self._sign ^ other._sign]
1563
1564        if not other:
1565            if self:
1566                return context._raise_error(DivisionByZero, 'x // 0',
1567                                            self._sign ^ other._sign)
1568            else:
1569                return context._raise_error(DivisionUndefined, '0 // 0')
1570
1571        return self._divide(other, context)[0]
1572
1573    def __rfloordiv__(self, other, context=None):
1574        """Swaps self/other and returns __floordiv__."""
1575        other = _convert_other(other)
1576        if other is NotImplemented:
1577            return other
1578        return other.__floordiv__(self, context=context)
1579
1580    def __float__(self):
1581        """Float representation."""
1582        if self._isnan():
1583            if self.is_snan():
1584                raise ValueError("Cannot convert signaling NaN to float")
1585            s = "-nan" if self._sign else "nan"
1586        else:
1587            s = str(self)
1588        return float(s)
1589
1590    def __int__(self):
1591        """Converts self to an int, truncating if necessary."""
1592        if self._is_special:
1593            if self._isnan():
1594                raise ValueError("Cannot convert NaN to integer")
1595            elif self._isinfinity():
1596                raise OverflowError("Cannot convert infinity to integer")
1597        s = (-1)**self._sign
1598        if self._exp >= 0:
1599            return s*int(self._int)*10**self._exp
1600        else:
1601            return s*int(self._int[:self._exp] or '0')
1602
1603    __trunc__ = __int__
1604
1605    def real(self):
1606        return self
1607    real = property(real)
1608
1609    def imag(self):
1610        return Decimal(0)
1611    imag = property(imag)
1612
1613    def conjugate(self):
1614        return self
1615
1616    def __complex__(self):
1617        return complex(float(self))
1618
1619    def __long__(self):
1620        """Converts to a long.
1621
1622        Equivalent to long(int(self))
1623        """
1624        return long(self.__int__())
1625
1626    def _fix_nan(self, context):
1627        """Decapitate the payload of a NaN to fit the context"""
1628        payload = self._int
1629
1630        # maximum length of payload is precision if _clamp=0,
1631        # precision-1 if _clamp=1.
1632        max_payload_len = context.prec - context._clamp
1633        if len(payload) > max_payload_len:
1634            payload = payload[len(payload)-max_payload_len:].lstrip('0')
1635            return _dec_from_triple(self._sign, payload, self._exp, True)
1636        return Decimal(self)
1637
1638    def _fix(self, context):
1639        """Round if it is necessary to keep self within prec precision.
1640
1641        Rounds and fixes the exponent.  Does not raise on a sNaN.
1642
1643        Arguments:
1644        self - Decimal instance
1645        context - context used.
1646        """
1647
1648        if self._is_special:
1649            if self._isnan():
1650                # decapitate payload if necessary
1651                return self._fix_nan(context)
1652            else:
1653                # self is +/-Infinity; return unaltered
1654                return Decimal(self)
1655
1656        # if self is zero then exponent should be between Etiny and
1657        # Emax if _clamp==0, and between Etiny and Etop if _clamp==1.
1658        Etiny = context.Etiny()
1659        Etop = context.Etop()
1660        if not self:
1661            exp_max = [context.Emax, Etop][context._clamp]
1662            new_exp = min(max(self._exp, Etiny), exp_max)
1663            if new_exp != self._exp:
1664                context._raise_error(Clamped)
1665                return _dec_from_triple(self._sign, '0', new_exp)
1666            else:
1667                return Decimal(self)
1668
1669        # exp_min is the smallest allowable exponent of the result,
1670        # equal to max(self.adjusted()-context.prec+1, Etiny)
1671        exp_min = len(self._int) + self._exp - context.prec
1672        if exp_min > Etop:
1673            # overflow: exp_min > Etop iff self.adjusted() > Emax
1674            ans = context._raise_error(Overflow, 'above Emax', self._sign)
1675            context._raise_error(Inexact)
1676            context._raise_error(Rounded)
1677            return ans
1678
1679        self_is_subnormal = exp_min < Etiny
1680        if self_is_subnormal:
1681            exp_min = Etiny
1682
1683        # round if self has too many digits
1684        if self._exp < exp_min:
1685            digits = len(self._int) + self._exp - exp_min
1686            if digits < 0:
1687                self = _dec_from_triple(self._sign, '1', exp_min-1)
1688                digits = 0
1689            rounding_method = self._pick_rounding_function[context.rounding]
1690            changed = rounding_method(self, digits)
1691            coeff = self._int[:digits] or '0'
1692            if changed > 0:
1693                coeff = str(int(coeff)+1)
1694                if len(coeff) > context.prec:
1695                    coeff = coeff[:-1]
1696                    exp_min += 1
1697
1698            # check whether the rounding pushed the exponent out of range
1699            if exp_min > Etop:
1700                ans = context._raise_error(Overflow, 'above Emax', self._sign)
1701            else:
1702                ans = _dec_from_triple(self._sign, coeff, exp_min)
1703
1704            # raise the appropriate signals, taking care to respect
1705            # the precedence described in the specification
1706            if changed and self_is_subnormal:
1707                context._raise_error(Underflow)
1708            if self_is_subnormal:
1709                context._raise_error(Subnormal)
1710            if changed:
1711                context._raise_error(Inexact)
1712            context._raise_error(Rounded)
1713            if not ans:
1714                # raise Clamped on underflow to 0
1715                context._raise_error(Clamped)
1716            return ans
1717
1718        if self_is_subnormal:
1719            context._raise_error(Subnormal)
1720
1721        # fold down if _clamp == 1 and self has too few digits
1722        if context._clamp == 1 and self._exp > Etop:
1723            context._raise_error(Clamped)
1724            self_padded = self._int + '0'*(self._exp - Etop)
1725            return _dec_from_triple(self._sign, self_padded, Etop)
1726
1727        # here self was representable to begin with; return unchanged
1728        return Decimal(self)
1729
1730    # for each of the rounding functions below:
1731    #   self is a finite, nonzero Decimal
1732    #   prec is an integer satisfying 0 <= prec < len(self._int)
1733    #
1734    # each function returns either -1, 0, or 1, as follows:
1735    #   1 indicates that self should be rounded up (away from zero)
1736    #   0 indicates that self should be truncated, and that all the
1737    #     digits to be truncated are zeros (so the value is unchanged)
1738    #  -1 indicates that there are nonzero digits to be truncated
1739
1740    def _round_down(self, prec):
1741        """Also known as round-towards-0, truncate."""
1742        if _all_zeros(self._int, prec):
1743            return 0
1744        else:
1745            return -1
1746
1747    def _round_up(self, prec):
1748        """Rounds away from 0."""
1749        return -self._round_down(prec)
1750
1751    def _round_half_up(self, prec):
1752        """Rounds 5 up (away from 0)"""
1753        if self._int[prec] in '56789':
1754            return 1
1755        elif _all_zeros(self._int, prec):
1756            return 0
1757        else:
1758            return -1
1759
1760    def _round_half_down(self, prec):
1761        """Round 5 down"""
1762        if _exact_half(self._int, prec):
1763            return -1
1764        else:
1765            return self._round_half_up(prec)
1766
1767    def _round_half_even(self, prec):
1768        """Round 5 to even, rest to nearest."""
1769        if _exact_half(self._int, prec) and \
1770                (prec == 0 or self._int[prec-1] in '02468'):
1771            return -1
1772        else:
1773            return self._round_half_up(prec)
1774
1775    def _round_ceiling(self, prec):
1776        """Rounds up (not away from 0 if negative.)"""
1777        if self._sign:
1778            return self._round_down(prec)
1779        else:
1780            return -self._round_down(prec)
1781
1782    def _round_floor(self, prec):
1783        """Rounds down (not towards 0 if negative)"""
1784        if not self._sign:
1785            return self._round_down(prec)
1786        else:
1787            return -self._round_down(prec)
1788
1789    def _round_05up(self, prec):
1790        """Round down unless digit prec-1 is 0 or 5."""
1791        if prec and self._int[prec-1] not in '05':
1792            return self._round_down(prec)
1793        else:
1794            return -self._round_down(prec)
1795
1796    _pick_rounding_function = dict(
1797        ROUND_DOWN = _round_down,
1798        ROUND_UP = _round_up,
1799        ROUND_HALF_UP = _round_half_up,
1800        ROUND_HALF_DOWN = _round_half_down,
1801        ROUND_HALF_EVEN = _round_half_even,
1802        ROUND_CEILING = _round_ceiling,
1803        ROUND_FLOOR = _round_floor,
1804        ROUND_05UP = _round_05up,
1805    )
1806
1807    def fma(self, other, third, context=None):
1808        """Fused multiply-add.
1809
1810        Returns self*other+third with no rounding of the intermediate
1811        product self*other.
1812
1813        self and other are multiplied together, with no rounding of
1814        the result.  The third operand is then added to the result,
1815        and a single final rounding is performed.
1816        """
1817
1818        other = _convert_other(other, raiseit=True)
1819
1820        # compute product; raise InvalidOperation if either operand is
1821        # a signaling NaN or if the product is zero times infinity.
1822        if self._is_special or other._is_special:
1823            if context is None:
1824                context = getcontext()
1825            if self._exp == 'N':
1826                return context._raise_error(InvalidOperation, 'sNaN', self)
1827            if other._exp == 'N':
1828                return context._raise_error(InvalidOperation, 'sNaN', other)
1829            if self._exp == 'n':
1830                product = self
1831            elif other._exp == 'n':
1832                product = other
1833            elif self._exp == 'F':
1834                if not other:
1835                    return context._raise_error(InvalidOperation,
1836                                                'INF * 0 in fma')
1837                product = _SignedInfinity[self._sign ^ other._sign]
1838            elif other._exp == 'F':
1839                if not self:
1840                    return context._raise_error(InvalidOperation,
1841                                                '0 * INF in fma')
1842                product = _SignedInfinity[self._sign ^ other._sign]
1843        else:
1844            product = _dec_from_triple(self._sign ^ other._sign,
1845                                       str(int(self._int) * int(other._int)),
1846                                       self._exp + other._exp)
1847
1848        third = _convert_other(third, raiseit=True)
1849        return product.__add__(third, context)
1850
1851    def _power_modulo(self, other, modulo, context=None):
1852        """Three argument version of __pow__"""
1853
1854        # if can't convert other and modulo to Decimal, raise
1855        # TypeError; there's no point returning NotImplemented (no
1856        # equivalent of __rpow__ for three argument pow)
1857        other = _convert_other(other, raiseit=True)
1858        modulo = _convert_other(modulo, raiseit=True)
1859
1860        if context is None:
1861            context = getcontext()
1862
1863        # deal with NaNs: if there are any sNaNs then first one wins,
1864        # (i.e. behaviour for NaNs is identical to that of fma)
1865        self_is_nan = self._isnan()
1866        other_is_nan = other._isnan()
1867        modulo_is_nan = modulo._isnan()
1868        if self_is_nan or other_is_nan or modulo_is_nan:
1869            if self_is_nan == 2:
1870                return context._raise_error(InvalidOperation, 'sNaN',
1871                                        self)
1872            if other_is_nan == 2:
1873                return context._raise_error(InvalidOperation, 'sNaN',
1874                                        other)
1875            if modulo_is_nan == 2:
1876                return context._raise_error(InvalidOperation, 'sNaN',
1877                                        modulo)
1878            if self_is_nan:
1879                return self._fix_nan(context)
1880            if other_is_nan:
1881                return other._fix_nan(context)
1882            return modulo._fix_nan(context)
1883
1884        # check inputs: we apply same restrictions as Python's pow()
1885        if not (self._isinteger() and
1886                other._isinteger() and
1887                modulo._isinteger()):
1888            return context._raise_error(InvalidOperation,
1889                                        'pow() 3rd argument not allowed '
1890                                        'unless all arguments are integers')
1891        if other < 0:
1892            return context._raise_error(InvalidOperation,
1893                                        'pow() 2nd argument cannot be '
1894                                        'negative when 3rd argument specified')
1895        if not modulo:
1896            return context._raise_error(InvalidOperation,
1897                                        'pow() 3rd argument cannot be 0')
1898
1899        # additional restriction for decimal: the modulus must be less
1900        # than 10**prec in absolute value
1901        if modulo.adjusted() >= context.prec:
1902            return context._raise_error(InvalidOperation,
1903                                        'insufficient precision: pow() 3rd '
1904                                        'argument must not have more than '
1905                                        'precision digits')
1906
1907        # define 0**0 == NaN, for consistency with two-argument pow
1908        # (even though it hurts!)
1909        if not other and not self:
1910            return context._raise_error(InvalidOperation,
1911                                        'at least one of pow() 1st argument '
1912                                        'and 2nd argument must be nonzero ;'
1913                                        '0**0 is not defined')
1914
1915        # compute sign of result
1916        if other._iseven():
1917            sign = 0
1918        else:
1919            sign = self._sign
1920
1921        # convert modulo to a Python integer, and self and other to
1922        # Decimal integers (i.e. force their exponents to be >= 0)
1923        modulo = abs(int(modulo))
1924        base = _WorkRep(self.to_integral_value())
1925        exponent = _WorkRep(other.to_integral_value())
1926
1927        # compute result using integer pow()
1928        base = (base.int % modulo * pow(10, base.exp, modulo)) % modulo
1929        for i in xrange(exponent.exp):
1930            base = pow(base, 10, modulo)
1931        base = pow(base, exponent.int, modulo)
1932
1933        return _dec_from_triple(sign, str(base), 0)
1934
1935    def _power_exact(self, other, p):
1936        """Attempt to compute self**other exactly.
1937
1938        Given Decimals self and other and an integer p, attempt to
1939        compute an exact result for the power self**other, with p
1940        digits of precision.  Return None if self**other is not
1941        exactly representable in p digits.
1942
1943        Assumes that elimination of special cases has already been
1944        performed: self and other must both be nonspecial; self must
1945        be positive and not numerically equal to 1; other must be
1946        nonzero.  For efficiency, other._exp should not be too large,
1947        so that 10**abs(other._exp) is a feasible calculation."""
1948
1949        # In the comments below, we write x for the value of self and y for the
1950        # value of other.  Write x = xc*10**xe and abs(y) = yc*10**ye, with xc
1951        # and yc positive integers not divisible by 10.
1952
1953        # The main purpose of this method is to identify the *failure*
1954        # of x**y to be exactly representable with as little effort as
1955        # possible.  So we look for cheap and easy tests that
1956        # eliminate the possibility of x**y being exact.  Only if all
1957        # these tests are passed do we go on to actually compute x**y.
1958
1959        # Here's the main idea.  Express y as a rational number m/n, with m and
1960        # n relatively prime and n>0.  Then for x**y to be exactly
1961        # representable (at *any* precision), xc must be the nth power of a
1962        # positive integer and xe must be divisible by n.  If y is negative
1963        # then additionally xc must be a power of either 2 or 5, hence a power
1964        # of 2**n or 5**n.
1965        #
1966        # There's a limit to how small |y| can be: if y=m/n as above
1967        # then:
1968        #
1969        #  (1) if xc != 1 then for the result to be representable we
1970        #      need xc**(1/n) >= 2, and hence also xc**|y| >= 2.  So
1971        #      if |y| <= 1/nbits(xc) then xc < 2**nbits(xc) <=
1972        #      2**(1/|y|), hence xc**|y| < 2 and the result is not
1973        #      representable.
1974        #
1975        #  (2) if xe != 0, |xe|*(1/n) >= 1, so |xe|*|y| >= 1.  Hence if
1976        #      |y| < 1/|xe| then the result is not representable.
1977        #
1978        # Note that since x is not equal to 1, at least one of (1) and
1979        # (2) must apply.  Now |y| < 1/nbits(xc) iff |yc|*nbits(xc) <
1980        # 10**-ye iff len(str(|yc|*nbits(xc)) <= -ye.
1981        #
1982        # There's also a limit to how large y can be, at least if it's
1983        # positive: the normalized result will have coefficient xc**y,
1984        # so if it's representable then xc**y < 10**p, and y <
1985        # p/log10(xc).  Hence if y*log10(xc) >= p then the result is
1986        # not exactly representable.
1987
1988        # if len(str(abs(yc*xe)) <= -ye then abs(yc*xe) < 10**-ye,
1989        # so |y| < 1/xe and the result is not representable.
1990        # Similarly, len(str(abs(yc)*xc_bits)) <= -ye implies |y|
1991        # < 1/nbits(xc).
1992
1993        x = _WorkRep(self)
1994        xc, xe = x.int, x.exp
1995        while xc % 10 == 0:
1996            xc //= 10
1997            xe += 1
1998
1999        y = _WorkRep(other)
2000        yc, ye = y.int, y.exp
2001        while yc % 10 == 0:
2002            yc //= 10
2003            ye += 1
2004
2005        # case where xc == 1: result is 10**(xe*y), with xe*y
2006        # required to be an integer
2007        if xc == 1:
2008            xe *= yc
2009            # result is now 10**(xe * 10**ye);  xe * 10**ye must be integral
2010            while xe % 10 == 0:
2011                xe //= 10
2012                ye += 1
2013            if ye < 0:
2014                return None
2015            exponent = xe * 10**ye
2016            if y.sign == 1:
2017                exponent = -exponent
2018            # if other is a nonnegative integer, use ideal exponent
2019            if other._isinteger() and other._sign == 0:
2020                ideal_exponent = self._exp*int(other)
2021                zeros = min(exponent-ideal_exponent, p-1)
2022            else:
2023                zeros = 0
2024            return _dec_from_triple(0, '1' + '0'*zeros, exponent-zeros)
2025
2026        # case where y is negative: xc must be either a power
2027        # of 2 or a power of 5.
2028        if y.sign == 1:
2029            last_digit = xc % 10
2030            if last_digit in (2,4,6,8):
2031                # quick test for power of 2
2032                if xc & -xc != xc:
2033                    return None
2034                # now xc is a power of 2; e is its exponent
2035                e = _nbits(xc)-1
2036
2037                # We now have:
2038                #
2039                #   x = 2**e * 10**xe, e > 0, and y < 0.
2040                #
2041                # The exact result is:
2042                #
2043                #   x**y = 5**(-e*y) * 10**(e*y + xe*y)
2044                #
2045                # provided that both e*y and xe*y are integers.  Note that if
2046                # 5**(-e*y) >= 10**p, then the result can't be expressed
2047                # exactly with p digits of precision.
2048                #
2049                # Using the above, we can guard against large values of ye.
2050                # 93/65 is an upper bound for log(10)/log(5), so if
2051                #
2052                #   ye >= len(str(93*p//65))
2053                #
2054                # then
2055                #
2056                #   -e*y >= -y >= 10**ye > 93*p/65 > p*log(10)/log(5),
2057                #
2058                # so 5**(-e*y) >= 10**p, and the coefficient of the result
2059                # can't be expressed in p digits.
2060
2061                # emax >= largest e such that 5**e < 10**p.
2062                emax = p*93//65
2063                if ye >= len(str(emax)):
2064                    return None
2065
2066                # Find -e*y and -xe*y; both must be integers
2067                e = _decimal_lshift_exact(e * yc, ye)
2068                xe = _decimal_lshift_exact(xe * yc, ye)
2069                if e is None or xe is None:
2070                    return None
2071
2072                if e > emax:
2073                    return None
2074                xc = 5**e
2075
2076            elif last_digit == 5:
2077                # e >= log_5(xc) if xc is a power of 5; we have
2078                # equality all the way up to xc=5**2658
2079                e = _nbits(xc)*28//65
2080                xc, remainder = divmod(5**e, xc)
2081                if remainder:
2082                    return None
2083                while xc % 5 == 0:
2084                    xc //= 5
2085                    e -= 1
2086
2087                # Guard against large values of ye, using the same logic as in
2088                # the 'xc is a power of 2' branch.  10/3 is an upper bound for
2089                # log(10)/log(2).
2090                emax = p*10//3
2091                if ye >= len(str(emax)):
2092                    return None
2093
2094                e = _decimal_lshift_exact(e * yc, ye)
2095                xe = _decimal_lshift_exact(xe * yc, ye)
2096                if e is None or xe is None:
2097                    return None
2098
2099                if e > emax:
2100                    return None
2101                xc = 2**e
2102            else:
2103                return None
2104
2105            if xc >= 10**p:
2106                return None
2107            xe = -e-xe
2108            return _dec_from_triple(0, str(xc), xe)
2109
2110        # now y is positive; find m and n such that y = m/n
2111        if ye >= 0:
2112            m, n = yc*10**ye, 1
2113        else:
2114            if xe != 0 and len(str(abs(yc*xe))) <= -ye:
2115                return None
2116            xc_bits = _nbits(xc)
2117            if xc != 1 and len(str(abs(yc)*xc_bits)) <= -ye:
2118                return None
2119            m, n = yc, 10**(-ye)
2120            while m % 2 == n % 2 == 0:
2121                m //= 2
2122                n //= 2
2123            while m % 5 == n % 5 == 0:
2124                m //= 5
2125                n //= 5
2126
2127        # compute nth root of xc*10**xe
2128        if n > 1:
2129            # if 1 < xc < 2**n then xc isn't an nth power
2130            if xc != 1 and xc_bits <= n:
2131                return None
2132
2133            xe, rem = divmod(xe, n)
2134            if rem != 0:
2135                return None
2136
2137            # compute nth root of xc using Newton's method
2138            a = 1L << -(-_nbits(xc)//n) # initial estimate
2139            while True:
2140                q, r = divmod(xc, a**(n-1))
2141                if a <= q:
2142                    break
2143                else:
2144                    a = (a*(n-1) + q)//n
2145            if not (a == q and r == 0):
2146                return None
2147            xc = a
2148
2149        # now xc*10**xe is the nth root of the original xc*10**xe
2150        # compute mth power of xc*10**xe
2151
2152        # if m > p*100//_log10_lb(xc) then m > p/log10(xc), hence xc**m >
2153        # 10**p and the result is not representable.
2154        if xc > 1 and m > p*100//_log10_lb(xc):
2155            return None
2156        xc = xc**m
2157        xe *= m
2158        if xc > 10**p:
2159            return None
2160
2161        # by this point the result *is* exactly representable
2162        # adjust the exponent to get as close as possible to the ideal
2163        # exponent, if necessary
2164        str_xc = str(xc)
2165        if other._isinteger() and other._sign == 0:
2166            ideal_exponent = self._exp*int(other)
2167            zeros = min(xe-ideal_exponent, p-len(str_xc))
2168        else:
2169            zeros = 0
2170        return _dec_from_triple(0, str_xc+'0'*zeros, xe-zeros)
2171
2172    def __pow__(self, other, modulo=None, context=None):
2173        """Return self ** other [ % modulo].
2174
2175        With two arguments, compute self**other.
2176
2177        With three arguments, compute (self**other) % modulo.  For the
2178        three argument form, the following restrictions on the
2179        arguments hold:
2180
2181         - all three arguments must be integral
2182         - other must be nonnegative
2183         - either self or other (or both) must be nonzero
2184         - modulo must be nonzero and must have at most p digits,
2185           where p is the context precision.
2186
2187        If any of these restrictions is violated the InvalidOperation
2188        flag is raised.
2189
2190        The result of pow(self, other, modulo) is identical to the
2191        result that would be obtained by computing (self**other) %
2192        modulo with unbounded precision, but is computed more
2193        efficiently.  It is always exact.
2194        """
2195
2196        if modulo is not None:
2197            return self._power_modulo(other, modulo, context)
2198
2199        other = _convert_other(other)
2200        if other is NotImplemented:
2201            return other
2202
2203        if context is None:
2204            context = getcontext()
2205
2206        # either argument is a NaN => result is NaN
2207        ans = self._check_nans(other, context)
2208        if ans:
2209            return ans
2210
2211        # 0**0 = NaN (!), x**0 = 1 for nonzero x (including +/-Infinity)
2212        if not other:
2213            if not self:
2214                return context._raise_error(InvalidOperation, '0 ** 0')
2215            else:
2216                return _One
2217
2218        # result has sign 1 iff self._sign is 1 and other is an odd integer
2219        result_sign = 0
2220        if self._sign == 1:
2221            if other._isinteger():
2222                if not other._iseven():
2223                    result_sign = 1
2224            else:
2225                # -ve**noninteger = NaN
2226                # (-0)**noninteger = 0**noninteger
2227                if self:
2228                    return context._raise_error(InvalidOperation,
2229                        'x ** y with x negative and y not an integer')
2230            # negate self, without doing any unwanted rounding
2231            self = self.copy_negate()
2232
2233        # 0**(+ve or Inf)= 0; 0**(-ve or -Inf) = Infinity
2234        if not self:
2235            if other._sign == 0:
2236                return _dec_from_triple(result_sign, '0', 0)
2237            else:
2238                return _SignedInfinity[result_sign]
2239
2240        # Inf**(+ve or Inf) = Inf; Inf**(-ve or -Inf) = 0
2241        if self._isinfinity():
2242            if other._sign == 0:
2243                return _SignedInfinity[result_sign]
2244            else:
2245                return _dec_from_triple(result_sign, '0', 0)
2246
2247        # 1**other = 1, but the choice of exponent and the flags
2248        # depend on the exponent of self, and on whether other is a
2249        # positive integer, a negative integer, or neither
2250        if self == _One:
2251            if other._isinteger():
2252                # exp = max(self._exp*max(int(other), 0),
2253                # 1-context.prec) but evaluating int(other) directly
2254                # is dangerous until we know other is small (other
2255                # could be 1e999999999)
2256                if other._sign == 1:
2257                    multiplier = 0
2258                elif other > context.prec:
2259                    multiplier = context.prec
2260                else:
2261                    multiplier = int(other)
2262
2263                exp = self._exp * multiplier
2264                if exp < 1-context.prec:
2265                    exp = 1-context.prec
2266                    context._raise_error(Rounded)
2267            else:
2268                context._raise_error(Inexact)
2269                context._raise_error(Rounded)
2270                exp = 1-context.prec
2271
2272            return _dec_from_triple(result_sign, '1'+'0'*-exp, exp)
2273
2274        # compute adjusted exponent of self
2275        self_adj = self.adjusted()
2276
2277        # self ** infinity is infinity if self > 1, 0 if self < 1
2278        # self ** -infinity is infinity if self < 1, 0 if self > 1
2279        if other._isinfinity():
2280            if (other._sign == 0) == (self_adj < 0):
2281                return _dec_from_triple(result_sign, '0', 0)
2282            else:
2283                return _SignedInfinity[result_sign]
2284
2285        # from here on, the result always goes through the call
2286        # to _fix at the end of this function.
2287        ans = None
2288        exact = False
2289
2290        # crude test to catch cases of extreme overflow/underflow.  If
2291        # log10(self)*other >= 10**bound and bound >= len(str(Emax))
2292        # then 10**bound >= 10**len(str(Emax)) >= Emax+1 and hence
2293        # self**other >= 10**(Emax+1), so overflow occurs.  The test
2294        # for underflow is similar.
2295        bound = self._log10_exp_bound() + other.adjusted()
2296        if (self_adj >= 0) == (other._sign == 0):
2297            # self > 1 and other +ve, or self < 1 and other -ve
2298            # possibility of overflow
2299            if bound >= len(str(context.Emax)):
2300                ans = _dec_from_triple(result_sign, '1', context.Emax+1)
2301        else:
2302            # self > 1 and other -ve, or self < 1 and other +ve
2303            # possibility of underflow to 0
2304            Etiny = context.Etiny()
2305            if bound >= len(str(-Etiny)):
2306                ans = _dec_from_triple(result_sign, '1', Etiny-1)
2307
2308        # try for an exact result with precision +1
2309        if ans is None:
2310            ans = self._power_exact(other, context.prec + 1)
2311            if ans is not None:
2312                if result_sign == 1:
2313                    ans = _dec_from_triple(1, ans._int, ans._exp)
2314                exact = True
2315
2316        # usual case: inexact result, x**y computed directly as exp(y*log(x))
2317        if ans is None:
2318            p = context.prec
2319            x = _WorkRep(self)
2320            xc, xe = x.int, x.exp
2321            y = _WorkRep(other)
2322            yc, ye = y.int, y.exp
2323            if y.sign == 1:
2324                yc = -yc
2325
2326            # compute correctly rounded result:  start with precision +3,
2327            # then increase precision until result is unambiguously roundable
2328            extra = 3
2329            while True:
2330                coeff, exp = _dpower(xc, xe, yc, ye, p+extra)
2331                if coeff % (5*10**(len(str(coeff))-p-1)):
2332                    break
2333                extra += 3
2334
2335            ans = _dec_from_triple(result_sign, str(coeff), exp)
2336
2337        # unlike exp, ln and log10, the power function respects the
2338        # rounding mode; no need to switch to ROUND_HALF_EVEN here
2339
2340        # There's a difficulty here when 'other' is not an integer and
2341        # the result is exact.  In this case, the specification
2342        # requires that the Inexact flag be raised (in spite of
2343        # exactness), but since the result is exact _fix won't do this
2344        # for us.  (Correspondingly, the Underflow signal should also
2345        # be raised for subnormal results.)  We can't directly raise
2346        # these signals either before or after calling _fix, since
2347        # that would violate the precedence for signals.  So we wrap
2348        # the ._fix call in a temporary context, and reraise
2349        # afterwards.
2350        if exact and not other._isinteger():
2351            # pad with zeros up to length context.prec+1 if necessary; this
2352            # ensures that the Rounded signal will be raised.
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,
2356                                       ans._exp-expdiff)
2357
2358            # create a copy of the current context, with cleared flags/traps
2359            newcontext = context.copy()
2360            newcontext.clear_flags()
2361            for exception in _signals:
2362                newcontext.traps[exception] = 0
2363
2364            # round in the new context
2365            ans = ans._fix(newcontext)
2366
2367            # raise Inexact, and if necessary, Underflow
2368            newcontext._raise_error(Inexact)
2369            if newcontext.flags[Subnormal]:
2370                newcontext._raise_error(Underflow)
2371
2372            # propagate signals to the original context; _fix could
2373            # have raised any of Overflow, Underflow, Subnormal,
2374            # Inexact, Rounded, Clamped.  Overflow needs the correct
2375            # arguments.  Note that the order of the exceptions is
2376            # important here.
2377            if newcontext.flags[Overflow]:
2378                context._raise_error(Overflow, 'above Emax', ans._sign)
2379            for exception in Underflow, Subnormal, Inexact, Rounded, Clamped:
2380                if newcontext.flags[exception]:
2381                    context._raise_error(exception)
2382
2383        else:
2384            ans = ans._fix(context)
2385
2386        return ans
2387
2388    def __rpow__(self, other, context=None):
2389        """Swaps self/other and returns __pow__."""
2390        other = _convert_other(other)
2391        if other is NotImplemented:
2392            return other
2393        return other.__pow__(self, context=context)
2394
2395    def normalize(self, context=None):
2396        """Normalize- strip trailing 0s, change anything equal to 0 to 0e0"""
2397
2398        if context is None:
2399            context = getcontext()
2400
2401        if self._is_special:
2402            ans = self._check_nans(context=context)
2403            if ans:
2404                return ans
2405
2406        dup = self._fix(context)
2407        if dup._isinfinity():
2408            return dup
2409
2410        if not dup:
2411            return _dec_from_triple(dup._sign, '0', 0)
2412        exp_max = [context.Emax, context.Etop()][context._clamp]
2413        end = len(dup._int)
2414        exp = dup._exp
2415        while dup._int[end-1] == '0' and exp < exp_max:
2416            exp += 1
2417            end -= 1
2418        return _dec_from_triple(dup._sign, dup._int[:end], exp)
2419
2420    def quantize(self, exp, rounding=None, context=None, watchexp=True):
2421        """Quantize self so its exponent is the same as that of exp.
2422
2423        Similar to self._rescale(exp._exp) but with error checking.
2424        """
2425        exp = _convert_other(exp, raiseit=True)
2426
2427        if context is None:
2428            context = getcontext()
2429        if rounding is None:
2430            rounding = context.rounding
2431
2432        if self._is_special or exp._is_special:
2433            ans = self._check_nans(exp, context)
2434            if ans:
2435                return ans
2436
2437            if exp._isinfinity() or self._isinfinity():
2438                if exp._isinfinity() and self._isinfinity():
2439                    return Decimal(self)  # if both are inf, it is OK
2440                return context._raise_error(InvalidOperation,
2441                                        'quantize with one INF')
2442
2443        # if we're not watching exponents, do a simple rescale
2444        if not watchexp:
2445            ans = self._rescale(exp._exp, rounding)
2446            # raise Inexact and Rounded where appropriate
2447            if ans._exp > self._exp:
2448                context._raise_error(Rounded)
2449                if ans != self:
2450                    context._raise_error(Inexact)
2451            return ans
2452
2453        # exp._exp should be between Etiny and Emax
2454        if not (context.Etiny() <= exp._exp <= context.Emax):
2455            return context._raise_error(InvalidOperation,
2456                   'target exponent out of bounds in quantize')
2457
2458        if not self:
2459            ans = _dec_from_triple(self._sign, '0', exp._exp)
2460            return ans._fix(context)
2461
2462        self_adjusted = self.adjusted()
2463        if self_adjusted > context.Emax:
2464            return context._raise_error(InvalidOperation,
2465                                        'exponent of quantize result too large for current context')
2466        if self_adjusted - exp._exp + 1 > context.prec:
2467            return context._raise_error(InvalidOperation,
2468                                        'quantize result has too many digits for current context')
2469
2470        ans = self._rescale(exp._exp, rounding)
2471        if ans.adjusted() > context.Emax:
2472            return context._raise_error(InvalidOperation,
2473                                        'exponent of quantize result too large for current context')
2474        if len(ans._int) > context.prec:
2475            return context._raise_error(InvalidOperation,
2476                                        'quantize result has too many digits for current context')
2477
2478        # raise appropriate flags
2479        if ans and ans.adjusted() < context.Emin:
2480            context._raise_error(Subnormal)
2481        if ans._exp > self._exp:
2482            if ans != self:
2483                context._raise_error(Inexact)
2484            context._raise_error(Rounded)
2485
2486        # call to fix takes care of any necessary folddown, and
2487        # signals Clamped if necessary
2488        ans = ans._fix(context)
2489        return ans
2490
2491    def same_quantum(self, other):
2492        """Return True if self and other have the same exponent; otherwise
2493        return False.
2494
2495        If either operand is a special value, the following rules are used:
2496           * return True if both operands are infinities
2497           * return True if both operands are NaNs
2498           * otherwise, return False.
2499        """
2500        other = _convert_other(other, raiseit=True)
2501        if self._is_special or other._is_special:
2502            return (self.is_nan() and other.is_nan() or
2503                    self.is_infinite() and other.is_infinite())
2504        return self._exp == other._exp
2505
2506    def _rescale(self, exp, rounding):
2507        """Rescale self so that the exponent is exp, either by padding with zeros
2508        or by truncating digits, using the given rounding mode.
2509
2510        Specials are returned without change.  This operation is
2511        quiet: it raises no flags, and uses no information from the
2512        context.
2513
2514        exp = exp to scale to (an integer)
2515        rounding = rounding mode
2516        """
2517        if self._is_special:
2518            return Decimal(self)
2519        if not self:
2520            return _dec_from_triple(self._sign, '0', exp)
2521
2522        if self._exp >= exp:
2523            # pad answer with zeros if necessary
2524            return _dec_from_triple(self._sign,
2525                                        self._int + '0'*(self._exp - exp), exp)
2526
2527        # too many digits; round and lose data.  If self.adjusted() <
2528        # exp-1, replace self by 10**(exp-1) before rounding
2529        digits = len(self._int) + self._exp - exp
2530        if digits < 0:
2531            self = _dec_from_triple(self._sign, '1', exp-1)
2532            digits = 0
2533        this_function = self._pick_rounding_function[rounding]
2534        changed = this_function(self, digits)
2535        coeff = self._int[:digits] or '0'
2536        if changed == 1:
2537            coeff = str(int(coeff)+1)
2538        return _dec_from_triple(self._sign, coeff, exp)
2539
2540    def _round(self, places, rounding):
2541        """Round a nonzero, nonspecial Decimal to a fixed number of
2542        significant figures, using the given rounding mode.
2543
2544        Infinities, NaNs and zeros are returned unaltered.
2545
2546        This operation is quiet: it raises no flags, and uses no
2547        information from the context.
2548
2549        """
2550        if places <= 0:
2551            raise ValueError("argument should be at least 1 in _round")
2552        if self._is_special or not self:
2553            return Decimal(self)
2554        ans = self._rescale(self.adjusted()+1-places, rounding)
2555        # it can happen that the rescale alters the adjusted exponent;
2556        # for example when rounding 99.97 to 3 significant figures.
2557        # When this happens we end up with an extra 0 at the end of
2558        # the number; a second rescale fixes this.
2559        if ans.adjusted() != self.adjusted():
2560            ans = ans._rescale(ans.adjusted()+1-places, rounding)
2561        return ans
2562
2563    def to_integral_exact(self, rounding=None, context=None):
2564        """Rounds to a nearby integer.
2565
2566        If no rounding mode is specified, take the rounding mode from
2567        the context.  This method raises the Rounded and Inexact flags
2568        when appropriate.
2569
2570        See also: to_integral_value, which does exactly the same as
2571        this method except that it doesn't raise Inexact or Rounded.
2572        """
2573        if self._is_special:
2574            ans = self._check_nans(context=context)
2575            if ans:
2576                return ans
2577            return Decimal(self)
2578        if self._exp >= 0:
2579            return Decimal(self)
2580        if not self:
2581            return _dec_from_triple(self._sign, '0', 0)
2582        if context is None:
2583            context = getcontext()
2584        if rounding is None:
2585            rounding = context.rounding
2586        ans = self._rescale(0, rounding)
2587        if ans != self:
2588            context._raise_error(Inexact)
2589        context._raise_error(Rounded)
2590        return ans
2591
2592    def to_integral_value(self, rounding=None, context=None):
2593        """Rounds to the nearest integer, without raising inexact, rounded."""
2594        if context is None:
2595            context = getcontext()
2596        if rounding is None:
2597            rounding = context.rounding
2598        if self._is_special:
2599            ans = self._check_nans(context=context)
2600            if ans:
2601                return ans
2602            return Decimal(self)
2603        if self._exp >= 0:
2604            return Decimal(self)
2605        else:
2606            return self._rescale(0, rounding)
2607
2608    # the method name changed, but we provide also the old one, for compatibility
2609    to_integral = to_integral_value
2610
2611    def sqrt(self, context=None):
2612        """Return the square root of self."""
2613        if context is None:
2614            context = getcontext()
2615
2616        if self._is_special:
2617            ans = self._check_nans(context=context)
2618            if ans:
2619                return ans
2620
2621            if self._isinfinity() and self._sign == 0:
2622                return Decimal(self)
2623
2624        if not self:
2625            # exponent = self._exp // 2.  sqrt(-0) = -0
2626            ans = _dec_from_triple(self._sign, '0', self._exp // 2)
2627            return ans._fix(context)
2628
2629        if self._sign == 1:
2630            return context._raise_error(InvalidOperation, 'sqrt(-x), x > 0')
2631
2632        # At this point self represents a positive number.  Let p be
2633        # the desired precision and express self in the form c*100**e
2634        # with c a positive real number and e an integer, c and e
2635        # being chosen so that 100**(p-1) <= c < 100**p.  Then the
2636        # (exact) square root of self is sqrt(c)*10**e, and 10**(p-1)
2637        # <= sqrt(c) < 10**p, so the closest representable Decimal at
2638        # precision p is n*10**e where n = round_half_even(sqrt(c)),
2639        # the closest integer to sqrt(c) with the even integer chosen
2640        # in the case of a tie.
2641        #
2642        # To ensure correct rounding in all cases, we use the
2643        # following trick: we compute the square root to an extra
2644        # place (precision p+1 instead of precision p), rounding down.
2645        # Then, if the result is inexact and its last digit is 0 or 5,
2646        # we increase the last digit to 1 or 6 respectively; if it's
2647        # exact we leave the last digit alone.  Now the final round to
2648        # p places (or fewer in the case of underflow) will round
2649        # correctly and raise the appropriate flags.
2650
2651        # use an extra digit of precision
2652        prec = context.prec+1
2653
2654        # write argument in the form c*100**e where e = self._exp//2
2655        # is the 'ideal' exponent, to be used if the square root is
2656        # exactly representable.  l is the number of 'digits' of c in
2657        # base 100, so that 100**(l-1) <= c < 100**l.
2658        op = _WorkRep(self)
2659        e = op.exp >> 1
2660        if op.exp & 1:
2661            c = op.int * 10
2662            l = (len(self._int) >> 1) + 1
2663        else:
2664            c = op.int
2665            l = len(self._int)+1 >> 1
2666
2667        # rescale so that c has exactly prec base 100 'digits'
2668        shift = prec-l
2669        if shift >= 0:
2670            c *= 100**shift
2671            exact = True
2672        else:
2673            c, remainder = divmod(c, 100**-shift)
2674            exact = not remainder
2675        e -= shift
2676
2677        # find n = floor(sqrt(c)) using Newton's method
2678        n = 10**prec
2679        while True:
2680            q = c//n
2681            if n <= q:
2682                break
2683            else:
2684                n = n + q >> 1
2685        exact = exact and n*n == c
2686
2687        if exact:
2688            # result is exact; rescale to use ideal exponent e
2689            if shift >= 0:
2690                # assert n % 10**shift == 0
2691                n //= 10**shift
2692            else:
2693                n *= 10**-shift
2694            e += shift
2695        else:
2696            # result is not exact; fix last digit as described above
2697            if n % 5 == 0:
2698                n += 1
2699
2700        ans = _dec_from_triple(0, str(n), e)
2701
2702        # round, and fit to current context
2703        context = context._shallow_copy()
2704        rounding = context._set_rounding(ROUND_HALF_EVEN)
2705        ans = ans._fix(context)
2706        context.rounding = rounding
2707
2708        return ans
2709
2710    def max(self, other, context=None):
2711        """Returns the larger value.
2712
2713        Like max(self, other) except if one is not a number, returns
2714        NaN (and signals if one is sNaN).  Also rounds.
2715        """
2716        other = _convert_other(other, raiseit=True)
2717
2718        if context is None:
2719            context = getcontext()
2720
2721        if self._is_special or other._is_special:
2722            # If one operand is a quiet NaN and the other is number, then the
2723            # number is always returned
2724            sn = self._isnan()
2725            on = other._isnan()
2726            if sn or on:
2727                if on == 1 and sn == 0:
2728                    return self._fix(context)
2729                if sn == 1 and on == 0:
2730                    return other._fix(context)
2731                return self._check_nans(other, context)
2732
2733        c = self._cmp(other)
2734        if c == 0:
2735            # If both operands are finite and equal in numerical value
2736            # then an ordering is applied:
2737            #
2738            # If the signs differ then max returns the operand with the
2739            # positive sign and min returns the operand with the negative sign
2740            #
2741            # If the signs are the same then the exponent is used to select
2742            # the result.  This is exactly the ordering used in compare_total.
2743            c = self.compare_total(other)
2744
2745        if c == -1:
2746            ans = other
2747        else:
2748            ans = self
2749
2750        return ans._fix(context)
2751
2752    def min(self, other, context=None):
2753        """Returns the smaller value.
2754
2755        Like min(self, other) except if one is not a number, returns
2756        NaN (and signals if one is sNaN).  Also rounds.
2757        """
2758        other = _convert_other(other, raiseit=True)
2759
2760        if context is None:
2761            context = getcontext()
2762
2763        if self._is_special or other._is_special:
2764            # If one operand is a quiet NaN and the other is number, then the
2765            # number is always returned
2766            sn = self._isnan()
2767            on = other._isnan()
2768            if sn or on:
2769                if on == 1 and sn == 0:
2770                    return self._fix(context)
2771                if sn == 1 and on == 0:
2772                    return other._fix(context)
2773                return self._check_nans(other, context)
2774
2775        c = self._cmp(other)
2776        if c == 0:
2777            c = self.compare_total(other)
2778
2779        if c == -1:
2780            ans = self
2781        else:
2782            ans = other
2783
2784        return ans._fix(context)
2785
2786    def _isinteger(self):
2787        """Returns whether self is an integer"""
2788        if self._is_special:
2789            return False
2790        if self._exp >= 0:
2791            return True
2792        rest = self._int[self._exp:]
2793        return rest == '0'*len(rest)
2794
2795    def _iseven(self):
2796        """Returns True if self is even.  Assumes self is an integer."""
2797        if not self or self._exp > 0:
2798            return True
2799        return self._int[-1+self._exp] in '02468'
2800
2801    def adjusted(self):
2802        """Return the adjusted exponent of self"""
2803        try:
2804            return self._exp + len(self._int) - 1
2805        # If NaN or Infinity, self._exp is string
2806        except TypeError:
2807            return 0
2808
2809    def canonical(self, context=None):
2810        """Returns the same Decimal object.
2811
2812        As we do not have different encodings for the same number, the
2813        received object already is in its canonical form.
2814        """
2815        return self
2816
2817    def compare_signal(self, other, context=None):
2818        """Compares self to the other operand numerically.
2819
2820        It's pretty much like compare(), but all NaNs signal, with signaling
2821        NaNs taking precedence over quiet NaNs.
2822        """
2823        other = _convert_other(other, raiseit = True)
2824        ans = self._compare_check_nans(other, context)
2825        if ans:
2826            return ans
2827        return self.compare(other, context=context)
2828
2829    def compare_total(self, other):
2830        """Compares self to other using the abstract representations.
2831
2832        This is not like the standard compare, which use their numerical
2833        value. Note that a total ordering is defined for all possible abstract
2834        representations.
2835        """
2836        other = _convert_other(other, raiseit=True)
2837
2838        # if one is negative and the other is positive, it's easy
2839        if self._sign and not other._sign:
2840            return _NegativeOne
2841        if not self._sign and other._sign:
2842            return _One
2843        sign = self._sign
2844
2845        # let's handle both NaN types
2846        self_nan = self._isnan()
2847        other_nan = other._isnan()
2848        if self_nan or other_nan:
2849            if self_nan == other_nan:
2850                # compare payloads as though they're integers
2851                self_key = len(self._int), self._int
2852                other_key = len(other._int), other._int
2853                if self_key < other_key:
2854                    if sign:
2855                        return _One
2856                    else:
2857                        return _NegativeOne
2858                if self_key > other_key:
2859                    if sign:
2860                        return _NegativeOne
2861                    else:
2862                        return _One
2863                return _Zero
2864
2865            if sign:
2866                if self_nan == 1:
2867                    return _NegativeOne
2868                if other_nan == 1:
2869                    return _One
2870                if self_nan == 2:
2871                    return _NegativeOne
2872                if other_nan == 2:
2873                    return _One
2874            else:
2875                if self_nan == 1:
2876                    return _One
2877                if other_nan == 1:
2878                    return _NegativeOne
2879                if self_nan == 2:
2880                    return _One
2881                if other_nan == 2:
2882                    return _NegativeOne
2883
2884        if self < other:
2885            return _NegativeOne
2886        if self > other:
2887            return _One
2888
2889        if self._exp < other._exp:
2890            if sign:
2891                return _One
2892            else:
2893                return _NegativeOne
2894        if self._exp > other._exp:
2895            if sign:
2896                return _NegativeOne
2897            else:
2898                return _One
2899        return _Zero
2900
2901
2902    def compare_total_mag(self, other):
2903        """Compares self to other using abstract repr., ignoring sign.
2904
2905        Like compare_total, but with operand's sign ignored and assumed to be 0.
2906        """
2907        other = _convert_other(other, raiseit=True)
2908
2909        s = self.copy_abs()
2910        o = other.copy_abs()
2911        return s.compare_total(o)
2912
2913    def copy_abs(self):
2914        """Returns a copy with the sign set to 0. """
2915        return _dec_from_triple(0, self._int, self._exp, self._is_special)
2916
2917    def copy_negate(self):
2918        """Returns a copy with the sign inverted."""
2919        if self._sign:
2920            return _dec_from_triple(0, self._int, self._exp, self._is_special)
2921        else:
2922            return _dec_from_triple(1, self._int, self._exp, self._is_special)
2923
2924    def copy_sign(self, other):
2925        """Returns self with the sign of other."""
2926        other = _convert_other(other, raiseit=True)
2927        return _dec_from_triple(other._sign, self._int,
2928                                self._exp, self._is_special)
2929
2930    def exp(self, context=None):
2931        """Returns e ** self."""
2932
2933        if context is None:
2934            context = getcontext()
2935
2936        # exp(NaN) = NaN
2937        ans = self._check_nans(context=context)
2938        if ans:
2939            return ans
2940
2941        # exp(-Infinity) = 0
2942        if self._isinfinity() == -1:
2943            return _Zero
2944
2945        # exp(0) = 1
2946        if not self:
2947            return _One
2948
2949        # exp(Infinity) = Infinity
2950        if self._isinfinity() == 1:
2951            return Decimal(self)
2952
2953        # the result is now guaranteed to be inexact (the true
2954        # mathematical result is transcendental). There's no need to
2955        # raise Rounded and Inexact here---they'll always be raised as
2956        # a result of the call to _fix.
2957        p = context.prec
2958        adj = self.adjusted()
2959
2960        # we only need to do any computation for quite a small range
2961        # of adjusted exponents---for example, -29 <= adj <= 10 for
2962        # the default context.  For smaller exponent the result is
2963        # indistinguishable from 1 at the given precision, while for
2964        # larger exponent the result either overflows or underflows.
2965        if self._sign == 0 and adj > len(str((context.Emax+1)*3)):
2966            # overflow
2967            ans = _dec_from_triple(0, '1', context.Emax+1)
2968        elif self._sign == 1 and adj > len(str((-context.Etiny()+1)*3)):
2969            # underflow to 0
2970            ans = _dec_from_triple(0, '1', context.Etiny()-1)
2971        elif self._sign == 0 and adj < -p:
2972            # p+1 digits; final round will raise correct flags
2973            ans = _dec_from_triple(0, '1' + '0'*(p-1) + '1', -p)
2974        elif self._sign == 1 and adj < -p-1:
2975            # p+1 digits; final round will raise correct flags
2976            ans = _dec_from_triple(0, '9'*(p+1), -p-1)
2977        # general case
2978        else:
2979            op = _WorkRep(self)
2980            c, e = op.int, op.exp
2981            if op.sign == 1:
2982                c = -c
2983
2984            # compute correctly rounded result: increase precision by
2985            # 3 digits at a time until we get an unambiguously
2986            # roundable result
2987            extra = 3
2988            while True:
2989                coeff, exp = _dexp(c, e, p+extra)
2990                if coeff % (5*10**(len(str(coeff))-p-1)):
2991                    break
2992                extra += 3
2993
2994            ans = _dec_from_triple(0, str(coeff), exp)
2995
2996        # at this stage, ans should round correctly with *any*
2997        # rounding mode, not just with ROUND_HALF_EVEN
2998        context = context._shallow_copy()
2999        rounding = context._set_rounding(ROUND_HALF_EVEN)
3000        ans = ans._fix(context)
3001        context.rounding = rounding
3002
3003        return ans
3004
3005    def is_canonical(self):
3006        """Return True if self is canonical; otherwise return False.
3007
3008        Currently, the encoding of a Decimal instance is always
3009        canonical, so this method returns True for any Decimal.
3010        """
3011        return True
3012
3013    def is_finite(self):
3014        """Return True if self is finite; otherwise return False.
3015
3016        A Decimal instance is considered finite if it is neither
3017        infinite nor a NaN.
3018        """
3019        return not self._is_special
3020
3021    def is_infinite(self):
3022        """Return True if self is infinite; otherwise return False."""
3023        return self._exp == 'F'
3024
3025    def is_nan(self):
3026        """Return True if self is a qNaN or sNaN; otherwise return False."""
3027        return self._exp in ('n', 'N')
3028
3029    def is_normal(self, context=None):
3030        """Return True if self is a normal number; otherwise return False."""
3031        if self._is_special or not self:
3032            return False
3033        if context is None:
3034            context = getcontext()
3035        return context.Emin <= self.adjusted()
3036
3037    def is_qnan(self):
3038        """Return True if self is a quiet NaN; otherwise return False."""
3039        return self._exp == 'n'
3040
3041    def is_signed(self):
3042        """Return True if self is negative; otherwise return False."""
3043        return self._sign == 1
3044
3045    def is_snan(self):
3046        """Return True if self is a signaling NaN; otherwise return False."""
3047        return self._exp == 'N'
3048
3049    def is_subnormal(self, context=None):
3050        """Return True if self is subnormal; otherwise return False."""
3051        if self._is_special or not self:
3052            return False
3053        if context is None:
3054            context = getcontext()
3055        return self.adjusted() < context.Emin
3056
3057    def is_zero(self):
3058        """Return True if self is a zero; otherwise return False."""
3059        return not self._is_special and self._int == '0'
3060
3061    def _ln_exp_bound(self):
3062        """Compute a lower bound for the adjusted exponent of self.ln().
3063        In other words, compute r such that self.ln() >= 10**r.  Assumes
3064        that self is finite and positive and that self != 1.
3065        """
3066
3067        # for 0.1 <= x <= 10 we use the inequalities 1-1/x <= ln(x) <= x-1
3068        adj = self._exp + len(self._int) - 1
3069        if adj >= 1:
3070            # argument >= 10; we use 23/10 = 2.3 as a lower bound for ln(10)
3071            return len(str(adj*23//10)) - 1
3072        if adj <= -2:
3073            # argument <= 0.1
3074            return len(str((-1-adj)*23//10)) - 1
3075        op = _WorkRep(self)
3076        c, e = op.int, op.exp
3077        if adj == 0:
3078            # 1 < self < 10
3079            num = str(c-10**-e)
3080            den = str(c)
3081            return len(num) - len(den) - (num < den)
3082        # adj == -1, 0.1 <= self < 1
3083        return e + len(str(10**-e - c)) - 1
3084
3085
3086    def ln(self, context=None):
3087        """Returns the natural (base e) logarithm of self."""
3088
3089        if context is None:
3090            context = getcontext()
3091
3092        # ln(NaN) = NaN
3093        ans = self._check_nans(context=context)
3094        if ans:
3095            return ans
3096
3097        # ln(0.0) == -Infinity
3098        if not self:
3099            return _NegativeInfinity
3100
3101        # ln(Infinity) = Infinity
3102        if self._isinfinity() == 1:
3103            return _Infinity
3104
3105        # ln(1.0) == 0.0
3106        if self == _One:
3107            return _Zero
3108
3109        # ln(negative) raises InvalidOperation
3110        if self._sign == 1:
3111            return context._raise_error(InvalidOperation,
3112                                        'ln of a negative value')
3113
3114        # result is irrational, so necessarily inexact
3115        op = _WorkRep(self)
3116        c, e = op.int, op.exp
3117        p = context.prec
3118
3119        # correctly rounded result: repeatedly increase precision by 3
3120        # until we get an unambiguously roundable result
3121        places = p - self._ln_exp_bound() + 2 # at least p+3 places
3122        while True:
3123            coeff = _dlog(c, e, places)
3124            # assert len(str(abs(coeff)))-p >= 1
3125            if coeff % (5*10**(len(str(abs(coeff)))-p-1)):
3126                break
3127            places += 3
3128        ans = _dec_from_triple(int(coeff<0), str(abs(coeff)), -places)
3129
3130        context = context._shallow_copy()
3131        rounding = context._set_rounding(ROUND_HALF_EVEN)
3132        ans = ans._fix(context)
3133        context.rounding = rounding
3134        return ans
3135
3136    def _log10_exp_bound(self):
3137        """Compute a lower bound for the adjusted exponent of self.log10().
3138        In other words, find r such that self.log10() >= 10**r.
3139        Assumes that self is finite and positive and that self != 1.
3140        """
3141
3142        # For x >= 10 or x < 0.1 we only need a bound on the integer
3143        # part of log10(self), and this comes directly from the
3144        # exponent of x.  For 0.1 <= x <= 10 we use the inequalities
3145        # 1-1/x <= log(x) <= x-1. If x > 1 we have |log10(x)| >
3146        # (1-1/x)/2.31 > 0.  If x < 1 then |log10(x)| > (1-x)/2.31 > 0
3147
3148        adj = self._exp + len(self._int) - 1
3149        if adj >= 1:
3150            # self >= 10
3151            return len(str(adj))-1
3152        if adj <= -2:
3153            # self < 0.1
3154            return len(str(-1-adj))-1
3155        op = _WorkRep(self)
3156        c, e = op.int, op.exp
3157        if adj == 0:
3158            # 1 < self < 10
3159            num = str(c-10**-e)
3160            den = str(231*c)
3161            return len(num) - len(den) - (num < den) + 2
3162        # adj == -1, 0.1 <= self < 1
3163        num = str(10**-e-c)
3164        return len(num) + e - (num < "231") - 1
3165
3166    def log10(self, context=None):
3167        """Returns the base 10 logarithm of self."""
3168
3169        if context is None:
3170            context = getcontext()
3171
3172        # log10(NaN) = NaN
3173        ans = self._check_nans(context=context)
3174        if ans:
3175            return ans
3176
3177        # log10(0.0) == -Infinity
3178        if not self:
3179            return _NegativeInfinity
3180
3181        # log10(Infinity) = Infinity
3182        if self._isinfinity() == 1:
3183            return _Infinity
3184
3185        # log10(negative or -Infinity) raises InvalidOperation
3186        if self._sign == 1:
3187            return context._raise_error(InvalidOperation,
3188                                        'log10 of a negative value')
3189
3190        # log10(10**n) = n
3191        if self._int[0] == '1' and self._int[1:] == '0'*(len(self._int) - 1):
3192            # answer may need rounding
3193            ans = Decimal(self._exp + len(self._int) - 1)
3194        else:
3195            # result is irrational, so necessarily inexact
3196            op = _WorkRep(self)
3197            c, e = op.int, op.exp
3198            p = context.prec
3199
3200            # correctly rounded result: repeatedly increase precision
3201            # until result is unambiguously roundable
3202            places = p-self._log10_exp_bound()+2
3203            while True:
3204                coeff = _dlog10(c, e, places)
3205                # assert len(str(abs(coeff)))-p >= 1
3206                if coeff % (5*10**(len(str(abs(coeff)))-p-1)):
3207                    break
3208                places += 3
3209            ans = _dec_from_triple(int(coeff<0), str(abs(coeff)), -places)
3210
3211        context = context._shallow_copy()
3212        rounding = context._set_rounding(ROUND_HALF_EVEN)
3213        ans = ans._fix(context)
3214        context.rounding = rounding
3215        return ans
3216
3217    def logb(self, context=None):
3218        """ Returns the exponent of the magnitude of self's MSD.
3219
3220        The result is the integer which is the exponent of the magnitude
3221        of the most significant digit of self (as though it were truncated
3222        to a single digit while maintaining the value of that digit and
3223        without limiting the resulting exponent).
3224        """
3225        # logb(NaN) = NaN
3226        ans = self._check_nans(context=context)
3227        if ans:
3228            return ans
3229
3230        if context is None:
3231            context = getcontext()
3232
3233        # logb(+/-Inf) = +Inf
3234        if self._isinfinity():
3235            return _Infinity
3236
3237        # logb(0) = -Inf, DivisionByZero
3238        if not self:
3239            return context._raise_error(DivisionByZero, 'logb(0)', 1)
3240
3241        # otherwise, simply return the adjusted exponent of self, as a
3242        # Decimal.  Note that no attempt is made to fit the result
3243        # into the current context.
3244        ans = Decimal(self.adjusted())
3245        return ans._fix(context)
3246
3247    def _islogical(self):
3248        """Return True if self is a logical operand.
3249
3250        For being logical, it must be a finite number with a sign of 0,
3251        an exponent of 0, and a coefficient whose digits must all be
3252        either 0 or 1.
3253        """
3254        if self._sign != 0 or self._exp != 0:
3255            return False
3256        for dig in self._int:
3257            if dig not in '01':
3258                return False
3259        return True
3260
3261    def _fill_logical(self, context, opa, opb):
3262        dif = context.prec - len(opa)
3263        if dif > 0:
3264            opa = '0'*dif + opa
3265        elif dif < 0:
3266            opa = opa[-context.prec:]
3267        dif = context.prec - len(opb)
3268        if dif > 0:
3269            opb = '0'*dif + opb
3270        elif dif < 0:
3271            opb = opb[-context.prec:]
3272        return opa, opb
3273
3274    def logical_and(self, other, context=None):
3275        """Applies an 'and' operation between self and other's digits."""
3276        if context is None:
3277            context = getcontext()
3278
3279        other = _convert_other(other, raiseit=True)
3280
3281        if not self._islogical() or not other._islogical():
3282            return context._raise_error(InvalidOperation)
3283
3284        # fill to context.prec
3285        (opa, opb) = self._fill_logical(context, self._int, other._int)
3286
3287        # make the operation, and clean starting zeroes
3288        result = "".join([str(int(a)&int(b)) for a,b in zip(opa,opb)])
3289        return _dec_from_triple(0, result.lstrip('0') or '0', 0)
3290
3291    def logical_invert(self, context=None):
3292        """Invert all its digits."""
3293        if context is None:
3294            context = getcontext()
3295        return self.logical_xor(_dec_from_triple(0,'1'*context.prec,0),
3296                                context)
3297
3298    def logical_or(self, other, context=None):
3299        """Applies an 'or' operation between self and other's digits."""
3300        if context is None:
3301            context = getcontext()
3302
3303        other = _convert_other(other, raiseit=True)
3304
3305        if not self._islogical() or not other._islogical():
3306            return context._raise_error(InvalidOperation)
3307
3308        # fill to context.prec
3309        (opa, opb) = self._fill_logical(context, self._int, other._int)
3310
3311        # make the operation, and clean starting zeroes
3312        result = "".join([str(int(a)|int(b)) for a,b in zip(opa,opb)])
3313        return _dec_from_triple(0, result.lstrip('0') or '0', 0)
3314
3315    def logical_xor(self, other, context=None):
3316        """Applies an 'xor' operation between self and other's digits."""
3317        if context is None:
3318            context = getcontext()
3319
3320        other = _convert_other(other, raiseit=True)
3321
3322        if not self._islogical() or not other._islogical():
3323            return context._raise_error(InvalidOperation)
3324
3325        # fill to context.prec
3326        (opa, opb) = self._fill_logical(context, self._int, other._int)
3327
3328        # make the operation, and clean starting zeroes
3329        result = "".join([str(int(a)^int(b)) for a,b in zip(opa,opb)])
3330        return _dec_from_triple(0, result.lstrip('0') or '0', 0)
3331
3332    def max_mag(self, other, context=None):
3333        """Compares the values numerically with their sign ignored."""
3334        other = _convert_other(other, raiseit=True)
3335
3336        if context is None:
3337            context = getcontext()
3338
3339        if self._is_special or other._is_special:
3340            # If one operand is a quiet NaN and the other is number, then the
3341            # number is always returned
3342            sn = self._isnan()
3343            on = other._isnan()
3344            if sn or on:
3345                if on == 1 and sn == 0:
3346                    return self._fix(context)
3347                if sn == 1 and on == 0:
3348                    return other._fix(context)
3349                return self._check_nans(other, context)
3350
3351        c = self.copy_abs()._cmp(other.copy_abs())
3352        if c == 0:
3353            c = self.compare_total(other)
3354
3355        if c == -1:
3356            ans = other
3357        else:
3358            ans = self
3359
3360        return ans._fix(context)
3361
3362    def min_mag(self, other, context=None):
3363        """Compares the values numerically with their sign ignored."""
3364        other = _convert_other(other, raiseit=True)
3365
3366        if context is None:
3367            context = getcontext()
3368
3369        if self._is_special or other._is_special:
3370            # If one operand is a quiet NaN and the other is number, then the
3371            # number is always returned
3372            sn = self._isnan()
3373            on = other._isnan()
3374            if sn or on:
3375                if on == 1 and sn == 0:
3376                    return self._fix(context)
3377                if sn == 1 and on == 0:
3378                    return other._fix(context)
3379                return self._check_nans(other, context)
3380
3381        c = self.copy_abs()._cmp(other.copy_abs())
3382        if c == 0:
3383            c = self.compare_total(other)
3384
3385        if c == -1:
3386            ans = self
3387        else:
3388            ans = other
3389
3390        return ans._fix(context)
3391
3392    def next_minus(self, context=None):
3393        """Returns the largest representable number smaller than itself."""
3394        if context is None:
3395            context = getcontext()
3396
3397        ans = self._check_nans(context=context)
3398        if ans:
3399            return ans
3400
3401        if self._isinfinity() == -1:
3402            return _NegativeInfinity
3403        if self._isinfinity() == 1:
3404            return _dec_from_triple(0, '9'*context.prec, context.Etop())
3405
3406        context = context.copy()
3407        context._set_rounding(ROUND_FLOOR)
3408        context._ignore_all_flags()
3409        new_self = self._fix(context)
3410        if new_self != self:
3411            return new_self
3412        return self.__sub__(_dec_from_triple(0, '1', context.Etiny()-1),
3413                            context)
3414
3415    def next_plus(self, context=None):
3416        """Returns the smallest representable number larger than itself."""
3417        if context is None:
3418            context = getcontext()
3419
3420        ans = self._check_nans(context=context)
3421        if ans:
3422            return ans
3423
3424        if self._isinfinity() == 1:
3425            return _Infinity
3426        if self._isinfinity() == -1:
3427            return _dec_from_triple(1, '9'*context.prec, context.Etop())
3428
3429        context = context.copy()
3430        context._set_rounding(ROUND_CEILING)
3431        context._ignore_all_flags()
3432        new_self = self._fix(context)
3433        if new_self != self:
3434            return new_self
3435        return self.__add__(_dec_from_triple(0, '1', context.Etiny()-1),
3436                            context)
3437
3438    def next_toward(self, other, context=None):
3439        """Returns the number closest to self, in the direction towards other.
3440
3441        The result is the closest representable number to self
3442        (excluding self) that is in the direction towards other,
3443        unless both have the same value.  If the two operands are
3444        numerically equal, then the result is a copy of self with the
3445        sign set to be the same as the sign of other.
3446        """
3447        other = _convert_other(other, raiseit=True)
3448
3449        if context is None:
3450            context = getcontext()
3451
3452        ans = self._check_nans(other, context)
3453        if ans:
3454            return ans
3455
3456        comparison = self._cmp(other)
3457        if comparison == 0:
3458            return self.copy_sign(other)
3459
3460        if comparison == -1:
3461            ans = self.next_plus(context)
3462        else: # comparison == 1
3463            ans = self.next_minus(context)
3464
3465        # decide which flags to raise using value of ans
3466        if ans._isinfinity():
3467            context._raise_error(Overflow,
3468                                 'Infinite result from next_toward',
3469                                 ans._sign)
3470            context._raise_error(Inexact)
3471            context._raise_error(Rounded)
3472        elif ans.adjusted() < context.Emin:
3473            context._raise_error(Underflow)
3474            context._raise_error(Subnormal)
3475            context._raise_error(Inexact)
3476            context._raise_error(Rounded)
3477            # if precision == 1 then we don't raise Clamped for a
3478            # result 0E-Etiny.
3479            if not ans:
3480                context._raise_error(Clamped)
3481
3482        return ans
3483
3484    def number_class(self, context=None):
3485        """Returns an indication of the class of self.
3486
3487        The class is one of the following strings:
3488          sNaN
3489          NaN
3490          -Infinity
3491          -Normal
3492          -Subnormal
3493          -Zero
3494          +Zero
3495          +Subnormal
3496          +Normal
3497          +Infinity
3498        """
3499        if self.is_snan():
3500            return "sNaN"
3501        if self.is_qnan():
3502            return "NaN"
3503        inf = self._isinfinity()
3504        if inf == 1:
3505            return "+Infinity"
3506        if inf == -1:
3507            return "-Infinity"
3508        if self.is_zero():
3509            if self._sign:
3510                return "-Zero"
3511            else:
3512                return "+Zero"
3513        if context is None:
3514            context = getcontext()
3515        if self.is_subnormal(context=context):
3516            if self._sign:
3517                return "-Subnormal"
3518            else:
3519                return "+Subnormal"
3520        # just a normal, regular, boring number, :)
3521        if self._sign:
3522            return "-Normal"
3523        else:
3524            return "+Normal"
3525
3526    def radix(self):
3527        """Just returns 10, as this is Decimal, :)"""
3528        return Decimal(10)
3529
3530    def rotate(self, other, context=None):
3531        """Returns a rotated copy of self, value-of-other times."""
3532        if context is None:
3533            context = getcontext()
3534
3535        other = _convert_other(other, raiseit=True)
3536
3537        ans = self._check_nans(other, context)
3538        if ans:
3539            return ans
3540
3541        if other._exp != 0:
3542            return context._raise_error(InvalidOperation)
3543        if not (-context.prec <= int(other) <= context.prec):
3544            return context._raise_error(InvalidOperation)
3545
3546        if self._isinfinity():
3547            return Decimal(self)
3548
3549        # get values, pad if necessary
3550        torot = int(other)
3551        rotdig = self._int
3552        topad = context.prec - len(rotdig)
3553        if topad > 0:
3554            rotdig = '0'*topad + rotdig
3555        elif topad < 0:
3556            rotdig = rotdig[-topad:]
3557
3558        # let's rotate!
3559        rotated = rotdig[torot:] + rotdig[:torot]
3560        return _dec_from_triple(self._sign,
3561                                rotated.lstrip('0') or '0', self._exp)
3562
3563    def scaleb(self, other, context=None):
3564        """Returns self operand after adding the second value to its exp."""
3565        if context is None:
3566            context = getcontext()
3567
3568        other = _convert_other(other, raiseit=True)
3569
3570        ans = self._check_nans(other, context)
3571        if ans:
3572            return ans
3573
3574        if other._exp != 0:
3575            return context._raise_error(InvalidOperation)
3576        liminf = -2 * (context.Emax + context.prec)
3577        limsup =  2 * (context.Emax + context.prec)
3578        if not (liminf <= int(other) <= limsup):
3579            return context._raise_error(InvalidOperation)
3580
3581        if self._isinfinity():
3582            return Decimal(self)
3583
3584        d = _dec_from_triple(self._sign, self._int, self._exp + int(other))
3585        d = d._fix(context)
3586        return d
3587
3588    def shift(self, other, context=None):
3589        """Returns a shifted copy of self, value-of-other times."""
3590        if context is None:
3591            context = getcontext()
3592
3593        other = _convert_other(other, raiseit=True)
3594
3595        ans = self._check_nans(other, context)
3596        if ans:
3597            return ans
3598
3599        if other._exp != 0:
3600            return context._raise_error(InvalidOperation)
3601        if not (-context.prec <= int(other) <= context.prec):
3602            return context._raise_error(InvalidOperation)
3603
3604        if self._isinfinity():
3605            return Decimal(self)
3606
3607        # get values, pad if necessary
3608        torot = int(other)
3609        rotdig = self._int
3610        topad = context.prec - len(rotdig)
3611        if topad > 0:
3612            rotdig = '0'*topad + rotdig
3613        elif topad < 0:
3614            rotdig = rotdig[-topad:]
3615
3616        # let's shift!
3617        if torot < 0:
3618            shifted = rotdig[:torot]
3619        else:
3620            shifted = rotdig + '0'*torot
3621            shifted = shifted[-context.prec:]
3622
3623        return _dec_from_triple(self._sign,
3624                                    shifted.lstrip('0') or '0', self._exp)
3625
3626    # Support for pickling, copy, and deepcopy
3627    def __reduce__(self):
3628        return (self.__class__, (str(self),))
3629
3630    def __copy__(self):
3631        if type(self) is Decimal:
3632            return self     # I'm immutable; therefore I am my own clone
3633        return self.__class__(str(self))
3634
3635    def __deepcopy__(self, memo):
3636        if type(self) is Decimal:
3637            return self     # My components are also immutable
3638        return self.__class__(str(self))
3639
3640    # PEP 3101 support.  the _localeconv keyword argument should be
3641    # considered private: it's provided for ease of testing only.
3642    def __format__(self, specifier, context=None, _localeconv=None):
3643        """Format a Decimal instance according to the given specifier.
3644
3645        The specifier should be a standard format specifier, with the
3646        form described in PEP 3101.  Formatting types 'e', 'E', 'f',
3647        'F', 'g', 'G', 'n' and '%' are supported.  If the formatting
3648        type is omitted it defaults to 'g' or 'G', depending on the
3649        value of context.capitals.
3650        """
3651
3652        # Note: PEP 3101 says that if the type is not present then
3653        # there should be at least one digit after the decimal point.
3654        # We take the liberty of ignoring this requirement for
3655        # Decimal---it's presumably there to make sure that
3656        # format(float, '') behaves similarly to str(float).
3657        if context is None:
3658            context = getcontext()
3659
3660        spec = _parse_format_specifier(specifier, _localeconv=_localeconv)
3661
3662        # special values don't care about the type or precision
3663        if self._is_special:
3664            sign = _format_sign(self._sign, spec)
3665            body = str(self.copy_abs())
3666            if spec['type'] == '%':
3667                body += '%'
3668            return _format_align(sign, body, spec)
3669
3670        # a type of None defaults to 'g' or 'G', depending on context
3671        if spec['type'] is None:
3672            spec['type'] = ['g', 'G'][context.capitals]
3673
3674        # if type is '%', adjust exponent of self accordingly
3675        if spec['type'] == '%':
3676            self = _dec_from_triple(self._sign, self._int, self._exp+2)
3677
3678        # round if necessary, taking rounding mode from the context
3679        rounding = context.rounding
3680        precision = spec['precision']
3681        if precision is not None:
3682            if spec['type'] in 'eE':
3683                self = self._round(precision+1, rounding)
3684            elif spec['type'] in 'fF%':
3685                self = self._rescale(-precision, rounding)
3686            elif spec['type'] in 'gG' and len(self._int) > precision:
3687                self = self._round(precision, rounding)
3688        # special case: zeros with a positive exponent can't be
3689        # represented in fixed point; rescale them to 0e0.
3690        if not self and self._exp > 0 and spec['type'] in 'fF%':
3691            self = self._rescale(0, rounding)
3692
3693        # figure out placement of the decimal point
3694        leftdigits = self._exp + len(self._int)
3695        if spec['type'] in 'eE':
3696            if not self and precision is not None:
3697                dotplace = 1 - precision
3698            else:
3699                dotplace = 1
3700        elif spec['type'] in 'fF%':
3701            dotplace = leftdigits
3702        elif spec['type'] in 'gG':
3703            if self._exp <= 0 and leftdigits > -6:
3704                dotplace = leftdigits
3705            else:
3706                dotplace = 1
3707
3708        # find digits before and after decimal point, and get exponent
3709        if dotplace < 0:
3710            intpart = '0'
3711            fracpart = '0'*(-dotplace) + self._int
3712        elif dotplace > len(self._int):
3713            intpart = self._int + '0'*(dotplace-len(self._int))
3714            fracpart = ''
3715        else:
3716            intpart = self._int[:dotplace] or '0'
3717            fracpart = self._int[dotplace:]
3718        exp = leftdigits-dotplace
3719
3720        # done with the decimal-specific stuff;  hand over the rest
3721        # of the formatting to the _format_number function
3722        return _format_number(self._sign, intpart, fracpart, exp, spec)
3723
3724def _dec_from_triple(sign, coefficient, exponent, special=False):
3725    """Create a decimal instance directly, without any validation,
3726    normalization (e.g. removal of leading zeros) or argument
3727    conversion.
3728
3729    This function is for *internal use only*.
3730    """
3731
3732    self = object.__new__(Decimal)
3733    self._sign = sign
3734    self._int = coefficient
3735    self._exp = exponent
3736    self._is_special = special
3737
3738    return self
3739
3740# Register Decimal as a kind of Number (an abstract base class).
3741# However, do not register it as Real (because Decimals are not
3742# interoperable with floats).
3743_numbers.Number.register(Decimal)
3744
3745
3746##### Context class #######################################################
3747
3748class _ContextManager(object):
3749    """Context manager class to support localcontext().
3750
3751      Sets a copy of the supplied context in __enter__() and restores
3752      the previous decimal context in __exit__()
3753    """
3754    def __init__(self, new_context):
3755        self.new_context = new_context.copy()
3756    def __enter__(self):
3757        self.saved_context = getcontext()
3758        setcontext(self.new_context)
3759        return self.new_context
3760    def __exit__(self, t, v, tb):
3761        setcontext(self.saved_context)
3762
3763class Context(object):
3764    """Contains the context for a Decimal instance.
3765
3766    Contains:
3767    prec - precision (for use in rounding, division, square roots..)
3768    rounding - rounding type (how you round)
3769    traps - If traps[exception] = 1, then the exception is
3770                    raised when it is caused.  Otherwise, a value is
3771                    substituted in.
3772    flags  - When an exception is caused, flags[exception] is set.
3773             (Whether or not the trap_enabler is set)
3774             Should be reset by user of Decimal instance.
3775    Emin -   Minimum exponent
3776    Emax -   Maximum exponent
3777    capitals -      If 1, 1*10^1 is printed as 1E+1.
3778                    If 0, printed as 1e1
3779    _clamp - If 1, change exponents if too high (Default 0)
3780    """
3781
3782    def __init__(self, prec=None, rounding=None,
3783                 traps=None, flags=None,
3784                 Emin=None, Emax=None,
3785                 capitals=None, _clamp=0,
3786                 _ignored_flags=None):
3787        # Set defaults; for everything except flags and _ignored_flags,
3788        # inherit from DefaultContext.
3789        try:
3790            dc = DefaultContext
3791        except NameError:
3792            pass
3793
3794        self.prec = prec if prec is not None else dc.prec
3795        self.rounding = rounding if rounding is not None else dc.rounding
3796        self.Emin = Emin if Emin is not None else dc.Emin
3797        self.Emax = Emax if Emax is not None else dc.Emax
3798        self.capitals = capitals if capitals is not None else dc.capitals
3799        self._clamp = _clamp if _clamp is not None else dc._clamp
3800
3801        if _ignored_flags is None:
3802            self._ignored_flags = []
3803        else:
3804            self._ignored_flags = _ignored_flags
3805
3806        if traps is None:
3807            self.traps = dc.traps.copy()
3808        elif not isinstance(traps, dict):
3809            self.traps = dict((s, int(s in traps)) for s in _signals)
3810        else:
3811            self.traps = traps
3812
3813        if flags is None:
3814            self.flags = dict.fromkeys(_signals, 0)
3815        elif not isinstance(flags, dict):
3816            self.flags = dict((s, int(s in flags)) for s in _signals)
3817        else:
3818            self.flags = flags
3819
3820    def __repr__(self):
3821        """Show the current context."""
3822        s = []
3823        s.append('Context(prec=%(prec)d, rounding=%(rounding)s, '
3824                 'Emin=%(Emin)d, Emax=%(Emax)d, capitals=%(capitals)d'
3825                 % vars(self))
3826        names = [f.__name__ for f, v in self.flags.items() if v]
3827        s.append('flags=[' + ', '.join(names) + ']')
3828        names = [t.__name__ for t, v in self.traps.items() if v]
3829        s.append('traps=[' + ', '.join(names) + ']')
3830        return ', '.join(s) + ')'
3831
3832    def clear_flags(self):
3833        """Reset all flags to zero"""
3834        for flag in self.flags:
3835            self.flags[flag] = 0
3836
3837    def _shallow_copy(self):
3838        """Returns a shallow copy from self."""
3839        nc = Context(self.prec, self.rounding, self.traps,
3840                     self.flags, self.Emin, self.Emax,
3841                     self.capitals, self._clamp, self._ignored_flags)
3842        return nc
3843
3844    def copy(self):
3845        """Returns a deep copy from self."""
3846        nc = Context(self.prec, self.rounding, self.traps.copy(),
3847                     self.flags.copy(), self.Emin, self.Emax,
3848                     self.capitals, self._clamp, self._ignored_flags)
3849        return nc
3850    __copy__ = copy
3851
3852    def _raise_error(self, condition, explanation = None, *args):
3853        """Handles an error
3854
3855        If the flag is in _ignored_flags, returns the default response.
3856        Otherwise, it sets the flag, then, if the corresponding
3857        trap_enabler is set, it reraises the exception.  Otherwise, it returns
3858        the default value after setting the flag.
3859        """
3860        error = _condition_map.get(condition, condition)
3861        if error in self._ignored_flags:
3862            # Don't touch the flag
3863            return error().handle(self, *args)
3864
3865        self.flags[error] = 1
3866        if not self.traps[error]:
3867            # The errors define how to handle themselves.
3868            return condition().handle(self, *args)
3869
3870        # Errors should only be risked on copies of the context
3871        # self._ignored_flags = []
3872        raise error(explanation)
3873
3874    def _ignore_all_flags(self):
3875        """Ignore all flags, if they are raised"""
3876        return self._ignore_flags(*_signals)
3877
3878    def _ignore_flags(self, *flags):
3879        """Ignore the flags, if they are raised"""
3880        # Do not mutate-- This way, copies of a context leave the original
3881        # alone.
3882        self._ignored_flags = (self._ignored_flags + list(flags))
3883        return list(flags)
3884
3885    def _regard_flags(self, *flags):
3886        """Stop ignoring the flags, if they are raised"""
3887        if flags and isinstance(flags[0], (tuple,list)):
3888            flags = flags[0]
3889        for flag in flags:
3890            self._ignored_flags.remove(flag)
3891
3892    # We inherit object.__hash__, so we must deny this explicitly
3893    __hash__ = None
3894
3895    def Etiny(self):
3896        """Returns Etiny (= Emin - prec + 1)"""
3897        return int(self.Emin - self.prec + 1)
3898
3899    def Etop(self):
3900        """Returns maximum exponent (= Emax - prec + 1)"""
3901        return int(self.Emax - self.prec + 1)
3902
3903    def _set_rounding(self, type):
3904        """Sets the rounding type.
3905
3906        Sets the rounding type, and returns the current (previous)
3907        rounding type.  Often used like:
3908
3909        context = context.copy()
3910        # so you don't change the calling context
3911        # if an error occurs in the middle.
3912        rounding = context._set_rounding(ROUND_UP)
3913        val = self.__sub__(other, context=context)
3914        context._set_rounding(rounding)
3915
3916        This will make it round up for that operation.
3917        """
3918        rounding = self.rounding
3919        self.rounding= type
3920        return rounding
3921
3922    def create_decimal(self, num='0'):
3923        """Creates a new Decimal instance but using self as context.
3924
3925        This method implements the to-number operation of the
3926        IBM Decimal specification."""
3927
3928        if isinstance(num, basestring) and num != num.strip():
3929            return self._raise_error(ConversionSyntax,
3930                                     "no trailing or leading whitespace is "
3931                                     "permitted.")
3932
3933        d = Decimal(num, context=self)
3934        if d._isnan() and len(d._int) > self.prec - self._clamp:
3935            return self._raise_error(ConversionSyntax,
3936                                     "diagnostic info too long in NaN")
3937        return d._fix(self)
3938
3939    def create_decimal_from_float(self, f):
3940        """Creates a new Decimal instance from a float but rounding using self
3941        as the context.
3942
3943        >>> context = Context(prec=5, rounding=ROUND_DOWN)
3944        >>> context.create_decimal_from_float(3.1415926535897932)
3945        Decimal('3.1415')
3946        >>> context = Context(prec=5, traps=[Inexact])
3947        >>> context.create_decimal_from_float(3.1415926535897932)
3948        Traceback (most recent call last):
3949            ...
3950        Inexact: None
3951
3952        """
3953        d = Decimal.from_float(f)       # An exact conversion
3954        return d._fix(self)             # Apply the context rounding
3955
3956    # Methods
3957    def abs(self, a):
3958        """Returns the absolute value of the operand.
3959
3960        If the operand is negative, the result is the same as using the minus
3961        operation on the operand.  Otherwise, the result is the same as using
3962        the plus operation on the operand.
3963
3964        >>> ExtendedContext.abs(Decimal('2.1'))
3965        Decimal('2.1')
3966        >>> ExtendedContext.abs(Decimal('-100'))
3967        Decimal('100')
3968        >>> ExtendedContext.abs(Decimal('101.5'))
3969        Decimal('101.5')
3970        >>> ExtendedContext.abs(Decimal('-101.5'))
3971        Decimal('101.5')
3972        >>> ExtendedContext.abs(-1)
3973        Decimal('1')
3974        """
3975        a = _convert_other(a, raiseit=True)
3976        return a.__abs__(context=self)
3977
3978    def add(self, a, b):
3979        """Return the sum of the two operands.
3980
3981        >>> ExtendedContext.add(Decimal('12'), Decimal('7.00'))
3982        Decimal('19.00')
3983        >>> ExtendedContext.add(Decimal('1E+2'), Decimal('1.01E+4'))
3984        Decimal('1.02E+4')
3985        >>> ExtendedContext.add(1, Decimal(2))
3986        Decimal('3')
3987        >>> ExtendedContext.add(Decimal(8), 5)
3988        Decimal('13')
3989        >>> ExtendedContext.add(5, 5)
3990        Decimal('10')
3991        """
3992        a = _convert_other(a, raiseit=True)
3993        r = a.__add__(b, context=self)
3994        if r is NotImplemented:
3995            raise TypeError("Unable to convert %s to Decimal" % b)
3996        else:
3997            return r
3998
3999    def _apply(self, a):
4000        return str(a._fix(self))
4001
4002    def canonical(self, a):
4003        """Returns the same Decimal object.
4004
4005        As we do not have different encodings for the same number, the
4006        received object already is in its canonical form.
4007
4008        >>> ExtendedContext.canonical(Decimal('2.50'))
4009        Decimal('2.50')
4010        """
4011        return a.canonical(context=self)
4012
4013    def compare(self, a, b):
4014        """Compares values numerically.
4015
4016        If the signs of the operands differ, a value representing each operand
4017        ('-1' if the operand is less than zero, '0' if the operand is zero or
4018        negative zero, or '1' if the operand is greater than zero) is used in
4019        place of that operand for the comparison instead of the actual
4020        operand.
4021
4022        The comparison is then effected by subtracting the second operand from
4023        the first and then returning a value according to the result of the
4024        subtraction: '-1' if the result is less than zero, '0' if the result is
4025        zero or negative zero, or '1' if the result is greater than zero.
4026
4027        >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))
4028        Decimal('-1')
4029        >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))
4030        Decimal('0')
4031        >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))
4032        Decimal('0')
4033        >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))
4034        Decimal('1')
4035        >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))
4036        Decimal('1')
4037        >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))
4038        Decimal('-1')
4039        >>> ExtendedContext.compare(1, 2)
4040        Decimal('-1')
4041        >>> ExtendedContext.compare(Decimal(1), 2)
4042        Decimal('-1')
4043        >>> ExtendedContext.compare(1, Decimal(2))
4044        Decimal('-1')
4045        """
4046        a = _convert_other(a, raiseit=True)
4047        return a.compare(b, context=self)
4048
4049    def compare_signal(self, a, b):
4050        """Compares the values of the two operands numerically.
4051
4052        It's pretty much like compare(), but all NaNs signal, with signaling
4053        NaNs taking precedence over quiet NaNs.
4054
4055        >>> c = ExtendedContext
4056        >>> c.compare_signal(Decimal('2.1'), Decimal('3'))
4057        Decimal('-1')
4058        >>> c.compare_signal(Decimal('2.1'), Decimal('2.1'))
4059        Decimal('0')
4060        >>> c.flags[InvalidOperation] = 0
4061        >>> print c.flags[InvalidOperation]
4062        0
4063        >>> c.compare_signal(Decimal('NaN'), Decimal('2.1'))
4064        Decimal('NaN')
4065        >>> print c.flags[InvalidOperation]
4066        1
4067        >>> c.flags[InvalidOperation] = 0
4068        >>> print c.flags[InvalidOperation]
4069        0
4070        >>> c.compare_signal(Decimal('sNaN'), Decimal('2.1'))
4071        Decimal('NaN')
4072        >>> print c.flags[InvalidOperation]
4073        1
4074        >>> c.compare_signal(-1, 2)
4075        Decimal('-1')
4076        >>> c.compare_signal(Decimal(-1), 2)
4077        Decimal('-1')
4078        >>> c.compare_signal(-1, Decimal(2))
4079        Decimal('-1')
4080        """
4081        a = _convert_other(a, raiseit=True)
4082        return a.compare_signal(b, context=self)
4083
4084    def compare_total(self, a, b):
4085        """Compares two operands using their abstract representation.
4086
4087        This is not like the standard compare, which use their numerical
4088        value. Note that a total ordering is defined for all possible abstract
4089        representations.
4090
4091        >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))
4092        Decimal('-1')
4093        >>> ExtendedContext.compare_total(Decimal('-127'),  Decimal('12'))
4094        Decimal('-1')
4095        >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))
4096        Decimal('-1')
4097        >>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))
4098        Decimal('0')
4099        >>> ExtendedContext.compare_total(Decimal('12.3'),  Decimal('12.300'))
4100        Decimal('1')
4101        >>> ExtendedContext.compare_total(Decimal('12.3'),  Decimal('NaN'))
4102        Decimal('-1')
4103        >>> ExtendedContext.compare_total(1, 2)
4104        Decimal('-1')
4105        >>> ExtendedContext.compare_total(Decimal(1), 2)
4106        Decimal('-1')
4107        >>> ExtendedContext.compare_total(1, Decimal(2))
4108        Decimal('-1')
4109        """
4110        a = _convert_other(a, raiseit=True)
4111        return a.compare_total(b)
4112
4113    def compare_total_mag(self, a, b):
4114        """Compares two operands using their abstract representation ignoring sign.
4115
4116        Like compare_total, but with operand's sign ignored and assumed to be 0.
4117        """
4118        a = _convert_other(a, raiseit=True)
4119        return a.compare_total_mag(b)
4120
4121    def copy_abs(self, a):
4122        """Returns a copy of the operand with the sign set to 0.
4123
4124        >>> ExtendedContext.copy_abs(Decimal('2.1'))
4125        Decimal('2.1')
4126        >>> ExtendedContext.copy_abs(Decimal('-100'))
4127        Decimal('100')
4128        >>> ExtendedContext.copy_abs(-1)
4129        Decimal('1')
4130        """
4131        a = _convert_other(a, raiseit=True)
4132        return a.copy_abs()
4133
4134    def copy_decimal(self, a):
4135        """Returns a copy of the decimal object.
4136
4137        >>> ExtendedContext.copy_decimal(Decimal('2.1'))
4138        Decimal('2.1')
4139        >>> ExtendedContext.copy_decimal(Decimal('-1.00'))
4140        Decimal('-1.00')
4141        >>> ExtendedContext.copy_decimal(1)
4142        Decimal('1')
4143        """
4144        a = _convert_other(a, raiseit=True)
4145        return Decimal(a)
4146
4147    def copy_negate(self, a):
4148        """Returns a copy of the operand with the sign inverted.
4149
4150        >>> ExtendedContext.copy_negate(Decimal('101.5'))
4151        Decimal('-101.5')
4152        >>> ExtendedContext.copy_negate(Decimal('-101.5'))
4153        Decimal('101.5')
4154        >>> ExtendedContext.copy_negate(1)
4155        Decimal('-1')
4156        """
4157        a = _convert_other(a, raiseit=True)
4158        return a.copy_negate()
4159
4160    def copy_sign(self, a, b):
4161        """Copies the second operand's sign to the first one.
4162
4163        In detail, it returns a copy of the first operand with the sign
4164        equal to the sign of the second operand.
4165
4166        >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))
4167        Decimal('1.50')
4168        >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))
4169        Decimal('1.50')
4170        >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))
4171        Decimal('-1.50')
4172        >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))
4173        Decimal('-1.50')
4174        >>> ExtendedContext.copy_sign(1, -2)
4175        Decimal('-1')
4176        >>> ExtendedContext.copy_sign(Decimal(1), -2)
4177        Decimal('-1')
4178        >>> ExtendedContext.copy_sign(1, Decimal(-2))
4179        Decimal('-1')
4180        """
4181        a = _convert_other(a, raiseit=True)
4182        return a.copy_sign(b)
4183
4184    def divide(self, a, b):
4185        """Decimal division in a specified context.
4186
4187        >>> ExtendedContext.divide(Decimal('1'), Decimal('3'))
4188        Decimal('0.333333333')
4189        >>> ExtendedContext.divide(Decimal('2'), Decimal('3'))
4190        Decimal('0.666666667')
4191        >>> ExtendedContext.divide(Decimal('5'), Decimal('2'))
4192        Decimal('2.5')
4193        >>> ExtendedContext.divide(Decimal('1'), Decimal('10'))
4194        Decimal('0.1')
4195        >>> ExtendedContext.divide(Decimal('12'), Decimal('12'))
4196        Decimal('1')
4197        >>> ExtendedContext.divide(Decimal('8.00'), Decimal('2'))
4198        Decimal('4.00')
4199        >>> ExtendedContext.divide(Decimal('2.400'), Decimal('2.0'))
4200        Decimal('1.20')
4201        >>> ExtendedContext.divide(Decimal('1000'), Decimal('100'))
4202        Decimal('10')
4203        >>> ExtendedContext.divide(Decimal('1000'), Decimal('1'))
4204        Decimal('1000')
4205        >>> ExtendedContext.divide(Decimal('2.40E+6'), Decimal('2'))
4206        Decimal('1.20E+6')
4207        >>> ExtendedContext.divide(5, 5)
4208        Decimal('1')
4209        >>> ExtendedContext.divide(Decimal(5), 5)
4210        Decimal('1')
4211        >>> ExtendedContext.divide(5, Decimal(5))
4212        Decimal('1')
4213        """
4214        a = _convert_other(a, raiseit=True)
4215        r = a.__div__(b, context=self)
4216        if r is NotImplemented:
4217            raise TypeError("Unable to convert %s to Decimal" % b)
4218        else:
4219            return r
4220
4221    def divide_int(self, a, b):
4222        """Divides two numbers and returns the integer part of the result.
4223
4224        >>> ExtendedContext.divide_int(Decimal('2'), Decimal('3'))
4225        Decimal('0')
4226        >>> ExtendedContext.divide_int(Decimal('10'), Decimal('3'))
4227        Decimal('3')
4228        >>> ExtendedContext.divide_int(Decimal('1'), Decimal('0.3'))
4229        Decimal('3')
4230        >>> ExtendedContext.divide_int(10, 3)
4231        Decimal('3')
4232        >>> ExtendedContext.divide_int(Decimal(10), 3)
4233        Decimal('3')
4234        >>> ExtendedContext.divide_int(10, Decimal(3))
4235        Decimal('3')
4236        """
4237        a = _convert_other(a, raiseit=True)
4238        r = a.__floordiv__(b, context=self)
4239        if r is NotImplemented:
4240            raise TypeError("Unable to convert %s to Decimal" % b)
4241        else:
4242            return r
4243
4244    def divmod(self, a, b):
4245        """Return (a // b, a % b).
4246
4247        >>> ExtendedContext.divmod(Decimal(8), Decimal(3))
4248        (Decimal('2'), Decimal('2'))
4249        >>> ExtendedContext.divmod(Decimal(8), Decimal(4))
4250        (Decimal('2'), Decimal('0'))
4251        >>> ExtendedContext.divmod(8, 4)
4252        (Decimal('2'), Decimal('0'))
4253        >>> ExtendedContext.divmod(Decimal(8), 4)
4254        (Decimal('2'), Decimal('0'))
4255        >>> ExtendedContext.divmod(8, Decimal(4))
4256        (Decimal('2'), Decimal('0'))
4257        """
4258        a = _convert_other(a, raiseit=True)
4259        r = a.__divmod__(b, context=self)
4260        if r is NotImplemented:
4261            raise TypeError("Unable to convert %s to Decimal" % b)
4262        else:
4263            return r
4264
4265    def exp(self, a):
4266        """Returns e ** a.
4267
4268        >>> c = ExtendedContext.copy()
4269        >>> c.Emin = -999
4270        >>> c.Emax = 999
4271        >>> c.exp(Decimal('-Infinity'))
4272        Decimal('0')
4273        >>> c.exp(Decimal('-1'))
4274        Decimal('0.367879441')
4275        >>> c.exp(Decimal('0'))
4276        Decimal('1')
4277        >>> c.exp(Decimal('1'))
4278        Decimal('2.71828183')
4279        >>> c.exp(Decimal('0.693147181'))
4280        Decimal('2.00000000')
4281        >>> c.exp(Decimal('+Infinity'))
4282        Decimal('Infinity')
4283        >>> c.exp(10)
4284        Decimal('22026.4658')
4285        """
4286        a =_convert_other(a, raiseit=True)
4287        return a.exp(context=self)
4288
4289    def fma(self, a, b, c):
4290        """Returns a multiplied by b, plus c.
4291
4292        The first two operands are multiplied together, using multiply,
4293        the third operand is then added to the result of that
4294        multiplication, using add, all with only one final rounding.
4295
4296        >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))
4297        Decimal('22')
4298        >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))
4299        Decimal('-8')
4300        >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578'))
4301        Decimal('1.38435736E+12')
4302        >>> ExtendedContext.fma(1, 3, 4)
4303        Decimal('7')
4304        >>> ExtendedContext.fma(1, Decimal(3), 4)
4305        Decimal('7')
4306        >>> ExtendedContext.fma(1, 3, Decimal(4))
4307        Decimal('7')
4308        """
4309        a = _convert_other(a, raiseit=True)
4310        return a.fma(b, c, context=self)
4311
4312    def is_canonical(self, a):
4313        """Return True if the operand is canonical; otherwise return False.
4314
4315        Currently, the encoding of a Decimal instance is always
4316        canonical, so this method returns True for any Decimal.
4317
4318        >>> ExtendedContext.is_canonical(Decimal('2.50'))
4319        True
4320        """
4321        return a.is_canonical()
4322
4323    def is_finite(self, a):
4324        """Return True if the operand is finite; otherwise return False.
4325
4326        A Decimal instance is considered finite if it is neither
4327        infinite nor a NaN.
4328
4329        >>> ExtendedContext.is_finite(Decimal('2.50'))
4330        True
4331        >>> ExtendedContext.is_finite(Decimal('-0.3'))
4332        True
4333        >>> ExtendedContext.is_finite(Decimal('0'))
4334        True
4335        >>> ExtendedContext.is_finite(Decimal('Inf'))
4336        False
4337        >>> ExtendedContext.is_finite(Decimal('NaN'))
4338        False
4339        >>> ExtendedContext.is_finite(1)
4340        True
4341        """
4342        a = _convert_other(a, raiseit=True)
4343        return a.is_finite()
4344
4345    def is_infinite(self, a):
4346        """Return True if the operand is infinite; otherwise return False.
4347
4348        >>> ExtendedContext.is_infinite(Decimal('2.50'))
4349        False
4350        >>> ExtendedContext.is_infinite(Decimal('-Inf'))
4351        True
4352        >>> ExtendedContext.is_infinite(Decimal('NaN'))
4353        False
4354        >>> ExtendedContext.is_infinite(1)
4355        False
4356        """
4357        a = _convert_other(a, raiseit=True)
4358        return a.is_infinite()
4359
4360    def is_nan(self, a):
4361        """Return True if the operand is a qNaN or sNaN;
4362        otherwise return False.
4363
4364        >>> ExtendedContext.is_nan(Decimal('2.50'))
4365        False
4366        >>> ExtendedContext.is_nan(Decimal('NaN'))
4367        True
4368        >>> ExtendedContext.is_nan(Decimal('-sNaN'))
4369        True
4370        >>> ExtendedContext.is_nan(1)
4371        False
4372        """
4373        a = _convert_other(a, raiseit=True)
4374        return a.is_nan()
4375
4376    def is_normal(self, a):
4377        """Return True if the operand is a normal number;
4378        otherwise return False.
4379
4380        >>> c = ExtendedContext.copy()
4381        >>> c.Emin = -999
4382        >>> c.Emax = 999
4383        >>> c.is_normal(Decimal('2.50'))
4384        True
4385        >>> c.is_normal(Decimal('0.1E-999'))
4386        False
4387        >>> c.is_normal(Decimal('0.00'))
4388        False
4389        >>> c.is_normal(Decimal('-Inf'))
4390        False
4391        >>> c.is_normal(Decimal('NaN'))
4392        False
4393        >>> c.is_normal(1)
4394        True
4395        """
4396        a = _convert_other(a, raiseit=True)
4397        return a.is_normal(context=self)
4398
4399    def is_qnan(self, a):
4400        """Return True if the operand is a quiet NaN; otherwise return False.
4401
4402        >>> ExtendedContext.is_qnan(Decimal('2.50'))
4403        False
4404        >>> ExtendedContext.is_qnan(Decimal('NaN'))
4405        True
4406        >>> ExtendedContext.is_qnan(Decimal('sNaN'))
4407        False
4408        >>> ExtendedContext.is_qnan(1)
4409        False
4410        """
4411        a = _convert_other(a, raiseit=True)
4412        return a.is_qnan()
4413
4414    def is_signed(self, a):
4415        """Return True if the operand is negative; otherwise return False.
4416
4417        >>> ExtendedContext.is_signed(Decimal('2.50'))
4418        False
4419        >>> ExtendedContext.is_signed(Decimal('-12'))
4420        True
4421        >>> ExtendedContext.is_signed(Decimal('-0'))
4422        True
4423        >>> ExtendedContext.is_signed(8)
4424        False
4425        >>> ExtendedContext.is_signed(-8)
4426        True
4427        """
4428        a = _convert_other(a, raiseit=True)
4429        return a.is_signed()
4430
4431    def is_snan(self, a):
4432        """Return True if the operand is a signaling NaN;
4433        otherwise return False.
4434
4435        >>> ExtendedContext.is_snan(Decimal('2.50'))
4436        False
4437        >>> ExtendedContext.is_snan(Decimal('NaN'))
4438        False
4439        >>> ExtendedContext.is_snan(Decimal('sNaN'))
4440        True
4441        >>> ExtendedContext.is_snan(1)
4442        False
4443        """
4444        a = _convert_other(a, raiseit=True)
4445        return a.is_snan()
4446
4447    def is_subnormal(self, a):
4448        """Return True if the operand is subnormal; otherwise return False.
4449
4450        >>> c = ExtendedContext.copy()
4451        >>> c.Emin = -999
4452        >>> c.Emax = 999
4453        >>> c.is_subnormal(Decimal('2.50'))
4454        False
4455        >>> c.is_subnormal(Decimal('0.1E-999'))
4456        True
4457        >>> c.is_subnormal(Decimal('0.00'))
4458        False
4459        >>> c.is_subnormal(Decimal('-Inf'))
4460        False
4461        >>> c.is_subnormal(Decimal('NaN'))
4462        False
4463        >>> c.is_subnormal(1)
4464        False
4465        """
4466        a = _convert_other(a, raiseit=True)
4467        return a.is_subnormal(context=self)
4468
4469    def is_zero(self, a):
4470        """Return True if the operand is a zero; otherwise return False.
4471
4472        >>> ExtendedContext.is_zero(Decimal('0'))
4473        True
4474        >>> ExtendedContext.is_zero(Decimal('2.50'))
4475        False
4476        >>> ExtendedContext.is_zero(Decimal('-0E+2'))
4477        True
4478        >>> ExtendedContext.is_zero(1)
4479        False
4480        >>> ExtendedContext.is_zero(0)
4481        True
4482        """
4483        a = _convert_other(a, raiseit=True)
4484        return a.is_zero()
4485
4486    def ln(self, a):
4487        """Returns the natural (base e) logarithm of the operand.
4488
4489        >>> c = ExtendedContext.copy()
4490        >>> c.Emin = -999
4491        >>> c.Emax = 999
4492        >>> c.ln(Decimal('0'))
4493        Decimal('-Infinity')
4494        >>> c.ln(Decimal('1.000'))
4495        Decimal('0')
4496        >>> c.ln(Decimal('2.71828183'))
4497        Decimal('1.00000000')
4498        >>> c.ln(Decimal('10'))
4499        Decimal('2.30258509')
4500        >>> c.ln(Decimal('+Infinity'))
4501        Decimal('Infinity')
4502        >>> c.ln(1)
4503        Decimal('0')
4504        """
4505        a = _convert_other(a, raiseit=True)
4506        return a.ln(context=self)
4507
4508    def log10(self, a):
4509        """Returns the base 10 logarithm of the operand.
4510
4511        >>> c = ExtendedContext.copy()
4512        >>> c.Emin = -999
4513        >>> c.Emax = 999
4514        >>> c.log10(Decimal('0'))
4515        Decimal('-Infinity')
4516        >>> c.log10(Decimal('0.001'))
4517        Decimal('-3')
4518        >>> c.log10(Decimal('1.000'))
4519        Decimal('0')
4520        >>> c.log10(Decimal('2'))
4521        Decimal('0.301029996')
4522        >>> c.log10(Decimal('10'))
4523        Decimal('1')
4524        >>> c.log10(Decimal('70'))
4525        Decimal('1.84509804')
4526        >>> c.log10(Decimal('+Infinity'))
4527        Decimal('Infinity')
4528        >>> c.log10(0)
4529        Decimal('-Infinity')
4530        >>> c.log10(1)
4531        Decimal('0')
4532        """
4533        a = _convert_other(a, raiseit=True)
4534        return a.log10(context=self)
4535
4536    def logb(self, a):
4537        """ Returns the exponent of the magnitude of the operand's MSD.
4538
4539        The result is the integer which is the exponent of the magnitude
4540        of the most significant digit of the operand (as though the
4541        operand were truncated to a single digit while maintaining the
4542        value of that digit and without limiting the resulting exponent).
4543
4544        >>> ExtendedContext.logb(Decimal('250'))
4545        Decimal('2')
4546        >>> ExtendedContext.logb(Decimal('2.50'))
4547        Decimal('0')
4548        >>> ExtendedContext.logb(Decimal('0.03'))
4549        Decimal('-2')
4550        >>> ExtendedContext.logb(Decimal('0'))
4551        Decimal('-Infinity')
4552        >>> ExtendedContext.logb(1)
4553        Decimal('0')
4554        >>> ExtendedContext.logb(10)
4555        Decimal('1')
4556        >>> ExtendedContext.logb(100)
4557        Decimal('2')
4558        """
4559        a = _convert_other(a, raiseit=True)
4560        return a.logb(context=self)
4561
4562    def logical_and(self, a, b):
4563        """Applies the logical operation 'and' between each operand's digits.
4564
4565        The operands must be both logical numbers.
4566
4567        >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))
4568        Decimal('0')
4569        >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))
4570        Decimal('0')
4571        >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))
4572        Decimal('0')
4573        >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))
4574        Decimal('1')
4575        >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))
4576        Decimal('1000')
4577        >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))
4578        Decimal('10')
4579        >>> ExtendedContext.logical_and(110, 1101)
4580        Decimal('100')
4581        >>> ExtendedContext.logical_and(Decimal(110), 1101)
4582        Decimal('100')
4583        >>> ExtendedContext.logical_and(110, Decimal(1101))
4584        Decimal('100')
4585        """
4586        a = _convert_other(a, raiseit=True)
4587        return a.logical_and(b, context=self)
4588
4589    def logical_invert(self, a):
4590        """Invert all the digits in the operand.
4591
4592        The operand must be a logical number.
4593
4594        >>> ExtendedContext.logical_invert(Decimal('0'))
4595        Decimal('111111111')
4596        >>> ExtendedContext.logical_invert(Decimal('1'))
4597        Decimal('111111110')
4598        >>> ExtendedContext.logical_invert(Decimal('111111111'))
4599        Decimal('0')
4600        >>> ExtendedContext.logical_invert(Decimal('101010101'))
4601        Decimal('10101010')
4602        >>> ExtendedContext.logical_invert(1101)
4603        Decimal('111110010')
4604        """
4605        a = _convert_other(a, raiseit=True)
4606        return a.logical_invert(context=self)
4607
4608    def logical_or(self, a, b):
4609        """Applies the logical operation 'or' between each operand's digits.
4610
4611        The operands must be both logical numbers.
4612
4613        >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))
4614        Decimal('0')
4615        >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))
4616        Decimal('1')
4617        >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))
4618        Decimal('1')
4619        >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))
4620        Decimal('1')
4621        >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))
4622        Decimal('1110')
4623        >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))
4624        Decimal('1110')
4625        >>> ExtendedContext.logical_or(110, 1101)
4626        Decimal('1111')
4627        >>> ExtendedContext.logical_or(Decimal(110), 1101)
4628        Decimal('1111')
4629        >>> ExtendedContext.logical_or(110, Decimal(1101))
4630        Decimal('1111')
4631        """
4632        a = _convert_other(a, raiseit=True)
4633        return a.logical_or(b, context=self)
4634
4635    def logical_xor(self, a, b):
4636        """Applies the logical operation 'xor' between each operand's digits.
4637
4638        The operands must be both logical numbers.
4639
4640        >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))
4641        Decimal('0')
4642        >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))
4643        Decimal('1')
4644        >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))
4645        Decimal('1')
4646        >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))
4647        Decimal('0')
4648        >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))
4649        Decimal('110')
4650        >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))
4651        Decimal('1101')
4652        >>> ExtendedContext.logical_xor(110, 1101)
4653        Decimal('1011')
4654        >>> ExtendedContext.logical_xor(Decimal(110), 1101)
4655        Decimal('1011')
4656        >>> ExtendedContext.logical_xor(110, Decimal(1101))
4657        Decimal('1011')
4658        """
4659        a = _convert_other(a, raiseit=True)
4660        return a.logical_xor(b, context=self)
4661
4662    def max(self, a, b):
4663        """max compares two values numerically and returns the maximum.
4664
4665        If either operand is a NaN then the general rules apply.
4666        Otherwise, the operands are compared as though by the compare
4667        operation.  If they are numerically equal then the left-hand operand
4668        is chosen as the result.  Otherwise the maximum (closer to positive
4669        infinity) of the two operands is chosen as the result.
4670
4671        >>> ExtendedContext.max(Decimal('3'), Decimal('2'))
4672        Decimal('3')
4673        >>> ExtendedContext.max(Decimal('-10'), Decimal('3'))
4674        Decimal('3')
4675        >>> ExtendedContext.max(Decimal('1.0'), Decimal('1'))
4676        Decimal('1')
4677        >>> ExtendedContext.max(Decimal('7'), Decimal('NaN'))
4678        Decimal('7')
4679        >>> ExtendedContext.max(1, 2)
4680        Decimal('2')
4681        >>> ExtendedContext.max(Decimal(1), 2)
4682        Decimal('2')
4683        >>> ExtendedContext.max(1, Decimal(2))
4684        Decimal('2')
4685        """
4686        a = _convert_other(a, raiseit=True)
4687        return a.max(b, context=self)
4688
4689    def max_mag(self, a, b):
4690        """Compares the values numerically with their sign ignored.
4691
4692        >>> ExtendedContext.max_mag(Decimal('7'), Decimal('NaN'))
4693        Decimal('7')
4694        >>> ExtendedContext.max_mag(Decimal('7'), Decimal('-10'))
4695        Decimal('-10')
4696        >>> ExtendedContext.max_mag(1, -2)
4697        Decimal('-2')
4698        >>> ExtendedContext.max_mag(Decimal(1), -2)
4699        Decimal('-2')
4700        >>> ExtendedContext.max_mag(1, Decimal(-2))
4701        Decimal('-2')
4702        """
4703        a = _convert_other(a, raiseit=True)
4704        return a.max_mag(b, context=self)
4705
4706    def min(self, a, b):
4707        """min compares two values numerically and returns the minimum.
4708
4709        If either operand is a NaN then the general rules apply.
4710        Otherwise, the operands are compared as though by the compare
4711        operation.  If they are numerically equal then the left-hand operand
4712        is chosen as the result.  Otherwise the minimum (closer to negative
4713        infinity) of the two operands is chosen as the result.
4714
4715        >>> ExtendedContext.min(Decimal('3'), Decimal('2'))
4716        Decimal('2')
4717        >>> ExtendedContext.min(Decimal('-10'), Decimal('3'))
4718        Decimal('-10')
4719        >>> ExtendedContext.min(Decimal('1.0'), Decimal('1'))
4720        Decimal('1.0')
4721        >>> ExtendedContext.min(Decimal('7'), Decimal('NaN'))
4722        Decimal('7')
4723        >>> ExtendedContext.min(1, 2)
4724        Decimal('1')
4725        >>> ExtendedContext.min(Decimal(1), 2)
4726        Decimal('1')
4727        >>> ExtendedContext.min(1, Decimal(29))
4728        Decimal('1')
4729        """
4730        a = _convert_other(a, raiseit=True)
4731        return a.min(b, context=self)
4732
4733    def min_mag(self, a, b):
4734        """Compares the values numerically with their sign ignored.
4735
4736        >>> ExtendedContext.min_mag(Decimal('3'), Decimal('-2'))
4737        Decimal('-2')
4738        >>> ExtendedContext.min_mag(Decimal('-3'), Decimal('NaN'))
4739        Decimal('-3')
4740        >>> ExtendedContext.min_mag(1, -2)
4741        Decimal('1')
4742        >>> ExtendedContext.min_mag(Decimal(1), -2)
4743        Decimal('1')
4744        >>> ExtendedContext.min_mag(1, Decimal(-2))
4745        Decimal('1')
4746        """
4747        a = _convert_other(a, raiseit=True)
4748        return a.min_mag(b, context=self)
4749
4750    def minus(self, a):
4751        """Minus corresponds to unary prefix minus in Python.
4752
4753        The operation is evaluated using the same rules as subtract; the
4754        operation minus(a) is calculated as subtract('0', a) where the '0'
4755        has the same exponent as the operand.
4756
4757        >>> ExtendedContext.minus(Decimal('1.3'))
4758        Decimal('-1.3')
4759        >>> ExtendedContext.minus(Decimal('-1.3'))
4760        Decimal('1.3')
4761        >>> ExtendedContext.minus(1)
4762        Decimal('-1')
4763        """
4764        a = _convert_other(a, raiseit=True)
4765        return a.__neg__(context=self)
4766
4767    def multiply(self, a, b):
4768        """multiply multiplies two operands.
4769
4770        If either operand is a special value then the general rules apply.
4771        Otherwise, the operands are multiplied together
4772        ('long multiplication'), resulting in a number which may be as long as
4773        the sum of the lengths of the two operands.
4774
4775        >>> ExtendedContext.multiply(Decimal('1.20'), Decimal('3'))
4776        Decimal('3.60')
4777        >>> ExtendedContext.multiply(Decimal('7'), Decimal('3'))
4778        Decimal('21')
4779        >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('0.8'))
4780        Decimal('0.72')
4781        >>> ExtendedContext.multiply(Decimal('0.9'), Decimal('-0'))
4782        Decimal('-0.0')
4783        >>> ExtendedContext.multiply(Decimal('654321'), Decimal('654321'))
4784        Decimal('4.28135971E+11')
4785        >>> ExtendedContext.multiply(7, 7)
4786        Decimal('49')
4787        >>> ExtendedContext.multiply(Decimal(7), 7)
4788        Decimal('49')
4789        >>> ExtendedContext.multiply(7, Decimal(7))
4790        Decimal('49')
4791        """
4792        a = _convert_other(a, raiseit=True)
4793        r = a.__mul__(b, context=self)
4794        if r is NotImplemented:
4795            raise TypeError("Unable to convert %s to Decimal" % b)
4796        else:
4797            return r
4798
4799    def next_minus(self, a):
4800        """Returns the largest representable number smaller than a.
4801
4802        >>> c = ExtendedContext.copy()
4803        >>> c.Emin = -999
4804        >>> c.Emax = 999
4805        >>> ExtendedContext.next_minus(Decimal('1'))
4806        Decimal('0.999999999')
4807        >>> c.next_minus(Decimal('1E-1007'))
4808        Decimal('0E-1007')
4809        >>> ExtendedContext.next_minus(Decimal('-1.00000003'))
4810        Decimal('-1.00000004')
4811        >>> c.next_minus(Decimal('Infinity'))
4812        Decimal('9.99999999E+999')
4813        >>> c.next_minus(1)
4814        Decimal('0.999999999')
4815        """
4816        a = _convert_other(a, raiseit=True)
4817        return a.next_minus(context=self)
4818
4819    def next_plus(self, a):
4820        """Returns the smallest representable number larger than a.
4821
4822        >>> c = ExtendedContext.copy()
4823        >>> c.Emin = -999
4824        >>> c.Emax = 999
4825        >>> ExtendedContext.next_plus(Decimal('1'))
4826        Decimal('1.00000001')
4827        >>> c.next_plus(Decimal('-1E-1007'))
4828        Decimal('-0E-1007')
4829        >>> ExtendedContext.next_plus(Decimal('-1.00000003'))
4830        Decimal('-1.00000002')
4831        >>> c.next_plus(Decimal('-Infinity'))
4832        Decimal('-9.99999999E+999')
4833        >>> c.next_plus(1)
4834        Decimal('1.00000001')
4835        """
4836        a = _convert_other(a, raiseit=True)
4837        return a.next_plus(context=self)
4838
4839    def next_toward(self, a, b):
4840        """Returns the number closest to a, in direction towards b.
4841
4842        The result is the closest representable number from the first
4843        operand (but not the first operand) that is in the direction
4844        towards the second operand, unless the operands have the same
4845        value.
4846
4847        >>> c = ExtendedContext.copy()
4848        >>> c.Emin = -999
4849        >>> c.Emax = 999
4850        >>> c.next_toward(Decimal('1'), Decimal('2'))
4851        Decimal('1.00000001')
4852        >>> c.next_toward(Decimal('-1E-1007'), Decimal('1'))
4853        Decimal('-0E-1007')
4854        >>> c.next_toward(Decimal('-1.00000003'), Decimal('0'))
4855        Decimal('-1.00000002')
4856        >>> c.next_toward(Decimal('1'), Decimal('0'))
4857        Decimal('0.999999999')
4858        >>> c.next_toward(Decimal('1E-1007'), Decimal('-100'))
4859        Decimal('0E-1007')
4860        >>> c.next_toward(Decimal('-1.00000003'), Decimal('-10'))
4861        Decimal('-1.00000004')
4862        >>> c.next_toward(Decimal('0.00'), Decimal('-0.0000'))
4863        Decimal('-0.00')
4864        >>> c.next_toward(0, 1)
4865        Decimal('1E-1007')
4866        >>> c.next_toward(Decimal(0), 1)
4867        Decimal('1E-1007')
4868        >>> c.next_toward(0, Decimal(1))
4869        Decimal('1E-1007')
4870        """
4871        a = _convert_other(a, raiseit=True)
4872        return a.next_toward(b, context=self)
4873
4874    def normalize(self, a):
4875        """normalize reduces an operand to its simplest form.
4876
4877        Essentially a plus operation with all trailing zeros removed from the
4878        result.
4879
4880        >>> ExtendedContext.normalize(Decimal('2.1'))
4881        Decimal('2.1')
4882        >>> ExtendedContext.normalize(Decimal('-2.0'))
4883        Decimal('-2')
4884        >>> ExtendedContext.normalize(Decimal('1.200'))
4885        Decimal('1.2')
4886        >>> ExtendedContext.normalize(Decimal('-120'))
4887        Decimal('-1.2E+2')
4888        >>> ExtendedContext.normalize(Decimal('120.00'))
4889        Decimal('1.2E+2')
4890        >>> ExtendedContext.normalize(Decimal('0.00'))
4891        Decimal('0')
4892        >>> ExtendedContext.normalize(6)
4893        Decimal('6')
4894        """
4895        a = _convert_other(a, raiseit=True)
4896        return a.normalize(context=self)
4897
4898    def number_class(self, a):
4899        """Returns an indication of the class of the operand.
4900
4901        The class is one of the following strings:
4902          -sNaN
4903          -NaN
4904          -Infinity
4905          -Normal
4906          -Subnormal
4907          -Zero
4908          +Zero
4909          +Subnormal
4910          +Normal
4911          +Infinity
4912
4913        >>> c = Context(ExtendedContext)
4914        >>> c.Emin = -999
4915        >>> c.Emax = 999
4916        >>> c.number_class(Decimal('Infinity'))
4917        '+Infinity'
4918        >>> c.number_class(Decimal('1E-10'))
4919        '+Normal'
4920        >>> c.number_class(Decimal('2.50'))
4921        '+Normal'
4922        >>> c.number_class(Decimal('0.1E-999'))
4923        '+Subnormal'
4924        >>> c.number_class(Decimal('0'))
4925        '+Zero'
4926        >>> c.number_class(Decimal('-0'))
4927        '-Zero'
4928        >>> c.number_class(Decimal('-0.1E-999'))
4929        '-Subnormal'
4930        >>> c.number_class(Decimal('-1E-10'))
4931        '-Normal'
4932        >>> c.number_class(Decimal('-2.50'))
4933        '-Normal'
4934        >>> c.number_class(Decimal('-Infinity'))
4935        '-Infinity'
4936        >>> c.number_class(Decimal('NaN'))
4937        'NaN'
4938        >>> c.number_class(Decimal('-NaN'))
4939        'NaN'
4940        >>> c.number_class(Decimal('sNaN'))
4941        'sNaN'
4942        >>> c.number_class(123)
4943        '+Normal'
4944        """
4945        a = _convert_other(a, raiseit=True)
4946        return a.number_class(context=self)
4947
4948    def plus(self, a):
4949        """Plus corresponds to unary prefix plus in Python.
4950
4951        The operation is evaluated using the same rules as add; the
4952        operation plus(a) is calculated as add('0', a) where the '0'
4953        has the same exponent as the operand.
4954
4955        >>> ExtendedContext.plus(Decimal('1.3'))
4956        Decimal('1.3')
4957        >>> ExtendedContext.plus(Decimal('-1.3'))
4958        Decimal('-1.3')
4959        >>> ExtendedContext.plus(-1)
4960        Decimal('-1')
4961        """
4962        a = _convert_other(a, raiseit=True)
4963        return a.__pos__(context=self)
4964
4965    def power(self, a, b, modulo=None):
4966        """Raises a to the power of b, to modulo if given.
4967
4968        With two arguments, compute a**b.  If a is negative then b
4969        must be integral.  The result will be inexact unless b is
4970        integral and the result is finite and can be expressed exactly
4971        in 'precision' digits.
4972
4973        With three arguments, compute (a**b) % modulo.  For the
4974        three argument form, the following restrictions on the
4975        arguments hold:
4976
4977         - all three arguments must be integral
4978         - b must be nonnegative
4979         - at least one of a or b must be nonzero
4980         - modulo must be nonzero and have at most 'precision' digits
4981
4982        The result of pow(a, b, modulo) is identical to the result
4983        that would be obtained by computing (a**b) % modulo with
4984        unbounded precision, but is computed more efficiently.  It is
4985        always exact.
4986
4987        >>> c = ExtendedContext.copy()
4988        >>> c.Emin = -999
4989        >>> c.Emax = 999
4990        >>> c.power(Decimal('2'), Decimal('3'))
4991        Decimal('8')
4992        >>> c.power(Decimal('-2'), Decimal('3'))
4993        Decimal('-8')
4994        >>> c.power(Decimal('2'), Decimal('-3'))
4995        Decimal('0.125')
4996        >>> c.power(Decimal('1.7'), Decimal('8'))
4997        Decimal('69.7575744')
4998        >>> c.power(Decimal('10'), Decimal('0.301029996'))
4999        Decimal('2.00000000')
5000        >>> c.power(Decimal('Infinity'), Decimal('-1'))
5001        Decimal('0')
5002        >>> c.power(Decimal('Infinity'), Decimal('0'))
5003        Decimal('1')
5004        >>> c.power(Decimal('Infinity'), Decimal('1'))
5005        Decimal('Infinity')
5006        >>> c.power(Decimal('-Infinity'), Decimal('-1'))
5007        Decimal('-0')
5008        >>> c.power(Decimal('-Infinity'), Decimal('0'))
5009        Decimal('1')
5010        >>> c.power(Decimal('-Infinity'), Decimal('1'))
5011        Decimal('-Infinity')
5012        >>> c.power(Decimal('-Infinity'), Decimal('2'))
5013        Decimal('Infinity')
5014        >>> c.power(Decimal('0'), Decimal('0'))
5015        Decimal('NaN')
5016
5017        >>> c.power(Decimal('3'), Decimal('7'), Decimal('16'))
5018        Decimal('11')
5019        >>> c.power(Decimal('-3'), Decimal('7'), Decimal('16'))
5020        Decimal('-11')
5021        >>> c.power(Decimal('-3'), Decimal('8'), Decimal('16'))
5022        Decimal('1')
5023        >>> c.power(Decimal('3'), Decimal('7'), Decimal('-16'))
5024        Decimal('11')
5025        >>> c.power(Decimal('23E12345'), Decimal('67E189'), Decimal('123456789'))
5026        Decimal('11729830')
5027        >>> c.power(Decimal('-0'), Decimal('17'), Decimal('1729'))
5028        Decimal('-0')
5029        >>> c.power(Decimal('-23'), Decimal('0'), Decimal('65537'))
5030        Decimal('1')
5031        >>> ExtendedContext.power(7, 7)
5032        Decimal('823543')
5033        >>> ExtendedContext.power(Decimal(7), 7)
5034        Decimal('823543')
5035        >>> ExtendedContext.power(7, Decimal(7), 2)
5036        Decimal('1')
5037        """
5038        a = _convert_other(a, raiseit=True)
5039        r = a.__pow__(b, modulo, context=self)
5040        if r is NotImplemented:
5041            raise TypeError("Unable to convert %s to Decimal" % b)
5042        else:
5043            return r
5044
5045    def quantize(self, a, b):
5046        """Returns a value equal to 'a' (rounded), having the exponent of 'b'.
5047
5048        The coefficient of the result is derived from that of the left-hand
5049        operand.  It may be rounded using the current rounding setting (if the
5050        exponent is being increased), multiplied by a positive power of ten (if
5051        the exponent is being decreased), or is unchanged (if the exponent is
5052        already equal to that of the right-hand operand).
5053
5054        Unlike other operations, if the length of the coefficient after the
5055        quantize operation would be greater than precision then an Invalid
5056        operation condition is raised.  This guarantees that, unless there is
5057        an error condition, the exponent of the result of a quantize is always
5058        equal to that of the right-hand operand.
5059
5060        Also unlike other operations, quantize will never raise Underflow, even
5061        if the result is subnormal and inexact.
5062
5063        >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))
5064        Decimal('2.170')
5065        >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))
5066        Decimal('2.17')
5067        >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))
5068        Decimal('2.2')
5069        >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))
5070        Decimal('2')
5071        >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))
5072        Decimal('0E+1')
5073        >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))
5074        Decimal('-Infinity')
5075        >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))
5076        Decimal('NaN')
5077        >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))
5078        Decimal('-0')
5079        >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))
5080        Decimal('-0E+5')
5081        >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))
5082        Decimal('NaN')
5083        >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))
5084        Decimal('NaN')
5085        >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))
5086        Decimal('217.0')
5087        >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))
5088        Decimal('217')
5089        >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))
5090        Decimal('2.2E+2')
5091        >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))
5092        Decimal('2E+2')
5093        >>> ExtendedContext.quantize(1, 2)
5094        Decimal('1')
5095        >>> ExtendedContext.quantize(Decimal(1), 2)
5096        Decimal('1')
5097        >>> ExtendedContext.quantize(1, Decimal(2))
5098        Decimal('1')
5099        """
5100        a = _convert_other(a, raiseit=True)
5101        return a.quantize(b, context=self)
5102
5103    def radix(self):
5104        """Just returns 10, as this is Decimal, :)
5105
5106        >>> ExtendedContext.radix()
5107        Decimal('10')
5108        """
5109        return Decimal(10)
5110
5111    def remainder(self, a, b):
5112        """Returns the remainder from integer division.
5113
5114        The result is the residue of the dividend after the operation of
5115        calculating integer division as described for divide-integer, rounded
5116        to precision digits if necessary.  The sign of the result, if
5117        non-zero, is the same as that of the original dividend.
5118
5119        This operation will fail under the same conditions as integer division
5120        (that is, if integer division on the same two operands would fail, the
5121        remainder cannot be calculated).
5122
5123        >>> ExtendedContext.remainder(Decimal('2.1'), Decimal('3'))
5124        Decimal('2.1')
5125        >>> ExtendedContext.remainder(Decimal('10'), Decimal('3'))
5126        Decimal('1')
5127        >>> ExtendedContext.remainder(Decimal('-10'), Decimal('3'))
5128        Decimal('-1')
5129        >>> ExtendedContext.remainder(Decimal('10.2'), Decimal('1'))
5130        Decimal('0.2')
5131        >>> ExtendedContext.remainder(Decimal('10'), Decimal('0.3'))
5132        Decimal('0.1')
5133        >>> ExtendedContext.remainder(Decimal('3.6'), Decimal('1.3'))
5134        Decimal('1.0')
5135        >>> ExtendedContext.remainder(22, 6)
5136        Decimal('4')
5137        >>> ExtendedContext.remainder(Decimal(22), 6)
5138        Decimal('4')
5139        >>> ExtendedContext.remainder(22, Decimal(6))
5140        Decimal('4')
5141        """
5142        a = _convert_other(a, raiseit=True)
5143        r = a.__mod__(b, context=self)
5144        if r is NotImplemented:
5145            raise TypeError("Unable to convert %s to Decimal" % b)
5146        else:
5147            return r
5148
5149    def remainder_near(self, a, b):
5150        """Returns to be "a - b * n", where n is the integer nearest the exact
5151        value of "x / b" (if two integers are equally near then the even one
5152        is chosen).  If the result is equal to 0 then its sign will be the
5153        sign of a.
5154
5155        This operation will fail under the same conditions as integer division
5156        (that is, if integer division on the same two operands would fail, the
5157        remainder cannot be calculated).
5158
5159        >>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))
5160        Decimal('-0.9')
5161        >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))
5162        Decimal('-2')
5163        >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))
5164        Decimal('1')
5165        >>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))
5166        Decimal('-1')
5167        >>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))
5168        Decimal('0.2')
5169        >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))
5170        Decimal('0.1')
5171        >>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))
5172        Decimal('-0.3')
5173        >>> ExtendedContext.remainder_near(3, 11)
5174        Decimal('3')
5175        >>> ExtendedContext.remainder_near(Decimal(3), 11)
5176        Decimal('3')
5177        >>> ExtendedContext.remainder_near(3, Decimal(11))
5178        Decimal('3')
5179        """
5180        a = _convert_other(a, raiseit=True)
5181        return a.remainder_near(b, context=self)
5182
5183    def rotate(self, a, b):
5184        """Returns a rotated copy of a, b times.
5185
5186        The coefficient of the result is a rotated copy of the digits in
5187        the coefficient of the first operand.  The number of places of
5188        rotation is taken from the absolute value of the second operand,
5189        with the rotation being to the left if the second operand is
5190        positive or to the right otherwise.
5191
5192        >>> ExtendedContext.rotate(Decimal('34'), Decimal('8'))
5193        Decimal('400000003')
5194        >>> ExtendedContext.rotate(Decimal('12'), Decimal('9'))
5195        Decimal('12')
5196        >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('-2'))
5197        Decimal('891234567')
5198        >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('0'))
5199        Decimal('123456789')
5200        >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('+2'))
5201        Decimal('345678912')
5202        >>> ExtendedContext.rotate(1333333, 1)
5203        Decimal('13333330')
5204        >>> ExtendedContext.rotate(Decimal(1333333), 1)
5205        Decimal('13333330')
5206        >>> ExtendedContext.rotate(1333333, Decimal(1))
5207        Decimal('13333330')
5208        """
5209        a = _convert_other(a, raiseit=True)
5210        return a.rotate(b, context=self)
5211
5212    def same_quantum(self, a, b):
5213        """Returns True if the two operands have the same exponent.
5214
5215        The result is never affected by either the sign or the coefficient of
5216        either operand.
5217
5218        >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))
5219        False
5220        >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))
5221        True
5222        >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))
5223        False
5224        >>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))
5225        True
5226        >>> ExtendedContext.same_quantum(10000, -1)
5227        True
5228        >>> ExtendedContext.same_quantum(Decimal(10000), -1)
5229        True
5230        >>> ExtendedContext.same_quantum(10000, Decimal(-1))
5231        True
5232        """
5233        a = _convert_other(a, raiseit=True)
5234        return a.same_quantum(b)
5235
5236    def scaleb (self, a, b):
5237        """Returns the first operand after adding the second value its exp.
5238
5239        >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('-2'))
5240        Decimal('0.0750')
5241        >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('0'))
5242        Decimal('7.50')
5243        >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('3'))
5244        Decimal('7.50E+3')
5245        >>> ExtendedContext.scaleb(1, 4)
5246        Decimal('1E+4')
5247        >>> ExtendedContext.scaleb(Decimal(1), 4)
5248        Decimal('1E+4')
5249        >>> ExtendedContext.scaleb(1, Decimal(4))
5250        Decimal('1E+4')
5251        """
5252        a = _convert_other(a, raiseit=True)
5253        return a.scaleb(b, context=self)
5254
5255    def shift(self, a, b):
5256        """Returns a shifted copy of a, b times.
5257
5258        The coefficient of the result is a shifted copy of the digits
5259        in the coefficient of the first operand.  The number of places
5260        to shift is taken from the absolute value of the second operand,
5261        with the shift being to the left if the second operand is
5262        positive or to the right otherwise.  Digits shifted into the
5263        coefficient are zeros.
5264
5265        >>> ExtendedContext.shift(Decimal('34'), Decimal('8'))
5266        Decimal('400000000')
5267        >>> ExtendedContext.shift(Decimal('12'), Decimal('9'))
5268        Decimal('0')
5269        >>> ExtendedContext.shift(Decimal('123456789'), Decimal('-2'))
5270        Decimal('1234567')
5271        >>> ExtendedContext.shift(Decimal('123456789'), Decimal('0'))
5272        Decimal('123456789')
5273        >>> ExtendedContext.shift(Decimal('123456789'), Decimal('+2'))
5274        Decimal('345678900')
5275        >>> ExtendedContext.shift(88888888, 2)
5276        Decimal('888888800')
5277        >>> ExtendedContext.shift(Decimal(88888888), 2)
5278        Decimal('888888800')
5279        >>> ExtendedContext.shift(88888888, Decimal(2))
5280        Decimal('888888800')
5281        """
5282        a = _convert_other(a, raiseit=True)
5283        return a.shift(b, context=self)
5284
5285    def sqrt(self, a):
5286        """Square root of a non-negative number to context precision.
5287
5288        If the result must be inexact, it is rounded using the round-half-even
5289        algorithm.
5290
5291        >>> ExtendedContext.sqrt(Decimal('0'))
5292        Decimal('0')
5293        >>> ExtendedContext.sqrt(Decimal('-0'))
5294        Decimal('-0')
5295        >>> ExtendedContext.sqrt(Decimal('0.39'))
5296        Decimal('0.624499800')
5297        >>> ExtendedContext.sqrt(Decimal('100'))
5298        Decimal('10')
5299        >>> ExtendedContext.sqrt(Decimal('1'))
5300        Decimal('1')
5301        >>> ExtendedContext.sqrt(Decimal('1.0'))
5302        Decimal('1.0')
5303        >>> ExtendedContext.sqrt(Decimal('1.00'))
5304        Decimal('1.0')
5305        >>> ExtendedContext.sqrt(Decimal('7'))
5306        Decimal('2.64575131')
5307        >>> ExtendedContext.sqrt(Decimal('10'))
5308        Decimal('3.16227766')
5309        >>> ExtendedContext.sqrt(2)
5310        Decimal('1.41421356')
5311        >>> ExtendedContext.prec
5312        9
5313        """
5314        a = _convert_other(a, raiseit=True)
5315        return a.sqrt(context=self)
5316
5317    def subtract(self, a, b):
5318        """Return the difference between the two operands.
5319
5320        >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.07'))
5321        Decimal('0.23')
5322        >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.30'))
5323        Decimal('0.00')
5324        >>> ExtendedContext.subtract(Decimal('1.3'), Decimal('2.07'))
5325        Decimal('-0.77')
5326        >>> ExtendedContext.subtract(8, 5)
5327        Decimal('3')
5328        >>> ExtendedContext.subtract(Decimal(8), 5)
5329        Decimal('3')
5330        >>> ExtendedContext.subtract(8, Decimal(5))
5331        Decimal('3')
5332        """
5333        a = _convert_other(a, raiseit=True)
5334        r = a.__sub__(b, context=self)
5335        if r is NotImplemented:
5336            raise TypeError("Unable to convert %s to Decimal" % b)
5337        else:
5338            return r
5339
5340    def to_eng_string(self, a):
5341        """Convert to a string, using engineering notation if an exponent is needed.
5342
5343        Engineering notation has an exponent which is a multiple of 3.  This
5344        can leave up to 3 digits to the left of the decimal place and may
5345        require the addition of either one or two trailing zeros.
5346
5347        The operation is not affected by the context.
5348
5349        >>> ExtendedContext.to_eng_string(Decimal('123E+1'))
5350        '1.23E+3'
5351        >>> ExtendedContext.to_eng_string(Decimal('123E+3'))
5352        '123E+3'
5353        >>> ExtendedContext.to_eng_string(Decimal('123E-10'))
5354        '12.3E-9'
5355        >>> ExtendedContext.to_eng_string(Decimal('-123E-12'))
5356        '-123E-12'
5357        >>> ExtendedContext.to_eng_string(Decimal('7E-7'))
5358        '700E-9'
5359        >>> ExtendedContext.to_eng_string(Decimal('7E+1'))
5360        '70'
5361        >>> ExtendedContext.to_eng_string(Decimal('0E+1'))
5362        '0.00E+3'
5363
5364        """
5365        a = _convert_other(a, raiseit=True)
5366        return a.to_eng_string(context=self)
5367
5368    def to_sci_string(self, a):
5369        """Converts a number to a string, using scientific notation.
5370
5371        The operation is not affected by the context.
5372        """
5373        a = _convert_other(a, raiseit=True)
5374        return a.__str__(context=self)
5375
5376    def to_integral_exact(self, a):
5377        """Rounds to an integer.
5378
5379        When the operand has a negative exponent, the result is the same
5380        as using the quantize() operation using the given operand as the
5381        left-hand-operand, 1E+0 as the right-hand-operand, and the precision
5382        of the operand as the precision setting; Inexact and Rounded flags
5383        are allowed in this operation.  The rounding mode is taken from the
5384        context.
5385
5386        >>> ExtendedContext.to_integral_exact(Decimal('2.1'))
5387        Decimal('2')
5388        >>> ExtendedContext.to_integral_exact(Decimal('100'))
5389        Decimal('100')
5390        >>> ExtendedContext.to_integral_exact(Decimal('100.0'))
5391        Decimal('100')
5392        >>> ExtendedContext.to_integral_exact(Decimal('101.5'))
5393        Decimal('102')
5394        >>> ExtendedContext.to_integral_exact(Decimal('-101.5'))
5395        Decimal('-102')
5396        >>> ExtendedContext.to_integral_exact(Decimal('10E+5'))
5397        Decimal('1.0E+6')
5398        >>> ExtendedContext.to_integral_exact(Decimal('7.89E+77'))
5399        Decimal('7.89E+77')
5400        >>> ExtendedContext.to_integral_exact(Decimal('-Inf'))
5401        Decimal('-Infinity')
5402        """
5403        a = _convert_other(a, raiseit=True)
5404        return a.to_integral_exact(context=self)
5405
5406    def to_integral_value(self, a):
5407        """Rounds to an integer.
5408
5409        When the operand has a negative exponent, the result is the same
5410        as using the quantize() operation using the given operand as the
5411        left-hand-operand, 1E+0 as the right-hand-operand, and the precision
5412        of the operand as the precision setting, except that no flags will
5413        be set.  The rounding mode is taken from the context.
5414
5415        >>> ExtendedContext.to_integral_value(Decimal('2.1'))
5416        Decimal('2')
5417        >>> ExtendedContext.to_integral_value(Decimal('100'))
5418        Decimal('100')
5419        >>> ExtendedContext.to_integral_value(Decimal('100.0'))
5420        Decimal('100')
5421        >>> ExtendedContext.to_integral_value(Decimal('101.5'))
5422        Decimal('102')
5423        >>> ExtendedContext.to_integral_value(Decimal('-101.5'))
5424        Decimal('-102')
5425        >>> ExtendedContext.to_integral_value(Decimal('10E+5'))
5426        Decimal('1.0E+6')
5427        >>> ExtendedContext.to_integral_value(Decimal('7.89E+77'))
5428        Decimal('7.89E+77')
5429        >>> ExtendedContext.to_integral_value(Decimal('-Inf'))
5430        Decimal('-Infinity')
5431        """
5432        a = _convert_other(a, raiseit=True)
5433        return a.to_integral_value(context=self)
5434
5435    # the method name changed, but we provide also the old one, for compatibility
5436    to_integral = to_integral_value
5437
5438class _WorkRep(object):
5439    __slots__ = ('sign','int','exp')
5440    # sign: 0 or 1
5441    # int:  int or long
5442    # exp:  None, int, or string
5443
5444    def __init__(self, value=None):
5445        if value is None:
5446            self.sign = None
5447            self.int = 0
5448            self.exp = None
5449        elif isinstance(value, Decimal):
5450            self.sign = value._sign
5451            self.int = int(value._int)
5452            self.exp = value._exp
5453        else:
5454            # assert isinstance(value, tuple)
5455            self.sign = value[0]
5456            self.int = value[1]
5457            self.exp = value[2]
5458
5459    def __repr__(self):
5460        return "(%r, %r, %r)" % (self.sign, self.int, self.exp)
5461
5462    __str__ = __repr__
5463
5464
5465
5466def _normalize(op1, op2, prec = 0):
5467    """Normalizes op1, op2 to have the same exp and length of coefficient.
5468
5469    Done during addition.
5470    """
5471    if op1.exp < op2.exp:
5472        tmp = op2
5473        other = op1
5474    else:
5475        tmp = op1
5476        other = op2
5477
5478    # Let exp = min(tmp.exp - 1, tmp.adjusted() - precision - 1).
5479    # Then adding 10**exp to tmp has the same effect (after rounding)
5480    # as adding any positive quantity smaller than 10**exp; similarly
5481    # for subtraction.  So if other is smaller than 10**exp we replace
5482    # it with 10**exp.  This avoids tmp.exp - other.exp getting too large.
5483    tmp_len = len(str(tmp.int))
5484    other_len = len(str(other.int))
5485    exp = tmp.exp + min(-1, tmp_len - prec - 2)
5486    if other_len + other.exp - 1 < exp:
5487        other.int = 1
5488        other.exp = exp
5489
5490    tmp.int *= 10 ** (tmp.exp - other.exp)
5491    tmp.exp = other.exp
5492    return op1, op2
5493
5494##### Integer arithmetic functions used by ln, log10, exp and __pow__ #####
5495
5496# This function from Tim Peters was taken from here:
5497# http://mail.python.org/pipermail/python-list/1999-July/007758.html
5498# The correction being in the function definition is for speed, and
5499# the whole function is not resolved with math.log because of avoiding
5500# the use of floats.
5501def _nbits(n, correction = {
5502        '0': 4, '1': 3, '2': 2, '3': 2,
5503        '4': 1, '5': 1, '6': 1, '7': 1,
5504        '8': 0, '9': 0, 'a': 0, 'b': 0,
5505        'c': 0, 'd': 0, 'e': 0, 'f': 0}):
5506    """Number of bits in binary representation of the positive integer n,
5507    or 0 if n == 0.
5508    """
5509    if n < 0:
5510        raise ValueError("The argument to _nbits should be nonnegative.")
5511    hex_n = "%x" % n
5512    return 4*len(hex_n) - correction[hex_n[0]]
5513
5514def _decimal_lshift_exact(n, e):
5515    """ Given integers n and e, return n * 10**e if it's an integer, else None.
5516
5517    The computation is designed to avoid computing large powers of 10
5518    unnecessarily.
5519
5520    >>> _decimal_lshift_exact(3, 4)
5521    30000
5522    >>> _decimal_lshift_exact(300, -999999999)  # returns None
5523
5524    """
5525    if n == 0:
5526        return 0
5527    elif e >= 0:
5528        return n * 10**e
5529    else:
5530        # val_n = largest power of 10 dividing n.
5531        str_n = str(abs(n))
5532        val_n = len(str_n) - len(str_n.rstrip('0'))
5533        return None if val_n < -e else n // 10**-e
5534
5535def _sqrt_nearest(n, a):
5536    """Closest integer to the square root of the positive integer n.  a is
5537    an initial approximation to the square root.  Any positive integer
5538    will do for a, but the closer a is to the square root of n the
5539    faster convergence will be.
5540
5541    """
5542    if n <= 0 or a <= 0:
5543        raise ValueError("Both arguments to _sqrt_nearest should be positive.")
5544
5545    b=0
5546    while a != b:
5547        b, a = a, a--n//a>>1
5548    return a
5549
5550def _rshift_nearest(x, shift):
5551    """Given an integer x and a nonnegative integer shift, return closest
5552    integer to x / 2**shift; use round-to-even in case of a tie.
5553
5554    """
5555    b, q = 1L << shift, x >> shift
5556    return q + (2*(x & (b-1)) + (q&1) > b)
5557
5558def _div_nearest(a, b):
5559    """Closest integer to a/b, a and b positive integers; rounds to even
5560    in the case of a tie.
5561
5562    """
5563    q, r = divmod(a, b)
5564    return q + (2*r + (q&1) > b)
5565
5566def _ilog(x, M, L = 8):
5567    """Integer approximation to M*log(x/M), with absolute error boundable
5568    in terms only of x/M.
5569
5570    Given positive integers x and M, return an integer approximation to
5571    M * log(x/M).  For L = 8 and 0.1 <= x/M <= 10 the difference
5572    between the approximation and the exact result is at most 22.  For
5573    L = 8 and 1.0 <= x/M <= 10.0 the difference is at most 15.  In
5574    both cases these are upper bounds on the error; it will usually be
5575    much smaller."""
5576
5577    # The basic algorithm is the following: let log1p be the function
5578    # log1p(x) = log(1+x).  Then log(x/M) = log1p((x-M)/M).  We use
5579    # the reduction
5580    #
5581    #    log1p(y) = 2*log1p(y/(1+sqrt(1+y)))
5582    #
5583    # repeatedly until the argument to log1p is small (< 2**-L in
5584    # absolute value).  For small y we can use the Taylor series
5585    # expansion
5586    #
5587    #    log1p(y) ~ y - y**2/2 + y**3/3 - ... - (-y)**T/T
5588    #
5589    # truncating at T such that y**T is small enough.  The whole
5590    # computation is carried out in a form of fixed-point arithmetic,
5591    # with a real number z being represented by an integer
5592    # approximation to z*M.  To avoid loss of precision, the y below
5593    # is actually an integer approximation to 2**R*y*M, where R is the
5594    # number of reductions performed so far.
5595
5596    y = x-M
5597    # argument reduction; R = number of reductions performed
5598    R = 0
5599    while (R <= L and long(abs(y)) << L-R >= M or
5600           R > L and abs(y) >> R-L >= M):
5601        y = _div_nearest(long(M*y) << 1,
5602                         M + _sqrt_nearest(M*(M+_rshift_nearest(y, R)), M))
5603        R += 1
5604
5605    # Taylor series with T terms
5606    T = -int(-10*len(str(M))//(3*L))
5607    yshift = _rshift_nearest(y, R)
5608    w = _div_nearest(M, T)
5609    for k in xrange(T-1, 0, -1):
5610        w = _div_nearest(M, k) - _div_nearest(yshift*w, M)
5611
5612    return _div_nearest(w*y, M)
5613
5614def _dlog10(c, e, p):
5615    """Given integers c, e and p with c > 0, p >= 0, compute an integer
5616    approximation to 10**p * log10(c*10**e), with an absolute error of
5617    at most 1.  Assumes that c*10**e is not exactly 1."""
5618
5619    # increase precision by 2; compensate for this by dividing
5620    # final result by 100
5621    p += 2
5622
5623    # write c*10**e as d*10**f with either:
5624    #   f >= 0 and 1 <= d <= 10, or
5625    #   f <= 0 and 0.1 <= d <= 1.
5626    # Thus for c*10**e close to 1, f = 0
5627    l = len(str(c))
5628    f = e+l - (e+l >= 1)
5629
5630    if p > 0:
5631        M = 10**p
5632        k = e+p-f
5633        if k >= 0:
5634            c *= 10**k
5635        else:
5636            c = _div_nearest(c, 10**-k)
5637
5638        log_d = _ilog(c, M) # error < 5 + 22 = 27
5639        log_10 = _log10_digits(p) # error < 1
5640        log_d = _div_nearest(log_d*M, log_10)
5641        log_tenpower = f*M # exact
5642    else:
5643        log_d = 0  # error < 2.31
5644        log_tenpower = _div_nearest(f, 10**-p) # error < 0.5
5645
5646    return _div_nearest(log_tenpower+log_d, 100)
5647
5648def _dlog(c, e, p):
5649    """Given integers c, e and p with c > 0, compute an integer
5650    approximation to 10**p * log(c*10**e), with an absolute error of
5651    at most 1.  Assumes that c*10**e is not exactly 1."""
5652
5653    # Increase precision by 2. The precision increase is compensated
5654    # for at the end with a division by 100.
5655    p += 2
5656
5657    # rewrite c*10**e as d*10**f with either f >= 0 and 1 <= d <= 10,
5658    # or f <= 0 and 0.1 <= d <= 1.  Then we can compute 10**p * log(c*10**e)
5659    # as 10**p * log(d) + 10**p*f * log(10).
5660    l = len(str(c))
5661    f = e+l - (e+l >= 1)
5662
5663    # compute approximation to 10**p*log(d), with error < 27
5664    if p > 0:
5665        k = e+p-f
5666        if k >= 0:
5667            c *= 10**k
5668        else:
5669            c = _div_nearest(c, 10**-k)  # error of <= 0.5 in c
5670
5671        # _ilog magnifies existing error in c by a factor of at most 10
5672        log_d = _ilog(c, 10**p) # error < 5 + 22 = 27
5673    else:
5674        # p <= 0: just approximate the whole thing by 0; error < 2.31
5675        log_d = 0
5676
5677    # compute approximation to f*10**p*log(10), with error < 11.
5678    if f:
5679        extra = len(str(abs(f)))-1
5680        if p + extra >= 0:
5681            # error in f * _log10_digits(p+extra) < |f| * 1 = |f|
5682            # after division, error < |f|/10**extra + 0.5 < 10 + 0.5 < 11
5683            f_log_ten = _div_nearest(f*_log10_digits(p+extra), 10**extra)
5684        else:
5685            f_log_ten = 0
5686    else:
5687        f_log_ten = 0
5688
5689    # error in sum < 11+27 = 38; error after division < 0.38 + 0.5 < 1
5690    return _div_nearest(f_log_ten + log_d, 100)
5691
5692class _Log10Memoize(object):
5693    """Class to compute, store, and allow retrieval of, digits of the
5694    constant log(10) = 2.302585....  This constant is needed by
5695    Decimal.ln, Decimal.log10, Decimal.exp and Decimal.__pow__."""
5696    def __init__(self):
5697        self.digits = "23025850929940456840179914546843642076011014886"
5698
5699    def getdigits(self, p):
5700        """Given an integer p >= 0, return floor(10**p)*log(10).
5701
5702        For example, self.getdigits(3) returns 2302.
5703        """
5704        # digits are stored as a string, for quick conversion to
5705        # integer in the case that we've already computed enough
5706        # digits; the stored digits should always be correct
5707        # (truncated, not rounded to nearest).
5708        if p < 0:
5709            raise ValueError("p should be nonnegative")
5710
5711        if p >= len(self.digits):
5712            # compute p+3, p+6, p+9, ... digits; continue until at
5713            # least one of the extra digits is nonzero
5714            extra = 3
5715            while True:
5716                # compute p+extra digits, correct to within 1ulp
5717                M = 10**(p+extra+2)
5718                digits = str(_div_nearest(_ilog(10*M, M), 100))
5719                if digits[-extra:] != '0'*extra:
5720                    break
5721                extra += 3
5722            # keep all reliable digits so far; remove trailing zeros
5723            # and next nonzero digit
5724            self.digits = digits.rstrip('0')[:-1]
5725        return int(self.digits[:p+1])
5726
5727_log10_digits = _Log10Memoize().getdigits
5728
5729def _iexp(x, M, L=8):
5730    """Given integers x and M, M > 0, such that x/M is small in absolute
5731    value, compute an integer approximation to M*exp(x/M).  For 0 <=
5732    x/M <= 2.4, the absolute error in the result is bounded by 60 (and
5733    is usually much smaller)."""
5734
5735    # Algorithm: to compute exp(z) for a real number z, first divide z
5736    # by a suitable power R of 2 so that |z/2**R| < 2**-L.  Then
5737    # compute expm1(z/2**R) = exp(z/2**R) - 1 using the usual Taylor
5738    # series
5739    #
5740    #     expm1(x) = x + x**2/2! + x**3/3! + ...
5741    #
5742    # Now use the identity
5743    #
5744    #     expm1(2x) = expm1(x)*(expm1(x)+2)
5745    #
5746    # R times to compute the sequence expm1(z/2**R),
5747    # expm1(z/2**(R-1)), ... , exp(z/2), exp(z).
5748
5749    # Find R such that x/2**R/M <= 2**-L
5750    R = _nbits((long(x)<<L)//M)
5751
5752    # Taylor series.  (2**L)**T > M
5753    T = -int(-10*len(str(M))//(3*L))
5754    y = _div_nearest(x, T)
5755    Mshift = long(M)<<R
5756    for i in xrange(T-1, 0, -1):
5757        y = _div_nearest(x*(Mshift + y), Mshift * i)
5758
5759    # Expansion
5760    for k in xrange(R-1, -1, -1):
5761        Mshift = long(M)<<(k+2)
5762        y = _div_nearest(y*(y+Mshift), Mshift)
5763
5764    return M+y
5765
5766def _dexp(c, e, p):
5767    """Compute an approximation to exp(c*10**e), with p decimal places of
5768    precision.
5769
5770    Returns integers d, f such that:
5771
5772      10**(p-1) <= d <= 10**p, and
5773      (d-1)*10**f < exp(c*10**e) < (d+1)*10**f
5774
5775    In other words, d*10**f is an approximation to exp(c*10**e) with p
5776    digits of precision, and with an error in d of at most 1.  This is
5777    almost, but not quite, the same as the error being < 1ulp: when d
5778    = 10**(p-1) the error could be up to 10 ulp."""
5779
5780    # we'll call iexp with M = 10**(p+2), giving p+3 digits of precision
5781    p += 2
5782
5783    # compute log(10) with extra precision = adjusted exponent of c*10**e
5784    extra = max(0, e + len(str(c)) - 1)
5785    q = p + extra
5786
5787    # compute quotient c*10**e/(log(10)) = c*10**(e+q)/(log(10)*10**q),
5788    # rounding down
5789    shift = e+q
5790    if shift >= 0:
5791        cshift = c*10**shift
5792    else:
5793        cshift = c//10**-shift
5794    quot, rem = divmod(cshift, _log10_digits(q))
5795
5796    # reduce remainder back to original precision
5797    rem = _div_nearest(rem, 10**extra)
5798
5799    # error in result of _iexp < 120;  error after division < 0.62
5800    return _div_nearest(_iexp(rem, 10**p), 1000), quot - p + 3
5801
5802def _dpower(xc, xe, yc, ye, p):
5803    """Given integers xc, xe, yc and ye representing Decimals x = xc*10**xe and
5804    y = yc*10**ye, compute x**y.  Returns a pair of integers (c, e) such that:
5805
5806      10**(p-1) <= c <= 10**p, and
5807      (c-1)*10**e < x**y < (c+1)*10**e
5808
5809    in other words, c*10**e is an approximation to x**y with p digits
5810    of precision, and with an error in c of at most 1.  (This is
5811    almost, but not quite, the same as the error being < 1ulp: when c
5812    == 10**(p-1) we can only guarantee error < 10ulp.)
5813
5814    We assume that: x is positive and not equal to 1, and y is nonzero.
5815    """
5816
5817    # Find b such that 10**(b-1) <= |y| <= 10**b
5818    b = len(str(abs(yc))) + ye
5819
5820    # log(x) = lxc*10**(-p-b-1), to p+b+1 places after the decimal point
5821    lxc = _dlog(xc, xe, p+b+1)
5822
5823    # compute product y*log(x) = yc*lxc*10**(-p-b-1+ye) = pc*10**(-p-1)
5824    shift = ye-b
5825    if shift >= 0:
5826        pc = lxc*yc*10**shift
5827    else:
5828        pc = _div_nearest(lxc*yc, 10**-shift)
5829
5830    if pc == 0:
5831        # we prefer a result that isn't exactly 1; this makes it
5832        # easier to compute a correctly rounded result in __pow__
5833        if ((len(str(xc)) + xe >= 1) == (yc > 0)): # if x**y > 1:
5834            coeff, exp = 10**(p-1)+1, 1-p
5835        else:
5836            coeff, exp = 10**p-1, -p
5837    else:
5838        coeff, exp = _dexp(pc, -(p+1), p+1)
5839        coeff = _div_nearest(coeff, 10)
5840        exp += 1
5841
5842    return coeff, exp
5843
5844def _log10_lb(c, correction = {
5845        '1': 100, '2': 70, '3': 53, '4': 40, '5': 31,
5846        '6': 23, '7': 16, '8': 10, '9': 5}):
5847    """Compute a lower bound for 100*log10(c) for a positive integer c."""
5848    if c <= 0:
5849        raise ValueError("The argument to _log10_lb should be nonnegative.")
5850    str_c = str(c)
5851    return 100*len(str_c) - correction[str_c[0]]
5852
5853##### Helper Functions ####################################################
5854
5855def _convert_other(other, raiseit=False, allow_float=False):
5856    """Convert other to Decimal.
5857
5858    Verifies that it's ok to use in an implicit construction.
5859    If allow_float is true, allow conversion from float;  this
5860    is used in the comparison methods (__eq__ and friends).
5861
5862    """
5863    if isinstance(other, Decimal):
5864        return other
5865    if isinstance(other, (int, long)):
5866        return Decimal(other)
5867    if allow_float and isinstance(other, float):
5868        return Decimal.from_float(other)
5869
5870    if raiseit:
5871        raise TypeError("Unable to convert %s to Decimal" % other)
5872    return NotImplemented
5873
5874##### Setup Specific Contexts ############################################
5875
5876# The default context prototype used by Context()
5877# Is mutable, so that new contexts can have different default values
5878
5879DefaultContext = Context(
5880        prec=28, rounding=ROUND_HALF_EVEN,
5881        traps=[DivisionByZero, Overflow, InvalidOperation],
5882        flags=[],
5883        Emax=999999999,
5884        Emin=-999999999,
5885        capitals=1
5886)
5887
5888# Pre-made alternate contexts offered by the specification
5889# Don't change these; the user should be able to select these
5890# contexts and be able to reproduce results from other implementations
5891# of the spec.
5892
5893BasicContext = Context(
5894        prec=9, rounding=ROUND_HALF_UP,
5895        traps=[DivisionByZero, Overflow, InvalidOperation, Clamped, Underflow],
5896        flags=[],
5897)
5898
5899ExtendedContext = Context(
5900        prec=9, rounding=ROUND_HALF_EVEN,
5901        traps=[],
5902        flags=[],
5903)
5904
5905
5906##### crud for parsing strings #############################################
5907#
5908# Regular expression used for parsing numeric strings.  Additional
5909# comments:
5910#
5911# 1. Uncomment the two '\s*' lines to allow leading and/or trailing
5912# whitespace.  But note that the specification disallows whitespace in
5913# a numeric string.
5914#
5915# 2. For finite numbers (not infinities and NaNs) the body of the
5916# number between the optional sign and the optional exponent must have
5917# at least one decimal digit, possibly after the decimal point.  The
5918# lookahead expression '(?=\d|\.\d)' checks this.
5919
5920import re
5921_parser = re.compile(r"""        # A numeric string consists of:
5922#    \s*
5923    (?P<sign>[-+])?              # an optional sign, followed by either...
5924    (
5925        (?=\d|\.\d)              # ...a number (with at least one digit)
5926        (?P<int>\d*)             # having a (possibly empty) integer part
5927        (\.(?P<frac>\d*))?       # followed by an optional fractional part
5928        (E(?P<exp>[-+]?\d+))?    # followed by an optional exponent, or...
5929    |
5930        Inf(inity)?              # ...an infinity, or...
5931    |
5932        (?P<signal>s)?           # ...an (optionally signaling)
5933        NaN                      # NaN
5934        (?P<diag>\d*)            # with (possibly empty) diagnostic info.
5935    )
5936#    \s*
5937    \Z
5938""", re.VERBOSE | re.IGNORECASE | re.UNICODE).match
5939
5940_all_zeros = re.compile('0*$').match
5941_exact_half = re.compile('50*$').match
5942
5943##### PEP3101 support functions ##############################################
5944# The functions in this section have little to do with the Decimal
5945# class, and could potentially be reused or adapted for other pure
5946# Python numeric classes that want to implement __format__
5947#
5948# A format specifier for Decimal looks like:
5949#
5950#   [[fill]align][sign][0][minimumwidth][,][.precision][type]
5951
5952_parse_format_specifier_regex = re.compile(r"""\A
5953(?:
5954   (?P<fill>.)?
5955   (?P<align>[<>=^])
5956)?
5957(?P<sign>[-+ ])?
5958(?P<zeropad>0)?
5959(?P<minimumwidth>(?!0)\d+)?
5960(?P<thousands_sep>,)?
5961(?:\.(?P<precision>0|(?!0)\d+))?
5962(?P<type>[eEfFgGn%])?
5963\Z
5964""", re.VERBOSE)
5965
5966del re
5967
5968# The locale module is only needed for the 'n' format specifier.  The
5969# rest of the PEP 3101 code functions quite happily without it, so we
5970# don't care too much if locale isn't present.
5971try:
5972    import locale as _locale
5973except ImportError:
5974    pass
5975
5976def _parse_format_specifier(format_spec, _localeconv=None):
5977    """Parse and validate a format specifier.
5978
5979    Turns a standard numeric format specifier into a dict, with the
5980    following entries:
5981
5982      fill: fill character to pad field to minimum width
5983      align: alignment type, either '<', '>', '=' or '^'
5984      sign: either '+', '-' or ' '
5985      minimumwidth: nonnegative integer giving minimum width
5986      zeropad: boolean, indicating whether to pad with zeros
5987      thousands_sep: string to use as thousands separator, or ''
5988      grouping: grouping for thousands separators, in format
5989        used by localeconv
5990      decimal_point: string to use for decimal point
5991      precision: nonnegative integer giving precision, or None
5992      type: one of the characters 'eEfFgG%', or None
5993      unicode: boolean (always True for Python 3.x)
5994
5995    """
5996    m = _parse_format_specifier_regex.match(format_spec)
5997    if m is None:
5998        raise ValueError("Invalid format specifier: " + format_spec)
5999
6000    # get the dictionary
6001    format_dict = m.groupdict()
6002
6003    # zeropad; defaults for fill and alignment.  If zero padding
6004    # is requested, the fill and align fields should be absent.
6005    fill = format_dict['fill']
6006    align = format_dict['align']
6007    format_dict['zeropad'] = (format_dict['zeropad'] is not None)
6008    if format_dict['zeropad']:
6009        if fill is not None:
6010            raise ValueError("Fill character conflicts with '0'"
6011                             " in format specifier: " + format_spec)
6012        if align is not None:
6013            raise ValueError("Alignment conflicts with '0' in "
6014                             "format specifier: " + format_spec)
6015    format_dict['fill'] = fill or ' '
6016    # PEP 3101 originally specified that the default alignment should
6017    # be left;  it was later agreed that right-aligned makes more sense
6018    # for numeric types.  See http://bugs.python.org/issue6857.
6019    format_dict['align'] = align or '>'
6020
6021    # default sign handling: '-' for negative, '' for positive
6022    if format_dict['sign'] is None:
6023        format_dict['sign'] = '-'
6024
6025    # minimumwidth defaults to 0; precision remains None if not given
6026    format_dict['minimumwidth'] = int(format_dict['minimumwidth'] or '0')
6027    if format_dict['precision'] is not None:
6028        format_dict['precision'] = int(format_dict['precision'])
6029
6030    # if format type is 'g' or 'G' then a precision of 0 makes little
6031    # sense; convert it to 1.  Same if format type is unspecified.
6032    if format_dict['precision'] == 0:
6033        if format_dict['type'] is None or format_dict['type'] in 'gG':
6034            format_dict['precision'] = 1
6035
6036    # determine thousands separator, grouping, and decimal separator, and
6037    # add appropriate entries to format_dict
6038    if format_dict['type'] == 'n':
6039        # apart from separators, 'n' behaves just like 'g'
6040        format_dict['type'] = 'g'
6041        if _localeconv is None:
6042            _localeconv = _locale.localeconv()
6043        if format_dict['thousands_sep'] is not None:
6044            raise ValueError("Explicit thousands separator conflicts with "
6045                             "'n' type in format specifier: " + format_spec)
6046        format_dict['thousands_sep'] = _localeconv['thousands_sep']
6047        format_dict['grouping'] = _localeconv['grouping']
6048        format_dict['decimal_point'] = _localeconv['decimal_point']
6049    else:
6050        if format_dict['thousands_sep'] is None:
6051            format_dict['thousands_sep'] = ''
6052        format_dict['grouping'] = [3, 0]
6053        format_dict['decimal_point'] = '.'
6054
6055    # record whether return type should be str or unicode
6056    try:
6057        format_dict['unicode'] = isinstance(format_spec, unicode)
6058    except NameError:
6059        format_dict['unicode'] = False
6060
6061    return format_dict
6062
6063def _format_align(sign, body, spec):
6064    """Given an unpadded, non-aligned numeric string 'body' and sign
6065    string 'sign', add padding and alignment conforming to the given
6066    format specifier dictionary 'spec' (as produced by
6067    parse_format_specifier).
6068
6069    Also converts result to unicode if necessary.
6070
6071    """
6072    # how much extra space do we have to play with?
6073    minimumwidth = spec['minimumwidth']
6074    fill = spec['fill']
6075    padding = fill*(minimumwidth - len(sign) - len(body))
6076
6077    align = spec['align']
6078    if align == '<':
6079        result = sign + body + padding
6080    elif align == '>':
6081        result = padding + sign + body
6082    elif align == '=':
6083        result = sign + padding + body
6084    elif align == '^':
6085        half = len(padding)//2
6086        result = padding[:half] + sign + body + padding[half:]
6087    else:
6088        raise ValueError('Unrecognised alignment field')
6089
6090    # make sure that result is unicode if necessary
6091    if spec['unicode']:
6092        result = unicode(result)
6093
6094    return result
6095
6096def _group_lengths(grouping):
6097    """Convert a localeconv-style grouping into a (possibly infinite)
6098    iterable of integers representing group lengths.
6099
6100    """
6101    # The result from localeconv()['grouping'], and the input to this
6102    # function, should be a list of integers in one of the
6103    # following three forms:
6104    #
6105    #   (1) an empty list, or
6106    #   (2) nonempty list of positive integers + [0]
6107    #   (3) list of positive integers + [locale.CHAR_MAX], or
6108
6109    from itertools import chain, repeat
6110    if not grouping:
6111        return []
6112    elif grouping[-1] == 0 and len(grouping) >= 2:
6113        return chain(grouping[:-1], repeat(grouping[-2]))
6114    elif grouping[-1] == _locale.CHAR_MAX:
6115        return grouping[:-1]
6116    else:
6117        raise ValueError('unrecognised format for grouping')
6118
6119def _insert_thousands_sep(digits, spec, min_width=1):
6120    """Insert thousands separators into a digit string.
6121
6122    spec is a dictionary whose keys should include 'thousands_sep' and
6123    'grouping'; typically it's the result of parsing the format
6124    specifier using _parse_format_specifier.
6125
6126    The min_width keyword argument gives the minimum length of the
6127    result, which will be padded on the left with zeros if necessary.
6128
6129    If necessary, the zero padding adds an extra '0' on the left to
6130    avoid a leading thousands separator.  For example, inserting
6131    commas every three digits in '123456', with min_width=8, gives
6132    '0,123,456', even though that has length 9.
6133
6134    """
6135
6136    sep = spec['thousands_sep']
6137    grouping = spec['grouping']
6138
6139    groups = []
6140    for l in _group_lengths(grouping):
6141        if l <= 0:
6142            raise ValueError("group length should be positive")
6143        # max(..., 1) forces at least 1 digit to the left of a separator
6144        l = min(max(len(digits), min_width, 1), l)
6145        groups.append('0'*(l - len(digits)) + digits[-l:])
6146        digits = digits[:-l]
6147        min_width -= l
6148        if not digits and min_width <= 0:
6149            break
6150        min_width -= len(sep)
6151    else:
6152        l = max(len(digits), min_width, 1)
6153        groups.append('0'*(l - len(digits)) + digits[-l:])
6154    return sep.join(reversed(groups))
6155
6156def _format_sign(is_negative, spec):
6157    """Determine sign character."""
6158
6159    if is_negative:
6160        return '-'
6161    elif spec['sign'] in ' +':
6162        return spec['sign']
6163    else:
6164        return ''
6165
6166def _format_number(is_negative, intpart, fracpart, exp, spec):
6167    """Format a number, given the following data:
6168
6169    is_negative: true if the number is negative, else false
6170    intpart: string of digits that must appear before the decimal point
6171    fracpart: string of digits that must come after the point
6172    exp: exponent, as an integer
6173    spec: dictionary resulting from parsing the format specifier
6174
6175    This function uses the information in spec to:
6176      insert separators (decimal separator and thousands separators)
6177      format the sign
6178      format the exponent
6179      add trailing '%' for the '%' type
6180      zero-pad if necessary
6181      fill and align if necessary
6182    """
6183
6184    sign = _format_sign(is_negative, spec)
6185
6186    if fracpart:
6187        fracpart = spec['decimal_point'] + fracpart
6188
6189    if exp != 0 or spec['type'] in 'eE':
6190        echar = {'E': 'E', 'e': 'e', 'G': 'E', 'g': 'e'}[spec['type']]
6191        fracpart += "{0}{1:+}".format(echar, exp)
6192    if spec['type'] == '%':
6193        fracpart += '%'
6194
6195    if spec['zeropad']:
6196        min_width = spec['minimumwidth'] - len(fracpart) - len(sign)
6197    else:
6198        min_width = 0
6199    intpart = _insert_thousands_sep(intpart, spec, min_width)
6200
6201    return _format_align(sign, intpart+fracpart, spec)
6202
6203
6204##### Useful Constants (internal use only) ################################
6205
6206# Reusable defaults
6207_Infinity = Decimal('Inf')
6208_NegativeInfinity = Decimal('-Inf')
6209_NaN = Decimal('NaN')
6210_Zero = Decimal(0)
6211_One = Decimal(1)
6212_NegativeOne = Decimal(-1)
6213
6214# _SignedInfinity[sign] is infinity w/ that sign
6215_SignedInfinity = (_Infinity, _NegativeInfinity)
6216
6217
6218
6219if __name__ == '__main__':
6220    import doctest, sys
6221    doctest.testmod(sys.modules[__name__])
6222