Module decimal :: Class Context
[hide private]
[frames] | no frames]

type Context

object --+
         |
        Context

Contains the context for a Decimal instance.

Contains:
prec - precision (for use in rounding, division, square roots..)
rounding - rounding type. (how you round)
_rounding_decision - ALWAYS_ROUND, NEVER_ROUND -- do you round?
traps - If traps[exception] = 1, then the exception is
                raised when it is caused.  Otherwise, a value is
                substituted in.
flags  - When an exception is caused, flags[exception] is incremented.
         (Whether or not the trap_enabler is set)
         Should be reset by user of Decimal instance.
Emin -   Minimum exponent
Emax -   Maximum exponent
capitals -      If 1, 1*10^1 is printed as 1E+1.
                If 0, printed as 1e1
_clamp - If 1, change exponents if too high (Default 0)

Instance Methods [hide private]
 
__init__(self, prec=None, rounding=None, traps=None, flags=None, _rounding_decision=None, Emin=None, Emax=None, capitals=None, _clamp=0, _ignored_flags=None)
 
__repr__(self)
Show the current context.
 
clear_flags(self)
Reset all flags to zero
 
_shallow_copy(self)
Returns a shallow copy from self.
 
copy(self)
Returns a deep copy from self.
 
__copy__(self)
Returns a deep copy from self.
 
_raise_error(self, condition, explanation=None, *args)
Handles an error
 
_ignore_all_flags(self)
Ignore all flags, if they are raised
 
_ignore_flags(self, *flags)
Ignore the flags, if they are raised
 
_regard_flags(self, *flags)
Stop ignoring the flags, if they are raised
 
__hash__(self)
A Context cannot be hashed.
 
Etiny(self)
Returns Etiny (= Emin - prec + 1)
 
Etop(self)
Returns maximum exponent (= Emax - prec + 1)
 
_set_rounding_decision(self, type)
Sets the rounding decision.
 
_set_rounding(self, type)
Sets the rounding type.
 
create_decimal(self, num='0')
Creates a new Decimal instance but using self as context.
 
abs(self, a)
Returns the absolute value of the operand.
 
add(self, a, b)
Return the sum of the two operands.
 
_apply(self, a)
 
compare(self, a, b)
Compares values numerically.
 
divide(self, a, b)
Decimal division in a specified context.
 
divide_int(self, a, b)
Divides two numbers and returns the integer part of the result.
 
divmod(self, a, b)
 
max(self, a, b)
max compares two values numerically and returns the maximum.
 
min(self, a, b)
min compares two values numerically and returns the minimum.
 
minus(self, a)
Minus corresponds to unary prefix minus in Python.
 
multiply(self, a, b)
multiply multiplies two operands.
 
normalize(self, a)
normalize reduces an operand to its simplest form.
 
plus(self, a)
Plus corresponds to unary prefix plus in Python.
 
power(self, a, b, modulo=None)
Raises a to the power of b, to modulo if given.
 
quantize(self, a, b)
Returns a value equal to 'a' (rounded) and having the exponent of 'b'.
 
remainder(self, a, b)
Returns the remainder from integer division.
 
remainder_near(self, a, b)
Returns to be "a - b * n", where n is the integer nearest the exact value of "x / b" (if two integers are equally near then the even one is chosen).
 
same_quantum(self, a, b)
Returns True if the two operands have the same exponent.
 
sqrt(self, a)
Returns the square root of a non-negative number to context precision.
 
subtract(self, a, b)
Return the difference between the two operands.
 
to_eng_string(self, a)
Converts a number to a string, using scientific notation.
 
to_sci_string(self, a)
Converts a number to a string, using scientific notation.
 
to_integral(self, a)
Rounds to an integer.
Method Details [hide private]

__init__(self, prec=None, rounding=None, traps=None, flags=None, _rounding_decision=None, Emin=None, Emax=None, capitals=None, _clamp=0, _ignored_flags=None)
(Constructor)

 
Overrides: object.__init__
(inherited documentation)

__repr__(self)
(Representation operator)

 

Show the current context.

Overrides: object.__repr__

_raise_error(self, condition, explanation=None, *args)

 

Handles an error

If the flag is in _ignored_flags, returns the default response. Otherwise, it increments the flag, then, if the corresponding trap_enabler is set, it reaises the exception. Otherwise, it returns the default value after incrementing the flag.

__hash__(self)
(Hashing function)

 

A Context cannot be hashed.

Overrides: object.__hash__

_set_rounding_decision(self, type)

 

Sets the rounding decision.

Sets the rounding decision, and returns the current (previous) rounding decision. Often used like:

context = context._shallow_copy() # That so you don't change the calling context # if an error occurs in the middle (say DivisionImpossible is raised).

rounding = context._set_rounding_decision(NEVER_ROUND) instance = instance / Decimal(2) context._set_rounding_decision(rounding)

This will make it not round for that operation.

_set_rounding(self, type)

 

Sets the rounding type.

Sets the rounding type, and returns the current (previous) rounding type. Often used like:

context = context.copy() # so you don't change the calling context # if an error occurs in the middle. rounding = context._set_rounding(ROUND_UP) val = self.__sub__(other, context=context) context._set_rounding(rounding)

This will make it round up for that operation.

abs(self, a)

 

Returns the absolute value of the operand.

If the operand is negative, the result is the same as using the minus operation on the operand. Otherwise, the result is the same as using the plus operation on the operand.

>>> ExtendedContext.abs(Decimal('2.1'))
Decimal("2.1")
>>> ExtendedContext.abs(Decimal('-100'))
Decimal("100")
>>> ExtendedContext.abs(Decimal('101.5'))
Decimal("101.5")
>>> ExtendedContext.abs(Decimal('-101.5'))
Decimal("101.5")

add(self, a, b)

 

Return the sum of the two operands.

>>> ExtendedContext.add(Decimal('12'), Decimal('7.00'))
Decimal("19.00")
>>> ExtendedContext.add(Decimal('1E+2'), Decimal('1.01E+4'))
Decimal("1.02E+4")

compare(self, a, b)

 

Compares values numerically.

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.

>>> 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")

divide(self, a, b)

 

Decimal division in a specified context.

>>> ExtendedContext.divide(Decimal('1'), Decimal('3'))
Decimal("0.333333333")
>>> ExtendedContext.divide(Decimal('2'), Decimal('3'))
Decimal("0.666666667")
>>> ExtendedContext.divide(Decimal('5'), Decimal('2'))
Decimal("2.5")
>>> ExtendedContext.divide(Decimal('1'), Decimal('10'))
Decimal("0.1")
>>> ExtendedContext.divide(Decimal('12'), Decimal('12'))
Decimal("1")
>>> ExtendedContext.divide(Decimal('8.00'), Decimal('2'))
Decimal("4.00")
>>> ExtendedContext.divide(Decimal('2.400'), Decimal('2.0'))
Decimal("1.20")
>>> ExtendedContext.divide(Decimal('1000'), Decimal('100'))
Decimal("10")
>>> ExtendedContext.divide(Decimal('1000'), Decimal('1'))
Decimal("1000")
>>> ExtendedContext.divide(Decimal('2.40E+6'), Decimal('2'))
Decimal("1.20E+6")

divide_int(self, a, b)

 

Divides two numbers and returns the integer part of the result.

>>> ExtendedContext.divide_int(Decimal('2'), Decimal('3'))
Decimal("0")
>>> ExtendedContext.divide_int(Decimal('10'), Decimal('3'))
Decimal("3")
>>> ExtendedContext.divide_int(Decimal('1'), Decimal('0.3'))
Decimal("3")

max(self, a, b)

 

max compares two values numerically and returns the maximum.

If either operand is a NaN then the general rules apply. Otherwise, the operands are compared as as though by the compare operation. If they are numerically equal then the left-hand operand 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")

min(self, a, b)

 

min compares two values numerically and returns the minimum.

If either operand is a NaN then the general rules apply. Otherwise, the operands are compared as as though by the compare operation. If they are numerically equal then the left-hand operand 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")

minus(self, a)

 

Minus corresponds to unary prefix minus in Python.

The operation is evaluated using the same rules as subtract; the operation minus(a) is calculated as subtract('0', a) where the '0' has the same exponent as the operand.

>>> ExtendedContext.minus(Decimal('1.3'))
Decimal("-1.3")
>>> ExtendedContext.minus(Decimal('-1.3'))
Decimal("1.3")

multiply(self, a, b)

 

multiply multiplies two operands.

If either operand is a special value then the general rules apply. Otherwise, the operands are multiplied together ('long multiplication'), resulting in a number which may be as long as the sum of the lengths of the two operands.

>>> ExtendedContext.multiply(Decimal('1.20'), Decimal('3'))
Decimal("3.60")
>>> ExtendedContext.multiply(Decimal('7'), Decimal('3'))
Decimal("21")
>>> ExtendedContext.multiply(Decimal('0.9'), Decimal('0.8'))
Decimal("0.72")
>>> ExtendedContext.multiply(Decimal('0.9'), Decimal('-0'))
Decimal("-0.0")
>>> ExtendedContext.multiply(Decimal('654321'), Decimal('654321'))
Decimal("4.28135971E+11")

normalize(self, a)

 

normalize reduces an operand to its simplest form.

Essentially a plus operation with all trailing zeros removed from the result.

>>> ExtendedContext.normalize(Decimal('2.1'))
Decimal("2.1")
>>> ExtendedContext.normalize(Decimal('-2.0'))
Decimal("-2")
>>> ExtendedContext.normalize(Decimal('1.200'))
Decimal("1.2")
>>> ExtendedContext.normalize(Decimal('-120'))
Decimal("-1.2E+2")
>>> ExtendedContext.normalize(Decimal('120.00'))
Decimal("1.2E+2")
>>> ExtendedContext.normalize(Decimal('0.00'))
Decimal("0")

plus(self, a)

 

Plus corresponds to unary prefix plus in Python.

The operation is evaluated using the same rules as add; the operation plus(a) is calculated as add('0', a) where the '0' has the same exponent as the operand.

>>> ExtendedContext.plus(Decimal('1.3'))
Decimal("1.3")
>>> ExtendedContext.plus(Decimal('-1.3'))
Decimal("-1.3")

power(self, a, b, modulo=None)

 

Raises a to the power of b, to modulo if given.

The right-hand operand must be a whole number whose integer part (after any exponent has been applied) has no more than 9 digits and whose fractional part (if any) is all zeros before any rounding. The operand may be positive, negative, or zero; if negative, the absolute value of the power is used, and the left-hand operand is inverted (divided into 1) before use.

If the increased precision needed for the intermediate calculations exceeds the capabilities of the implementation then an Invalid operation condition is raised.

If, when raising to a negative power, an underflow occurs during the division into 1, the operation is not halted at that point but continues.

>>> ExtendedContext.power(Decimal('2'), Decimal('3'))
Decimal("8")
>>> ExtendedContext.power(Decimal('2'), Decimal('-3'))
Decimal("0.125")
>>> ExtendedContext.power(Decimal('1.7'), Decimal('8'))
Decimal("69.7575744")
>>> ExtendedContext.power(Decimal('Infinity'), Decimal('-2'))
Decimal("0")
>>> ExtendedContext.power(Decimal('Infinity'), Decimal('-1'))
Decimal("0")
>>> ExtendedContext.power(Decimal('Infinity'), Decimal('0'))
Decimal("1")
>>> ExtendedContext.power(Decimal('Infinity'), Decimal('1'))
Decimal("Infinity")
>>> ExtendedContext.power(Decimal('Infinity'), Decimal('2'))
Decimal("Infinity")
>>> ExtendedContext.power(Decimal('-Infinity'), Decimal('-2'))
Decimal("0")
>>> ExtendedContext.power(Decimal('-Infinity'), Decimal('-1'))
Decimal("-0")
>>> ExtendedContext.power(Decimal('-Infinity'), Decimal('0'))
Decimal("1")
>>> ExtendedContext.power(Decimal('-Infinity'), Decimal('1'))
Decimal("-Infinity")
>>> ExtendedContext.power(Decimal('-Infinity'), Decimal('2'))
Decimal("Infinity")
>>> ExtendedContext.power(Decimal('0'), Decimal('0'))
Decimal("NaN")

quantize(self, a, b)

 

Returns a value equal to 'a' (rounded) and having the exponent of 'b'.

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).

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")

remainder(self, a, b)

 

Returns the remainder from integer division.

The result is the residue of the dividend after the operation of calculating integer division as described for divide-integer, rounded to precision digits if necessary. The sign of the result, if non-zero, is the same as that of the original dividend.

This operation will fail under the same conditions as integer division (that is, if integer division on the same two operands would fail, the remainder cannot be calculated).

>>> ExtendedContext.remainder(Decimal('2.1'), Decimal('3'))
Decimal("2.1")
>>> ExtendedContext.remainder(Decimal('10'), Decimal('3'))
Decimal("1")
>>> ExtendedContext.remainder(Decimal('-10'), Decimal('3'))
Decimal("-1")
>>> ExtendedContext.remainder(Decimal('10.2'), Decimal('1'))
Decimal("0.2")
>>> ExtendedContext.remainder(Decimal('10'), Decimal('0.3'))
Decimal("0.1")
>>> ExtendedContext.remainder(Decimal('3.6'), Decimal('1.3'))
Decimal("1.0")

remainder_near(self, a, b)

 

Returns to be "a - b * n", where n is the integer nearest the exact value of "x / b" (if two integers are equally near then the even one is chosen). If the result is equal to 0 then its sign will be the sign of a.

This operation will fail under the same conditions as integer division (that is, if integer division on the same two operands would fail, the remainder cannot be calculated).

>>> ExtendedContext.remainder_near(Decimal('2.1'), Decimal('3'))
Decimal("-0.9")
>>> ExtendedContext.remainder_near(Decimal('10'), Decimal('6'))
Decimal("-2")
>>> ExtendedContext.remainder_near(Decimal('10'), Decimal('3'))
Decimal("1")
>>> ExtendedContext.remainder_near(Decimal('-10'), Decimal('3'))
Decimal("-1")
>>> ExtendedContext.remainder_near(Decimal('10.2'), Decimal('1'))
Decimal("0.2")
>>> ExtendedContext.remainder_near(Decimal('10'), Decimal('0.3'))
Decimal("0.1")
>>> ExtendedContext.remainder_near(Decimal('3.6'), Decimal('1.3'))
Decimal("-0.3")

same_quantum(self, a, b)

 

Returns True if the two operands have the same exponent.

The result is never affected by either the sign or the coefficient of either operand.

>>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.001'))
False
>>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('0.01'))
True
>>> ExtendedContext.same_quantum(Decimal('2.17'), Decimal('1'))
False
>>> ExtendedContext.same_quantum(Decimal('Inf'), Decimal('-Inf'))
True

sqrt(self, a)

 

Returns the square root of a non-negative number to context precision.

If the result must be inexact, it is rounded using the round-half-even algorithm.

>>> ExtendedContext.sqrt(Decimal('0'))
Decimal("0")
>>> ExtendedContext.sqrt(Decimal('-0'))
Decimal("-0")
>>> ExtendedContext.sqrt(Decimal('0.39'))
Decimal("0.624499800")
>>> ExtendedContext.sqrt(Decimal('100'))
Decimal("10")
>>> ExtendedContext.sqrt(Decimal('1'))
Decimal("1")
>>> ExtendedContext.sqrt(Decimal('1.0'))
Decimal("1.0")
>>> ExtendedContext.sqrt(Decimal('1.00'))
Decimal("1.0")
>>> ExtendedContext.sqrt(Decimal('7'))
Decimal("2.64575131")
>>> ExtendedContext.sqrt(Decimal('10'))
Decimal("3.16227766")
>>> ExtendedContext.prec
9

subtract(self, a, b)

 

Return the difference between the two operands.

>>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.07'))
Decimal("0.23")
>>> ExtendedContext.subtract(Decimal('1.3'), Decimal('1.30'))
Decimal("0.00")
>>> ExtendedContext.subtract(Decimal('1.3'), Decimal('2.07'))
Decimal("-0.77")

to_eng_string(self, a)

 

Converts a number to a string, using scientific notation.

The operation is not affected by the context.

to_sci_string(self, a)

 

Converts a number to a string, using scientific notation.

The operation is not affected by the context.

to_integral(self, a)

 

Rounds to an integer.

When the operand has a negative exponent, the result is the same as using the quantize() operation using the given operand as the left-hand-operand, 1E+0 as the right-hand-operand, and the precision of the operand as the precision setting, except that no flags will be set. The rounding mode is taken from the context.

>>> ExtendedContext.to_integral(Decimal('2.1'))
Decimal("2")
>>> ExtendedContext.to_integral(Decimal('100'))
Decimal("100")
>>> ExtendedContext.to_integral(Decimal('100.0'))
Decimal("100")
>>> ExtendedContext.to_integral(Decimal('101.5'))
Decimal("102")
>>> ExtendedContext.to_integral(Decimal('-101.5'))
Decimal("-102")
>>> ExtendedContext.to_integral(Decimal('10E+5'))
Decimal("1.0E+6")
>>> ExtendedContext.to_integral(Decimal('7.89E+77'))
Decimal("7.89E+77")
>>> ExtendedContext.to_integral(Decimal('-Inf'))
Decimal("-Infinity")