| \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 representations in binary floating point. |
| End users typically wound 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 that indicate the results of operations, |
| and trap enablers which determine whether signals are to be 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 types of information that arise during the course of a |
| computation. Depending on the needs of the application, some 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 normal start to using decimals is to import the module, and then use |
| \function{getcontext()} to view the context and, if necessary, set the context |
| precision, rounding, or trap enablers: |
| |
| \begin{verbatim} |
| >>> from decimal import * |
| >>> getcontext() |
| Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, |
| capitals=1, flags=[], traps=[]) |
| |
| >>> getcontext().prec = 7 |
| \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). Malformed strings signal \constant{InvalidOperation} |
| and return a special kind of Decimal called a \constant{NaN} which stands for |
| ``Not a number''. Positive and negative \constant{Infinity} is yet another |
| special kind of Decimal. |
| |
| \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} |
| |
| Creating decimals is unaffected by context precision. Their level of |
| significance is completely determined by the number of digits input. It is |
| the arithmetic operations that are governed by context. |
| |
| \begin{verbatim} |
| >>> getcontext().prec = 6 |
| >>> Decimal('3.0000') |
| Decimal("3.0000") |
| >>> 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) |
| 1.3 |
| >>> int(a) |
| 1 |
| >>> a * 5 |
| Decimal("6.70") |
| >>> a * b |
| Decimal("2.5058") |
| >>> c % a |
| Decimal("0.77") |
| \end{verbatim} |
| |
| The \function{getcontext()} function accesses the current context. This one |
| context is sufficient for many applications; however, for more advanced work, |
| multiple contexts can be created using the Context() constructor. To make a |
| new context 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) |
| >>> myothercontext |
| Context(prec=60, rounding=ROUND_HALF_DOWN, Emin=-999999999, Emax=999999999, |
| capitals=1, flags=[], traps=[]) |
| >>> ExtendedContext |
| Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, |
| capitals=1, flags=[], traps=[]) |
| >>> setcontext(myothercontext) |
| >>> Decimal(1) / Decimal(7) |
| Decimal("0.142857142857142857142857142857142857142857142857142857142857") |
| >>> 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} |
| |
| Besides using contexts to control precision, rounding, and trapping signals, |
| they can be used to monitor flags which give information collected during |
| computation. 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) |
| >>> 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} |
| |
| To turn all the traps on or off all at once, use a loop. Also, the |
| \method{dict.update()} method is useful for changing a handfull of values. |
| |
| \begin{verbatim} |
| >>> getcontext.clear_flags() |
| >>> for sig in getcontext().traps: |
| ... getcontext().traps[sig] = 1 |
| |
| >>> getcontext().traps.update({Rounded:0, Inexact:0, Subnormal:0}) |
| >>> getcontext() |
| Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, |
| capitals=1, flags=[], traps=[Clamped, Underflow, |
| InvalidOperation, DivisionByZero, Overflow]) |
| \end{verbatim} |
| |
| Applications typically set the context once at the beginning of a program |
| and no further changes are needed. For many applications, the data resides |
| in a resource external to the program and is converted to \class{Decimal} with |
| a single cast inside a loop. Afterwards, decimals are as easily manipulated |
| as 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 exponent represented as an integer. |
| For example, \samp{Decimal((0, (1, 4, 1, 4), -3))} returns |
| \code{Decimal("1.414")}. |
| |
| The supplied \var{context} or, if not specified, the current context |
| governs only the handling of malformed strings not conforming to the |
| numeric string syntax. If the context traps \constant{InvalidOperation}, |
| an exception is raised; otherwise, the constructor returns a new Decimal |
| with the value of \constant{NaN}. |
| |
| The context serves no other purpose. The number of significant digits |
| recorded is determined solely by the \var{value} and the \var{context} |
| precision is not a factor. For example, \samp{Decimal("3.0000")} records |
| all four zeroes even if the context precision is only three. |
| |
| 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 |
| have a number of more 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 place value of the most significant |
| digit. |
| \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)} but returns \constant{NaN} if either is a |
| \constant{NaN}. Applies the context rounding rule before returning. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{min}{other\optional{, context}} |
| Like \samp{min(self, other)} but returns \constant{NaN} if either is a |
| \constant{NaN}. Applies the context rounding rule before returning. |
| \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}} |
| 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}{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 the precision, |
| rules for rounding, determine which signals are treated as exceptions, and set limits |
| on 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 presense of conditions that would otherwise halt the program. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{DefaultContext} |
| This class 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. This is especially |
| important because the default values context may change between releases |
| (with initial release having precision=28, rounding=ROUND_HALF_EVEN, |
| cleared flags, and no traps enabled). |
| \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 are mappings from signals |
| to either \constant{0} or \constant{1}. |
| |
| 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, lowercase is used: \constant{Decimal('6.02e+23')}. |
| \end{classdesc} |
| |
| The \class{Context} class defines several general methods as well as a |
| large number of methods for doing arithmetic directly from the 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 but using \var{self} as context. |
| Unlike the \class{Decimal} constructor, 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. |
| \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 |
| exponont 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 s 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 returns 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 returns 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 plus operation with all trailing zeros removed from the |
| result. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{plus}{x} |
| Minus corresponds to the unary prefix plus operator in Python. |
| \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 v\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 exponent of the result of a quantize 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, the 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. |
| \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, return |
| \constant{Infinity} or \constant{-Infinity} with sign determined by |
| the inputs to the calculation. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{Inexact} |
| Indicates that rounding occurred and the result is not exact. |
| |
| Signals whenever 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{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 and without needing mutexes. |
| |
| 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 with 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=dict.fromkeys(Signals, 0) |
| setcontext(DefaultContext) |
| |
| # Now start all of the threads |
| t1.start() |
| t2.start() |
| t3.start() |
| . . . |
| \end{verbatim} |
| |
| |
| |
| %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| \subsection{Recipes \label{decimal-recipes}} |
| |
| Here are some functions demonstrating ways to work with the |
| \class{Decimal} class: |
| |
| \begin{verbatim} |
| from decimal import Decimal, getcontext |
| getcontext().prec = 28 |
| |
| def moneyfmt(value, places=2, curr='$', sep=',', dp='.', pos='', neg='-'): |
| """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 set to blank if places is zero |
| pos: optional sign for positive numbers ("+" or blank) |
| neg: optional sign for negative numbers ("-" or blank) |
| leave blank to separately add brackets or a trailing minus |
| |
| >>> d = Decimal('-1234567.8901') |
| >>> moneyfmt(d) |
| '-$1,234,567.89' |
| >>> moneyfmt(d, places=0, curr='', sep='.', dp='') |
| '-1.234.568' |
| >>> '($%s)' % moneyfmt(d, curr='', neg='') |
| '($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 |
| for i in range(places): |
| build(next()) |
| build(dp) |
| try: |
| while 1: |
| for i in range(3): |
| build(next()) |
| if digits: |
| build(sep) |
| except IndexError: |
| pass |
| 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 |
| lastc, t, c, n, na, d, da = 0, three, 3, 1, 0, 0, 24 |
| while c != lastc: |
| lastc = c |
| n, na = n+na, na+8 |
| d, da = d+da, da+32 |
| t = (t * n) / d |
| c += t |
| getcontext().prec -= 2 |
| return c + 0 # Adding zero causes rounding to 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 # extra digits for intermediate steps |
| i, laste, e, fact, num = 0, 0, 1, 1, 1 |
| while e != laste: |
| laste = e |
| i += 1 |
| fact *= i |
| num *= x |
| e += num / fact |
| getcontext().prec -= 2 |
| return e + 0 |
| |
| 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 # extra digits for intermediate steps |
| i, laste, e, fact, num, sign = 0, 0, 1, 1, 1, 1 |
| while e != laste: |
| laste = e |
| i += 2 |
| fact *= i * (i-1) |
| num *= x * x |
| sign *= -1 |
| e += num / fact * sign |
| getcontext().prec -= 2 |
| return e + 0 |
| |
| 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 # extra digits for intermediate steps |
| i, laste, e, fact, num, sign = 1, 0, x, 1, x, 1 |
| while e != laste: |
| laste = e |
| i += 2 |
| fact *= i * (i-1) |
| num *= x * x |
| sign *= -1 |
| e += num / fact * sign |
| getcontext().prec -= 2 |
| return e + 0 |
| |
| \end{verbatim} |