PageRenderTime 2082ms CodeModel.GetById 93ms app.highlight 1816ms RepoModel.GetById 56ms app.codeStats 1ms

/Lib/decimal.py

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