diff options
Diffstat (limited to 'Doc/lib/libdecimal.tex')
| -rw-r--r-- | Doc/lib/libdecimal.tex | 1313 |
1 files changed, 0 insertions, 1313 deletions
diff --git a/Doc/lib/libdecimal.tex b/Doc/lib/libdecimal.tex deleted file mode 100644 index 8c665da294..0000000000 --- a/Doc/lib/libdecimal.tex +++ /dev/null @@ -1,1313 +0,0 @@ -\section{\module{decimal} --- - Decimal floating point arithmetic} - -\declaremodule{standard}{decimal} -\modulesynopsis{Implementation of the General Decimal Arithmetic -Specification.} - -\moduleauthor{Eric Price}{eprice at tjhsst.edu} -\moduleauthor{Facundo Batista}{facundo at taniquetil.com.ar} -\moduleauthor{Raymond Hettinger}{python at rcn.com} -\moduleauthor{Aahz}{aahz at pobox.com} -\moduleauthor{Tim Peters}{tim.one at comcast.net} - -\sectionauthor{Raymond D. Hettinger}{python at rcn.com} - -\versionadded{2.4} - -The \module{decimal} module provides support for decimal floating point -arithmetic. It offers several advantages over the \class{float()} datatype: - -\begin{itemize} - -\item Decimal numbers can be represented exactly. In contrast, numbers like -\constant{1.1} do not have an exact representation in binary floating point. -End users typically would not expect \constant{1.1} to display as -\constant{1.1000000000000001} as it does with binary floating point. - -\item The exactness carries over into arithmetic. In decimal floating point, -\samp{0.1 + 0.1 + 0.1 - 0.3} is exactly equal to zero. In binary floating -point, result is \constant{5.5511151231257827e-017}. While near to zero, the -differences prevent reliable equality testing and differences can accumulate. -For this reason, decimal would be preferred in accounting applications which -have strict equality invariants. - -\item The decimal module incorporates a notion of significant places so that -\samp{1.30 + 1.20} is \constant{2.50}. The trailing zero is kept to indicate -significance. This is the customary presentation for monetary applications. For -multiplication, the ``schoolbook'' approach uses all the figures in the -multiplicands. For instance, \samp{1.3 * 1.2} gives \constant{1.56} while -\samp{1.30 * 1.20} gives \constant{1.5600}. - -\item Unlike hardware based binary floating point, the decimal module has a user -settable precision (defaulting to 28 places) which can be as large as needed for -a given problem: - -\begin{verbatim} ->>> getcontext().prec = 6 ->>> Decimal(1) / Decimal(7) -Decimal("0.142857") ->>> getcontext().prec = 28 ->>> Decimal(1) / Decimal(7) -Decimal("0.1428571428571428571428571429") -\end{verbatim} - -\item Both binary and decimal floating point are implemented in terms of published -standards. While the built-in float type exposes only a modest portion of its -capabilities, the decimal module exposes all required parts of the standard. -When needed, the programmer has full control over rounding and signal handling. - -\end{itemize} - - -The module design is centered around three concepts: the decimal number, the -context for arithmetic, and signals. - -A decimal number is immutable. It has a sign, coefficient digits, and an -exponent. To preserve significance, the coefficient digits do not truncate -trailing zeroes. Decimals also include special values such as -\constant{Infinity}, \constant{-Infinity}, and \constant{NaN}. The standard -also differentiates \constant{-0} from \constant{+0}. - -The context for arithmetic is an environment specifying precision, rounding -rules, limits on exponents, flags indicating the results of operations, -and trap enablers which determine whether signals are treated as -exceptions. Rounding options include \constant{ROUND_CEILING}, -\constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN}, -\constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, and \constant{ROUND_UP}. - -Signals are groups of exceptional conditions arising during the course of -computation. Depending on the needs of the application, signals may be -ignored, considered as informational, or treated as exceptions. The signals in -the decimal module are: \constant{Clamped}, \constant{InvalidOperation}, -\constant{DivisionByZero}, \constant{Inexact}, \constant{Rounded}, -\constant{Subnormal}, \constant{Overflow}, and \constant{Underflow}. - -For each signal there is a flag and a trap enabler. When a signal is -encountered, its flag is incremented from zero and, then, if the trap enabler -is set to one, an exception is raised. Flags are sticky, so the user -needs to reset them before monitoring a calculation. - - -\begin{seealso} - \seetext{IBM's General Decimal Arithmetic Specification, - \citetitle[http://www2.hursley.ibm.com/decimal/decarith.html] - {The General Decimal Arithmetic Specification}.} - - \seetext{IEEE standard 854-1987, - \citetitle[http://www.cs.berkeley.edu/\textasciitilde ejr/projects/754/private/drafts/854-1987/dir.html] - {Unofficial IEEE 854 Text}.} -\end{seealso} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Quick-start Tutorial \label{decimal-tutorial}} - -The usual start to using decimals is importing the module, viewing the current -context with \function{getcontext()} and, if necessary, setting new values -for precision, rounding, or enabled traps: - -\begin{verbatim} ->>> from decimal import * ->>> getcontext() -Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, - capitals=1, flags=[], traps=[Overflow, InvalidOperation, - DivisionByZero]) - ->>> getcontext().prec = 7 # Set a new precision -\end{verbatim} - - -Decimal instances can be constructed from integers, strings, or tuples. To -create a Decimal from a \class{float}, first convert it to a string. This -serves as an explicit reminder of the details of the conversion (including -representation error). Decimal numbers include special values such as -\constant{NaN} which stands for ``Not a number'', positive and negative -\constant{Infinity}, and \constant{-0}. - -\begin{verbatim} ->>> Decimal(10) -Decimal("10") ->>> Decimal("3.14") -Decimal("3.14") ->>> Decimal((0, (3, 1, 4), -2)) -Decimal("3.14") ->>> Decimal(str(2.0 ** 0.5)) -Decimal("1.41421356237") ->>> Decimal("NaN") -Decimal("NaN") ->>> Decimal("-Infinity") -Decimal("-Infinity") -\end{verbatim} - - -The significance of a new Decimal is determined solely by the number -of digits input. Context precision and rounding only come into play during -arithmetic operations. - -\begin{verbatim} ->>> getcontext().prec = 6 ->>> Decimal('3.0') -Decimal("3.0") ->>> Decimal('3.1415926535') -Decimal("3.1415926535") ->>> Decimal('3.1415926535') + Decimal('2.7182818285') -Decimal("5.85987") ->>> getcontext().rounding = ROUND_UP ->>> Decimal('3.1415926535') + Decimal('2.7182818285') -Decimal("5.85988") -\end{verbatim} - - -Decimals interact well with much of the rest of Python. Here is a small -decimal floating point flying circus: - -\begin{verbatim} ->>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()) ->>> max(data) -Decimal("9.25") ->>> min(data) -Decimal("0.03") ->>> sorted(data) -[Decimal("0.03"), Decimal("1.00"), Decimal("1.34"), Decimal("1.87"), - Decimal("2.35"), Decimal("3.45"), Decimal("9.25")] ->>> sum(data) -Decimal("19.29") ->>> a,b,c = data[:3] ->>> str(a) -'1.34' ->>> float(a) -1.3400000000000001 ->>> round(a, 1) # round() first converts to binary floating point -1.3 ->>> int(a) -1 ->>> a * 5 -Decimal("6.70") ->>> a * b -Decimal("2.5058") ->>> c % a -Decimal("0.77") -\end{verbatim} - -The \method{quantize()} method rounds a number to a fixed exponent. This -method is useful for monetary applications that often round results to a fixed -number of places: - -\begin{verbatim} ->>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN) -Decimal("7.32") ->>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP) -Decimal("8") -\end{verbatim} - -As shown above, the \function{getcontext()} function accesses the current -context and allows the settings to be changed. This approach meets the -needs of most applications. - -For more advanced work, it may be useful to create alternate contexts using -the Context() constructor. To make an alternate active, use the -\function{setcontext()} function. - -In accordance with the standard, the \module{Decimal} module provides two -ready to use standard contexts, \constant{BasicContext} and -\constant{ExtendedContext}. The former is especially useful for debugging -because many of the traps are enabled: - -\begin{verbatim} ->>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN) ->>> setcontext(myothercontext) ->>> Decimal(1) / Decimal(7) -Decimal("0.142857142857142857142857142857142857142857142857142857142857") - ->>> ExtendedContext -Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, - capitals=1, flags=[], traps=[]) ->>> setcontext(ExtendedContext) ->>> Decimal(1) / Decimal(7) -Decimal("0.142857143") ->>> Decimal(42) / Decimal(0) -Decimal("Infinity") - ->>> setcontext(BasicContext) ->>> Decimal(42) / Decimal(0) -Traceback (most recent call last): - File "<pyshell#143>", line 1, in -toplevel- - Decimal(42) / Decimal(0) -DivisionByZero: x / 0 -\end{verbatim} - - -Contexts also have signal flags for monitoring exceptional conditions -encountered during computations. The flags remain set until explicitly -cleared, so it is best to clear the flags before each set of monitored -computations by using the \method{clear_flags()} method. - -\begin{verbatim} ->>> setcontext(ExtendedContext) ->>> getcontext().clear_flags() ->>> Decimal(355) / Decimal(113) -Decimal("3.14159292") ->>> getcontext() -Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, - capitals=1, flags=[Inexact, Rounded], traps=[]) -\end{verbatim} - -The \var{flags} entry shows that the rational approximation to \constant{Pi} -was rounded (digits beyond the context precision were thrown away) and that -the result is inexact (some of the discarded digits were non-zero). - -Individual traps are set using the dictionary in the \member{traps} -field of a context: - -\begin{verbatim} ->>> Decimal(1) / Decimal(0) -Decimal("Infinity") ->>> getcontext().traps[DivisionByZero] = 1 ->>> Decimal(1) / Decimal(0) -Traceback (most recent call last): - File "<pyshell#112>", line 1, in -toplevel- - Decimal(1) / Decimal(0) -DivisionByZero: x / 0 -\end{verbatim} - -Most programs adjust the current context only once, at the beginning of the -program. And, in many applications, data is converted to \class{Decimal} with -a single cast inside a loop. With context set and decimals created, the bulk -of the program manipulates the data no differently than with other Python -numeric types. - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Decimal objects \label{decimal-decimal}} - -\begin{classdesc}{Decimal}{\optional{value \optional{, context}}} - Constructs a new \class{Decimal} object based from \var{value}. - - \var{value} can be an integer, string, tuple, or another \class{Decimal} - object. If no \var{value} is given, returns \code{Decimal("0")}. If - \var{value} is a string, it should conform to the decimal numeric string - syntax: - - \begin{verbatim} - 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 - \end{verbatim} - - If \var{value} is a \class{tuple}, it should have three components, - a sign (\constant{0} for positive or \constant{1} for negative), - a \class{tuple} of digits, and an integer exponent. For example, - \samp{Decimal((0, (1, 4, 1, 4), -3))} returns \code{Decimal("1.414")}. - - The \var{context} precision does not affect how many digits are stored. - That is determined exclusively by the number of digits in \var{value}. For - example, \samp{Decimal("3.00000")} records all five zeroes even if the - context precision is only three. - - The purpose of the \var{context} argument is determining what to do if - \var{value} is a malformed string. If the context traps - \constant{InvalidOperation}, an exception is raised; otherwise, the - constructor returns a new Decimal with the value of \constant{NaN}. - - Once constructed, \class{Decimal} objects are immutable. -\end{classdesc} - -Decimal floating point objects share many properties with the other builtin -numeric types such as \class{float} and \class{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 \class{float} -or \class{long}). - -In addition to the standard numeric properties, decimal floating point objects -also have a number of specialized methods: - -\begin{methoddesc}{adjusted}{} - Return the adjusted exponent after shifting out the coefficient's rightmost - digits until only the lead digit remains: \code{Decimal("321e+5").adjusted()} - returns seven. Used for determining the position of the most significant - digit with respect to the decimal point. -\end{methoddesc} - -\begin{methoddesc}{as_tuple}{} - Returns a tuple representation of the number: - \samp{(sign, digittuple, exponent)}. -\end{methoddesc} - -\begin{methoddesc}{compare}{other\optional{, context}} - Compares like \method{__cmp__()} but returns a decimal instance: - \begin{verbatim} - a or b is a NaN ==> Decimal("NaN") - a < b ==> Decimal("-1") - a == b ==> Decimal("0") - a > b ==> Decimal("1") - \end{verbatim} -\end{methoddesc} - -\begin{methoddesc}{max}{other\optional{, context}} - Like \samp{max(self, other)} except that the context rounding rule - is applied before returning and that \constant{NaN} values are - either signalled or ignored (depending on the context and whether - they are signaling or quiet). -\end{methoddesc} - -\begin{methoddesc}{min}{other\optional{, context}} - Like \samp{min(self, other)} except that the context rounding rule - is applied before returning and that \constant{NaN} values are - either signalled or ignored (depending on the context and whether - they are signaling or quiet). -\end{methoddesc} - -\begin{methoddesc}{normalize}{\optional{context}} - Normalize the number by stripping the rightmost trailing zeroes and - converting any result equal to \constant{Decimal("0")} to - \constant{Decimal("0e0")}. Used for producing canonical values for members - of an equivalence class. For example, \code{Decimal("32.100")} and - \code{Decimal("0.321000e+2")} both normalize to the equivalent value - \code{Decimal("32.1")}. -\end{methoddesc} - -\begin{methoddesc}{quantize} - {exp \optional{, rounding\optional{, context\optional{, watchexp}}}} - Quantize makes the exponent the same as \var{exp}. Searches for a - rounding method in \var{rounding}, then in \var{context}, and then - in the current context. - - If \var{watchexp} is set (default), then an error is returned whenever - the resulting exponent is greater than \member{Emax} or less than - \member{Etiny}. -\end{methoddesc} - -\begin{methoddesc}{remainder_near}{other\optional{, context}} - Computes the modulo as either a positive or negative value depending - on which is closest to zero. For instance, - \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")} - which is closer to zero than \code{Decimal("4")}. - - If both are equally close, the one chosen will have the same sign - as \var{self}. -\end{methoddesc} - -\begin{methoddesc}{same_quantum}{other\optional{, context}} - Test whether self and other have the same exponent or whether both - are \constant{NaN}. -\end{methoddesc} - -\begin{methoddesc}{sqrt}{\optional{context}} - Return the square root to full precision. -\end{methoddesc} - -\begin{methoddesc}{to_eng_string}{\optional{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 - \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")} -\end{methoddesc} - -\begin{methoddesc}{to_integral}{\optional{rounding\optional{, context}}} - Rounds to the nearest integer without signaling \constant{Inexact} - or \constant{Rounded}. If given, applies \var{rounding}; otherwise, - uses the rounding method in either the supplied \var{context} or the - current context. -\end{methoddesc} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Context objects \label{decimal-context}} - -Contexts are environments for arithmetic operations. They govern precision, -set rules for rounding, determine which signals are treated as exceptions, and -limit the range for exponents. - -Each thread has its own current context which is accessed or changed using -the \function{getcontext()} and \function{setcontext()} functions: - -\begin{funcdesc}{getcontext}{} - Return the current context for the active thread. -\end{funcdesc} - -\begin{funcdesc}{setcontext}{c} - Set the current context for the active thread to \var{c}. -\end{funcdesc} - -Beginning with Python 2.5, you can also use the \keyword{with} statement -and the \function{localcontext()} function to temporarily change the -active context. - -\begin{funcdesc}{localcontext}{\optional{c}} - Return a context manager that will set the current context for - the active thread to a copy of \var{c} on entry to the with-statement - and restore the previous context when exiting the with-statement. If - no context is specified, a copy of the current context is used. - \versionadded{2.5} - - For example, the following code sets the current decimal precision - to 42 places, performs a calculation, and then automatically restores - the previous context: -\begin{verbatim} - from __future__ import with_statement - from decimal import localcontext - - with localcontext() as ctx: - ctx.prec = 42 # Perform a high precision calculation - s = calculate_something() - s = +s # Round the final result back to the default precision -\end{verbatim} -\end{funcdesc} - -New contexts can also be created using the \class{Context} constructor -described below. In addition, the module provides three pre-made -contexts: - -\begin{classdesc*}{BasicContext} - This is a standard context defined by the General Decimal Arithmetic - Specification. Precision is set to nine. Rounding is set to - \constant{ROUND_HALF_UP}. All flags are cleared. All traps are enabled - (treated as exceptions) except \constant{Inexact}, \constant{Rounded}, and - \constant{Subnormal}. - - Because many of the traps are enabled, this context is useful for debugging. -\end{classdesc*} - -\begin{classdesc*}{ExtendedContext} - This is a standard context defined by the General Decimal Arithmetic - Specification. Precision is set to nine. Rounding is set to - \constant{ROUND_HALF_EVEN}. All flags are cleared. No traps are enabled - (so that exceptions are not raised during computations). - - Because the trapped are disabled, this context is useful for applications - that prefer to have result value of \constant{NaN} or \constant{Infinity} - instead of raising exceptions. This allows an application to complete a - run in the presence of conditions that would otherwise halt the program. -\end{classdesc*} - -\begin{classdesc*}{DefaultContext} - This context is used by the \class{Context} constructor as a prototype for - new contexts. Changing a field (such a precision) has the effect of - changing the default for new contexts creating by the \class{Context} - constructor. - - This context is most useful in multi-threaded environments. Changing one of - the fields before threads are started has the effect of setting system-wide - defaults. Changing the fields after threads have started is not recommended - as it would require thread synchronization to prevent race conditions. - - In single threaded environments, it is preferable to not use this context - at all. Instead, simply create contexts explicitly as described below. - - The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled - traps for Overflow, InvalidOperation, and DivisionByZero. -\end{classdesc*} - - -In addition to the three supplied contexts, new contexts can be created -with the \class{Context} constructor. - -\begin{classdesc}{Context}{prec=None, rounding=None, traps=None, - flags=None, Emin=None, Emax=None, capitals=1} - Creates a new context. If a field is not specified or is \constant{None}, - the default values are copied from the \constant{DefaultContext}. If the - \var{flags} field is not specified or is \constant{None}, all flags are - cleared. - - The \var{prec} field is a positive integer that sets the precision for - arithmetic operations in the context. - - The \var{rounding} option is one of: - \begin{itemize} - \item \constant{ROUND_CEILING} (towards \constant{Infinity}), - \item \constant{ROUND_DOWN} (towards zero), - \item \constant{ROUND_FLOOR} (towards \constant{-Infinity}), - \item \constant{ROUND_HALF_DOWN} (to nearest with ties going towards zero), - \item \constant{ROUND_HALF_EVEN} (to nearest with ties going to nearest even integer), - \item \constant{ROUND_HALF_UP} (to nearest with ties going away from zero), or - \item \constant{ROUND_UP} (away from zero). - \end{itemize} - - The \var{traps} and \var{flags} fields list any signals to be set. - Generally, new contexts should only set traps and leave the flags clear. - - The \var{Emin} and \var{Emax} fields are integers specifying the outer - limits allowable for exponents. - - The \var{capitals} field is either \constant{0} or \constant{1} (the - default). If set to \constant{1}, exponents are printed with a capital - \constant{E}; otherwise, a lowercase \constant{e} is used: - \constant{Decimal('6.02e+23')}. -\end{classdesc} - -The \class{Context} class defines several general purpose methods as well as a -large number of methods for doing arithmetic directly in a given context. - -\begin{methoddesc}{clear_flags}{} - Resets all of the flags to \constant{0}. -\end{methoddesc} - -\begin{methoddesc}{copy}{} - Return a duplicate of the context. -\end{methoddesc} - -\begin{methoddesc}{create_decimal}{num} - Creates a new Decimal instance from \var{num} but using \var{self} as - context. Unlike the \class{Decimal} constructor, the context precision, - rounding method, flags, and traps are applied to the conversion. - - This is useful because constants are often given to a greater precision than - is needed by the application. Another benefit is that rounding immediately - eliminates unintended effects from digits beyond the current precision. - In the following example, using unrounded inputs means that adding zero - to a sum can change the result: - - \begin{verbatim} - >>> getcontext().prec = 3 - >>> Decimal("3.4445") + Decimal("1.0023") - Decimal("4.45") - >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023") - Decimal("4.44") - \end{verbatim} - -\end{methoddesc} - -\begin{methoddesc}{Etiny}{} - Returns a value equal to \samp{Emin - prec + 1} which is the minimum - exponent value for subnormal results. When underflow occurs, the - exponent is set to \constant{Etiny}. -\end{methoddesc} - -\begin{methoddesc}{Etop}{} - Returns a value equal to \samp{Emax - prec + 1}. -\end{methoddesc} - - -The usual approach to working with decimals is to create \class{Decimal} -instances and then apply arithmetic operations which take place within the -current context for the active thread. An alternate approach is to use -context methods for calculating within a specific context. The methods are -similar to those for the \class{Decimal} class and are only briefly recounted -here. - -\begin{methoddesc}{abs}{x} - Returns the absolute value of \var{x}. -\end{methoddesc} - -\begin{methoddesc}{add}{x, y} - Return the sum of \var{x} and \var{y}. -\end{methoddesc} - -\begin{methoddesc}{compare}{x, y} - Compares values numerically. - - Like \method{__cmp__()} but returns a decimal instance: - \begin{verbatim} - a or b is a NaN ==> Decimal("NaN") - a < b ==> Decimal("-1") - a == b ==> Decimal("0") - a > b ==> Decimal("1") - \end{verbatim} -\end{methoddesc} - -\begin{methoddesc}{divide}{x, y} - Return \var{x} divided by \var{y}. -\end{methoddesc} - -\begin{methoddesc}{divmod}{x, y} - Divides two numbers and returns the integer part of the result. -\end{methoddesc} - -\begin{methoddesc}{max}{x, y} - Compare two values numerically and return the maximum. - - If they are numerically equal then the left-hand operand is chosen as the - result. -\end{methoddesc} - -\begin{methoddesc}{min}{x, y} - Compare two values numerically and return the minimum. - - If they are numerically equal then the left-hand operand is chosen as the - result. -\end{methoddesc} - -\begin{methoddesc}{minus}{x} - Minus corresponds to the unary prefix minus operator in Python. -\end{methoddesc} - -\begin{methoddesc}{multiply}{x, y} - Return the product of \var{x} and \var{y}. -\end{methoddesc} - -\begin{methoddesc}{normalize}{x} - Normalize reduces an operand to its simplest form. - - Essentially a \method{plus} operation with all trailing zeros removed from - the result. -\end{methoddesc} - -\begin{methoddesc}{plus}{x} - Plus corresponds to the unary prefix plus operator in Python. This - operation applies the context precision and rounding, so it is - \emph{not} an identity operation. -\end{methoddesc} - -\begin{methoddesc}{power}{x, y\optional{, modulo}} - Return \samp{x ** y} to the \var{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 \constant{InvalidOperation} - condition is signaled. - - 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. -\end{methoddesc} - -\begin{methoddesc}{quantize}{x, y} - Returns a value equal to \var{x} after rounding and having the exponent of - \var{y}. - - Unlike other operations, if the length of the coefficient after the quantize - operation would be greater than precision, then an - \constant{InvalidOperation} is signaled. This guarantees that, unless there - is an error condition, the quantized exponent is always equal to that of the - right-hand operand. - - Also unlike other operations, quantize never signals Underflow, even - if the result is subnormal and inexact. -\end{methoddesc} - -\begin{methoddesc}{remainder}{x, y} - Returns the remainder from integer division. - - The sign of the result, if non-zero, is the same as that of the original - dividend. -\end{methoddesc} - -\begin{methoddesc}{remainder_near}{x, y} - Computed the modulo as either a positive or negative value depending - on which is closest to zero. For instance, - \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")} - which is closer to zero than \code{Decimal("4")}. - - If both are equally close, the one chosen will have the same sign - as \var{self}. -\end{methoddesc} - -\begin{methoddesc}{same_quantum}{x, y} - Test whether \var{x} and \var{y} have the same exponent or whether both are - \constant{NaN}. -\end{methoddesc} - -\begin{methoddesc}{sqrt}{x} - Return the square root of \var{x} to full precision. -\end{methoddesc} - -\begin{methoddesc}{subtract}{x, y} - Return the difference between \var{x} and \var{y}. -\end{methoddesc} - -\begin{methoddesc}{to_eng_string}{} - Convert to 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 - \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")} -\end{methoddesc} - -\begin{methoddesc}{to_integral}{x} - Rounds to the nearest integer without signaling \constant{Inexact} - or \constant{Rounded}. -\end{methoddesc} - -\begin{methoddesc}{to_sci_string}{x} - Converts a number to a string using scientific notation. -\end{methoddesc} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Signals \label{decimal-signals}} - -Signals represent conditions that arise during computation. -Each corresponds to one context flag and one context trap enabler. - -The context flag is incremented whenever the condition is encountered. -After the computation, flags may be checked for informational -purposes (for instance, to determine whether a computation was exact). -After checking the flags, be sure to clear all flags before starting -the next computation. - -If the context's trap enabler is set for the signal, then the condition -causes a Python exception to be raised. For example, if the -\class{DivisionByZero} trap is set, then a \exception{DivisionByZero} -exception is raised upon encountering the condition. - - -\begin{classdesc*}{Clamped} - Altered an exponent to fit representation constraints. - - Typically, clamping occurs when an exponent falls outside the context's - \member{Emin} and \member{Emax} limits. If possible, the exponent is - reduced to fit by adding zeroes to the coefficient. -\end{classdesc*} - -\begin{classdesc*}{DecimalException} - Base class for other signals and a subclass of - \exception{ArithmeticError}. -\end{classdesc*} - -\begin{classdesc*}{DivisionByZero} - Signals the division of a non-infinite number by zero. - - Can occur with division, modulo division, or when raising a number to a - negative power. If this signal is not trapped, returns - \constant{Infinity} or \constant{-Infinity} with the sign determined by - the inputs to the calculation. -\end{classdesc*} - -\begin{classdesc*}{Inexact} - Indicates that rounding occurred and the result is not exact. - - Signals when non-zero digits were discarded during rounding. The rounded - result is returned. The signal flag or trap is used to detect when - results are inexact. -\end{classdesc*} - -\begin{classdesc*}{InvalidOperation} - An invalid operation was performed. - - Indicates that an operation was requested that does not make sense. - If not trapped, returns \constant{NaN}. Possible causes include: - - \begin{verbatim} - Infinity - Infinity - 0 * Infinity - Infinity / Infinity - x % 0 - Infinity % x - x._rescale( non-integer ) - sqrt(-x) and x > 0 - 0 ** 0 - x ** (non-integer) - x ** Infinity - \end{verbatim} -\end{classdesc*} - -\begin{classdesc*}{Overflow} - Numerical overflow. - - Indicates the exponent is larger than \member{Emax} after rounding has - occurred. If not trapped, the result depends on the rounding mode, either - pulling inward to the largest representable finite number or rounding - outward to \constant{Infinity}. In either case, \class{Inexact} and - \class{Rounded} are also signaled. -\end{classdesc*} - -\begin{classdesc*}{Rounded} - Rounding occurred though possibly no information was lost. - - Signaled whenever rounding discards digits; even if those digits are - zero (such as rounding \constant{5.00} to \constant{5.0}). If not - trapped, returns the result unchanged. This signal is used to detect - loss of significant digits. -\end{classdesc*} - -\begin{classdesc*}{Subnormal} - Exponent was lower than \member{Emin} prior to rounding. - - Occurs when an operation result is subnormal (the exponent is too small). - If not trapped, returns the result unchanged. -\end{classdesc*} - -\begin{classdesc*}{Underflow} - Numerical underflow with result rounded to zero. - - Occurs when a subnormal result is pushed to zero by rounding. - \class{Inexact} and \class{Subnormal} are also signaled. -\end{classdesc*} - -The following table summarizes the hierarchy of signals: - -\begin{verbatim} - exceptions.ArithmeticError(exceptions.Exception) - DecimalException - Clamped - DivisionByZero(DecimalException, exceptions.ZeroDivisionError) - Inexact - Overflow(Inexact, Rounded) - Underflow(Inexact, Rounded, Subnormal) - InvalidOperation - Rounded - Subnormal -\end{verbatim} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Floating Point Notes \label{decimal-notes}} - -\subsubsection{Mitigating round-off error with increased precision} - -The use of decimal floating point eliminates decimal representation error -(making it possible to represent \constant{0.1} exactly); however, some -operations can still incur round-off error when non-zero digits exceed the -fixed precision. - -The effects of round-off error can be amplified by the addition or subtraction -of nearly offsetting quantities resulting in loss of significance. Knuth -provides two instructive examples where rounded floating point arithmetic with -insufficient precision causes the breakdown of the associative and -distributive properties of addition: - -\begin{verbatim} -# Examples from Seminumerical Algorithms, Section 4.2.2. ->>> from decimal import Decimal, getcontext ->>> getcontext().prec = 8 - ->>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111') ->>> (u + v) + w -Decimal("9.5111111") ->>> u + (v + w) -Decimal("10") - ->>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003') ->>> (u*v) + (u*w) -Decimal("0.01") ->>> u * (v+w) -Decimal("0.0060000") -\end{verbatim} - -The \module{decimal} module makes it possible to restore the identities -by expanding the precision sufficiently to avoid loss of significance: - -\begin{verbatim} ->>> getcontext().prec = 20 ->>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111') ->>> (u + v) + w -Decimal("9.51111111") ->>> u + (v + w) -Decimal("9.51111111") ->>> ->>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003') ->>> (u*v) + (u*w) -Decimal("0.0060000") ->>> u * (v+w) -Decimal("0.0060000") -\end{verbatim} - -\subsubsection{Special values} - -The number system for the \module{decimal} module provides special -values including \constant{NaN}, \constant{sNaN}, \constant{-Infinity}, -\constant{Infinity}, and two zeroes, \constant{+0} and \constant{-0}. - -Infinities can be constructed directly with: \code{Decimal('Infinity')}. Also, -they can arise from dividing by zero when the \exception{DivisionByZero} -signal is not trapped. Likewise, when the \exception{Overflow} signal is not -trapped, infinity can result from rounding beyond the limits of the largest -representable number. - -The infinities are signed (affine) and can be used in arithmetic operations -where they get treated as very large, indeterminate numbers. For instance, -adding a constant to infinity gives another infinite result. - -Some operations are indeterminate and return \constant{NaN}, or if the -\exception{InvalidOperation} signal is trapped, raise an exception. For -example, \code{0/0} returns \constant{NaN} which means ``not a number''. This -variety of \constant{NaN} is quiet and, once created, will flow through other -computations always resulting in another \constant{NaN}. This behavior can be -useful for a series of computations that occasionally have missing inputs --- -it allows the calculation to proceed while flagging specific results as -invalid. - -A variant is \constant{sNaN} which signals rather than remaining quiet -after every operation. This is a useful return value when an invalid -result needs to interrupt a calculation for special handling. - -The signed zeros can result from calculations that underflow. -They keep the sign that would have resulted if the calculation had -been carried out to greater precision. Since their magnitude is -zero, both positive and negative zeros are treated as equal and their -sign is informational. - -In addition to the two signed zeros which are distinct yet equal, -there are various representations of zero with differing precisions -yet equivalent in value. This takes a bit of getting used to. For -an eye accustomed to normalized floating point representations, it -is not immediately obvious that the following calculation returns -a value equal to zero: - -\begin{verbatim} ->>> 1 / Decimal('Infinity') -Decimal("0E-1000000026") -\end{verbatim} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Working with threads \label{decimal-threads}} - -The \function{getcontext()} function accesses a different \class{Context} -object for each thread. Having separate thread contexts means that threads -may make changes (such as \code{getcontext.prec=10}) without interfering with -other threads. - -Likewise, the \function{setcontext()} function automatically assigns its target -to the current thread. - -If \function{setcontext()} has not been called before \function{getcontext()}, -then \function{getcontext()} will automatically create a new context for use -in the current thread. - -The new context is copied from a prototype context called -\var{DefaultContext}. To control the defaults so that each thread will use the -same values throughout the application, directly modify the -\var{DefaultContext} object. This should be done \emph{before} any threads are -started so that there won't be a race condition between threads calling -\function{getcontext()}. For example: - -\begin{verbatim} -# Set applicationwide defaults for all threads about to be launched -DefaultContext.prec = 12 -DefaultContext.rounding = ROUND_DOWN -DefaultContext.traps = ExtendedContext.traps.copy() -DefaultContext.traps[InvalidOperation] = 1 -setcontext(DefaultContext) - -# Afterwards, the threads can be started -t1.start() -t2.start() -t3.start() - . . . -\end{verbatim} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Recipes \label{decimal-recipes}} - -Here are a few recipes that serve as utility functions and that demonstrate -ways to work with the \class{Decimal} class: - -\begin{verbatim} -def moneyfmt(value, places=2, curr='', sep=',', dp='.', - pos='', neg='-', trailneg=''): - """Convert Decimal to a money formatted string. - - places: required number of places after the decimal point - curr: optional currency symbol before the sign (may be blank) - sep: optional grouping separator (comma, period, space, or blank) - dp: decimal point indicator (comma or period) - only specify as blank when places is zero - pos: optional sign for positive numbers: '+', space or blank - neg: optional sign for negative numbers: '-', '(', space or blank - trailneg:optional trailing minus indicator: '-', ')', space or blank - - >>> d = Decimal('-1234567.8901') - >>> moneyfmt(d, curr='$') - '-$1,234,567.89' - >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-') - '1.234.568-' - >>> moneyfmt(d, curr='$', neg='(', trailneg=')') - '($1,234,567.89)' - >>> moneyfmt(Decimal(123456789), sep=' ') - '123 456 789.00' - >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>') - '<.02>' - - """ - q = Decimal((0, (1,), -places)) # 2 places --> '0.01' - sign, digits, exp = value.quantize(q).as_tuple() - assert exp == -places - result = [] - digits = map(str, digits) - build, next = result.append, digits.pop - if sign: - build(trailneg) - for i in range(places): - if digits: - build(next()) - else: - build('0') - build(dp) - i = 0 - while digits: - build(next()) - i += 1 - if i == 3 and digits: - i = 0 - build(sep) - build(curr) - if sign: - build(neg) - else: - build(pos) - result.reverse() - return ''.join(result) - -def pi(): - """Compute Pi to the current precision. - - >>> print pi() - 3.141592653589793238462643383 - - """ - getcontext().prec += 2 # extra digits for intermediate steps - three = Decimal(3) # substitute "three=3.0" for regular floats - lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24 - while s != lasts: - lasts = s - n, na = n+na, na+8 - d, da = d+da, da+32 - t = (t * n) / d - s += t - getcontext().prec -= 2 - return +s # unary plus applies the new precision - -def exp(x): - """Return e raised to the power of x. Result type matches input type. - - >>> print exp(Decimal(1)) - 2.718281828459045235360287471 - >>> print exp(Decimal(2)) - 7.389056098930650227230427461 - >>> print exp(2.0) - 7.38905609893 - >>> print exp(2+0j) - (7.38905609893+0j) - - """ - getcontext().prec += 2 - i, lasts, s, fact, num = 0, 0, 1, 1, 1 - while s != lasts: - lasts = s - i += 1 - fact *= i - num *= x - s += num / fact - getcontext().prec -= 2 - return +s - -def cos(x): - """Return the cosine of x as measured in radians. - - >>> print cos(Decimal('0.5')) - 0.8775825618903727161162815826 - >>> print cos(0.5) - 0.87758256189 - >>> print cos(0.5+0j) - (0.87758256189+0j) - - """ - getcontext().prec += 2 - i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1 - while s != lasts: - lasts = s - i += 2 - fact *= i * (i-1) - num *= x * x - sign *= -1 - s += num / fact * sign - getcontext().prec -= 2 - return +s - -def sin(x): - """Return the sine of x as measured in radians. - - >>> print sin(Decimal('0.5')) - 0.4794255386042030002732879352 - >>> print sin(0.5) - 0.479425538604 - >>> print sin(0.5+0j) - (0.479425538604+0j) - - """ - getcontext().prec += 2 - i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1 - while s != lasts: - lasts = s - i += 2 - fact *= i * (i-1) - num *= x * x - sign *= -1 - s += num / fact * sign - getcontext().prec -= 2 - return +s - -\end{verbatim} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Decimal FAQ \label{decimal-faq}} - -Q. It is cumbersome to type \code{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: - -\begin{verbatim} ->>> D = decimal.Decimal ->>> D('1.23') + D('3.45') -Decimal("4.68") -\end{verbatim} - - -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 \method{quantize()} method rounds to a fixed number of decimal places. -If the \constant{Inexact} trap is set, it is also useful for validation: - -\begin{verbatim} ->>> 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 -\end{verbatim} - - -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 \method{quantize()} step. - - -Q. There are many ways to express the same value. The numbers -\constant{200}, \constant{200.000}, \constant{2E2}, and \constant{.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 \method{normalize()} method maps all equivalent values to a single -representative: - -\begin{verbatim} ->>> 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")] -\end{verbatim} - - -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 \constant{5.0E+3} as \constant{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 \class{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 \constant{Inexact} will signal a need for more precision: - -\begin{verbatim} -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) -\end{verbatim} - - -Q. Why isn't the \function{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: - -\begin{verbatim} ->>> floatToDecimal(1.1) -Decimal("1.100000000000000088817841970012523233890533447265625") -\end{verbatim} - - -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: - -\begin{verbatim} ->>> getcontext().prec = 3 ->>> Decimal('3.104') + D('2.104') -Decimal("5.21") ->>> Decimal('3.104') + D('0.000') + D('2.104') -Decimal("5.20") -\end{verbatim} - -The solution is either to increase precision or to force rounding of inputs -using the unary plus operation: - -\begin{verbatim} ->>> getcontext().prec = 3 ->>> +Decimal('1.23456789') # unary plus triggers rounding -Decimal("1.23") -\end{verbatim} - -Alternatively, inputs can be rounded upon creation using the -\method{Context.create_decimal()} method: - -\begin{verbatim} ->>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678') -Decimal("1.2345") -\end{verbatim} |