From 48688d8c8e15fa5cef253e047af96e79a3463cf6 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Mon, 11 Feb 2008 22:53:01 +0000 Subject: [PATCH] Add notes on how decimal fits into the model. --- Lib/numbers.py | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/Lib/numbers.py b/Lib/numbers.py index cbcecedeca1..4728f99a590 100644 --- a/Lib/numbers.py +++ b/Lib/numbers.py @@ -49,6 +49,35 @@ Inexact.register(float) # Inexact.register(decimal.Decimal) +## Notes on Decimal and how relates to the numeric tower +## ----------------------------------------------------- +## Decimal is Real except that it does not support the real and imag properties +## or the conjugate() and complex() methods. If those get defined at some +## point, they cannot use the default implementation which would be sensitive +## to decimal.Context and could produce different answers at different times. +## +## Decimal has some of the characteristics of Integrals. It provides +## logical operations but not as operators. The logical operations only apply +## to a subset of decimals (those that are non-negative, have a zero exponent, +## and have digits that are only 0 or 1). It does provide __long__() and +## a three argument form of __pow__ that includes exactness guarantees. +## It does not provide an __index__() method. +## +## Depending on context, decimal operations may be exact or inexact. +## +## When decimal is run in a context with small precision and automatic rounding, +## it is Inexact. See the "Floating point notes" section of the decimal docs +## for an example of losing the associative and distributive properties of +## addition. +## +## When decimal is used for high precision integer arithmetic, it is Exact. +## When the decimal used as fixed-point, it is Exact. +## When it is run with sufficient precision, it is Exact. +## When the decimal.Inexact trap is set, decimal operations are Exact. +## For an example, see the float_to_decimal() recipe in the "Decimal FAQ" +## section of the docs -- it shows an how traps are used in conjunction +## with variable precision to reliably achieve exact results. + class Complex(Number): """Complex defines the operations that work on the builtin complex type.