sam-t2/devtools/v8plus/html/python/lib/decimal-signals.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="decimal-notes.html" />
<link rel="prev" href="decimal-decimal.html" />
<link rel="parent" href="module-decimal.html" />
<link rel="next" href="decimal-notes.html" />
<meta name='aesop' content='information' />
<title>5.6.4 Signals </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.6.3 Context objects"
  href="decimal-decimal.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="5.6 decimal  "
  href="module-decimal.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="5.6.5 Floating Point Notes"
  href="decimal-notes.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="decimal-decimal.html">5.6.3 Context objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-decimal.html">5.6 decimal  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="decimal-notes.html">5.6.5 Floating Point Notes</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION007640000000000000000"></A><A NAME="decimal-signals"></A>
<BR>
5.6.4 Signals
</H2>

<P>
Signals represent conditions that arise during computation.
Each corresponds to one context flag and one context trap enabler.

<P>
The context flag is incremented whenever the condition is encountered.
After the computation, flags may be checked for informational
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.

<P>
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
<tt class="class">DivisionByZero</tt> trap is set, then a <tt class="exception">DivisionByZero</tt>
exception is raised upon encountering the condition.

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1240' xml:id='l2h-1240' class="class">Clamped</tt></b>
<dd>
    Altered an exponent to fit representation constraints.

<P>
Typically, clamping occurs when an exponent falls outside the context's
    <tt class="member">Emin</tt> and <tt class="member">Emax</tt> limits.  If possible, the exponent is
    reduced to fit by adding zeroes to the coefficient.
</dl>

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1241' xml:id='l2h-1241' class="class">DecimalException</tt></b>
<dd>
    Base class for other signals and is a subclass of
    <tt class="exception">ArithmeticError</tt>.
</dl>

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1242' xml:id='l2h-1242' class="class">DivisionByZero</tt></b>
<dd>
    Signals the division of a non-infinite number by zero.

<P>
Can occur with division, modulo division, or when raising a number to a
    negative power.  If this signal is not trapped, returns
    <tt class="constant">Infinity</tt> or <tt class="constant">-Infinity</tt> with the sign determined by
    the inputs to the calculation.
</dl>

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1243' xml:id='l2h-1243' class="class">Inexact</tt></b>
<dd>
    Indicates that rounding occurred and the result is not exact.

<P>
Signals when 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.
</dl>

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1244' xml:id='l2h-1244' class="class">InvalidOperation</tt></b>
<dd>
    An invalid operation was performed.

<P>
Indicates that an operation was requested that does not make sense.
    If not trapped, returns <tt class="constant">NaN</tt>.  Possible causes include:

<P>
<div class="verbatim"><pre>
        Infinity - Infinity
        0 * Infinity
        Infinity / Infinity
        x % 0
        Infinity % x
        x._rescale( non-integer )
        sqrt(-x) and x &gt; 0
        0 ** 0
        x ** (non-integer)
        x ** Infinity
</pre></div>
</dl>

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1245' xml:id='l2h-1245' class="class">Overflow</tt></b>
<dd>
    Numerical overflow.

<P>
Indicates the exponent is larger than <tt class="member">Emax</tt> 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 <tt class="constant">Infinity</tt>.  In either case, <tt class="class">Inexact</tt> and
    <tt class="class">Rounded</tt> are also signaled.
</dl>

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1246' xml:id='l2h-1246' class="class">Rounded</tt></b>
<dd>
    Rounding occurred though possibly no information was lost.

<P>
Signaled whenever rounding discards digits; even if those digits are
    zero (such as rounding <tt class="constant">5.00</tt> to <tt class="constant">5.0</tt>).   If not
    trapped, returns the result unchanged.  This signal is used to detect
    loss of significant digits.
</dl>

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1247' xml:id='l2h-1247' class="class">Subnormal</tt></b>
<dd>
    Exponent was lower than <tt class="member">Emin</tt> prior to rounding.

<P>
Occurs when an operation result is subnormal (the exponent is too small).
    If not trapped, returns the result unchanged.
</dl>

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1248' xml:id='l2h-1248' class="class">Underflow</tt></b>
<dd>
    Numerical underflow with result rounded to zero.

<P>
Occurs when a subnormal result is pushed to zero by rounding.
    <tt class="class">Inexact</tt> and <tt class="class">Subnormal</tt> are also signaled.
</dl>

<P>
The following table summarizes the hierarchy of signals:

<P>
<div class="verbatim"><pre>
    exceptions.ArithmeticError(exceptions.StandardError)
        DecimalException
            Clamped
            DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
            Inexact
                Overflow(Inexact, Rounded)
                Underflow(Inexact, Rounded, Subnormal)
            InvalidOperation
            Rounded
            Subnormal
</pre></div>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.6.3 Context objects"
  href="decimal-decimal.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="5.6 decimal  "
  href="module-decimal.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="5.6.5 Floating Point Notes"
  href="decimal-notes.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="decimal-decimal.html">5.6.3 Context objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-decimal.html">5.6 decimal  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="decimal-notes.html">5.6.5 Floating Point Notes</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>