| \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 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 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} |
| {\optional{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-decimal}} |
| |
| 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} |
| |
| New contexts can formed 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: |
| \constant{ROUND_CEILING} (towards \constant{Infinity}), |
| \constant{ROUND_DOWN} (towards zero), |
| \constant{ROUND_FLOOR} (towards \constant{-Infinity}), |
| \constant{ROUND_HALF_DOWN} (towards zero), |
| \constant{ROUND_HALF_EVEN}, |
| \constant{ROUND_HALF_UP} (away from zero), or |
| \constant{ROUND_UP} (away from zero). |
| |
| 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}{} |
| Sets all of the flags to \constant{0}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{copy}{} |
| Returns 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}{} |
| Return the square root to full precision. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{substract}{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}{} |
| 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 is 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.StandardError) |
| 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}} |
| |
| 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 * |
| >>> 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} |
| |
| |
| 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, 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)' |
| |
| """ |
| q = Decimal((0, (1,), -places)) # 2 places --> '0.01' |
| sign, digits, exp = value.quantize(q).as_tuple() |
| result = [] |
| digits = map(str, digits) |
| build, next = result.append, digits.pop |
| if sign: |
| build(trailneg) |
| for i in range(places): |
| build(next()) |
| build(dp) |
| i = 0 |
| while digits: |
| build(next()) |
| i += 1 |
| if i == 3: |
| 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 cosine 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} |