diff options
| -rw-r--r-- | Doc/lib/libdecimal.tex | 124 |
1 files changed, 68 insertions, 56 deletions
diff --git a/Doc/lib/libdecimal.tex b/Doc/lib/libdecimal.tex index 66aad93..205a2c8 100644 --- a/Doc/lib/libdecimal.tex +++ b/Doc/lib/libdecimal.tex @@ -98,7 +98,7 @@ is set to one, an exception is raised. {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] + \citetitle[http://www.cs.berkeley.edu/\textasciitilde ejr/projects/754/private/drafts/854-1987/dir.html] {Unofficial IEEE 854 Text}.} \end{seealso} @@ -120,24 +120,26 @@ Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, >>> 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. +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{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("3.14") +>>> Decimal((0, (3, 1, 4), -2)) Decimal("3.14") >>> Decimal(str(2.0 ** 0.5)) Decimal("1.41421356237") ->>> Decimal('Mickey Mouse') +>>> Decimal("NaN") Decimal("NaN") ->>> Decimal('-Infinity') +>>> Decimal("-Infinity") Decimal("-Infinity") \end{verbatim} @@ -233,7 +235,6 @@ clear the flags before each set of monitored computations by using the \begin{verbatim} >>> setcontext(ExtendedContext) ->>> getcontext().clear_flags() >>> Decimal(355) / Decimal(113) Decimal("3.14159292") >>> getcontext() @@ -314,16 +315,16 @@ as other Python numeric types. 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 - \samp{Decimal("1.414")}. + \code{Decimal("1.414")}. The supplied \var{context} or, if not specified, the current context - governs only the handling of mal-formed strings not conforming to the + governs only the handling of malformed 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} + 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. @@ -341,10 +342,10 @@ 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. + 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}{} @@ -373,11 +374,12 @@ have a number of more specialized methods: \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")} + 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} @@ -386,7 +388,7 @@ have a number of more specialized methods: 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 + 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} @@ -401,7 +403,7 @@ have a number of more specialized methods: as \var{self}. \end{methoddesc} -\begin{methoddesc}{same_quantum{other\optional{, context}}} +\begin{methoddesc}{same_quantum}{other\optional{, context}} Test whether self and other have the same exponent or whether both are \constant{NaN}. \end{methoddesc} @@ -411,7 +413,7 @@ have a number of more specialized methods: \end{methoddesc} \begin{methoddesc}{to_eng_string}{\optional{context}} - Convert to engineering-type string. + 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 @@ -419,7 +421,7 @@ have a number of more specialized methods: \end{methoddesc} \begin{methoddesc}{to_integral}{\optional{rounding\optional{, context}}} - Rounds to the nearest integer, without signaling \constant{Inexact} + 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. @@ -463,6 +465,11 @@ In addition, the module provides three pre-made contexts: 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} @@ -482,7 +489,10 @@ In addition, the module provides three pre-made contexts: (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, trap_enablers=None, flags=None, Emin=None, Emax=None, capitals=1} @@ -491,13 +501,13 @@ In addition, the module provides three pre-made contexts: \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 + 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}, - \constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN}, - \constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, or - \constant{ROUND_UP}. + \constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN} + (towards zero), \constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, or + \constant{ROUND_UP} (away from zero). The \var{trap_enablers} and \var{flags} fields are mappings from signals to either \constant{0} or \constant{1}. @@ -536,15 +546,17 @@ large number of methods for doing arithmetic directly from the context. 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. +\begin{methoddesc}{Etop}{} + Returns a value equal to \samp{Emax - prec + 1}. +\end{methoddesc} -Those methods parallel those for the \class{Decimal} class and are -only briefed recounted here. +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}. @@ -570,7 +582,7 @@ only briefed recounted here. Return \var{x} divided by \var{y}. \end{methoddesc} -\begin{methoddesc}{divide}{x, y} +\begin{methoddesc}{divmod}{x, y} Divides two numbers and returns the integer part of the result. \end{methoddesc} @@ -589,7 +601,7 @@ only briefed recounted here. \end{methoddesc} \begin{methoddesc}{minus}{x} - Minus corresponds to unary prefix minus in Python. + Minus corresponds to the unary prefix minus operator in Python. \end{methoddesc} \begin{methoddesc}{multiply}{x, y} @@ -604,7 +616,7 @@ only briefed recounted here. \end{methoddesc} \begin{methoddesc}{plus}{x} - Minus corresponds to unary prefix plus in Python. + Minus corresponds to the unary prefix plus operator in Python. \end{methoddesc} \begin{methoddesc}{power}{x, y\optional{, modulo}} @@ -617,8 +629,8 @@ only briefed recounted here. 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. + 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. @@ -665,7 +677,7 @@ only briefed recounted here. \end{methoddesc} \begin{methoddesc}{substract}{x, y} - Return the difference of \var{x} and \var{y}. + Return the difference between \var{x} and \var{y}. \end{methoddesc} \begin{methoddesc}{to_eng_string}{} @@ -677,12 +689,12 @@ only briefed recounted here. \end{methoddesc} \begin{methoddesc}{to_integral}{x} - Rounds to the nearest integer, without signaling \constant{Inexact} + 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. + Converts a number to a string using scientific notation. \end{methoddesc} @@ -695,7 +707,7 @@ 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). +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. @@ -714,7 +726,7 @@ exception is raised upon encountering the condition. \end{classdesc*} \begin{classdesc*}{ConversionSyntax} - Trying to convert a mal-formed string such as: \code{Decimal('jump')}. + Trying to convert a malformed 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}. @@ -794,7 +806,7 @@ exception is raised upon encountering the condition. \begin{classdesc*}{Rounded} - Rounding occurred though possibly not information was lost. + 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 @@ -841,9 +853,9 @@ The following table summarizes the hierarchy of signals: \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. +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. @@ -859,7 +871,7 @@ 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 +# Set applicationwide defaults for all threads about to be launched DefaultContext.prec=12 DefaultContext.rounding=ROUND_DOWN DefaultContext.trap_enablers=dict.fromkeys(Signals, 0) @@ -944,7 +956,7 @@ def pi(): t = (t * n) / d c += t getcontext().prec -= 2 - return c + 0 + 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. |