diff options
| -rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/libdecimal.tex | 882 |
2 files changed, 883 insertions, 0 deletions
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index e6879fd..4fe4f01 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -120,6 +120,7 @@ and how to embed it in other applications. \input{libdoctest} \input{libunittest} \input{libtest} +\input{libdecimal} \input{libmath} \input{libcmath} \input{librandom} diff --git a/Doc/lib/libdecimal.tex b/Doc/lib/libdecimal.tex new file mode 100644 index 0000000..e668671 --- /dev/null +++ b/Doc/lib/libdecimal.tex @@ -0,0 +1,882 @@ +\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 decimal \module{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} (the result of \samp{1 / 0}), \constant{-Infinity}, +(the result of \samp{-1 / 0}), and \constant{NaN} (the result of +\samp{0 / 0}). 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{ConversionSyntax}, \constant{DivisionByZero}, +\constant{DivisionImpossible}, \constant{DivisionUndefined}, +\constant{Inexact}, \constant{InvalidContext}, \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. + + +\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/~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, + setflags=[], settraps=[]) + +>>> getcontext().prec = 7 +\end{verbatim} + +Decimal instances can be constructed from integers or strings. 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{ConversionSyntax} 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(str(2.0 ** 0.5)) +Decimal("1.41421356237") +>>> Decimal('Mickey Mouse') +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, + setflags=[], settraps=[]) +>>> ExtendedContext +Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, + setflags=[], settraps=[]) +>>> 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) +>>> getcontext().clear_flags() +>>> Decimal(355) / Decimal(113) +Decimal("3.14159292") +>>> getcontext() +Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, + setflags=['Inexact', 'Rounded'], settraps=[]) +\end{verbatim} + +The \var{setflags} 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{trap_enablers} +field of a context: + +\begin{verbatim} +>>> Decimal(1) / Decimal(0) +Decimal("Infinity") +>>> getcontext().trap_enablers[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().trap_enablers: +... getcontext().trap_enablers[sig] = 1 + +>>> getcontext().trap_enablers.update({Rounded:0, Inexact:0, Subnormal:0}) +>>> getcontext() +Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, + setflags=[], settraps=['Underflow', 'DecimalException', 'Clamped', + 'InvalidContext', 'InvalidOperation', 'ConversionSyntax', + 'DivisionByZero', 'DivisionImpossible', 'DivisionUndefined', + '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, 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} + + The supplied \var{context} or, if not specified, the current context + governs only the handling of mal-formed strings not conforming to the + numeric string syntax. If the context traps \constant{ConversionSyntax}, + 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 number's adjusted exponent that results from shifting out the + coefficients 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 striping the rightmost trailing zeroes and + converting any result equal to \constant{Decimal("0")} to Decimal("0e0"). + Used for producing a canonical value 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. + + Of \var{watchexp} is set (default), then an error is returned if + 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 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). +\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*} + + +\begin{classdesc}{Context}{prec=None, rounding=None, trap_enablers=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 in an positive integer that sets the precision for + arithmetic operations in the context. + + The \var{rounding} option is one of: \constant{ROUND_CEILING}, + \constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN}, + \constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, or + \constant{ROUND_UP}. + + The \var{trap_enablers} 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} + +The usual approach to working with decimals is to create Decimal +instances and then apply arithmetic operations which take place +within the current context for the active thread. An alternate +approach is to use a context method to perform a particular +computation within the given context rather than the current context. + +Those methods parallel those for the \class{Decimal} class and are +only briefed 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}{divide}{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 unary prefix minus 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 unary prefix plus 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 Invalid operation condition + is raised. + + 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 of \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 +purposed (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*}{ConversionSyntax} + Trying to convert a mal-formed string such as: \code{Decimal('jump')}. + + Decimal converts only strings conforming to the numeric string + syntax. If this signal is not trapped, returns \constant{NaN}. +\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*}{DivisionImpossible} + Error performing a division operation. Caused when an intermediate result + has more digits that the allowed by the current precision. If not trapped, + returns \constant{NaN}. +\end{classdesc*} + + +\begin{classdesc*}{DivisionUndefined} + This is a subclass of \class{DivisionByZero}. + + It occurs only in the context of division operations. +\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*}{InvalidContext} + This is a subclass of \class{InvalidOperation}. + + Indicates an error within the Context object such as an unknown + rounding operation. If not trapped, returns \constant{NaN}. +\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 not 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 + ConversionSyntax + DivisionImpossible + DivisionUndefined(InvalidOperation, exceptions.ZeroDivisionError) + InvalidContext + 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 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 application wide defaults for all threads about to be launched +DefaultContext.prec=12 +DefaultContext.rounding=ROUND_DOWN +DefaultContext.trap_enablers=dict.fromkeys(Signals, 0) +setcontext(DefaultContext) + +# Now start all of the threads +t1.start() +t2.start() +t3.start() + . . . +\end{verbatim} + + + + + + + + |