mirror of
https://github.com/python/cpython
synced 2024-10-08 02:59:48 +00:00
Fix markup, typos, and nits.
This commit is contained in:
parent
dfef882095
commit
536f76b25a
|
@ -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.
|
||||
|
|
Loading…
Reference in a new issue