5.6.2 Decimal objects

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