[Python-checkins]
python/nondist/sandbox/decimal libdecimal.tex, 1.5, 1.6
rhettinger at users.sourceforge.net
rhettinger at users.sourceforge.net
Sun Jul 4 10:04:08 EDT 2004
Update of /cvsroot/python/python/nondist/sandbox/decimal
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv308
Modified Files:
libdecimal.tex
Log Message:
Add the section for Decimal objects.
Index: libdecimal.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/decimal/libdecimal.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** libdecimal.tex 4 Jul 2004 10:52:14 -0000 1.5
--- libdecimal.tex 4 Jul 2004 14:03:59 -0000 1.6
***************
*** 1,3 ****
! \section{\module{decimal} ---
Decimal floating point arithmetic}
--- 1,3 ----
! \section{\module{decimal} ---
Decimal floating point arithmetic}
***************
*** 295,301 ****
--- 295,434 ----
\subsection{Decimal objects \label{decimal-decimal}}
+ \begin{classdesc}{Decimal}{\optional{value \optional{, context}}}
+ Constructs a new \class{Decimal} object based from the \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, or 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 to make 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}}
+
+
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Signals \label{decimal-signals}}
***************
*** 310,314 ****
the next computation.
! If the context's trap enable 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}
--- 443,447 ----
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}
***************
*** 316,320 ****
-
\begin{classdesc*}{Clamped}
Altered an exponent to fit representation constraints.
--- 449,452 ----
***************
*** 438,441 ****
--- 570,591 ----
+ 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}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
More information about the Python-checkins
mailing list