[OpenSPARC-T2-SAM] / 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>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="decimal-notes.html" />
	13	<link rel="prev" href="decimal-decimal.html" />
	14	<link rel="parent" href="module-decimal.html" />
	15	<link rel="next" href="decimal-notes.html" />
	16	<meta name='aesop' content='information' />
	17	<title>5.6.4 Signals </title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="5.6.3 Context objects"
	25	href="decimal-decimal.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="5.6 decimal "
	28	href="module-decimal.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="5.6.5 Floating Point Notes"
	31	href="decimal-notes.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="decimal-decimal.html">5.6.3 Context objects</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="module-decimal.html">5.6 decimal </A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="decimal-notes.html">5.6.5 Floating Point Notes</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION007640000000000000000"></A><A NAME="decimal-signals"></A>
	56	<BR>
	57	5.6.4 Signals
	58	</H2>
	59
	60	<P>
	61	Signals represent conditions that arise during computation.
	62	Each corresponds to one context flag and one context trap enabler.
	63
	64	<P>
65	The context flag is incremented whenever the condition is encountered.
66	After the computation, flags may be checked for informational
67	purposes (for instance, to determine whether a computation was exact).
68	After checking the flags, be sure to clear all flags before starting
69	the next computation.
70
71	<P>
72	If the context's trap enabler is set for the signal, then the condition
73	causes a Python exception to be raised. For example, if the
74	<tt class="class">DivisionByZero</tt> trap is set, then a <tt class="exception">DivisionByZero</tt>
75	exception is raised upon encountering the condition.
76
77	<P>
78	<dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1240' xml:id='l2h-1240' class="class">Clamped</tt></b>
79	<dd>
80	Altered an exponent to fit representation constraints.
81
82	<P>
83	Typically, clamping occurs when an exponent falls outside the context's
84	<tt class="member">Emin</tt> and <tt class="member">Emax</tt> limits. If possible, the exponent is
85	reduced to fit by adding zeroes to the coefficient.
86	</dl>
87
88	<P>
89	<dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1241' xml:id='l2h-1241' class="class">DecimalException</tt></b>
90	<dd>
91	Base class for other signals and is a subclass of
92	<tt class="exception">ArithmeticError</tt>.
93	</dl>
94
95	<P>
96	<dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1242' xml:id='l2h-1242' class="class">DivisionByZero</tt></b>
97	<dd>
98	Signals the division of a non-infinite number by zero.
99
100	<P>
101	Can occur with division, modulo division, or when raising a number to a
102	negative power. If this signal is not trapped, returns
103	<tt class="constant">Infinity</tt> or <tt class="constant">-Infinity</tt> with the sign determined by
104	the inputs to the calculation.
105	</dl>
106
107	<P>
108	<dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1243' xml:id='l2h-1243' class="class">Inexact</tt></b>
109	<dd>
110	Indicates that rounding occurred and the result is not exact.
111
112	<P>
113	Signals when non-zero digits were discarded during rounding. The rounded
114	result is returned. The signal flag or trap is used to detect when
115	results are inexact.
116	</dl>
117
118	<P>
119	<dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1244' xml:id='l2h-1244' class="class">InvalidOperation</tt></b>
120	<dd>
121	An invalid operation was performed.
122
123	<P>
124	Indicates that an operation was requested that does not make sense.
125	If not trapped, returns <tt class="constant">NaN</tt>. Possible causes include:
126
127	<P>
128	<div class="verbatim"><pre>
129	Infinity - Infinity
130	0 * Infinity
131	Infinity / Infinity
132	x % 0
133	Infinity % x
134	x._rescale( non-integer )
135	sqrt(-x) and x > 0
136	0 ** 0
137	x ** (non-integer)
138	x ** Infinity
139	</pre></div>
140	</dl>
141
142	<P>
143	<dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1245' xml:id='l2h-1245' class="class">Overflow</tt></b>
144	<dd>
145	Numerical overflow.
146
147	<P>
148	Indicates the exponent is larger than <tt class="member">Emax</tt> after rounding has
149	occurred. If not trapped, the result depends on the rounding mode, either
150	pulling inward to the largest representable finite number or rounding
151	outward to <tt class="constant">Infinity</tt>. In either case, <tt class="class">Inexact</tt> and
152	<tt class="class">Rounded</tt> are also signaled.
153	</dl>
154
155	<P>
156	<dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1246' xml:id='l2h-1246' class="class">Rounded</tt></b>
157	<dd>
158	Rounding occurred though possibly no information was lost.
159
160	<P>
161	Signaled whenever rounding discards digits; even if those digits are
162	zero (such as rounding <tt class="constant">5.00</tt> to <tt class="constant">5.0</tt>). If not
163	trapped, returns the result unchanged. This signal is used to detect
164	loss of significant digits.
165	</dl>
166
167	<P>
168	<dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1247' xml:id='l2h-1247' class="class">Subnormal</tt></b>
169	<dd>
170	Exponent was lower than <tt class="member">Emin</tt> prior to rounding.
171
172	<P>
173	Occurs when an operation result is subnormal (the exponent is too small).
174	If not trapped, returns the result unchanged.
175	</dl>
176
177	<P>
178	<dl><dt><b><span class="typelabel">class</span> <tt id='l2h-1248' xml:id='l2h-1248' class="class">Underflow</tt></b>
179	<dd>
180	Numerical underflow with result rounded to zero.
181
182	<P>
183	Occurs when a subnormal result is pushed to zero by rounding.
184	<tt class="class">Inexact</tt> and <tt class="class">Subnormal</tt> are also signaled.
185	</dl>
186
187	<P>
188	The following table summarizes the hierarchy of signals:
189
190	<P>
191	<div class="verbatim"><pre>
192	exceptions.ArithmeticError(exceptions.StandardError)
193	DecimalException
194	Clamped
195	DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
196	Inexact
197	Overflow(Inexact, Rounded)
198	Underflow(Inexact, Rounded, Subnormal)
199	InvalidOperation
200	Rounded
201	Subnormal
202	</pre></div>
203
204	<P>
205
206	<DIV CLASS="navigation">
207	<div class='online-navigation'>
208	<p></p><hr />
209	<table align="center" width="100%" cellpadding="0" cellspacing="2">
210	<tr>
211	<td class='online-navigation'><a rel="prev" title="5.6.3 Context objects"
212	href="decimal-decimal.html"><img src='../icons/previous.png'
213	border='0' height='32' alt='Previous Page' width='32' /></A></td>
214	<td class='online-navigation'><a rel="parent" title="5.6 decimal "
215	href="module-decimal.html"><img src='../icons/up.png'
216	border='0' height='32' alt='Up One Level' width='32' /></A></td>
217	<td class='online-navigation'><a rel="next" title="5.6.5 Floating Point Notes"
218	href="decimal-notes.html"><img src='../icons/next.png'
219	border='0' height='32' alt='Next Page' width='32' /></A></td>
220	<td align="center" width="100%">Python Library Reference</td>
221	<td class='online-navigation'><a rel="contents" title="Table of Contents"
222	href="contents.html"><img src='../icons/contents.png'
223	border='0' height='32' alt='Contents' width='32' /></A></td>
224	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
225	border='0' height='32' alt='Module Index' width='32' /></a></td>
226	<td class='online-navigation'><a rel="index" title="Index"
227	href="genindex.html"><img src='../icons/index.png'
228	border='0' height='32' alt='Index' width='32' /></A></td>
229	</tr></table>
230	<div class='online-navigation'>
231	<b class="navlabel">Previous:</b>
232	<a class="sectref" rel="prev" href="decimal-decimal.html">5.6.3 Context objects</A>
233	<b class="navlabel">Up:</b>
234	<a class="sectref" rel="parent" href="module-decimal.html">5.6 decimal </A>
235	<b class="navlabel">Next:</b>
236	<a class="sectref" rel="next" href="decimal-notes.html">5.6.5 Floating Point Notes</A>
237	</div>
238	</div>
239	<hr />
240	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
241	</DIV>
242	<!--End of Navigation Panel-->
243	<ADDRESS>
244	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
245	</ADDRESS>
246	</BODY>
247	</HTML>