sam-t2/devtools/v9/html/python/lib/module-decimal.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="module-math.html" />
<link rel="prev" href="module-test.testsupport.html" />
<link rel="parent" href="misc.html" />
<link rel="next" href="decimal-tutorial.html" />
<meta name='aesop' content='information' />
<title>5.6 decimal -- Decimal floating point arithmetic</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.5 test.test_support  "
  href="module-test.testsupport.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. Miscellaneous Services"
  href="misc.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.1 Quick-start Tutorial"
  href="decimal-tutorial.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="module-test.testsupport.html">5.5 test.test_support  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="misc.html">5. Miscellaneous Services</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="decimal-tutorial.html">5.6.1 Quick-start Tutorial</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION007600000000000000000">
5.6 <tt class="module">decimal</tt> --
         Decimal floating point arithmetic</A>
</H1>

<P>
<A NAME="module-decimal"></A>

<P>

<P>

<P>

<span class="versionnote">New in version 2.4.</span>

<P>
The <tt class="module">decimal</tt> module provides support for decimal floating point
arithmetic.  It offers several advantages over the <tt class="class">float()</tt> datatype:

<P>

<UL>
<LI>Decimal numbers can be represented exactly.  In contrast, numbers like
<tt class="constant">1.1</tt> do not have an exact representation in binary floating point.
End users typically would not expect <tt class="constant">1.1</tt> to display as
<tt class="constant">1.1000000000000001</tt> as it does with binary floating point.

<P>
</LI>
<LI>The exactness carries over into arithmetic.  In decimal floating point,
"<tt class="samp">0.1 + 0.1 + 0.1 - 0.3</tt>" is exactly equal to zero.  In binary floating
point, result is <tt class="constant">5.5511151231257827e-017</tt>.  While near to zero, the
differences prevent reliable equality testing and differences can accumulate.
For this reason, decimal would be preferred in accounting applications which
have strict equality invariants.

<P>
</LI>
<LI>The decimal module incorporates a notion of significant places so that
"<tt class="samp">1.30 + 1.20</tt>" is <tt class="constant">2.50</tt>.  The trailing zero is kept to indicate
significance.  This is the customary presentation for monetary applications. For
multiplication, the ``schoolbook'' approach uses all the figures in the
multiplicands.  For instance, "<tt class="samp">1.3 * 1.2</tt>" gives <tt class="constant">1.56</tt> while
"<tt class="samp">1.30 * 1.20</tt>" gives <tt class="constant">1.5600</tt>.

<P>
</LI>
<LI>Unlike hardware based binary floating point, the decimal module has a user
settable precision (defaulting to 28 places) which can be as large as needed for
a given problem:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; getcontext().prec = 6
&gt;&gt;&gt; Decimal(1) / Decimal(7)
Decimal("0.142857")
&gt;&gt;&gt; getcontext().prec = 28
&gt;&gt;&gt; Decimal(1) / Decimal(7)
Decimal("0.1428571428571428571428571429")
</pre></div>

<P>
</LI>
<LI>Both binary and decimal floating point are implemented in terms of published
standards.  While the built-in float type exposes only a modest portion of its
capabilities, the decimal module exposes all required parts of the standard.
When needed, the programmer has full control over rounding and signal handling.

<P>
</LI>
</UL>

<P>
The module design is centered around three concepts:  the decimal number, the
context for arithmetic, and signals.

<P>
A decimal number is immutable.  It has a sign, coefficient digits, and an
exponent.  To preserve significance, the coefficient digits do not truncate
trailing zeroes.  Decimals also include special values such as
<tt class="constant">Infinity</tt>, <tt class="constant">-Infinity</tt>, and <tt class="constant">NaN</tt>.  The standard
also differentiates <tt class="constant">-0</tt> from <tt class="constant">+0</tt>.

<P>
The context for arithmetic is an environment specifying precision, rounding
rules, limits on exponents, flags indicating the results of operations,
and trap enablers which determine whether signals are treated as
exceptions.  Rounding options include <tt class="constant">ROUND_CEILING</tt>,
<tt class="constant">ROUND_DOWN</tt>, <tt class="constant">ROUND_FLOOR</tt>, <tt class="constant">ROUND_HALF_DOWN</tt>,
<tt class="constant">ROUND_HALF_EVEN</tt>, <tt class="constant">ROUND_HALF_UP</tt>, and <tt class="constant">ROUND_UP</tt>.

<P>
Signals are groups of exceptional conditions arising during the course of
computation.  Depending on the needs of the application, signals may be
ignored, considered as informational, or treated as exceptions. The signals in
the decimal module are: <tt class="constant">Clamped</tt>, <tt class="constant">InvalidOperation</tt>,
<tt class="constant">DivisionByZero</tt>, <tt class="constant">Inexact</tt>, <tt class="constant">Rounded</tt>,
<tt class="constant">Subnormal</tt>, <tt class="constant">Overflow</tt>, and <tt class="constant">Underflow</tt>.

<P>
For each signal there is a flag and a trap enabler.  When a signal is
encountered, its flag incremented from zero and, then, if the trap enabler
is set to one, an exception is raised.  Flags are sticky, so the user
needs to reset them before monitoring a calculation.

<P>
<div class="seealso">
  <p class="heading">See Also:</p>

  <div class="seetext"><p>IBM's General Decimal Arithmetic Specification,
           <em class="citetitle"><a
 href="http://www2.hursley.ibm.com/decimal/decarith.html"
 title="The General Decimal Arithmetic Specification"
 >The General Decimal Arithmetic Specification</a></em>.</p></div>

<P>
<div class="seetext"><p>IEEE standard 854-1987,
           <em class="citetitle"><a
 href="http://www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html"
 title="Unofficial IEEE 854 Text"
 >Unofficial IEEE 854 Text</a></em>.</p></div>
</div>

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="decimal-tutorial.html">5.6.1 Quick-start Tutorial</a>
<LI><A href="node178.html">5.6.2 Decimal objects</a>
<LI><A href="decimal-decimal.html">5.6.3 Context objects</a>
<LI><A href="decimal-signals.html">5.6.4 Signals</a>
<LI><A href="decimal-notes.html">5.6.5 Floating Point Notes</a>
<UL>
<LI><A href="node182.html">5.6.5.1 Mitigating round-off error with increased precision</a>
<LI><A href="node183.html">5.6.5.2 Special values</a>
</ul>
<LI><A href="decimal-threads.html">5.6.6 Working with threads</a>
<LI><A href="decimal-recipes.html">5.6.7 Recipes</a>
<LI><A href="decimal-faq.html">5.6.8 Decimal FAQ</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<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.5 test.test_support  "
  href="module-test.testsupport.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. Miscellaneous Services"
  href="misc.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.1 Quick-start Tutorial"
  href="decimal-tutorial.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="module-test.testsupport.html">5.5 test.test_support  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="misc.html">5. Miscellaneous Services</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="decimal-tutorial.html">5.6.1 Quick-start Tutorial</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>