5.6.2 Decimal objects

Python PEP

previous page next page

5.6.2 Decimal objects

class Decimal( [value [, context]])

Constructs a new Decimal object based from value.

value can be an integer, string, tuple, or another Decimal object. If no value is given, returns Decimal("0"). If value is a string, it should conform to the decimal numeric string syntax:

    sign           ::=  '+' | '-'
    digit          ::=  '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
    indicator      ::=  'e' | 'E'
    digits         ::=  digit [digit]...
    decimal-part   ::=  digits '.' [digits] | ['.'] digits
    exponent-part  ::=  indicator [sign] digits
    infinity       ::=  'Infinity' | 'Inf'
    nan            ::=  'NaN' [digits] | 'sNaN' [digits]
    numeric-value  ::=  decimal-part [exponent-part] | infinity
    numeric-string ::=  [sign] numeric-value | [sign] nan

If value is a tuple, it should have three components, a sign (0 for positive or 1 for negative), a tuple of digits, and an integer exponent. For example, "Decimal((0, (1, 4, 1, 4), -3))" returns Decimal("1.414").

The context precision does not affect how many digits are stored. That is determined exclusively by the number of digits in value. For example, "Decimal("3.00000")" records all five zeroes even if the context precision is only three.

The purpose of the context argument is determining what to do if value is a malformed string. If the context traps InvalidOperation, an exception is raised; otherwise, the constructor returns a new Decimal with the value of NaN.

Once constructed, Decimal objects are immutable.

Decimal floating point objects share many properties with the other builtin numeric types such as float and int. All of the usual math operations and special methods apply. Likewise, decimal objects can be copied, pickled, printed, used as dictionary keys, used as set elements, compared, sorted, and coerced to another type (such as float or long).

In addition to the standard numeric properties, decimal floating point objects also have a number of specialized methods:

adjusted( ): Return the adjusted exponent after shifting out the coefficient's rightmost digits until only the lead digit remains: Decimal("321e+5").adjusted() returns seven. Used for determining the position of the most significant digit with respect to the decimal point.

as_tuple( ): Returns a tuple representation of the number: "(sign, digittuple, exponent)".

compare( other[, context])

Compares like __cmp__() but returns a decimal instance:

        a or b is a NaN ==> Decimal("NaN")
        a < b           ==> Decimal("-1")
        a == b          ==> Decimal("0")
        a > b           ==> Decimal("1")

max( other[, context]): Like "max(self, other)" except that the context rounding rule is applied before returning and that NaN values are either signalled or ignored (depending on the context and whether they are signaling or quiet).

min( other[, context]): Like "min(self, other)" except that the context rounding rule is applied before returning and that NaN values are either signalled or ignored (depending on the context and whether they are signaling or quiet).

normalize( [context]): Normalize the number by stripping the rightmost trailing zeroes 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").

quantize( exp [, rounding[, context[, watchexp]]]): Quantize makes the exponent the same as exp. Searches for a rounding method in rounding, then in context, and then in the current context.
If watchexp is set (default), then an error is returned whenever the resulting exponent is greater than Emax or less than Etiny.

remainder_near( other[, context]): Computes the modulo as either a positive or negative value depending on which is closest to zero. For instance, "Decimal(10).remainder_near(6)" returns Decimal("-2") which is closer to zero than Decimal("4").
If both are equally close, the one chosen will have the same sign as self.

same_quantum( other[, context]): Test whether self and other have the same exponent or whether both are NaN.

sqrt( [context]): Return the square root to full precision.

to_eng_string( [context]): Convert to an engineering-type string.
Engineering notation has an exponent which is a multiple of 3, so there are up to 3 digits left of the decimal place. For example, converts Decimal('123E+1') to Decimal("1.23E+3")

to_integral( [rounding[, context]]): Rounds to the nearest integer without signaling Inexact or Rounded. If given, applies rounding; otherwise, uses the rounding method in either the supplied context or the current context.

See About this document... for information on suggesting changes.

previous page start next page