mirrors
/
cpython
mirror of https://github.com/python/cpython.git
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix markup, typos, and nits.

This commit is contained in:
Raymond Hettinger 2004-07-08 09:22:33 +00:00
parent dfef882095
commit 536f76b25a
1 changed files with 68 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
Doc/lib/libdecimal.tex
View File

@ -98,7 +98,7 @@ is set to one, an exception is raised.
{The General Decimal Arithmetic Specification}.} {The General Decimal Arithmetic Specification}.}
\seetext{IEEE standard 854-1987, \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}.} {Unofficial IEEE 854 Text}.}
\end{seealso} \end{seealso}
@ -120,24 +120,26 @@ Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
>>> getcontext().prec = 7 >>> getcontext().prec = 7
\end{verbatim} \end{verbatim}
Decimal instances can be constructed from integers or strings. To create a Decimal instances can be constructed from integers, strings or tuples. To
Decimal from a \class{float}, first convert it to a string. This serves as an create a Decimal from a \class{float}, first convert it to a string. This
explicit reminder of the details of the conversion (including representation serves as an explicit reminder of the details of the conversion (including
error). Malformed strings signal \constant{ConversionSyntax} and return a representation error). Malformed strings signal \constant{ConversionSyntax}
special kind of Decimal called a \constant{NaN} which stands for ``Not a and return a special kind of Decimal called a \constant{NaN} which stands for
number''. Positive and negative \constant{Infinity} is yet another special ``Not a number''. Positive and negative \constant{Infinity} is yet another
kind of Decimal. special kind of Decimal.
\begin{verbatim} \begin{verbatim}
>>> Decimal(10) >>> Decimal(10)
Decimal("10") Decimal("10")
>>> Decimal('3.14') >>> Decimal("3.14")
Decimal("3.14")
>>> Decimal((0, (3, 1, 4), -2))
Decimal("3.14") Decimal("3.14")
>>> Decimal(str(2.0 ** 0.5)) >>> Decimal(str(2.0 ** 0.5))
Decimal("1.41421356237") Decimal("1.41421356237")
>>> Decimal('Mickey Mouse') >>> Decimal("NaN")
Decimal("NaN") Decimal("NaN")
>>> Decimal('-Infinity') >>> Decimal("-Infinity")
Decimal("-Infinity") Decimal("-Infinity")
\end{verbatim} \end{verbatim}
@ -233,7 +235,6 @@ clear the flags before each set of monitored computations by using the
\begin{verbatim} \begin{verbatim}
>>> setcontext(ExtendedContext) >>> setcontext(ExtendedContext)
>>> getcontext().clear_flags()
>>> Decimal(355) / Decimal(113) >>> Decimal(355) / Decimal(113)
Decimal("3.14159292") Decimal("3.14159292")
>>> getcontext() >>> getcontext()
@ -314,16 +315,16 @@ as other Python numeric types.
a sign (\constant{0} for positive or \constant{1} for negative), a sign (\constant{0} for positive or \constant{1} for negative),
a \class{tuple} of digits, and an exponent represented as an integer. a \class{tuple} of digits, and an exponent represented as an integer.
For example, \samp{Decimal((0, (1, 4, 1, 4), -3))} returns 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 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}, numeric string syntax. If the context traps \constant{ConversionSyntax},
an exception is raised; otherwise, the constructor returns a new Decimal an exception is raised; otherwise, the constructor returns a new Decimal
with the value of \constant{NaN}. with the value of \constant{NaN}.
The context serves no other purpose. The number of significant digits 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 precision is not a factor. For example, \samp{Decimal("3.0000")} records
all four zeroes even if the context precision is only three. 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: have a number of more specialized methods:
\begin{methoddesc}{adjusted}{} \begin{methoddesc}{adjusted}{}
Return the number's adjusted exponent that results from shifting out the Return the adjusted exponent after shifting out the coefficient's rightmost
coefficients rightmost digits until only the lead digit remains: digits until only the lead digit remains: \code{Decimal("321e+5").adjusted()}
\code{Decimal("321e+5").adjusted()} returns seven. Used for determining returns seven. Used for determining the place value of the most significant
the place value of the most significant digit. digit.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{as_tuple}{} \begin{methoddesc}{as_tuple}{}
@ -373,11 +374,12 @@ have a number of more specialized methods:
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{normalize}{\optional{context}} \begin{methoddesc}{normalize}{\optional{context}}
Normalize the number by striping the rightmost trailing zeroes and Normalize the number by stripping the rightmost trailing zeroes and
converting any result equal to \constant{Decimal("0")} to Decimal("0e0"). converting any result equal to \constant{Decimal("0")} to
Used for producing a canonical value for members of an equivalence class. \constant{Decimal("0e0")}. Used for producing canonical values for members
For example, \code{Decimal("32.100")} and \code{Decimal("0.321000e+2")} of an equivalence class. For example, \code{Decimal("32.100")} and
both normalize to the equivalent value \code{Decimal("32.1")} \code{Decimal("0.321000e+2")} both normalize to the equivalent value
\code{Decimal("32.1")},
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{quantize} \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 rounding method in \var{rounding}, then in \var{context}, and then
in the current context. 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 the resulting exponent is greater than \member{Emax} or less than
\member{Etiny}. \member{Etiny}.
\end{methoddesc} \end{methoddesc}
@ -401,7 +403,7 @@ have a number of more specialized methods:
as \var{self}. as \var{self}.
\end{methoddesc} \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 Test whether self and other have the same exponent or whether both
are \constant{NaN}. are \constant{NaN}.
\end{methoddesc} \end{methoddesc}
@ -411,7 +413,7 @@ have a number of more specialized methods:
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{to_eng_string}{\optional{context}} \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 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 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} \end{methoddesc}
\begin{methoddesc}{to_integral}{\optional{rounding\optional{, context}}} \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, or \constant{Rounded}. If given, applies \var{rounding}; otherwise,
uses the rounding method in either the supplied \var{context} or the uses the rounding method in either the supplied \var{context} or the
current context. 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 Specification. Precision is set to nine. Rounding is set to
\constant{ROUND_HALF_EVEN}. All flags are cleared. No traps are enabled \constant{ROUND_HALF_EVEN}. All flags are cleared. No traps are enabled
(so that exceptions are not raised during computations). (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*} \end{classdesc*}
\begin{classdesc*}{DefaultContext} \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, (with initial release having precision=28, rounding=ROUND_HALF_EVEN,
cleared flags, and no traps enabled). cleared flags, and no traps enabled).
\end{classdesc*} \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, \begin{classdesc}{Context}{prec=None, rounding=None, trap_enablers=None,
flags=None, Emin=None, Emax=None, capitals=1} 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 \var{flags} field is not specified or is \constant{None}, all flags are
cleared. 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. arithmetic operations in the context.
The \var{rounding} option is one of: \constant{ROUND_CEILING}, The \var{rounding} option is one of: \constant{ROUND_CEILING},
\constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN}, \constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN}
\constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, or (towards zero), \constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, or
\constant{ROUND_UP}. \constant{ROUND_UP} (away from zero).
The \var{trap_enablers} and \var{flags} fields are mappings from signals The \var{trap_enablers} and \var{flags} fields are mappings from signals
to either \constant{0} or \constant{1}. 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}. exponont is set to \constant{Etiny}.
\end{methoddesc} \end{methoddesc}
The usual approach to working with decimals is to create Decimal \begin{methoddesc}{Etop}{}
instances and then apply arithmetic operations which take place Returns a value equal to \samp{Emax - prec + 1}.
within the current context for the active thread. An alternate \end{methoddesc}
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.
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} \begin{methoddesc}{abs}{x}
Returns the absolute value of \var{x}. Returns the absolute value of \var{x}.
@ -570,7 +582,7 @@ only briefed recounted here.
Return \var{x} divided by \var{y}. Return \var{x} divided by \var{y}.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{divide}{x, y} \begin{methoddesc}{divmod}{x, y}
Divides two numbers and returns the integer part of the result. Divides two numbers and returns the integer part of the result.
\end{methoddesc} \end{methoddesc}
@ -589,7 +601,7 @@ only briefed recounted here.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{minus}{x} \begin{methoddesc}{minus}{x}
Minus corresponds to unary prefix minus in Python. Minus corresponds to the unary prefix minus operator in Python.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{multiply}{x, y} \begin{methoddesc}{multiply}{x, y}
@ -604,7 +616,7 @@ only briefed recounted here.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{plus}{x} \begin{methoddesc}{plus}{x}
Minus corresponds to unary prefix plus in Python. Minus corresponds to the unary prefix plus operator in Python.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{power}{x, y\optional{, modulo}} \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. the left-hand operand is inverted (divided into 1) before use.
If the increased precision needed for the intermediate calculations exceeds If the increased precision needed for the intermediate calculations exceeds
the capabilities of the implementation then an Invalid operation condition the capabilities of the implementation then an \constant{InvalidOperation}
is raised. condition is signaled.
If, when raising to a negative power, an underflow occurs during the 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. division into 1, the operation is not halted at that point but continues.
@ -665,7 +677,7 @@ only briefed recounted here.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{substract}{x, y} \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} \end{methoddesc}
\begin{methoddesc}{to_eng_string}{} \begin{methoddesc}{to_eng_string}{}
@ -677,12 +689,12 @@ only briefed recounted here.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{to_integral}{x} \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}. or \constant{Rounded}.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{to_sci_string}{} \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} \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. The context flag is incremented whenever the condition is encountered.
After the computation, flags may be checked for informational 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 After checking the flags, be sure to clear all flags before starting
the next computation. the next computation.
@ -714,7 +726,7 @@ exception is raised upon encountering the condition.
\end{classdesc*} \end{classdesc*}
\begin{classdesc*}{ConversionSyntax} \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 Decimal converts only strings conforming to the numeric string
syntax. If this signal is not trapped, returns \constant{NaN}. syntax. If this signal is not trapped, returns \constant{NaN}.
@ -794,7 +806,7 @@ exception is raised upon encountering the condition.
\begin{classdesc*}{Rounded} \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 Signaled whenever rounding discards digits; even if those digits are
zero (such as rounding \constant{5.00} to \constant{5.0}). If not 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}} \subsection{Working with threads \label{decimal-threads}}
The \function{getcontext()} function accesses a different \class{Context} The \function{getcontext()} function accesses a different \class{Context}
object for each thread. Having separate contexts means that threads may make object for each thread. Having separate thread contexts means that threads
changes (such as \code{getcontext.prec=10}) without interfering with other may make changes (such as \code{getcontext.prec=10}) without interfering with
threads and without needing mutexes. other threads and without needing mutexes.
Likewise, the \function{setcontext()} function automatically assigns its target Likewise, the \function{setcontext()} function automatically assigns its target
to the current thread. 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: be a race condition with threads calling \function{getcontext()}. For example:
\begin{verbatim} \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.prec=12
DefaultContext.rounding=ROUND_DOWN DefaultContext.rounding=ROUND_DOWN
DefaultContext.trap_enablers=dict.fromkeys(Signals, 0) DefaultContext.trap_enablers=dict.fromkeys(Signals, 0)
@ -944,7 +956,7 @@ def pi():
t = (t * n) / d t = (t * n) / d
c += t c += t
getcontext().prec -= 2 getcontext().prec -= 2
return c + 0 return c + 0 # Adding zero causes rounding to the new precision
def exp(x): def exp(x):
"""Return e raised to the power of x. Result type matches input type. """Return e raised to the power of x. Result type matches input type.