projects / OpenSPARC-T2-DV / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / module-decimal.html
CommitLineData
86530b38
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="module-math.html" />
13<link rel="prev" href="module-test.testsupport.html" />
14<link rel="parent" href="misc.html" />
15<link rel="next" href="decimal-tutorial.html" />
16<meta name='aesop' content='information' />
17<title>5.6 decimal -- Decimal floating point arithmetic</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.5 test.test_support "
25 href="module-test.testsupport.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. Miscellaneous Services"
28 href="misc.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.1 Quick-start Tutorial"
31 href="decimal-tutorial.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="module-test.testsupport.html">5.5 test.test_support </A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="misc.html">5. Miscellaneous Services</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="decimal-tutorial.html">5.6.1 Quick-start Tutorial</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION007600000000000000000">
565.6 <tt class="module">decimal</tt> --
57 Decimal floating point arithmetic</A>
58</H1>
59
60<P>
61<A NAME="module-decimal"></A>
62
63<P>
64
65<P>
66
67<P>
68
69<span class="versionnote">New in version 2.4.</span>
70
71<P>
72The <tt class="module">decimal</tt> module provides support for decimal floating point
73arithmetic. It offers several advantages over the <tt class="class">float()</tt> datatype:
74
75<P>
76
77<UL>
78<LI>Decimal numbers can be represented exactly. In contrast, numbers like
79<tt class="constant">1.1</tt> do not have an exact representation in binary floating point.
80End users typically would not expect <tt class="constant">1.1</tt> to display as
81<tt class="constant">1.1000000000000001</tt> as it does with binary floating point.
82
83<P>
84</LI>
85<LI>The exactness carries over into arithmetic. In decimal floating point,
86"<tt class="samp">0.1 + 0.1 + 0.1 - 0.3</tt>" is exactly equal to zero. In binary floating
87point, result is <tt class="constant">5.5511151231257827e-017</tt>. While near to zero, the
88differences prevent reliable equality testing and differences can accumulate.
89For this reason, decimal would be preferred in accounting applications which
90have strict equality invariants.
91
92<P>
93</LI>
94<LI>The decimal module incorporates a notion of significant places so that
95"<tt class="samp">1.30 + 1.20</tt>" is <tt class="constant">2.50</tt>. The trailing zero is kept to indicate
96significance. This is the customary presentation for monetary applications. For
97multiplication, the ``schoolbook'' approach uses all the figures in the
98multiplicands. For instance, "<tt class="samp">1.3 * 1.2</tt>" gives <tt class="constant">1.56</tt> while
99"<tt class="samp">1.30 * 1.20</tt>" gives <tt class="constant">1.5600</tt>.
100
101<P>
102</LI>
103<LI>Unlike hardware based binary floating point, the decimal module has a user
104settable precision (defaulting to 28 places) which can be as large as needed for
105a given problem:
106
107<P>
108<div class="verbatim"><pre>
109&gt;&gt;&gt; getcontext().prec = 6
110&gt;&gt;&gt; Decimal(1) / Decimal(7)
111Decimal("0.142857")
112&gt;&gt;&gt; getcontext().prec = 28
113&gt;&gt;&gt; Decimal(1) / Decimal(7)
114Decimal("0.1428571428571428571428571429")
115</pre></div>
116
117<P>
118</LI>
119<LI>Both binary and decimal floating point are implemented in terms of published
120standards. While the built-in float type exposes only a modest portion of its
121capabilities, the decimal module exposes all required parts of the standard.
122When needed, the programmer has full control over rounding and signal handling.
123
124<P>
125</LI>
126</UL>
127
128<P>
129The module design is centered around three concepts: the decimal number, the
130context for arithmetic, and signals.
131
132<P>
133A decimal number is immutable. It has a sign, coefficient digits, and an
134exponent. To preserve significance, the coefficient digits do not truncate
135trailing zeroes. Decimals also include special values such as
136<tt class="constant">Infinity</tt>, <tt class="constant">-Infinity</tt>, and <tt class="constant">NaN</tt>. The standard
137also differentiates <tt class="constant">-0</tt> from <tt class="constant">+0</tt>.
138
139<P>
140The context for arithmetic is an environment specifying precision, rounding
141rules, limits on exponents, flags indicating the results of operations,
142and trap enablers which determine whether signals are treated as
143exceptions. Rounding options include <tt class="constant">ROUND_CEILING</tt>,
144<tt class="constant">ROUND_DOWN</tt>, <tt class="constant">ROUND_FLOOR</tt>, <tt class="constant">ROUND_HALF_DOWN</tt>,
145<tt class="constant">ROUND_HALF_EVEN</tt>, <tt class="constant">ROUND_HALF_UP</tt>, and <tt class="constant">ROUND_UP</tt>.
146
147<P>
148Signals are groups of exceptional conditions arising during the course of
149computation. Depending on the needs of the application, signals may be
150ignored, considered as informational, or treated as exceptions. The signals in
151the decimal module are: <tt class="constant">Clamped</tt>, <tt class="constant">InvalidOperation</tt>,
152<tt class="constant">DivisionByZero</tt>, <tt class="constant">Inexact</tt>, <tt class="constant">Rounded</tt>,
153<tt class="constant">Subnormal</tt>, <tt class="constant">Overflow</tt>, and <tt class="constant">Underflow</tt>.
154
155<P>
156For each signal there is a flag and a trap enabler. When a signal is
157encountered, its flag incremented from zero and, then, if the trap enabler
158is set to one, an exception is raised. Flags are sticky, so the user
159needs to reset them before monitoring a calculation.
160
161<P>
162<div class="seealso">
163 <p class="heading">See Also:</p>
164
165 <div class="seetext"><p>IBM's General Decimal Arithmetic Specification,
166 <em class="citetitle"><a
167 href="http://www2.hursley.ibm.com/decimal/decarith.html"
168 title="The General Decimal Arithmetic Specification"
169 >The General Decimal Arithmetic Specification</a></em>.</p></div>
170
171<P>
172<div class="seetext"><p>IEEE standard 854-1987,
173 <em class="citetitle"><a
174 href="http://www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html"
175 title="Unofficial IEEE 854 Text"
176 >Unofficial IEEE 854 Text</a></em>.</p></div>
177</div>
178
179<P>
180
181<p><br /></p><hr class='online-navigation' />
182<div class='online-navigation'>
183<!--Table of Child-Links-->
184<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
185
186<UL CLASS="ChildLinks">
187<LI><A href="decimal-tutorial.html">5.6.1 Quick-start Tutorial</a>
188<LI><A href="node178.html">5.6.2 Decimal objects</a>
189<LI><A href="decimal-decimal.html">5.6.3 Context objects</a>
190<LI><A href="decimal-signals.html">5.6.4 Signals</a>
191<LI><A href="decimal-notes.html">5.6.5 Floating Point Notes</a>
192<UL>
193<LI><A href="node182.html">5.6.5.1 Mitigating round-off error with increased precision</a>
194<LI><A href="node183.html">5.6.5.2 Special values</a>
195</ul>
196<LI><A href="decimal-threads.html">5.6.6 Working with threads</a>
197<LI><A href="decimal-recipes.html">5.6.7 Recipes</a>
198<LI><A href="decimal-faq.html">5.6.8 Decimal FAQ</a>
199</ul>
200<!--End of Table of Child-Links-->
201</div>
202
203<DIV CLASS="navigation">
204<div class='online-navigation'>
205<p></p><hr />
206<table align="center" width="100%" cellpadding="0" cellspacing="2">
207<tr>
208<td class='online-navigation'><a rel="prev" title="5.5 test.test_support "
209 href="module-test.testsupport.html"><img src='../icons/previous.png'
210 border='0' height='32' alt='Previous Page' width='32' /></A></td>
211<td class='online-navigation'><a rel="parent" title="5. Miscellaneous Services"
212 href="misc.html"><img src='../icons/up.png'
213 border='0' height='32' alt='Up One Level' width='32' /></A></td>
214<td class='online-navigation'><a rel="next" title="5.6.1 Quick-start Tutorial"
215 href="decimal-tutorial.html"><img src='../icons/next.png'
216 border='0' height='32' alt='Next Page' width='32' /></A></td>
217<td align="center" width="100%">Python Library Reference</td>
218<td class='online-navigation'><a rel="contents" title="Table of Contents"
219 href="contents.html"><img src='../icons/contents.png'
220 border='0' height='32' alt='Contents' width='32' /></A></td>
221<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
222 border='0' height='32' alt='Module Index' width='32' /></a></td>
223<td class='online-navigation'><a rel="index" title="Index"
224 href="genindex.html"><img src='../icons/index.png'
225 border='0' height='32' alt='Index' width='32' /></A></td>
226</tr></table>
227<div class='online-navigation'>
228<b class="navlabel">Previous:</b>
229<a class="sectref" rel="prev" href="module-test.testsupport.html">5.5 test.test_support </A>
230<b class="navlabel">Up:</b>
231<a class="sectref" rel="parent" href="misc.html">5. Miscellaneous Services</A>
232<b class="navlabel">Next:</b>
233<a class="sectref" rel="next" href="decimal-tutorial.html">5.6.1 Quick-start Tutorial</A>
234</div>
235</div>
236<hr />
237<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
238</DIV>
239<!--End of Navigation Panel-->
240<ADDRESS>
241See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
242</ADDRESS>
243</BODY>
244</HTML>
Full OpenSPARC design & verification tarball including full HDL.