##
5.6.8 Decimal FAQ

Q. It is cumbersome to type `decimal.Decimal('1234.5')`. Is there a way to minimize typing when using the interactive interpreter?

A. Some users abbreviate the constructor to just a single letter:

    >>> D = decimal.Decimal
    >>> D('1.23') + D('3.45')
    Decimal("4.68")

Q. In a fixed-point application with two decimal places, some inputs have many places and need to be rounded. Others are not supposed to have excess digits and need to be validated. What methods should be used?

A. The `quantize()` method rounds to a fixed number of decimal places. If the `Inexact` trap is set, it is also useful for validation:

    >>> TWOPLACES = Decimal(10) ** -2       # same as Decimal('0.01')

    >>> # Round to two places
    >>> Decimal("3.214").quantize(TWOPLACES)
    Decimal("3.21")

    >>> # Validate that a number does not exceed two places
    >>> Decimal("3.21").quantize(TWOPLACES, context=Context(traps=[Inexact]))
    Decimal("3.21")

    >>> Decimal("3.214").quantize(TWOPLACES, context=Context(traps=[Inexact]))
    Traceback (most recent call last):
       ...
    Inexact: Changed in rounding

Q. Once I have valid two place inputs, how do I maintain that invariant throughout an application?

A. Some operations like addition and subtraction automatically preserve fixed point. Others, like multiplication and division, change the number of decimal places and need to be followed-up with a `quantize()` step.

Q. There are many ways to express the same value. The numbers `200`, `200.000`, `2E2`, and `.02E+4` all have the same value at various precisions. Is there a way to transform them to a single recognizable canonical value?

A. The `normalize()` method maps all equivalent values to a single representive:

    >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
    >>> [v.normalize() for v in values]
    [Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")]

Q. Some decimal values always print with exponential notation. Is there a way to get a non-exponential representation?

A. For some values, exponential notation is the only way to express the number of significant places in the coefficient. For example, expressing `5.0E+3` as `5000` keeps the value constant but cannot show the original's two-place significance.

Q. Is there a way to convert a regular float to a `Decimal`?

A. Yes, all binary floating point numbers can be exactly expressed as a Decimal. An exact conversion may take more precision than intuition would suggest, so trapping `Inexact` will signal a need for more precision:

    def floatToDecimal(f):
        "Convert a floating point number to a Decimal with no loss of information"
        # Transform (exactly) a float to a mantissa (0.5 <= abs(m) < 1.0) and an
        # exponent.  Double the mantissa until it is an integer.  Use the integer
        # mantissa and exponent to compute an equivalent Decimal.  If this cannot
        # be done exactly, then retry with more precision.

        mantissa, exponent = math.frexp(f)
        while mantissa != int(mantissa):
            mantissa *= 2.0
            exponent -= 1
        mantissa = int(mantissa)

        oldcontext = getcontext()
        setcontext(Context(traps=[Inexact]))
        try:
            while True:
                try:
                   return mantissa * Decimal(2) ** exponent
                except Inexact:
                    getcontext().prec += 1
        finally:
            setcontext(oldcontext)

Q. Why isn't the `floatToDecimal()` routine included in the module?

A. There is some question about whether it is advisable to mix binary and decimal floating point. Also, its use requires some care to avoid the representation issues associated with binary floating point:

    >>> floatToDecimal(1.1)
    Decimal("1.100000000000000088817841970012523233890533447265625")

Q. Within a complex calculation, how can I make sure that I haven't gotten a spurious result because of insufficient precision or rounding anomalies.

A. The decimal module makes it easy to test results. A best practice is to re-run calculations using greater precision and with various rounding modes. Widely differing results indicate insufficient precision, rounding mode issues, ill-conditioned inputs, or a numerically unstable algorithm.

Q. I noticed that context precision is applied to the results of operations but not to the inputs. Is there anything to watch out for when mixing values of different precisions?

A. Yes. The principle is that all values are considered to be exact and so is the arithmetic on those values. Only the results are rounded. The advantage for inputs is that ``what you type is what you get''. A disadvantage is that the results can look odd if you forget that the inputs haven't been rounded:

    >>> getcontext().prec = 3
    >>> Decimal('3.104') + D('2.104')
    Decimal("5.21")
    >>> Decimal('3.104') + D('0.000') + D('2.104')
    Decimal("5.20")

The solution is either to increase precision or to force rounding of inputs using the unary plus operation:

    >>> getcontext().prec = 3
    >>> +Decimal('1.23456789')      # unary plus triggers rounding
    Decimal("1.23")

Alternatively, inputs can be rounded upon creation using the `Context.create_decimal()` method:

    >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
    Decimal("1.2345")