[Python-checkins] python/nondist/sandbox/decimal libdecimal.tex, 1.3, 1.4

[rhettinger at users.sourceforge.net]

Update of /cvsroot/python/python/nondist/sandbox/decimal
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv14446

Modified Files:
	libdecimal.tex 
Log Message:
Add the signals section

Index: libdecimal.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/decimal/libdecimal.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** libdecimal.tex	4 Jul 2004 07:42:41 -0000	1.3
--- libdecimal.tex	4 Jul 2004 08:55:42 -0000	1.4
***************
*** 155,158 ****
--- 155,296 ----
  \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 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}
+ 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*}
+ 
+ 
+ 
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \subsection{Working with threads \label{decimal-threads}}