diff --git a/Lib/_pydecimal.py b/Lib/_pydecimal.py index de4561a5ee050b..a5ec5f825c106d 100644 --- a/Lib/_pydecimal.py +++ b/Lib/_pydecimal.py @@ -349,7 +349,7 @@ class FloatOperation(DecimalException, TypeError): ) def getcontext(): - """Returns this thread's context. + """Return this thread's context. If this thread does not yet have a context, returns a new context and sets this thread's context. @@ -372,40 +372,75 @@ def setcontext(context): del contextvars # Don't contaminate the namespace def localcontext(ctx=None, **kwargs): - """Return a context manager for a copy of the supplied context + """"Return a context manager that will set the default context to a copy of ctx + on entry to the with-statement and restore the previous default context when + exiting the with-statement. - Uses a copy of the current context if no context is specified + If no context is specified, a copy of the current default context is used. The returned context manager creates a local decimal context in a with statement: def sin(x): - with localcontext() as ctx: - ctx.prec += 2 - # Rest of sin calculation algorithm - # uses a precision 2 greater than normal - return +s # Convert result to normal precision - - def sin(x): - with localcontext(ExtendedContext): - # Rest of sin calculation algorithm - # uses the Extended Context from the - # General Decimal Arithmetic Specification - return +s # Convert result to normal context - - >>> setcontext(DefaultContext) - >>> print(getcontext().prec) - 28 - >>> with localcontext(): - ... ctx = getcontext() - ... ctx.prec += 2 - ... print(ctx.prec) - ... - 30 - >>> with localcontext(ExtendedContext): - ... print(getcontext().prec) - ... - 9 - >>> print(getcontext().prec) - 28 + with localcontext() as ctx: + ctx.prec += 2 + # Rest of sin calculation algorithm + # uses a precision 2 greater than normal + return +s # Convert result to normal precision + + def sin(x): + with localcontext(ExtendedContext): + # Rest of sin calculation algorithm + # uses the Extended Context from the + # General Decimal Arithmetic Specification + return +s # Convert result to normal context + + >>> setcontext(DefaultContext) + >>> print(getcontext().prec) # Return a context manager for a copy of the supplied context + + Uses a copy of the current context if no context is specified. + The returned context manager creates a local decimal context + in a with statement: + def sin(x): + with localcontext() as ctx: + ctx.prec += 2 + # Rest of sin calculation algorithm + # uses a precision 2 greater than normal + return +s # Convert result to normal precision + + def sin(x): + with localcontext(ExtendedContext): + # Rest of sin calculation algorithm + # uses the Extended Context from the + # General Decimal Arithmetic Specification + return +s # Convert result to normal context + + >>> setcontext(DefaultContext) + >>> print(getcontext().prec) + 28 + >>> with localcontext(): + ... ctx = getcontext() + ... ctx.prec += 2 + ... print(ctx.prec) + ... + 30 + >>> with localcontext(ExtendedContext): + ... print(getcontext().prec) + ... + 9 + >>> print(getcontext().prec) + 28 + 28 + >>> with localcontext(): + ... ctx = getcontext() + ... ctx.prec += 2 + ... print(ctx.prec) + ... + 30 + >>> with localcontext(ExtendedContext): + ... print(getcontext().prec) + ... + 9 + >>> print(getcontext().prec) + 28 """ if ctx is None: ctx = getcontext() @@ -433,18 +468,22 @@ class Decimal(object): # We're immutable, so use __new__ not __init__ def __new__(cls, value="0", context=None): - """Create a decimal point instance. - - >>> Decimal('3.14') # string input - Decimal('3.14') - >>> Decimal((0, (3, 1, 4), -2)) # tuple (sign, digit_tuple, exponent) - Decimal('3.14') - >>> Decimal(314) # int - Decimal('314') - >>> Decimal(Decimal(314)) # another decimal instance - Decimal('314') - >>> Decimal(' 3.14 \\n') # leading and trailing whitespace okay - Decimal('3.14') + """Construct a new Decimal object. + + 'value' can be an integer, string, tuple, or another Decimal object. If no value + is given, return Decimal('0'). The context does not affect the conversion and + is only passed to determine if the InvalidOperation trap is active. + + >>> Decimal('3.14') # string input + Decimal('3.14') + >>> Decimal((0, (3, 1, 4), -2)) # tuple (sign, digit_tuple, exponent) + Decimal('3.14') + >>> Decimal(314) # int + Decimal('314') + >>> Decimal(Decimal(314)) # another decimal instance + Decimal('314') + >>> Decimal(' 3.14 \\\\n') # leading and trailing whitespace okay + Decimal('3.14') """ # Note that the coefficient, self._int, is actually stored as @@ -836,12 +875,44 @@ def __ge__(self, other, context=None): return self._cmp(other) >= 0 def compare(self, other, context=None): - """Compare self to other. Return a decimal value: + """Compare values numerically. - a or b is a NaN ==> Decimal('NaN') - a < b ==> Decimal('-1') - a == b ==> Decimal('0') - a > b ==> Decimal('1') + If the signs of the operands differ, a value representing each operand + ('-1' if the operand is less than zero, '0' if the operand is zero or + negative zero, or '1' if the operand is greater than zero) is used in + place of that operand for the comparison instead of the actual + operand. + + The comparison is then effected by subtracting the second operand from + the first and then returning a value according to the result of the + subtraction: '-1' if the result is less than zero, '0' if the result is + zero or negative zero, or '1' if the result is greater than zero. + + a or b is a NaN ==> Decimal('NaN') + a < b ==> Decimal('-1') + a == b ==> Decimal('0') + a > b ==> Decimal('1') + + >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3')) + Decimal('-1') + >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1')) + Decimal('0') + >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10')) + Decimal('0') + >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1')) + Decimal('1') + >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3')) + Decimal('1') + >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1')) + Decimal('-1') + >>> ExtendedContext.compare(1, 2) + Decimal('-1') + >>> ExtendedContext.compare(Decimal(1), 2) + Decimal('-1') + >>> ExtendedContext.compare(1, Decimal(2)) + Decimal('-1') + >>> ExtendedContext.compare(Decimal('2'), Decimal('NaN')) + Decimal('NaN') """ other = _convert_other(other, raiseit=True) @@ -880,17 +951,18 @@ def __hash__(self): return -2 if ans == -1 else ans def as_tuple(self): - """Represents the number as a triple tuple. - - To show the internals exactly as they are. + """Represents the number as a triple tuple, to show the internals exactly as + they are. """ return DecimalTuple(self._sign, tuple(map(int, self._int)), self._exp) def as_integer_ratio(self): """Express a finite Decimal instance in the form n / d. - Returns a pair (n, d) of integers. When called on an infinity - or NaN, raises OverflowError or ValueError respectively. + Return a pair (n, d) of integers, whose ratio is exactly equal to the + original Decimal and with a positive denominator. The ratio is in + lowest terms. Raise OverflowError on infinities and a ValueError + on NaNs. >>> Decimal('3.14').as_integer_ratio() (157, 50) @@ -898,7 +970,6 @@ def as_integer_ratio(self): (-12300000, 1) >>> Decimal('0.00').as_integer_ratio() (0, 1) - """ if self._is_special: if self.is_nan(): @@ -1554,6 +1625,7 @@ def imag(self): return Decimal(0) def conjugate(self): + """Return self""" return self def __complex__(self): @@ -2447,9 +2519,59 @@ def normalize(self, context=None): return _dec_from_triple(dup._sign, dup._int[:end], exp) def quantize(self, exp, rounding=None, context=None): - """Quantize self so its exponent is the same as that of exp. + """Return a value equal to 'a' (rounded), having the exponent of 'b'. + + Similar to self._rescale(exp._exp) but with error checking. The + coefficient of the result is derived from that of the left-hand operand. + It may be rounded using the current rounding setting (if the exponent is + being increased), multiplied by a positive power of ten (if the exponent + is being decreased), or is unchanged (if the exponent is + already equal to that of the right-hand operand). - Similar to self._rescale(exp._exp) but with error checking. + Unlike other operations, if the length of the coefficient after the + quantize operation would be greater than precision then an Invalid + operation condition is raised. This guarantees that, unless there is + an error condition, the exponent of the result of a quantize is always + equal to that of the right-hand operand. + Also unlike other operations, quantize will never raise Underflow, even + if the result is subnormal and inexact. + + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001')) + Decimal('2.170') + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01')) + Decimal('2.17') + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1')) + Decimal('2.2') + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0')) + Decimal('2') + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1')) + Decimal('0E+1') + >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity')) + Decimal('-Infinity') + >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity')) + Decimal('NaN') + >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1')) + Decimal('-0') + >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5')) + Decimal('-0E+5') + >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2')) + Decimal('NaN') + >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2')) + Decimal('NaN') + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1')) + Decimal('217.0') + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0')) + Decimal('217') + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1')) + Decimal('2.2E+2') + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2')) + Decimal('2E+2') + >>> ExtendedContext.quantize(1, 2) + Decimal('1') + >>> ExtendedContext.quantize(Decimal(1), 2) + Decimal('1') + >>> ExtendedContext.quantize(1, Decimal(2)) + Decimal('1') """ exp = _convert_other(exp, raiseit=True) @@ -2818,7 +2940,10 @@ def _iseven(self): return self._int[-1+self._exp] in '02468' def adjusted(self): - """Return the adjusted exponent of self""" + """Return the adjusted exponent of the number. + + Defined as exp + digits - 1. + """ try: return self._exp + len(self._int) - 1 # If NaN or Infinity, self._exp is string @@ -2826,10 +2951,10 @@ def adjusted(self): return 0 def canonical(self): - """Returns the same Decimal object. + """Return the canonical encoding of the argument. - As we do not have different encodings for the same number, the - received object already is in its canonical form. + Currently, the encoding of a Decimal instance is always canonical, + so this operation returns its argument unchanged. """ return self @@ -2919,9 +3044,14 @@ def compare_total(self, other, context=None): def compare_total_mag(self, other, context=None): - """Compares self to other using abstract repr., ignoring sign. + """Compare two operands using their abstract representation rather than their + numerical value and with their sign ignored. Like compare_total, but with operand's sign ignored and assumed to be 0. + x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.copy_abs()). + This operation is unaffected by context and is quiet: no flags are changed + and no rounding is performed. As an exception, the C version may raise + InvalidOperation if the second operand cannot be converted exactly. """ other = _convert_other(other, raiseit=True) @@ -2930,7 +3060,18 @@ def compare_total_mag(self, other, context=None): return s.compare_total(o) def copy_abs(self): - """Returns a copy with the sign set to 0. """ + """Return the absolute value of the argument. + + This operation is unaffected by context and is quiet: no flags are changed + and no rounding is performed. + + >>> ExtendedContext.copy_abs(Decimal('2.1')) + Decimal('2.1') + >>> ExtendedContext.copy_abs(Decimal('-100')) + Decimal('100') + >>> ExtendedContext.copy_abs(-1) + Decimal('1') + """ return _dec_from_triple(0, self._int, self._exp, self._is_special) def copy_negate(self): @@ -3409,7 +3550,10 @@ def min_mag(self, other, context=None): return ans._fix(context) def next_minus(self, context=None): - """Returns the largest representable number smaller than itself.""" + """Return the largest number representable in the given context (or in the + current default context if no context is given) that is smaller than the\ + given operand. + """ if context is None: context = getcontext() @@ -4115,6 +4259,11 @@ def compare(self, a, b): subtraction: '-1' if the result is less than zero, '0' if the result is zero or negative zero, or '1' if the result is greater than zero. + a or b is a NaN ==> Decimal('NaN') + a < b ==> Decimal('-1') + a == b ==> Decimal('0') + a > b ==> Decimal('1') + >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3')) Decimal('-1') >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1')) @@ -4133,51 +4282,62 @@ def compare(self, a, b): Decimal('-1') >>> ExtendedContext.compare(1, Decimal(2)) Decimal('-1') + >>> ExtendedContext.compare(Decimal('2'), Decimal('NaN')) + Decimal('NaN') """ a = _convert_other(a, raiseit=True) return a.compare(b, context=self) def compare_signal(self, a, b): - """Compares the values of the two operands numerically. + """Compare the values of the two operands numerically. It's pretty much like compare(), but all NaNs signal, with signaling NaNs taking precedence over quiet NaNs. - >>> c = ExtendedContext - >>> c.compare_signal(Decimal('2.1'), Decimal('3')) + >>> ExtendedContext.compare_signal(Decimal('2.1'), Decimal('3')) Decimal('-1') - >>> c.compare_signal(Decimal('2.1'), Decimal('2.1')) + >>> ExtendedContext.compare_signal(Decimal('2.1'), Decimal('2.1')) Decimal('0') - >>> c.flags[InvalidOperation] = 0 - >>> print(c.flags[InvalidOperation]) + >>> ExtendedContext.flags[InvalidOperation] = 0 + >>> print(ExtendedContext.flags[InvalidOperation]) 0 - >>> c.compare_signal(Decimal('NaN'), Decimal('2.1')) + >>> ExtendedContext.compare_signal(Decimal('NaN'), Decimal('2.1')) Decimal('NaN') - >>> print(c.flags[InvalidOperation]) + >>> print(ExtendedContext.flags[InvalidOperation]) 1 - >>> c.flags[InvalidOperation] = 0 - >>> print(c.flags[InvalidOperation]) + >>> ExtendedContext.flags[InvalidOperation] = 0 + >>> print(ExtendedContext.flags[InvalidOperation]) 0 - >>> c.compare_signal(Decimal('sNaN'), Decimal('2.1')) + >>> ExtendedContext.compare_signal(Decimal('sNaN'), Decimal('2.1')) Decimal('NaN') - >>> print(c.flags[InvalidOperation]) + >>> print(ExtendedContext.flags[InvalidOperation]) 1 - >>> c.compare_signal(-1, 2) + >>> ExtendedContext.compare_signal(-1, 2) Decimal('-1') - >>> c.compare_signal(Decimal(-1), 2) + >>> ExtendedContext.compare_signal(Decimal(-1), 2) Decimal('-1') - >>> c.compare_signal(-1, Decimal(2)) + >>> ExtendedContext.compare_signal(-1, Decimal(2)) Decimal('-1') """ a = _convert_other(a, raiseit=True) return a.compare_signal(b, context=self) def compare_total(self, a, b): - """Compares two operands using their abstract representation. + """Compare two operands using their abstract representation rather + than their numerical value. - This is not like the standard compare, which use their numerical - value. Note that a total ordering is defined for all possible abstract - representations. + Similar to the compare() method, but the result gives a total ordering + on Decimal instances. + + Quiet and signaling NaNs are also included in the total ordering. + The result of this function is Decimal('0') if both operands have the + same representation, Decimal('-1') if the first operand is lower in + the total order than the second, and Decimal('1') if the first + operand is higher in the total order than the second operand. See + the specification for details of the total order. + + This operation is unaffected by context and is quiet: no flags are + changed and no rounding is performed. >>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9')) Decimal('-1') @@ -4202,23 +4362,19 @@ def compare_total(self, a, b): return a.compare_total(b) def compare_total_mag(self, a, b): - """Compares two operands using their abstract representation ignoring sign. + """Compare two operands using their abstract representation rather + than their numerical value and with their sign ignored. Like compare_total, but with operand's sign ignored and assumed to be 0. + x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.copy_abs()) + This operation is unaffected by context and is quiet: no flags are + changed and no rounding is performed. """ a = _convert_other(a, raiseit=True) return a.compare_total_mag(b) def copy_abs(self, a): - """Returns a copy of the operand with the sign set to 0. - - >>> ExtendedContext.copy_abs(Decimal('2.1')) - Decimal('2.1') - >>> ExtendedContext.copy_abs(Decimal('-100')) - Decimal('100') - >>> ExtendedContext.copy_abs(-1) - Decimal('1') - """ + """Return a copy of a with the sign set to 0.""" a = _convert_other(a, raiseit=True) return a.copy_abs() @@ -4236,7 +4392,10 @@ def copy_decimal(self, a): return Decimal(a) def copy_negate(self, a): - """Returns a copy of the operand with the sign inverted. + """Return a copy of the operand with the sign inverted. + + This operation is unaffected by context and is quiet: no flags are + changed and no rounding is performed. >>> ExtendedContext.copy_negate(Decimal('101.5')) Decimal('-101.5') @@ -4249,25 +4408,26 @@ def copy_negate(self, a): return a.copy_negate() def copy_sign(self, a, b): - """Copies the second operand's sign to the first one. - - In detail, it returns a copy of the first operand with the sign - equal to the sign of the second operand. - - >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33')) - Decimal('1.50') - >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33')) - Decimal('1.50') - >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33')) - Decimal('-1.50') - >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33')) - Decimal('-1.50') - >>> ExtendedContext.copy_sign(1, -2) - Decimal('-1') - >>> ExtendedContext.copy_sign(Decimal(1), -2) - Decimal('-1') - >>> ExtendedContext.copy_sign(1, Decimal(-2)) - Decimal('-1') + """Return a copy of the first operand with the sign equal to the second operand. + + >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33')) + Decimal('1.50') + >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33')) + Decimal('1.50') + >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33')) + Decimal('-1.50') + >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33')) + Decimal('-1.50') + >>> ExtendedContext.copy_sign(1, -2) + Decimal('-1') + >>> ExtendedContext.copy_sign(Decimal(1), -2) + Decimal('-1') + >>> ExtendedContext.copy_sign(1, Decimal(-2)) + Decimal('-1') + + This operation is unaffected by context and is quiet: no flags are changed + and no rounding is performed. As an exception, the C version may raise + InvalidOperation if the second operand cannot be converted exactly. """ a = _convert_other(a, raiseit=True) return a.copy_sign(b) @@ -4354,7 +4514,10 @@ def divmod(self, a, b): return r def exp(self, a): - """Returns e ** a. + """Return the value of the (natural) exponential function e ** a. + + The function always uses the ROUND_HALF_EVEN mode and the result + is correctly rounded. >>> c = ExtendedContext.copy() >>> c.Emin = -999 @@ -4380,22 +4543,22 @@ def exp(self, a): def fma(self, a, b, c): """Returns a multiplied by b, plus c. - The first two operands are multiplied together, using multiply, - the third operand is then added to the result of that + Fused multiply-add. The first two operands are multiplied together, + using multiply, the third operand is then added to the result of that multiplication, using add, all with only one final rounding. - >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7')) - Decimal('22') - >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7')) - Decimal('-8') - >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578')) - Decimal('1.38435736E+12') - >>> ExtendedContext.fma(1, 3, 4) - Decimal('7') - >>> ExtendedContext.fma(1, Decimal(3), 4) - Decimal('7') - >>> ExtendedContext.fma(1, 3, Decimal(4)) - Decimal('7') + >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7')) + Decimal('22') + >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7')) + Decimal('-8') + >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578')) + Decimal('1.38435736E+12') + >>> ExtendedContext.fma(1, 3, 4) + Decimal('7') + >>> ExtendedContext.fma(1, Decimal(3), 4) + Decimal('7') + >>> ExtendedContext.fma(1, 3, Decimal(4)) + Decimal('7') """ a = _convert_other(a, raiseit=True) return a.fma(b, c, context=self) @@ -4451,7 +4614,7 @@ def is_infinite(self, a): return a.is_infinite() def is_nan(self, a): - """Return True if the operand is a qNaN or sNaN; + """Return True if the operand is a (quiet or signaling) NaN or NaN; otherwise return False. >>> ExtendedContext.is_nan(Decimal('2.50')) @@ -4467,8 +4630,7 @@ def is_nan(self, a): return a.is_nan() def is_normal(self, a): - """Return True if the operand is a normal number; - otherwise return False. + """Return True if the operand is a normal number; otherwise return False. >>> c = ExtendedContext.copy() >>> c.Emin = -999 @@ -4505,7 +4667,9 @@ def is_qnan(self, a): return a.is_qnan() def is_signed(self, a): - """Return True if the operand is negative; otherwise return False. + """Return True if the argument has a negative sign and False otherwise. + + Note that both zeros and NaNs can carry signs. >>> ExtendedContext.is_signed(Decimal('2.50')) False @@ -4522,8 +4686,7 @@ def is_signed(self, a): return a.is_signed() def is_snan(self, a): - """Return True if the operand is a signaling NaN; - otherwise return False. + """Return True if the operand is a signaling NaN; otherwise return False. >>> ExtendedContext.is_snan(Decimal('2.50')) False @@ -4540,6 +4703,9 @@ def is_snan(self, a): def is_subnormal(self, a): """Return True if the operand is subnormal; otherwise return False. + A number is subnormal if it is non-zero, finite, and has an adjusted + exponent less than Emin. + >>> c = ExtendedContext.copy() >>> c.Emin = -999 >>> c.Emax = 999 @@ -4577,7 +4743,8 @@ def is_zero(self, a): return a.is_zero() def ln(self, a): - """Returns the natural (base e) logarithm of the operand. + """Return the natural (base e) logarithm of the operand. The function always + uses the ROUND_HALF_EVEN mode and the result is correctly rounded. >>> c = ExtendedContext.copy() >>> c.Emin = -999 @@ -4599,7 +4766,8 @@ def ln(self, a): return a.ln(context=self) def log10(self, a): - """Returns the base 10 logarithm of the operand. + """Return the base 10 logarithm of the operand. The function always uses the + ROUND_HALF_EVEN mode and the result is correctly rounded. >>> c = ExtendedContext.copy() >>> c.Emin = -999 @@ -4627,7 +4795,7 @@ def log10(self, a): return a.log10(context=self) def logb(self, a): - """ Returns the exponent of the magnitude of the operand's MSD. + """Return the exponent of the magnitude of the operand's MSD. The result is the integer which is the exponent of the magnitude of the most significant digit of the operand (as though the @@ -4653,28 +4821,28 @@ def logb(self, a): return a.logb(context=self) def logical_and(self, a, b): - """Applies the logical operation 'and' between each operand's digits. + """Apply the logical operation 'and' between each operand's digits. The operands must be both logical numbers. - >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0')) - Decimal('0') - >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1')) - Decimal('0') - >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0')) - Decimal('0') - >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1')) - Decimal('1') - >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010')) - Decimal('1000') - >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10')) - Decimal('10') - >>> ExtendedContext.logical_and(110, 1101) - Decimal('100') - >>> ExtendedContext.logical_and(Decimal(110), 1101) - Decimal('100') - >>> ExtendedContext.logical_and(110, Decimal(1101)) - Decimal('100') + >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0')) + Decimal('0') + >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1')) + Decimal('0') + >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0')) + Decimal('0') + >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1')) + Decimal('1') + >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010')) + Decimal('1000') + >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10')) + Decimal('10') + >>> ExtendedContext.logical_and(110, 1101) + Decimal('100') + >>> ExtendedContext.logical_and(Decimal(110), 1101) + Decimal('100') + >>> ExtendedContext.logical_and(110, Decimal(1101)) + Decimal('100') """ a = _convert_other(a, raiseit=True) return a.logical_and(b, context=self) @@ -4684,16 +4852,16 @@ def logical_invert(self, a): The operand must be a logical number. - >>> ExtendedContext.logical_invert(Decimal('0')) - Decimal('111111111') - >>> ExtendedContext.logical_invert(Decimal('1')) - Decimal('111111110') - >>> ExtendedContext.logical_invert(Decimal('111111111')) - Decimal('0') - >>> ExtendedContext.logical_invert(Decimal('101010101')) - Decimal('10101010') - >>> ExtendedContext.logical_invert(1101) - Decimal('111110010') + >>> ExtendedContext.logical_invert(Decimal('0')) + Decimal('111111111') + >>> ExtendedContext.logical_invert(Decimal('1')) + Decimal('111111110') + >>> ExtendedContext.logical_invert(Decimal('111111111')) + Decimal('0') + >>> ExtendedContext.logical_invert(Decimal('101010101')) + Decimal('10101010') + >>> ExtendedContext.logical_invert(1101) + Decimal('111110010') """ a = _convert_other(a, raiseit=True) return a.logical_invert(context=self) @@ -4703,57 +4871,57 @@ def logical_or(self, a, b): The operands must be both logical numbers. - >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0')) - Decimal('0') - >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1')) - Decimal('1') - >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0')) - Decimal('1') - >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1')) - Decimal('1') - >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010')) - Decimal('1110') - >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10')) - Decimal('1110') - >>> ExtendedContext.logical_or(110, 1101) - Decimal('1111') - >>> ExtendedContext.logical_or(Decimal(110), 1101) - Decimal('1111') - >>> ExtendedContext.logical_or(110, Decimal(1101)) - Decimal('1111') + >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0')) + Decimal('0') + >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1')) + Decimal('1') + >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0')) + Decimal('1') + >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1')) + Decimal('1') + >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010')) + Decimal('1110') + >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10')) + Decimal('1110') + >>> ExtendedContext.logical_or(110, 1101) + Decimal('1111') + >>> ExtendedContext.logical_or(Decimal(110), 1101) + Decimal('1111') + >>> ExtendedContext.logical_or(110, Decimal(1101)) + Decimal('1111') """ a = _convert_other(a, raiseit=True) return a.logical_or(b, context=self) def logical_xor(self, a, b): - """Applies the logical operation 'xor' between each operand's digits. + """Apply the logical operation 'xor' between each operand's digits. The operands must be both logical numbers. - >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0')) - Decimal('0') - >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1')) - Decimal('1') - >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0')) - Decimal('1') - >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1')) - Decimal('0') - >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010')) - Decimal('110') - >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10')) - Decimal('1101') - >>> ExtendedContext.logical_xor(110, 1101) - Decimal('1011') - >>> ExtendedContext.logical_xor(Decimal(110), 1101) - Decimal('1011') - >>> ExtendedContext.logical_xor(110, Decimal(1101)) - Decimal('1011') + >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0')) + Decimal('0') + >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1')) + Decimal('1') + >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0')) + Decimal('1') + >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1')) + Decimal('0') + >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010')) + Decimal('110') + >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10')) + Decimal('1101') + >>> ExtendedContext.logical_xor(110, 1101) + Decimal('1011') + >>> ExtendedContext.logical_xor(Decimal(110), 1101) + Decimal('1011') + >>> ExtendedContext.logical_xor(110, Decimal(1101)) + Decimal('1011') """ a = _convert_other(a, raiseit=True) return a.logical_xor(b, context=self) def max(self, a, b): - """max compares two values numerically and returns the maximum. + """Compare two values numerically and return the maximum. If either operand is a NaN then the general rules apply. Otherwise, the operands are compared as though by the compare @@ -4761,43 +4929,44 @@ def max(self, a, b): is chosen as the result. Otherwise the maximum (closer to positive infinity) of the two operands is chosen as the result. - >>> ExtendedContext.max(Decimal('3'), Decimal('2')) - Decimal('3') - >>> ExtendedContext.max(Decimal('-10'), Decimal('3')) - Decimal('3') - >>> ExtendedContext.max(Decimal('1.0'), Decimal('1')) - Decimal('1') - >>> ExtendedContext.max(Decimal('7'), Decimal('NaN')) - Decimal('7') - >>> ExtendedContext.max(1, 2) - Decimal('2') - >>> ExtendedContext.max(Decimal(1), 2) - Decimal('2') - >>> ExtendedContext.max(1, Decimal(2)) - Decimal('2') + >>> ExtendedContext.max(Decimal('3'), Decimal('2')) + Decimal('3') + >>> ExtendedContext.max(Decimal('-10'), Decimal('3')) + Decimal('3') + >>> ExtendedContext.max(Decimal('1.0'), Decimal('1')) + Decimal('1') + >>> ExtendedContext.max(Decimal('7'), Decimal('NaN')) + Decimal('7') + >>> ExtendedContext.max(1, 2) + Decimal('2') + >>> ExtendedContext.max(Decimal(1), 2) + Decimal('2') + >>> ExtendedContext.max(1, Decimal(2)) + Decimal('2') """ a = _convert_other(a, raiseit=True) return a.max(b, context=self) def max_mag(self, a, b): - """Compares the values numerically with their sign ignored. - - >>> ExtendedContext.max_mag(Decimal('7'), Decimal('NaN')) - Decimal('7') - >>> ExtendedContext.max_mag(Decimal('7'), Decimal('-10')) - Decimal('-10') - >>> ExtendedContext.max_mag(1, -2) - Decimal('-2') - >>> ExtendedContext.max_mag(Decimal(1), -2) - Decimal('-2') - >>> ExtendedContext.max_mag(1, Decimal(-2)) - Decimal('-2') + """Similar to the max() method, but the comparison is done using the absolute + values of the operands. + + >>> ExtendedContext.max_mag(Decimal('7'), Decimal('NaN')) + Decimal('7') + >>> ExtendedContext.max_mag(Decimal('7'), Decimal('-10')) + Decimal('-10') + >>> ExtendedContext.max_mag(1, -2) + Decimal('-2') + >>> ExtendedContext.max_mag(Decimal(1), -2) + Decimal('-2') + >>> ExtendedContext.max_mag(1, Decimal(-2)) + Decimal('-2') """ a = _convert_other(a, raiseit=True) return a.max_mag(b, context=self) def min(self, a, b): - """min compares two values numerically and returns the minimum. + """Compare two values numerically and return the minimum. If either operand is a NaN then the general rules apply. Otherwise, the operands are compared as though by the compare @@ -4805,20 +4974,20 @@ def min(self, a, b): is chosen as the result. Otherwise the minimum (closer to negative infinity) of the two operands is chosen as the result. - >>> ExtendedContext.min(Decimal('3'), Decimal('2')) - Decimal('2') - >>> ExtendedContext.min(Decimal('-10'), Decimal('3')) - Decimal('-10') - >>> ExtendedContext.min(Decimal('1.0'), Decimal('1')) - Decimal('1.0') - >>> ExtendedContext.min(Decimal('7'), Decimal('NaN')) - Decimal('7') - >>> ExtendedContext.min(1, 2) - Decimal('1') - >>> ExtendedContext.min(Decimal(1), 2) - Decimal('1') - >>> ExtendedContext.min(1, Decimal(29)) - Decimal('1') + >>> ExtendedContext.min(Decimal('3'), Decimal('2')) + Decimal('2') + >>> ExtendedContext.min(Decimal('-10'), Decimal('3')) + Decimal('-10') + >>> ExtendedContext.min(Decimal('1.0'), Decimal('1')) + Decimal('1.0') + >>> ExtendedContext.min(Decimal('7'), Decimal('NaN')) + Decimal('7') + >>> ExtendedContext.min(1, 2) + Decimal('1') + >>> ExtendedContext.min(Decimal(1), 2) + Decimal('1') + >>> ExtendedContext.min(1, Decimal(29)) + Decimal('1') """ a = _convert_other(a, raiseit=True) return a.min(b, context=self) @@ -4826,16 +4995,16 @@ def min(self, a, b): def min_mag(self, a, b): """Compares the values numerically with their sign ignored. - >>> ExtendedContext.min_mag(Decimal('3'), Decimal('-2')) - Decimal('-2') - >>> ExtendedContext.min_mag(Decimal('-3'), Decimal('NaN')) - Decimal('-3') - >>> ExtendedContext.min_mag(1, -2) - Decimal('1') - >>> ExtendedContext.min_mag(Decimal(1), -2) - Decimal('1') - >>> ExtendedContext.min_mag(1, Decimal(-2)) - Decimal('1') + >>> ExtendedContext.min_mag(Decimal('3'), Decimal('-2')) + Decimal('-2') + >>> ExtendedContext.min_mag(Decimal('-3'), Decimal('NaN')) + Decimal('-3') + >>> ExtendedContext.min_mag(1, -2) + Decimal('1') + >>> ExtendedContext.min_mag(Decimal(1), -2) + Decimal('1') + >>> ExtendedContext.min_mag(1, Decimal(-2)) + Decimal('1') """ a = _convert_other(a, raiseit=True) return a.min_mag(b, context=self) @@ -4890,27 +5059,29 @@ def multiply(self, a, b): return r def next_minus(self, a): - """Returns the largest representable number smaller than a. - - >>> c = ExtendedContext.copy() - >>> c.Emin = -999 - >>> c.Emax = 999 - >>> ExtendedContext.next_minus(Decimal('1')) - Decimal('0.999999999') - >>> c.next_minus(Decimal('1E-1007')) - Decimal('0E-1007') - >>> ExtendedContext.next_minus(Decimal('-1.00000003')) - Decimal('-1.00000004') - >>> c.next_minus(Decimal('Infinity')) - Decimal('9.99999999E+999') - >>> c.next_minus(1) - Decimal('0.999999999') + """Returns the largest representable number smaller than a.\n\ + + >>> c = ExtendedContext.copy() + >>> c.Emin = -999 + >>> c.Emax = 999 + >>> ExtendedContext.next_minus(Decimal('1')) + Decimal('0.999999999') + >>> c.next_minus(Decimal('1E-1007')) + Decimal('0E-1007') + >>> ExtendedContext.next_minus(Decimal('-1.00000003')) + Decimal('-1.00000004') + >>> c.next_minus(Decimal('Infinity')) + Decimal('9.99999999E+999') + >>> c.next_minus(1) + Decimal('0.999999999') """ a = _convert_other(a, raiseit=True) return a.next_minus(context=self) def next_plus(self, a): - """Returns the smallest representable number larger than a. + """Return the smallest number representable in the given context (or in the + current default context if no context is given) that is larger than the + given operand. >>> c = ExtendedContext.copy() >>> c.Emin = -999 @@ -4930,12 +5101,10 @@ def next_plus(self, a): return a.next_plus(context=self) def next_toward(self, a, b): - """Returns the number closest to a, in direction towards b. - - The result is the closest representable number from the first - operand (but not the first operand) that is in the direction - towards the second operand, unless the operands have the same - value. + """If the two operands are unequal, return the number closest to the first + operand in the direction of the second operand. If both operands are + numerically equal, return a copy of the first operand with the sign set + to be the same as the sign of the second operand. >>> c = ExtendedContext.copy() >>> c.Emin = -999 @@ -4965,10 +5134,11 @@ def next_toward(self, a, b): return a.next_toward(b, context=self) def normalize(self, a): - """normalize reduces an operand to its simplest form. - - Essentially a plus operation with all trailing zeros removed from the - result. + """Normalize the number by stripping the rightmost trailing zeros and + converting any result equal to Decimal('0') to Decimal('0e0'). Used + for producing canonical values for members of an equivalence class. + For example, Decimal('32.100') and Decimal('0.321000e+2') both normalize + to the equivalent value Decimal('32.1'). >>> ExtendedContext.normalize(Decimal('2.1')) Decimal('2.1') @@ -4989,7 +5159,8 @@ def normalize(self, a): return a.normalize(context=self) def number_class(self, a): - """Returns an indication of the class of the operand. + """Return a string describing the class of the operand. The returned value + is one of the following ten strings: The class is one of the following strings: -sNaN @@ -5194,7 +5365,8 @@ def quantize(self, a, b): return a.quantize(b, context=self) def radix(self): - """Just returns 10, as this is Decimal, :) + """Return Decimal(10), the radix (base) in which the Decimal class does + all its arithmetic. Included for compatibility with the specification. >>> ExtendedContext.radix() Decimal('10') @@ -5274,7 +5446,7 @@ def remainder_near(self, a, b): return a.remainder_near(b, context=self) def rotate(self, a, b): - """Returns a rotated copy of a, b times. + """Return a rotated copy of a, b times. The coefficient of the result is a rotated copy of the digits in the coefficient of the first operand. The number of places of @@ -5303,7 +5475,7 @@ def rotate(self, a, b): return a.rotate(b, context=self) def same_quantum(self, a, b): - """Returns True if the two operands have the same exponent. + """Return True if the two operands have the same exponent. The result is never affected by either the sign or the coefficient of either operand. @@ -5453,7 +5625,6 @@ def to_eng_string(self, a): '70' >>> ExtendedContext.to_eng_string(Decimal('0E+1')) '0.00E+3' - """ a = _convert_other(a, raiseit=True) return a.to_eng_string(context=self) diff --git a/Modules/_decimal/docstrings.h b/Modules/_decimal/docstrings.h index a1823cdd32b74c..af13e30a6beeb6 100644 --- a/Modules/_decimal/docstrings.h +++ b/Modules/_decimal/docstrings.h @@ -17,13 +17,114 @@ PyDoc_STRVAR(doc__decimal, -"C decimal arithmetic module"); +"This is an implementation of decimal floating point arithmetic based on\n\ +the General Decimal Arithmetic Specification:\n\ +\n\ + http://speleotrove.com/decimal/decarith.html\n\ +\n\ +and IEEE standard 854-1987:\n\ +\n\ + http://en.wikipedia.org/wiki/IEEE_854-1987\n\ +\n\ +Decimal floating point has finite precision with arbitrarily large bounds.\n\ +\n\ +The purpose of this module is to support arithmetic using familiar\n\ +\"schoolhouse\" rules and to avoid some of the tricky representation\n\ +issues associated with binary floating point. The package is especially\n\ +useful for financial applications or for contexts where users have\n\ +expectations that are at odds with binary floating point (for instance,\n\ +in binary floating point, 1.00 % 0.1 gives 0.09999999999999995 instead\n\ +of 0.0; Decimal('1.00') % Decimal('0.1') returns the expected\n\ +Decimal('0.00')).\n\ +\n\ +Here are some examples of using the decimal module:\n\ +\n\ + >>> from decimal import *\n\ + >>> setcontext(ExtendedContext)\n\ + >>> Decimal(0)\n\ + Decimal('0')\n\ + >>> Decimal('1')\n\ + Decimal('1')\n\ + >>> Decimal('-.0123')\n\ + Decimal('-0.0123')\n\ + >>> Decimal(123456)\n\ + Decimal('123456')\n\ + >>> Decimal('123.45e12345678')\n\ + Decimal('1.2345E+12345680')\n\ + >>> Decimal('1.33') + Decimal('1.27')\n\ + Decimal('2.60')\n\ + >>> Decimal('12.34') + Decimal('3.87') - Decimal('18.41')\n\ + Decimal('-2.20')\n\ + >>> dig = Decimal(1)\n\ + >>> print(dig / Decimal(3))\n\ + 0.333333333\n\ + >>> getcontext().prec = 18\n\ + >>> print(dig / Decimal(3))\n\ + 0.333333333333333333\n\ + >>> print(dig.sqrt())\n\ + 1\n\ + >>> print(Decimal(3).sqrt())\n\ + 1.73205080756887729\n\ + >>> print(Decimal(3) ** 123)\n\ + 4.85192780976896427E+58\n\ + >>> inf = Decimal(1) / Decimal(0)\n\ + >>> print(inf)\n\ + Infinity\n\ + >>> neginf = Decimal(-1) / Decimal(0)\n\ + >>> print(neginf)\n\ + -Infinity\n\ + >>> print(neginf + inf)\n\ + NaN\n\ + >>> print(neginf * inf)\n\ + -Infinity\n\ + >>> print(dig / 0)\n\ + Infinity\n\ + >>> getcontext().traps[DivisionByZero] = 1\n\ + >>> print(dig / 0)\n\ + Traceback (most recent call last):\n\ + ...\n\ + ...\n\ + ...\n\ + decimal.DivisionByZero: x / 0\n\ + >>> c = Context()\n\ + >>> c.traps[InvalidOperation] = 0\n\ + >>> print(c.flags[InvalidOperation])\n\ + 0\n\ + >>> c.divide(Decimal(0), Decimal(0))\n\ + Decimal('NaN')\n\ + >>> c.traps[InvalidOperation] = 1\n\ + >>> print(c.flags[InvalidOperation])\n\ + 1\n\ + >>> c.flags[InvalidOperation] = 0\n\ + >>> print(c.flags[InvalidOperation])\n\ + 0\n\ + >>> print(c.divide(Decimal(0), Decimal(0)))\n\ + Traceback (most recent call last):\n\ + ...\n\ + ...\n\ + ...\n\ + decimal.InvalidOperation: 0 / 0\n\ + >>> print(c.flags[InvalidOperation])\n\ + 1\n\ + >>> c.flags[InvalidOperation] = 0\n\ + >>> c.traps[InvalidOperation] = 0\n\ + >>> print(c.divide(Decimal(0), Decimal(0)))\n\ + NaN\n\ + >>> print(c.flags[InvalidOperation])\n\ + 1\n\ + >>>\n\ +\n"); PyDoc_STRVAR(doc_getcontext, "getcontext($module, /)\n--\n\n\ -Get the current default context.\n\ +Return this thread's context.\n\ +\n\ +If this thread does not yet have a context, returns\n\ +a new context and sets this thread's context.\n\ +New contexts are copies of DefaultContext.\n\ \n"); +/*This seems clearer than the python version*/ PyDoc_STRVAR(doc_setcontext, "setcontext($module, context, /)\n--\n\n\ Set a new default context.\n\ @@ -33,8 +134,73 @@ PyDoc_STRVAR(doc_localcontext, "localcontext($module, /, ctx=None, **kwargs)\n--\n\n\ Return a context manager that will set the default context to a copy of ctx\n\ on entry to the with-statement and restore the previous default context when\n\ -exiting the with-statement. If no context is specified, a copy of the current\n\ -default context is used.\n\ +exiting the with-statement.\n\ +\n\ +If no context is specified, a copy of the current default context is used.\n\ +The returned context manager creates a local decimal context\n\ +in a with statement:\n\ + def sin(x):\n\ + with localcontext() as ctx:\n\ + ctx.prec += 2\n\ + # Rest of sin calculation algorithm\n\ + # uses a precision 2 greater than normal\n\ + return +s # Convert result to normal precision\n\ +\n\ + def sin(x):\n\ + with localcontext(ExtendedContext):\n\ + # Rest of sin calculation algorithm\n\ + # uses the Extended Context from the\n\ + # General Decimal Arithmetic Specification\n\ + return +s # Convert result to normal context\n\ +\n\ + >>> setcontext(DefaultContext)\n\ + >>> print(getcontext().prec) # Return a context manager for a copy of the supplied context\n\ +\n\ +Uses a copy of the current context if no context is specified.\n\ +The returned context manager creates a local decimal context\n\ +in a with statement:\n\ + def sin(x):\n\ + with localcontext() as ctx:\n\ + ctx.prec += 2\n\ + # Rest of sin calculation algorithm\n\ + # uses a precision 2 greater than normal\n\ + return +s # Convert result to normal precision\n\ +\n\ + def sin(x):\n\ + with localcontext(ExtendedContext):\n\ + # Rest of sin calculation algorithm\n\ + # uses the Extended Context from the\n\ + # General Decimal Arithmetic Specification\n\ + return +s # Convert result to normal context\n\ +\n\ + >>> setcontext(DefaultContext)\n\ + >>> print(getcontext().prec)\n\ + 28\n\ + >>> with localcontext():\n\ + ... ctx = getcontext()\n\ + ... ctx.prec += 2\n\ + ... print(ctx.prec)\n\ + ...\n\ + 30\n\ + >>> with localcontext(ExtendedContext):\n\ + ... print(getcontext().prec)\n\ + ...\n\ + 9\n\ + >>> print(getcontext().prec)\n\ + 28\n\ + 28\n\ + >>> with localcontext():\n\ + ... ctx = getcontext()\n\ + ... ctx.prec += 2\n\ + ... print(ctx.prec)\n\ + ...\n\ + 30\n\ + >>> with localcontext(ExtendedContext):\n\ + ... print(getcontext().prec)\n\ + ...\n\ + 9\n\ + >>> print(getcontext().prec)\n\ + 28\n\ \n"); #ifdef EXTRA_FUNCTIONALITY @@ -54,82 +220,184 @@ DECIMAL32, DECIMAL64 and DECIMAL128 are provided.\n\ PyDoc_STRVAR(doc_decimal, "Decimal(value=\"0\", context=None)\n--\n\n\ -Construct a new Decimal object. 'value' can be an integer, string, tuple,\n\ -or another Decimal object. If no value is given, return Decimal('0'). The\n\ -context does not affect the conversion and is only passed to determine if\n\ -the InvalidOperation trap is active.\n\ +Construct a new Decimal object.\n\ +\n\ +'value' can be an integer, string, tuple, or another Decimal object. If no value\n\ +is given, return Decimal('0'). The context does not affect the conversion and\n\ +is only passed to determine if the InvalidOperation trap is active.\n\ +\n\ + >>> Decimal('3.14') # string input\n\ + Decimal('3.14')\n\ + >>> Decimal((0, (3, 1, 4), -2)) # tuple (sign, digit_tuple, exponent)\n\ + Decimal('3.14')\n\ + >>> Decimal(314) # int\n\ + Decimal('314')\n\ + >>> Decimal(Decimal(314)) # another decimal instance\n\ + Decimal('314')\n\ + >>> Decimal(' 3.14 \\\\n') # leading and trailing whitespace okay\n\ + Decimal('3.14')\n\ \n"); PyDoc_STRVAR(doc_adjusted, "adjusted($self, /)\n--\n\n\ -Return the adjusted exponent of the number. Defined as exp + digits - 1.\n\ +Return the adjusted exponent of the number.\n\ +\n\ +Defined as exp + digits - 1.\n\ \n"); PyDoc_STRVAR(doc_as_tuple, "as_tuple($self, /)\n--\n\n\ -Return a tuple representation of the number.\n\ +Represents the number as a triple tuple, to show the internals exactly as\n\ +they are.\n\ \n"); PyDoc_STRVAR(doc_as_integer_ratio, "as_integer_ratio($self, /)\n--\n\n\ -Decimal.as_integer_ratio() -> (int, int)\n\ +Express a finite Decimal instance in the form n / d.\n\ \n\ -Return a pair of integers, whose ratio is exactly equal to the original\n\ +Return a pair (n, d) of integers, whose ratio is exactly equal to the original\n\ Decimal and with a positive denominator. The ratio is in lowest terms.\n\ Raise OverflowError on infinities and a ValueError on NaNs.\n\ +\n\ + >>> Decimal('3.14').as_integer_ratio()\n\ + (157, 50)\n\ + >>> Decimal('-123e5').as_integer_ratio()\n\ + (-12300000, 1)\n\ + >>> Decimal('0.00').as_integer_ratio()\n\ + (0, 1)\n\ +\n\ \n"); PyDoc_STRVAR(doc_canonical, "canonical($self, /)\n--\n\n\ -Return the canonical encoding of the argument. Currently, the encoding\n\ -of a Decimal instance is always canonical, so this operation returns its\n\ -argument unchanged.\n\ +Returns the same Decimal object.\n\ +As we do not have different encodings for the same number, the received\n\ +object already is in its canonical form.\n\ +\n\ + >>> ExtendedContext.canonical(Decimal('2.50'))\n\ + Decimal('2.50')\n\ \n"); PyDoc_STRVAR(doc_compare, "compare($self, /, other, context=None)\n--\n\n\ -Compare self to other. Return a decimal value:\n\ +Compare values numerically.\n\ +\n\ +If the signs of the operands differ, a value representing each operand\n\ +('-1' if the operand is less than zero, '0' if the operand is zero or\n\ +negative zero, or '1' if the operand is greater than zero) is used in\n\ +place of that operand for the comparison instead of the actual\n\ +operand.\n\ +\n\ +The comparison is then effected by subtracting the second operand from\n\ +the first and then returning a value according to the result of the\n\ +subtraction: '-1' if the result is less than zero, '0' if the result is\n\ +zero or negative zero, or '1' if the result is greater than zero.\n\ \n\ a or b is a NaN ==> Decimal('NaN')\n\ a < b ==> Decimal('-1')\n\ a == b ==> Decimal('0')\n\ a > b ==> Decimal('1')\n\ +\n\ + >>> ExtendedContext.compare(Decimal('2.1'), Decimal('3'))\n\ + Decimal('-1')\n\ + >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.1'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.compare(Decimal('2.1'), Decimal('2.10'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.compare(Decimal('3'), Decimal('2.1'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.compare(Decimal('2.1'), Decimal('-3'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.compare(Decimal('-3'), Decimal('2.1'))\n\ + Decimal('-1')\n\ + >>> ExtendedContext.compare(1, 2)\n\ + Decimal('-1')\n\ + >>> ExtendedContext.compare(Decimal(1), 2)\n\ + Decimal('-1')\n\ + >>> ExtendedContext.compare(1, Decimal(2))\n\ + Decimal('-1')\n\ + >>> ExtendedContext.compare(Decimal('2'), Decimal('NaN'))\n\ + Decimal('NaN')\n\ \n"); PyDoc_STRVAR(doc_compare_signal, "compare_signal($self, /, other, context=None)\n--\n\n\ -Identical to compare, except that all NaNs signal.\n\ +Compares the values of the two operands numerically.\n\ +\n\ +It's pretty much like compare(), but all NaNs signal, with signaling\n\ +NaNs taking precedence over quiet NaNs.\n\ +\n\ +>>> ExtendedContext.compare_signal(Decimal('2.1'), Decimal('3'))\n\ +Decimal('-1')\n\ +>>> ExtendedContext.compare_signal(Decimal('2.1'), Decimal('2.1'))\n\ +Decimal('0')\n\ +>>> ExtendedContext.flags[InvalidOperation] = 0\n\ +>>> print(ExtendedContext.flags[InvalidOperation])\n\ +0\n\ +>>> ExtendedContext.compare_signal(Decimal('NaN'), Decimal('2.1'))\n\ +Decimal('NaN')\n\ +>>> print(ExtendedContext.flags[InvalidOperation])\n\ +1\n\ +>>> ExtendedContext.flags[InvalidOperation] = 0\n\ +>>> print(ExtendedContext.flags[InvalidOperation])\n\ +0\n\ +>>> ExtendedContext.compare_signal(Decimal('sNaN'), Decimal('2.1'))\n\ +Decimal('NaN')\n\ +>>> print(ExtendedContext.flags[InvalidOperation])\n\ +1\n\ +>>> ExtendedContext.compare_signal(-1, 2)\n\ +Decimal('-1')\n\ +>>> ExtendedContext.compare_signal(Decimal(-1), 2)\n\ +Decimal('-1')\n\ +>>> ExtendedContext.compare_signal(-1, Decimal(2))\n\ +Decimal('-1')\n\ \n"); PyDoc_STRVAR(doc_compare_total, "compare_total($self, /, other, context=None)\n--\n\n\ -Compare two operands using their abstract representation rather than\n\ -their numerical value. Similar to the compare() method, but the result\n\ -gives a total ordering on Decimal instances. Two Decimal instances with\n\ -the same numeric value but different representations compare unequal\n\ -in this ordering:\n\ +Compare two operands using their abstract representation rather\n\ +than their numerical value.\n\ \n\ - >>> Decimal('12.0').compare_total(Decimal('12'))\n\ - Decimal('-1')\n\ +Similar to the compare() method, but the result gives a total ordering\n\ +on Decimal instances.\n\ \n\ -Quiet and signaling NaNs are also included in the total ordering. The result\n\ -of this function is Decimal('0') if both operands have the same representation,\n\ -Decimal('-1') if the first operand is lower in the total order than the second,\n\ -and Decimal('1') if the first operand is higher in the total order than the\n\ -second operand. See the specification for details of the total order.\n\ +Quiet and signaling NaNs are also included in the total ordering.\n\ +The result of this function is Decimal('0') if both operands have the\n\ +same representation, Decimal('-1') if the first operand is lower in\n\ +the total order than the second, and Decimal('1') if the first\n\ +operand is higher in the total order than the second operand. See\n\ +the specification for details of the total order.\n\ \n\ -This operation is unaffected by context and is quiet: no flags are changed\n\ -and no rounding is performed. As an exception, the C version may raise\n\ -InvalidOperation if the second operand cannot be converted exactly.\n\ +This operation is unaffected by context and is quiet: no flags are\n\ +changed and no rounding is performed.\n\ +\n\ +>>> ExtendedContext.compare_total(Decimal('12.73'), Decimal('127.9'))\n\ +Decimal('-1')\n\ +>>> ExtendedContext.compare_total(Decimal('-127'), Decimal('12'))\n\ +Decimal('-1')\n\ +>>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.3'))\n\ +Decimal('-1')\n\ +>>> ExtendedContext.compare_total(Decimal('12.30'), Decimal('12.30'))\n\ +Decimal('0')\n\ +>>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('12.300'))\n\ +Decimal('1')\n\ +>>> ExtendedContext.compare_total(Decimal('12.3'), Decimal('NaN'))\n\ +Decimal('-1')\n\ +>>> ExtendedContext.compare_total(1, 2)\n\ +Decimal('-1')\n\ +>>> ExtendedContext.compare_total(Decimal(1), 2)\n\ +Decimal('-1')\n\ +>>> ExtendedContext.compare_total(1, Decimal(2))\n\ +Decimal('-1')\n\ \n"); PyDoc_STRVAR(doc_compare_total_mag, "compare_total_mag($self, /, other, context=None)\n--\n\n\ Compare two operands using their abstract representation rather than their\n\ -value as in compare_total(), but ignoring the sign of each operand.\n\ +numerical value and with their sign ignored.\n\ \n\ +Like compare_total, but with operand's sign ignored and assumed to be 0.\n\ x.compare_total_mag(y) is equivalent to x.copy_abs().compare_total(y.copy_abs()).\n\ -\n\ This operation is unaffected by context and is quiet: no flags are changed\n\ and no rounding is performed. As an exception, the C version may raise\n\ InvalidOperation if the second operand cannot be converted exactly.\n\ @@ -142,23 +410,52 @@ Return self.\n\ PyDoc_STRVAR(doc_copy_abs, "copy_abs($self, /)\n--\n\n\ -Return the absolute value of the argument. This operation is unaffected by\n\ -context and is quiet: no flags are changed and no rounding is performed.\n\ +Return the absolute value of the argument.\n\ +\n\ +This operation is unaffected by context and is quiet: no flags are changed\n\ +and no rounding is performed.\n\ +\n\ + >>> ExtendedContext.copy_abs(Decimal('2.1'))\n\ + Decimal('2.1')\n\ + >>> ExtendedContext.copy_abs(Decimal('-100'))\n\ + Decimal('100')\n\ + >>> ExtendedContext.copy_abs(-1)\n\ + Decimal('1')\n\ \n"); PyDoc_STRVAR(doc_copy_negate, "copy_negate($self, /)\n--\n\n\ -Return the negation of the argument. This operation is unaffected by context\n\ -and is quiet: no flags are changed and no rounding is performed.\n\ +Return a copy of the operand with the sign inverted.\n\ +\n\ +This operation is unaffected by context and is quiet: no flags are\n\ +changed and no rounding is performed.\n\ +\n\ + >>> ExtendedContext.copy_negate(Decimal('101.5'))\n\ + Decimal('-101.5')\n\ + >>> ExtendedContext.copy_negate(Decimal('-101.5'))\n\ + Decimal('101.5')\n\ + >>> ExtendedContext.copy_negate(1)\n\ + Decimal('-1')\n\ \n"); PyDoc_STRVAR(doc_copy_sign, "copy_sign($self, /, other, context=None)\n--\n\n\ -Return a copy of the first operand with the sign set to be the same as the\n\ -sign of the second operand. For example:\n\ +Return a copy of the first operand with the sign equal to the second operand.\n\ \n\ - >>> Decimal('2.3').copy_sign(Decimal('-1.5'))\n\ - Decimal('-2.3')\n\ + >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('7.33'))\n\ + Decimal('1.50')\n\ + >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('7.33'))\n\ + Decimal('1.50')\n\ + >>> ExtendedContext.copy_sign(Decimal( '1.50'), Decimal('-7.33'))\n\ + Decimal('-1.50')\n\ + >>> ExtendedContext.copy_sign(Decimal('-1.50'), Decimal('-7.33'))\n\ + Decimal('-1.50')\n\ + >>> ExtendedContext.copy_sign(1, -2)\n\ + Decimal('-1')\n\ + >>> ExtendedContext.copy_sign(Decimal(1), -2)\n\ + Decimal('-1')\n\ + >>> ExtendedContext.copy_sign(1, Decimal(-2))\n\ + Decimal('-1')\n\ \n\ This operation is unaffected by context and is quiet: no flags are changed\n\ and no rounding is performed. As an exception, the C version may raise\n\ @@ -167,9 +464,28 @@ InvalidOperation if the second operand cannot be converted exactly.\n\ PyDoc_STRVAR(doc_exp, "exp($self, /, context=None)\n--\n\n\ -Return the value of the (natural) exponential function e**x at the given\n\ -number. The function always uses the ROUND_HALF_EVEN mode and the result\n\ +Return the value of the (natural) exponential function e ** a.\n\ +\n\ +The function always uses the ROUND_HALF_EVEN mode and the result\n\ is correctly rounded.\n\ +\n\ + >>> c = ExtendedContext.copy()\n\ + >>> c.Emin = -999\n\ + >>> c.Emax = 999\n\ + >>> c.exp(Decimal('-Infinity'))\n\ + Decimal('0')\n\ + >>> c.exp(Decimal('-1'))\n\ + Decimal('0.367879441')\n\ + >>> c.exp(Decimal('0'))\n\ + Decimal('1')\n\ + >>> c.exp(Decimal('1'))\n\ + Decimal('2.71828183')\n\ + >>> c.exp(Decimal('0.693147181'))\n\ + Decimal('2.00000000')\n\ + >>> c.exp(Decimal('+Infinity'))\n\ + Decimal('Infinity')\n\ + >>> c.exp(10)\n\ + Decimal('22026.4658')\n\ \n"); PyDoc_STRVAR(doc_from_float, @@ -191,137 +507,443 @@ Decimal.from_float(0.1) is not the same as Decimal('0.1').\n\ PyDoc_STRVAR(doc_fma, "fma($self, /, other, third, context=None)\n--\n\n\ -Fused multiply-add. Return self*other+third with no rounding of the\n\ -intermediate product self*other.\n\ -\n\ - >>> Decimal(2).fma(3, 5)\n\ - Decimal('11')\n\ +Fused multiply-add. The first two operands are multiplied together,\n\ +using multiply, the third operand is then added to the result of that\n\ +multiplication, using add, all with only one final rounding.\n\ \n\ + >>> ExtendedContext.fma(Decimal('3'), Decimal('5'), Decimal('7'))\n\ + Decimal('22')\n\ + >>> ExtendedContext.fma(Decimal('3'), Decimal('-5'), Decimal('7'))\n\ + Decimal('-8')\n\ + >>> ExtendedContext.fma(Decimal('888565290'), Decimal('1557.96930'), Decimal('-86087.7578'))\n\ + Decimal('1.38435736E+12')\n\ + >>> ExtendedContext.fma(1, 3, 4)\n\ + Decimal('7')\n\ + >>> ExtendedContext.fma(1, Decimal(3), 4)\n\ + Decimal('7')\n\ + >>> ExtendedContext.fma(1, 3, Decimal(4))\n\ + Decimal('7')\n\ \n"); PyDoc_STRVAR(doc_is_canonical, "is_canonical($self, /)\n--\n\n\ -Return True if the argument is canonical and False otherwise. Currently,\n\ -a Decimal instance is always canonical, so this operation always returns\n\ -True.\n\ +Return True if the operand is canonical; otherwise return False.\n\ +Currently, the encoding of a Decimal instance is always\n\ +canonical, so this method returns True for any Decimal.\n\ +\n\ + >>> ExtendedContext.is_canonical(Decimal('2.50'))\n\ + True\n\ \n"); PyDoc_STRVAR(doc_is_finite, "is_finite($self, /)\n--\n\n\ -Return True if the argument is a finite number, and False if the argument\n\ -is infinite or a NaN.\n\ +Return True if the operand is finite; otherwise return False.\n\ +\n\ +A Decimal instance is considered finite if it is neither infinite nor a\n\ +NaN.\n\ +\n\ + >>> ExtendedContext.is_finite(Decimal('2.50'))\n\ + True\n\ + >>> ExtendedContext.is_finite(Decimal('-0.3'))\n\ + True\n\ + >>> ExtendedContext.is_finite(Decimal('0'))\n\ + True\n\ + >>> ExtendedContext.is_finite(Decimal('Inf'))\n\ + False\n\ + >>> ExtendedContext.is_finite(Decimal('NaN'))\n\ + False\n\ + >>> ExtendedContext.is_finite(1)\n\ + True\n\ \n"); PyDoc_STRVAR(doc_is_infinite, "is_infinite($self, /)\n--\n\n\ -Return True if the argument is either positive or negative infinity and\n\ -False otherwise.\n\ +Return True if the operand is infinite; otherwise return False.\n\ +\n\ + >>> ExtendedContext.is_infinite(Decimal('2.50'))\n\ + False\n\ + >>> ExtendedContext.is_infinite(Decimal('-Inf'))\n\ + True\n\ + >>> ExtendedContext.is_infinite(Decimal('NaN'))\n\ + False\n\ + >>> ExtendedContext.is_infinite(1)\n\ + False\n\ \n"); PyDoc_STRVAR(doc_is_nan, "is_nan($self, /)\n--\n\n\ -Return True if the argument is a (quiet or signaling) NaN and False\n\ -otherwise.\n\ +Return True if the operand is a (quiet or signaling) NaN or NaN;\n\ +otherwise return False.\n\ +\n\ + >>> ExtendedContext.is_nan(Decimal('2.50'))\n\ + False\n\ + >>> ExtendedContext.is_nan(Decimal('NaN'))\n\ + True\n\ + >>> ExtendedContext.is_nan(Decimal('-sNaN'))\n\ + True\n\ + >>> ExtendedContext.is_nan(1)\n\ + False\n\ \n"); PyDoc_STRVAR(doc_is_normal, "is_normal($self, /, context=None)\n--\n\n\ -Return True if the argument is a normal finite non-zero number with an\n\ -adjusted exponent greater than or equal to Emin. Return False if the\n\ -argument is zero, subnormal, infinite or a NaN.\n\ +Return True if the operand is a normal number; otherwise return False.\n\ +\n\ + >>> c = ExtendedContext.copy()\n\ + >>> c.Emin = -999\n\ + >>> c.Emax = 999\n\ + >>> c.is_normal(Decimal('2.50'))\n\ + True\n\ + >>> c.is_normal(Decimal('0.1E-999'))\n\ + False\n\ + >>> c.is_normal(Decimal('0.00'))\n\ + False\n\ + >>> c.is_normal(Decimal('-Inf'))\n\ + False\n\ + >>> c.is_normal(Decimal('NaN'))\n\ + False\n\ + >>> c.is_normal(1)\n\ + True\n\ \n"); PyDoc_STRVAR(doc_is_qnan, "is_qnan($self, /)\n--\n\n\ -Return True if the argument is a quiet NaN, and False otherwise.\n\ +Return True if the argument is a quiet NaN; otherwise return False.\n\ +\n\ + >>> ExtendedContext.is_qnan(Decimal('2.50'))\n\ + False\n\ + >>> ExtendedContext.is_qnan(Decimal('NaN'))\n\ + True\n\ + >>> ExtendedContext.is_qnan(Decimal('sNaN'))\n\ + False\n\ + >>> ExtendedContext.is_qnan(1)\n\ + False\n\ \n"); PyDoc_STRVAR(doc_is_signed, "is_signed($self, /)\n--\n\n\ Return True if the argument has a negative sign and False otherwise.\n\ +\n\ Note that both zeros and NaNs can carry signs.\n\ +\n\ + >>> ExtendedContext.is_signed(Decimal('2.50'))\n\ + False\n\ + >>> ExtendedContext.is_signed(Decimal('-12'))\n\ + True\n\ + >>> ExtendedContext.is_signed(Decimal('-0'))\n\ + True\n\ + >>> ExtendedContext.is_signed(8)\n\ + False\n\ + >>> ExtendedContext.is_signed(-8)\n\ + True\n\ \n"); PyDoc_STRVAR(doc_is_snan, "is_snan($self, /)\n--\n\n\ -Return True if the argument is a signaling NaN and False otherwise.\n\ +Return True if the operand is a signaling NaN; otherwise return False.\n\ +\n\ + >>> ExtendedContext.is_snan(Decimal('2.50'))\n\ + False\n\ + >>> ExtendedContext.is_snan(Decimal('NaN'))\n\ + False\n\ + >>> ExtendedContext.is_snan(Decimal('sNaN'))\n\ + True\n\ + >>> ExtendedContext.is_snan(1)\n\ + False\n\ \n"); PyDoc_STRVAR(doc_is_subnormal, "is_subnormal($self, /, context=None)\n--\n\n\ -Return True if the argument is subnormal, and False otherwise. A number is\n\ -subnormal if it is non-zero, finite, and has an adjusted exponent less\n\ -than Emin.\n\ +Return True if the argument is subnormal; otherwise return False.\n\ +\n\ +A number is subnormal if it is non-zero, finite, and has an adjusted\n\ +exponent less than Emin.\n\ +\n\ + >>> c = ExtendedContext.copy()\n\ + >>> c.Emin = -999\n\ + >>> c.Emax = 999\n\ + >>> c.is_subnormal(Decimal('2.50'))\n\ + False\n\ + >>> c.is_subnormal(Decimal('0.1E-999'))\n\ + True\n\ + >>> c.is_subnormal(Decimal('0.00'))\n\ + False\n\ + >>> c.is_subnormal(Decimal('-Inf'))\n\ + False\n\ + >>> c.is_subnormal(Decimal('NaN'))\n\ + False\n\ + >>> c.is_subnormal(1)\n\ + False\n\ \n"); PyDoc_STRVAR(doc_is_zero, "is_zero($self, /)\n--\n\n\ -Return True if the argument is a (positive or negative) zero and False\n\ -otherwise.\n\ +Return True if the operand is a zero; otherwise return False.\n\ +\n\ + >>> ExtendedContext.is_zero(Decimal('0'))\n\ + True\n\ + >>> ExtendedContext.is_zero(Decimal('2.50'))\n\ + False\n\ + >>> ExtendedContext.is_zero(Decimal('-0E+2'))\n\ + True\n\ + >>> ExtendedContext.is_zero(1)\n\ + False\n\ + >>> ExtendedContext.is_zero(0)\n\ + True\n\ \n"); PyDoc_STRVAR(doc_ln, "ln($self, /, context=None)\n--\n\n\ Return the natural (base e) logarithm of the operand. The function always\n\ uses the ROUND_HALF_EVEN mode and the result is correctly rounded.\n\ +\n\ + >>> c = ExtendedContext.copy()\n\ + >>> c.Emin = -999\n\ + >>> c.Emax = 999\n\ + >>> c.ln(Decimal('0'))\n\ + Decimal('-Infinity')\n\ + >>> c.ln(Decimal('1.000'))\n\ + Decimal('0')\n\ + >>> c.ln(Decimal('2.71828183'))\n\ + Decimal('1.00000000')\n\ + >>> c.ln(Decimal('10'))\n\ + Decimal('2.30258509')\n\ + >>> c.ln(Decimal('+Infinity'))\n\ + Decimal('Infinity')\n\ + >>> c.ln(1)\n\ + Decimal('0')\n\ \n"); PyDoc_STRVAR(doc_log10, "log10($self, /, context=None)\n--\n\n\ -Return the base ten logarithm of the operand. The function always uses the\n\ +Return the base 10 logarithm of the operand. The function always uses the\n\ ROUND_HALF_EVEN mode and the result is correctly rounded.\n\ +\n\ + >>> c = ExtendedContext.copy()\n\ + >>> c.Emin = -999\n\ + >>> c.Emax = 999\n\ + >>> c.log10(Decimal('0'))\n\ + Decimal('-Infinity')\n\ + >>> c.log10(Decimal('0.001'))\n\ + Decimal('-3')\n\ + >>> c.log10(Decimal('1.000'))\n\ + Decimal('0')\n\ + >>> c.log10(Decimal('2'))\n\ + Decimal('0.301029996')\n\ + >>> c.log10(Decimal('10'))\n\ + Decimal('1')\n\ + >>> c.log10(Decimal('70'))\n\ + Decimal('1.84509804')\n\ + >>> c.log10(Decimal('+Infinity'))\n\ + Decimal('Infinity')\n\ + >>> c.log10(0)\n\ + Decimal('-Infinity')\n\ + >>> c.log10(1)\n\ + Decimal('0')\n\ \n"); PyDoc_STRVAR(doc_logb, "logb($self, /, context=None)\n--\n\n\ -For a non-zero number, return the adjusted exponent of the operand as a\n\ -Decimal instance. If the operand is a zero, then Decimal('-Infinity') is\n\ -returned and the DivisionByZero condition is raised. If the operand is\n\ -an infinity then Decimal('Infinity') is returned.\n\ +Return the exponent of the magnitude of the operand's MSD.\n\ +\n\ +The result is the integer which is the exponent of the magnitude\n\ +of the most significant digit of the operand (as though the\n\ +operand were truncated to a single digit while maintaining the\n\ +value of that digit and without limiting the resulting exponent).\n\ +\n\ + >>> ExtendedContext.logb(Decimal('250'))\n\ + Decimal('2')\n\ + >>> ExtendedContext.logb(Decimal('2.50'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.logb(Decimal('0.03'))\n\ + Decimal('-2')\n\ + >>> ExtendedContext.logb(Decimal('0'))\n\ + Decimal('-Infinity')\n\ + >>> ExtendedContext.logb(1)\n\ + Decimal('0')\n\ + >>> ExtendedContext.logb(10)\n\ + Decimal('1')\n\ + >>> ExtendedContext.logb(100)\n\ + Decimal('2')\n\ \n"); PyDoc_STRVAR(doc_logical_and, "logical_and($self, /, other, context=None)\n--\n\n\ -Return the digit-wise 'and' of the two (logical) operands.\n\ +Apply the logical operation 'and' between each operand's digits.\n\ +\n\ +The operands must be both logical numbers.\n\ +\n\ + >>> ExtendedContext.logical_and(Decimal('0'), Decimal('0'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.logical_and(Decimal('0'), Decimal('1'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.logical_and(Decimal('1'), Decimal('0'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.logical_and(Decimal('1'), Decimal('1'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.logical_and(Decimal('1100'), Decimal('1010'))\n\ + Decimal('1000')\n\ + >>> ExtendedContext.logical_and(Decimal('1111'), Decimal('10'))\n\ + Decimal('10')\n\ + >>> ExtendedContext.logical_and(110, 1101)\n\ + Decimal('100')\n\ + >>> ExtendedContext.logical_and(Decimal(110), 1101)\n\ + Decimal('100')\n\ + >>> ExtendedContext.logical_and(110, Decimal(1101))\n\ + Decimal('100')\n\ \n"); PyDoc_STRVAR(doc_logical_invert, "logical_invert($self, /, context=None)\n--\n\n\ -Return the digit-wise inversion of the (logical) operand.\n\ +Invert all the digits in the operand.\n\ +\n\ +The operand must be a logical number.\n\ +\n\ + >>> ExtendedContext.logical_invert(Decimal('0'))\n\ + Decimal('111111111')\n\ + >>> ExtendedContext.logical_invert(Decimal('1'))\n\ + Decimal('111111110')\n\ + >>> ExtendedContext.logical_invert(Decimal('111111111'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.logical_invert(Decimal('101010101'))\n\ + Decimal('10101010')\n\ + >>> ExtendedContext.logical_invert(1101)\n\ + Decimal('111110010')\n\ \n"); PyDoc_STRVAR(doc_logical_or, "logical_or($self, /, other, context=None)\n--\n\n\ -Return the digit-wise 'or' of the two (logical) operands.\n\ +Apply the logical operation 'or' between each operand's digits.\n\ +The operands must be both logical numbers.\n\ +\n\ + >>> ExtendedContext.logical_or(Decimal('0'), Decimal('0'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.logical_or(Decimal('0'), Decimal('1'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.logical_or(Decimal('1'), Decimal('0'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.logical_or(Decimal('1'), Decimal('1'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.logical_or(Decimal('1100'), Decimal('1010'))\n\ + Decimal('1110')\n\ + >>> ExtendedContext.logical_or(Decimal('1110'), Decimal('10'))\n\ + Decimal('1110')\n\ + >>> ExtendedContext.logical_or(110, 1101)\n\ + Decimal('1111')\n\ + >>> ExtendedContext.logical_or(Decimal(110), 1101)\n\ + Decimal('1111')\n\ + >>> ExtendedContext.logical_or(110, Decimal(1101))\n\ + Decimal('1111')\n\ \n"); PyDoc_STRVAR(doc_logical_xor, "logical_xor($self, /, other, context=None)\n--\n\n\ -Return the digit-wise 'exclusive or' of the two (logical) operands.\n\ +Apply the logical operation 'xor' between each operand's digits.\n\ +\n\ +The operands must be both logical numbers.\n\ +\n\ + >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('0'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.logical_xor(Decimal('0'), Decimal('1'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('0'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.logical_xor(Decimal('1'), Decimal('1'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.logical_xor(Decimal('1100'), Decimal('1010'))\n\ + Decimal('110')\n\ + >>> ExtendedContext.logical_xor(Decimal('1111'), Decimal('10'))\n\ + Decimal('1101')\n\ + >>> ExtendedContext.logical_xor(110, 1101)\n\ + Decimal('1011')\n\ + >>> ExtendedContext.logical_xor(Decimal(110), 1101)\n\ + Decimal('1011')\n\ + >>> ExtendedContext.logical_xor(110, Decimal(1101))\n\ + Decimal('1011')\n\ \n"); PyDoc_STRVAR(doc_max, "max($self, /, other, context=None)\n--\n\n\ -Maximum of self and other. If one operand is a quiet NaN and the other is\n\ -numeric, the numeric operand is returned.\n\ +Compare two values numerically and return the maximum.\n\ +\n\ +If either operand is a NaN then the general rules apply.\n\ +Otherwise, the operands are compared as though by the compare\n\ +operation. If they are numerically equal then the left-hand operand\n\ +is chosen as the result. Otherwise the maximum (closer to positive\n\ +infinity) of the two operands is chosen as the result.\n\ +\n\ + >>> ExtendedContext.max(Decimal('3'), Decimal('2'))\n\ + Decimal('3')\n\ + >>> ExtendedContext.max(Decimal('-10'), Decimal('3'))\n\ + Decimal('3')\n\ + >>> ExtendedContext.max(Decimal('1.0'), Decimal('1'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.max(Decimal('7'), Decimal('NaN'))\n\ + Decimal('7')\n\ + >>> ExtendedContext.max(1, 2)\n\ + Decimal('2')\n\ + >>> ExtendedContext.max(Decimal(1), 2)\n\ + Decimal('2')\n\ + >>> ExtendedContext.max(1, Decimal(2))\n\ + Decimal('2')\n\ \n"); PyDoc_STRVAR(doc_max_mag, "max_mag($self, /, other, context=None)\n--\n\n\ Similar to the max() method, but the comparison is done using the absolute\n\ values of the operands.\n\ + >>> ExtendedContext.max_mag(Decimal('7'), Decimal('NaN'))\n\ + Decimal('7')\n\ + >>> ExtendedContext.max_mag(Decimal('7'), Decimal('-10'))\n\ + Decimal('-10')\n\ + >>> ExtendedContext.max_mag(1, -2)\n\ + Decimal('-2')\n\ + >>> ExtendedContext.max_mag(Decimal(1), -2)\n\ + Decimal('-2')\n\ + >>> ExtendedContext.max_mag(1, Decimal(-2))\n\ + Decimal('-2')\n\ \n"); PyDoc_STRVAR(doc_min, "min($self, /, other, context=None)\n--\n\n\ -Minimum of self and other. If one operand is a quiet NaN and the other is\n\ -numeric, the numeric operand is returned.\n\ +Compare two values numerically and return the minimum.\n\ +\n\ +If either operand is a NaN then the general rules apply.\n\ +Otherwise, the operands are compared as though by the compare\n\ +operation. If they are numerically equal then the left-hand operand\n\ +is chosen as the result. Otherwise the minimum (closer to negative\n\ +infinity) of the two operands is chosen as the result.\n\ +\n\ + >>> ExtendedContext.min(Decimal('3'), Decimal('2'))\n\ + Decimal('2')\n\ + >>> ExtendedContext.min(Decimal('-10'), Decimal('3'))\n\ + Decimal('-10')\n\ + >>> ExtendedContext.min(Decimal('1.0'), Decimal('1'))\n\ + Decimal('1.0')\n\ + >>> ExtendedContext.min(Decimal('7'), Decimal('NaN'))\n\ + Decimal('7')\n\ + >>> ExtendedContext.min(1, 2)\n\ + Decimal('1')\n\ + >>> ExtendedContext.min(Decimal(1), 2)\n\ + Decimal('1')\n\ + >>> ExtendedContext.min(1, Decimal(29))\n\ + Decimal('1')\n\ \n"); PyDoc_STRVAR(doc_min_mag, "min_mag($self, /, other, context=None)\n--\n\n\ -Similar to the min() method, but the comparison is done using the absolute\n\ -values of the operands.\n\ +Compare the values numerically with their sign ignored.\n\ +\n\ + >>> ExtendedContext.min_mag(Decimal('3'), Decimal('-2'))\n\ + Decimal('-2')\n\ + >>> ExtendedContext.min_mag(Decimal('-3'), Decimal('NaN'))\n\ + Decimal('-3')\n\ + >>> ExtendedContext.min_mag(1, -2)\n\ + Decimal('1')\n\ + >>> ExtendedContext.min_mag(Decimal(1), -2)\n\ + Decimal('1')\n\ + >>> ExtendedContext.min_mag(1, Decimal(-2))\n\ + Decimal('1')\n\ \n"); PyDoc_STRVAR(doc_next_minus, @@ -329,6 +951,20 @@ PyDoc_STRVAR(doc_next_minus, Return the largest number representable in the given context (or in the\n\ current default context if no context is given) that is smaller than the\n\ given operand.\n\ +\n\ + >>> c = ExtendedContext.copy()\n\ + >>> c.Emin = -999\n\ + >>> c.Emax = 999\n\ + >>> ExtendedContext.next_minus(Decimal('1'))\n\ + Decimal('0.999999999')\n\ + >>> c.next_minus(Decimal('1E-1007'))\n\ + Decimal('0E-1007')\n\ + >>> ExtendedContext.next_minus(Decimal('-1.00000003'))\n\ + Decimal('-1.00000004')\n\ + >>> c.next_minus(Decimal('Infinity'))\n\ + Decimal('9.99999999E+999')\n\ + >>> c.next_minus(1)\n\ + Decimal('0.999999999')\n\ \n"); PyDoc_STRVAR(doc_next_plus, @@ -336,6 +972,20 @@ PyDoc_STRVAR(doc_next_plus, Return the smallest number representable in the given context (or in the\n\ current default context if no context is given) that is larger than the\n\ given operand.\n\ +\n\ + >>> c = ExtendedContext.copy()\n\ + >>> c.Emin = -999\n\ + >>> c.Emax = 999\n\ + >>> ExtendedContext.next_plus(Decimal('1'))\n\ + Decimal('1.00000001')\n\ + >>> c.next_plus(Decimal('-1E-1007'))\n\ + Decimal('-0E-1007')\n\ + >>> ExtendedContext.next_plus(Decimal('-1.00000003'))\n\ + Decimal('-1.00000002')\n\ + >>> c.next_plus(Decimal('-Infinity'))\n\ + Decimal('-9.99999999E+999')\n\ + >>> c.next_plus(1)\n\ + Decimal('1.00000001')\n\ \n"); PyDoc_STRVAR(doc_next_toward, @@ -344,6 +994,30 @@ If the two operands are unequal, return the number closest to the first\n\ operand in the direction of the second operand. If both operands are\n\ numerically equal, return a copy of the first operand with the sign set\n\ to be the same as the sign of the second operand.\n\ +\n\ + >>> c = ExtendedContext.copy()\n\ + >>> c.Emin = -999\n\ + >>> c.Emax = 999\n\ + >>> c.next_toward(Decimal('1'), Decimal('2'))\n\ + Decimal('1.00000001')\n\ + >>> c.next_toward(Decimal('-1E-1007'), Decimal('1'))\n\ + Decimal('-0E-1007')\n\ + >>> c.next_toward(Decimal('-1.00000003'), Decimal('0'))\n\ + Decimal('-1.00000002')\n\ + >>> c.next_toward(Decimal('1'), Decimal('0'))\n\ + Decimal('0.999999999')\n\ + >>> c.next_toward(Decimal('1E-1007'), Decimal('-100'))\n\ + Decimal('0E-1007')\n\ + >>> c.next_toward(Decimal('-1.00000003'), Decimal('-10'))\n\ + Decimal('-1.00000004')\n\ + >>> c.next_toward(Decimal('0.00'), Decimal('-0.0000'))\n\ + Decimal('-0.00')\n\ + >>> c.next_toward(0, 1)\n\ + Decimal('1E-1007')\n\ + >>> c.next_toward(Decimal(0), 1)\n\ + Decimal('1E-1007')\n\ + >>> c.next_toward(0, Decimal(1))\n\ + Decimal('1E-1007')\n\ \n"); PyDoc_STRVAR(doc_normalize, @@ -353,6 +1027,21 @@ converting any result equal to Decimal('0') to Decimal('0e0'). Used\n\ for producing canonical values for members of an equivalence class.\n\ For example, Decimal('32.100') and Decimal('0.321000e+2') both normalize\n\ to the equivalent value Decimal('32.1').\n\ +\n\ + >>> ExtendedContext.normalize(Decimal('2.1'))\n\ + Decimal('2.1')\n\ + >>> ExtendedContext.normalize(Decimal('-2.0'))\n\ + Decimal('-2')\n\ + >>> ExtendedContext.normalize(Decimal('1.200'))\n\ + Decimal('1.2')\n\ + >>> ExtendedContext.normalize(Decimal('-120'))\n\ + Decimal('-1.2E+2')\n\ + >>> ExtendedContext.normalize(Decimal('120.00'))\n\ + Decimal('1.2E+2')\n\ + >>> ExtendedContext.normalize(Decimal('0.00'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.normalize(6)\n\ + Decimal('6')\n\ \n"); PyDoc_STRVAR(doc_number_class, @@ -371,100 +1060,292 @@ is one of the following ten strings:\n\ * 'NaN', indicating that the operand is a quiet NaN (Not a Number).\n\ * 'sNaN', indicating that the operand is a signaling NaN.\n\ \n\ + >>> c = ExtendedContext.copy()\n\ + >>> c.Emin = -999\n\ + >>> c.Emax = 999\n\ + >>> c.number_class(Decimal('Infinity'))\n\ + '+Infinity'\n\ + >>> c.number_class(Decimal('1E-10'))\n\ + '+Normal'\n\ + >>> c.number_class(Decimal('2.50'))\n\ + '+Normal'\n\ + >>> c.number_class(Decimal('0.1E-999'))\n\ + '+Subnormal'\n\ + >>> c.number_class(Decimal('0'))\n\ + '+Zero'\n\ + >>> c.number_class(Decimal('-0'))\n\ + '-Zero'\n\ + >>> c.number_class(Decimal('-0.1E-999'))\n\ + '-Subnormal'\n\ + >>> c.number_class(Decimal('-1E-10'))\n\ + '-Normal'\n\ + >>> c.number_class(Decimal('-2.50'))\n\ + '-Normal'\n\ + >>> c.number_class(Decimal('-Infinity'))\n\ + '-Infinity'\n\ + >>> c.number_class(Decimal('NaN'))\n\ + 'NaN'\n\ + >>> c.number_class(Decimal('-NaN'))\n\ + 'NaN'\n\ + >>> c.number_class(Decimal('sNaN'))\n\ + 'sNaN'\n\ + >>> c.number_class(123)\n\ + '+Normal'\n\ \n"); PyDoc_STRVAR(doc_quantize, "quantize($self, /, exp, rounding=None, context=None)\n--\n\n\ -Return a value equal to the first operand after rounding and having the\n\ -exponent of the second operand.\n\ -\n\ - >>> Decimal('1.41421356').quantize(Decimal('1.000'))\n\ - Decimal('1.414')\n\ +Return a value equal to 'a' (rounded), having the exponent of 'b'.\n\ \n\ -Unlike other operations, if the length of the coefficient after the quantize\n\ -operation would be greater than precision, then an InvalidOperation is signaled.\n\ -This guarantees that, unless there is an error condition, the quantized exponent\n\ -is always equal to that of the right-hand operand.\n\ +Similar to self._rescale(exp._exp) but with error checking.The\n\ +coefficient of the result is derived from that of the left-hand operand.\n\ +It may be rounded using the current rounding setting (if the exponent is\n\ +being increased), multiplied by a positive power of ten (if the exponent\n\ +is being decreased), or is unchanged (if the exponent is\n\ +already equal to that of the right-hand operand).\n\ \n\ -Also unlike other operations, quantize never signals Underflow, even if the\n\ -result is subnormal and inexact.\n\ +Unlike other operations, if the length of the coefficient after the\n\ +quantize operation would be greater than precision then an Invalid\n\ +operation condition is raised. This guarantees that, unless there is\n\ +an error condition, the exponent of the result of a quantize is always\n\ +equal to that of the right-hand operand.\n\ +Also unlike other operations, quantize will never raise Underflow, even\n\ +if the result is subnormal and inexact.\n\ \n\ -If the exponent of the second operand is larger than that of the first, then\n\ -rounding may be necessary. In this case, the rounding mode is determined by the\n\ -rounding argument if given, else by the given context argument; if neither\n\ -argument is given, the rounding mode of the current thread's context is used.\n\ + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))\n\ + Decimal('2.170')\n\ + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))\n\ + Decimal('2.17')\n\ + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))\n\ + Decimal('2.2')\n\ + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))\n\ + Decimal('2')\n\ + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))\n\ + Decimal('0E+1')\n\ + >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))\n\ + Decimal('-Infinity')\n\ + >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))\n\ + Decimal('NaN')\n\ + >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))\n\ + Decimal('-0')\n\ + >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))\n\ + Decimal('-0E+5')\n\ + >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))\n\ + Decimal('NaN')\n\ + >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))\n\ + Decimal('NaN') + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))\n\ + Decimal('217.0')\n\ + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))\n\ + Decimal('217')\n\ + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))\n\ + Decimal('2.2E+2')\n\ + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))\n\ + Decimal('2E+2')\n\ + >>> ExtendedContext.quantize(1, 2)\n\ + Decimal('1')\n\ + >>> ExtendedContext.quantize(Decimal(1), 2)\n\ + Decimal('1')\n\ + >>> ExtendedContext.quantize(1, Decimal(2))\n\ + Decimal('1')\n\ \n"); PyDoc_STRVAR(doc_radix, "radix($self, /)\n--\n\n\ Return Decimal(10), the radix (base) in which the Decimal class does\n\ all its arithmetic. Included for compatibility with the specification.\n\ +\n\ + >>> ExtendedContext.radix()\n\ + Decimal('10')\n\ \n"); PyDoc_STRVAR(doc_remainder_near, "remainder_near($self, /, other, context=None)\n--\n\n\ -Return the remainder from dividing self by other. This differs from\n\ -self % other in that the sign of the remainder is chosen so as to minimize\n\ -its absolute value. More precisely, the return value is self - n * other\n\ -where n is the integer nearest to the exact value of self / other, and\n\ -if two integers are equally near then the even one is chosen.\n\ +Returns to be \"a - b * n\", where n is the integer nearest the exact\n\ +value of \"x / b\" (if two integers are equally near then the even one\n\ +is chosen). If the result is equal to 0 then its sign will be the\n\ +sign of a.\n\ \n\ -If the result is zero then its sign will be the sign of self.\n\ +This operation will fail under the same conditions as integer division\n\ +(that is, if integer division on the same two operands would fail, the\n\ +remainder cannot be calculated).\n\ +\n\ + >>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))\n\ + Decimal('-0.9')\n\ + >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))\n\ + Decimal('-2')\n\ + >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))\n\ + Decimal('-1')\n\ + >>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))\n\ + Decimal('0.2')\n\ + >>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))\n\ + Decimal('0.1')\n\ + >>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))\n\ + Decimal('-0.3')\n\ + >>> ExtendedContext.remainder_near(3, 11)\n\ + Decimal('3')\n\ + >>> ExtendedContext.remainder_near(Decimal(3), 11)\n\ + Decimal('3')\n\ + >>> ExtendedContext.remainder_near(3, Decimal(11))\n\ + Decimal('3')\n\ \n"); PyDoc_STRVAR(doc_rotate, "rotate($self, /, other, context=None)\n--\n\n\ -Return the result of rotating the digits of the first operand by an amount\n\ -specified by the second operand. The second operand must be an integer in\n\ -the range -precision through precision. The absolute value of the second\n\ -operand gives the number of places to rotate. If the second operand is\n\ -positive then rotation is to the left; otherwise rotation is to the right.\n\ -The coefficient of the first operand is padded on the left with zeros to\n\ -length precision if necessary. The sign and exponent of the first operand are\n\ -unchanged.\n\ +Return a rotated copy of a, b times.\n\ +\n\ +The coefficient of the result is a rotated copy of the digits in\n\ +the coefficient of the first operand. The number of places of\n\ +rotation is taken from the absolute value of the second operand,\n\ +with the rotation being to the left if the second operand is\n\ +positive or to the right otherwise.\n\ +\n\ + >>> ExtendedContext.rotate(Decimal('34'), Decimal('8'))\n\ + Decimal('400000003')\n\ + >>> ExtendedContext.rotate(Decimal('12'), Decimal('9'))\n\ + Decimal('12')\n\ + >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('-2'))\n\ + Decimal('891234567')\n\ + >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('0'))\n\ + Decimal('123456789')\n\ + >>> ExtendedContext.rotate(Decimal('123456789'), Decimal('+2'))\n\ + Decimal('345678912')\n\ + >>> ExtendedContext.rotate(1333333, 1)\n\ + Decimal('13333330')\n\ + >>> ExtendedContext.rotate(Decimal(1333333), 1)\n\ + Decimal('13333330')\n\ + >>> ExtendedContext.rotate(1333333, Decimal(1))\n\ + Decimal('13333330')\n\ \n"); PyDoc_STRVAR(doc_same_quantum, "same_quantum($self, /, other, context=None)\n--\n\n\ -Test whether self and other have the same exponent or whether both are NaN.\n\ +Return True if the two operands have the same exponent.\n\ \n\ -This operation is unaffected by context and is quiet: no flags are changed\n\ -and no rounding is performed. As an exception, the C version may raise\n\ -InvalidOperation if the second operand cannot be converted exactly.\n\ +The result is never affected by either the sign or the coefficient of\n\ +either operand.\n\ +\n\ + >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))\n\ + False\n\ + >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))\n\ + True\n\ + >>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))\n\ + False\n\ + >>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))\n\ + True\n\ + >>> ExtendedContext.same_quantum(10000, -1)\n\ + True\n\ + >>> ExtendedContext.same_quantum(Decimal(10000), -1)\n\ + True\n\ + >>> ExtendedContext.same_quantum(10000, Decimal(-1))\n\ + True\n\ \n"); PyDoc_STRVAR(doc_scaleb, "scaleb($self, /, other, context=None)\n--\n\n\ -Return the first operand with the exponent adjusted the second. Equivalently,\n\ -return the first operand multiplied by 10**other. The second operand must be\n\ -an integer.\n\ +Return the first operand after adding the second value its exp.\n\ +\n\ + >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('-2'))\n\ + Decimal('0.0750')\n\ + >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('0'))\n\ + Decimal('7.50')\n\ + >>> ExtendedContext.scaleb(Decimal('7.50'), Decimal('3'))\n\ + Decimal('7.50E+3')\n\ + >>> ExtendedContext.scaleb(1, 4)\n\ + Decimal('1E+4')\n\ + >>> ExtendedContext.scaleb(Decimal(1), 4)\n\ + Decimal('1E+4')\n\ + >>> ExtendedContext.scaleb(1, Decimal(4))\n\ + Decimal('1E+4')\n\ \n"); PyDoc_STRVAR(doc_shift, "shift($self, /, other, context=None)\n--\n\n\ -Return the result of shifting the digits of the first operand by an amount\n\ -specified by the second operand. The second operand must be an integer in\n\ -the range -precision through precision. The absolute value of the second\n\ -operand gives the number of places to shift. If the second operand is\n\ -positive, then the shift is to the left; otherwise the shift is to the\n\ -right. Digits shifted into the coefficient are zeros. The sign and exponent\n\ -of the first operand are unchanged.\n\ +Return a shifted copy of a, b times.\n\ +\n\ +The coefficient of the result is a shifted copy of the digits\n\ +in the coefficient of the first operand. The number of places\n\ +to shift is taken from the absolute value of the second operand,\n\ +with the shift being to the left if the second operand is\n\ +positive or to the right otherwise. Digits shifted into the\n\ +coefficient are zeros.\n\ +\n\ + >>> ExtendedContext.shift(Decimal('34'), Decimal('8'))\n\ + Decimal('400000000')\n\ + >>> ExtendedContext.shift(Decimal('12'), Decimal('9'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.shift(Decimal('123456789'), Decimal('-2'))\n\ + Decimal('1234567')\n\ + >>> ExtendedContext.shift(Decimal('123456789'), Decimal('0'))\n\ + Decimal('123456789')\n\ + >>> ExtendedContext.shift(Decimal('123456789'), Decimal('+2'))\n\ + Decimal('345678900')\n\ + >>> ExtendedContext.shift(88888888, 2)\n\ + Decimal('888888800')\n\ + >>> ExtendedContext.shift(Decimal(88888888), 2)\n\ + Decimal('888888800')\n\ + >>> ExtendedContext.shift(88888888, Decimal(2))\n\ + Decimal('888888800')\n\ \n"); PyDoc_STRVAR(doc_sqrt, "sqrt($self, /, context=None)\n--\n\n\ -Return the square root of the argument to full precision. The result is\n\ -correctly rounded using the ROUND_HALF_EVEN rounding mode.\n\ +Square root of a non-negative number to context precision.\n\ +\n\ +If the result must be inexact, it is rounded using the round-half-even\n\ +algorithm.\n\ +\n\ + >>> ExtendedContext.sqrt(Decimal('0'))\n\ + Decimal('0')\n\ + >>> ExtendedContext.sqrt(Decimal('-0'))\n\ + Decimal('-0')\n\ + >>> ExtendedContext.sqrt(Decimal('0.39'))\n\ + Decimal('0.624499800')\n\ + >>> ExtendedContext.sqrt(Decimal('100'))\n\ + Decimal('10')\n\ + >>> ExtendedContext.sqrt(Decimal('1'))\n\ + Decimal('1')\n\ + >>> ExtendedContext.sqrt(Decimal('1.0'))\n\ + Decimal('1.0')\n\ + >>> ExtendedContext.sqrt(Decimal('1.00'))\n\ + Decimal('1.0')\n\ + >>> ExtendedContext.sqrt(Decimal('7'))\n\ + Decimal('2.64575131')\n\ + >>> ExtendedContext.sqrt(Decimal('10'))\n\ + Decimal('3.16227766')\n\ + >>> ExtendedContext.sqrt(2)\n\ + Decimal('1.41421356')\n\ + >>> ExtendedContext.prec\n\ + 9\n\ \n"); PyDoc_STRVAR(doc_to_eng_string, "to_eng_string($self, /, context=None)\n--\n\n\ -Convert to an engineering-type string. Engineering notation has an exponent\n\ -which is a multiple of 3, so there are up to 3 digits left of the decimal\n\ -place. For example, Decimal('123E+1') is converted to Decimal('1.23E+3').\n\ +Convert to a string, using engineering notation if an exponent is needed.\n\ +\n\ +Engineering notation has an exponent which is a multiple of 3. This\n\ +can leave up to 3 digits to the left of the decimal place and may\n\ +require the addition of either one or two trailing zeros.\n\ \n\ The value of context.capitals determines whether the exponent sign is lower\n\ or upper case. Otherwise, the context does not affect the operation.\n\ +\n\ + >>> ExtendedContext.to_eng_string(Decimal('123E+1'))\n\ + '1.23E+3'\n\ + >>> ExtendedContext.to_eng_string(Decimal('123E+3'))\n\ + '123E+3'\n\ + >>> ExtendedContext.to_eng_string(Decimal('123E-10'))\n\ + '12.3E-9'\n\ + >>> ExtendedContext.to_eng_string(Decimal('-123E-12'))\n\ + '-123E-12'\n\ + >>> ExtendedContext.to_eng_string(Decimal('7E-7'))\n\ + '700E-9'\n\ + >>> ExtendedContext.to_eng_string(Decimal('7E+1'))\n\ + '70'\n\ + >>> ExtendedContext.to_eng_string(Decimal('0E+1'))\n\ + '0.00E+3'\n\ \n"); PyDoc_STRVAR(doc_to_integral, @@ -475,18 +1356,59 @@ kept for compatibility with older versions.\n\ PyDoc_STRVAR(doc_to_integral_exact, "to_integral_exact($self, /, rounding=None, context=None)\n--\n\n\ -Round to the nearest integer, signaling Inexact or Rounded as appropriate if\n\ -rounding occurs. The rounding mode is determined by the rounding parameter\n\ -if given, else by the given context. If neither parameter is given, then the\n\ -rounding mode of the current default context is used.\n\ +Round to an integer.\n\ +\n\ +When the operand has a negative exponent, the result is the same\n\ +as using the quantize() operation using the given operand as the\n\ +left-hand-operand, 1E+0 as the right-hand-operand, and the precision\n\ +of the operand as the precision setting; Inexact and Rounded flags\n\ +are allowed in this operation. The rounding mode is taken from the\n\ +context.\n\ +\n\ + >>> ExtendedContext.to_integral_exact(Decimal('2.1'))\n\ + Decimal('2')\n\ + >>> ExtendedContext.to_integral_exact(Decimal('100'))\n\ + Decimal('100')\n\ + >>> ExtendedContext.to_integral_exact(Decimal('100.0'))\n\ + Decimal('100')\n\ + >>> ExtendedContext.to_integral_exact(Decimal('101.5'))\n\ + Decimal('102')\n\ + >>> ExtendedContext.to_integral_exact(Decimal('-101.5'))\n\ + Decimal('-102')\n\ + >>> ExtendedContext.to_integral_exact(Decimal('10E+5'))\n\ + Decimal('1.0E+6')\n\ + >>> ExtendedContext.to_integral_exact(Decimal('7.89E+77'))\n\ + Decimal('7.89E+77')\n\ + >>> ExtendedContext.to_integral_exact(Decimal('-Inf'))\n\ + Decimal('-Infinity')\n\ \n"); PyDoc_STRVAR(doc_to_integral_value, "to_integral_value($self, /, rounding=None, context=None)\n--\n\n\ -Round to the nearest integer without signaling Inexact or Rounded. The\n\ -rounding mode is determined by the rounding parameter if given, else by\n\ -the given context. If neither parameter is given, then the rounding mode\n\ -of the current default context is used.\n\ +Round to an integer.\n\ +\n\ +When the operand has a negative exponent, the result is the same\n\ +as using the quantize() operation using the given operand as the\n\ +left-hand-operand, 1E+0 as the right-hand-operand, and the precision\n\ +of the operand as the precision setting, except that no flags will\n\ +be set. The rounding mode is taken from the context.\n\ +\n\ + >>> ExtendedContext.to_integral_value(Decimal('2.1'))\n\ + Decimal('2')\n\ + >>> ExtendedContext.to_integral_value(Decimal('100'))\n\ + Decimal('100')\n\ + >>> ExtendedContext.to_integral_value(Decimal('100.0'))\n\ + Decimal('100')\n\ + >>> ExtendedContext.to_integral_value(Decimal('101.5'))\n\ + Decimal('102')\n\ + >>> ExtendedContext.to_integral_value(Decimal('-101.5'))\n\ + Decimal('-102')\n\ + >>> ExtendedContext.to_integral_value(Decimal('10E+5'))\n\ + Decimal('1.0E+6')\n\ + >>> ExtendedContext.to_integral_value(Decimal('7.89E+77'))\n\ + Decimal('7.89E+77')\n\ + >>> ExtendedContext.to_integral_value(Decimal('-Inf'))\n\ + Decimal('-Infinity')\n\ \n"); @@ -596,8 +1518,8 @@ Compare x and y using their abstract representation, ignoring sign.\n\ \n"); PyDoc_STRVAR(doc_ctx_copy_abs, -"copy_abs($self, x, /)\n--\n\n\ -Return a copy of x with the sign set to 0.\n\ +"copy_abs($self, a, /)\n--\n\n\ +Return a copy of a with the sign set to 0.\n\ \n"); PyDoc_STRVAR(doc_ctx_copy_negate, @@ -801,8 +1723,59 @@ hold:\n\ \n"); PyDoc_STRVAR(doc_ctx_quantize, -"quantize($self, x, y, /)\n--\n\n\ -Return a value equal to x (rounded), having the exponent of y.\n\ +"quantize($self, a, b, /)\n--\n\n\ +Return a value equal to 'a' (rounded), having the exponent of 'b'.\n\ +\n\ +The coefficient of the result is derived from that of the left-hand\n\ +operand. It may be rounded using the current rounding setting (if the\n\ +exponent is being increased), multiplied by a positive power of ten (if\n\ +the exponent is being decreased), or is unchanged (if the exponent is\n\ +already equal to that of the right-hand operand).\n\ +\n\ +Unlike other operations, if the length of the coefficient after the\n\ +quantize operation would be greater than precision then an Invalid\n\ +operation condition is raised. This guarantees that, unless there is\n\ +an error condition, the exponent of the result of a quantize is always\n\ +equal to that of the right-hand operand.\n\ +Also unlike other operations, quantize will never raise Underflow, even\n\ +if the result is subnormal and inexact.\n\ +\n\ + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.001'))\n\ + Decimal('2.170')\n\ + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.01'))\n\ + Decimal('2.17')\n\ + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('0.1'))\n\ + Decimal('2.2')\n\ + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+0'))\n\ + Decimal('2')\n\ + >>> ExtendedContext.quantize(Decimal('2.17'), Decimal('1e+1'))\n\ + Decimal('0E+1')\n\ + >>> ExtendedContext.quantize(Decimal('-Inf'), Decimal('Infinity'))\n\ + Decimal('-Infinity')\n\ + >>> ExtendedContext.quantize(Decimal('2'), Decimal('Infinity'))\n\ + Decimal('NaN')\n\ + >>> ExtendedContext.quantize(Decimal('-0.1'), Decimal('1'))\n\ + Decimal('-0')\n\ + >>> ExtendedContext.quantize(Decimal('-0'), Decimal('1e+5'))\n\ + Decimal('-0E+5')\n\ + >>> ExtendedContext.quantize(Decimal('+35236450.6'), Decimal('1e-2'))\n\ + Decimal('NaN')\n\ + >>> ExtendedContext.quantize(Decimal('-35236450.6'), Decimal('1e-2'))\n\ + Decimal('NaN')\n\ + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-1'))\n\ + Decimal('217.0')\n\ + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e-0'))\n\ + Decimal('217')\n\ + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+1'))\n\ + Decimal('2.2E+2')\n\ + >>> ExtendedContext.quantize(Decimal('217'), Decimal('1e+2'))\n\ + Decimal('2E+2')\n\ + >>> ExtendedContext.quantize(1, 2)\n\ + Decimal('1')\n\ + >>> ExtendedContext.quantize(Decimal(1), 2)\n\ + Decimal('1')\n\ + >>> ExtendedContext.quantize(1, Decimal(2))\n\ + Decimal('1')\n\ \n"); PyDoc_STRVAR(doc_ctx_radix, @@ -879,6 +1852,3 @@ Convert a number to a string using scientific notation.\n\ #endif /* DOCSTRINGS_H */ - - -