2419 lines
230 KiB
HTML
2419 lines
230 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>decimal — Decimal fixed point and floating point arithmetic — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="fractions — Rational numbers" href="fractions.html" />
|
||
<link rel="prev" title="cmath — Mathematical functions for complex numbers" href="cmath.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/decimal.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="fractions.html" title="fractions — Rational numbers"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="cmath.html" title="cmath — Mathematical functions for complex numbers"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="numeric.html" accesskey="U">Numeric and Mathematical Modules</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-decimal">
|
||
<span id="decimal-decimal-fixed-point-and-floating-point-arithmetic"></span><h1><a class="reference internal" href="#module-decimal" title="decimal: Implementation of the General Decimal Arithmetic Specification."><code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal</span></code></a> — Decimal fixed point and floating point arithmetic<a class="headerlink" href="#module-decimal" title="Permalink to this headline">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/decimal.py">Lib/decimal.py</a></p>
|
||
<hr class="docutils" />
|
||
<p>The <a class="reference internal" href="#module-decimal" title="decimal: Implementation of the General Decimal Arithmetic Specification."><code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal</span></code></a> module provides support for fast correctly-rounded
|
||
decimal floating point arithmetic. It offers several advantages over the
|
||
<a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> datatype:</p>
|
||
<ul>
|
||
<li><p>Decimal “is based on a floating-point model which was designed with people
|
||
in mind, and necessarily has a paramount guiding principle – computers must
|
||
provide an arithmetic that works in the same way as the arithmetic that
|
||
people learn at school.” – excerpt from the decimal arithmetic specification.</p></li>
|
||
<li><p>Decimal numbers can be represented exactly. In contrast, numbers like
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">1.1</span></code> and <code class="xref py py-const docutils literal notranslate"><span class="pre">2.2</span></code> do not have exact representations in binary
|
||
floating point. End users typically would not expect <code class="docutils literal notranslate"><span class="pre">1.1</span> <span class="pre">+</span> <span class="pre">2.2</span></code> to display
|
||
as <code class="xref py py-const docutils literal notranslate"><span class="pre">3.3000000000000003</span></code> as it does with binary floating point.</p></li>
|
||
<li><p>The exactness carries over into arithmetic. In decimal floating point, <code class="docutils literal notranslate"><span class="pre">0.1</span>
|
||
<span class="pre">+</span> <span class="pre">0.1</span> <span class="pre">+</span> <span class="pre">0.1</span> <span class="pre">-</span> <span class="pre">0.3</span></code> is exactly equal to zero. In binary floating point, the result
|
||
is <code class="xref py py-const docutils literal notranslate"><span class="pre">5.5511151231257827e-017</span></code>. While near to zero, the differences
|
||
prevent reliable equality testing and differences can accumulate. For this
|
||
reason, decimal is preferred in accounting applications which have strict
|
||
equality invariants.</p></li>
|
||
<li><p>The decimal module incorporates a notion of significant places so that <code class="docutils literal notranslate"><span class="pre">1.30</span>
|
||
<span class="pre">+</span> <span class="pre">1.20</span></code> is <code class="xref py py-const docutils literal notranslate"><span class="pre">2.50</span></code>. 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, <code class="docutils literal notranslate"><span class="pre">1.3</span> <span class="pre">*</span> <span class="pre">1.2</span></code> gives <code class="xref py py-const docutils literal notranslate"><span class="pre">1.56</span></code> while <code class="docutils literal notranslate"><span class="pre">1.30</span> <span class="pre">*</span>
|
||
<span class="pre">1.20</span></code> gives <code class="xref py py-const docutils literal notranslate"><span class="pre">1.5600</span></code>.</p></li>
|
||
<li><p>Unlike hardware based binary floating point, the decimal module has a user
|
||
alterable precision (defaulting to 28 places) which can be as large as needed for
|
||
a given problem:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">decimal</span> <span class="k">import</span> <span class="o">*</span>
|
||
<span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">6</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.142857')</span>
|
||
<span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">28</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.1428571428571428571428571429')</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>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.
|
||
This includes an option to enforce exact arithmetic by using exceptions
|
||
to block any inexact operations.</p></li>
|
||
<li><p>The decimal module was designed to support “without prejudice, both exact
|
||
unrounded decimal arithmetic (sometimes called fixed-point arithmetic)
|
||
and rounded floating-point arithmetic.” – excerpt from the decimal
|
||
arithmetic specification.</p></li>
|
||
</ul>
|
||
<p>The module design is centered around three concepts: the decimal number, the
|
||
context for arithmetic, and signals.</p>
|
||
<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 zeros. Decimals also include special values such as
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">Infinity</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">-Infinity</span></code>, and <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code>. The standard also
|
||
differentiates <code class="xref py py-const docutils literal notranslate"><span class="pre">-0</span></code> from <code class="xref py py-const docutils literal notranslate"><span class="pre">+0</span></code>.</p>
|
||
<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 <a class="reference internal" href="#decimal.ROUND_CEILING" title="decimal.ROUND_CEILING"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_CEILING</span></code></a>, <a class="reference internal" href="#decimal.ROUND_DOWN" title="decimal.ROUND_DOWN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_DOWN</span></code></a>,
|
||
<a class="reference internal" href="#decimal.ROUND_FLOOR" title="decimal.ROUND_FLOOR"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_FLOOR</span></code></a>, <a class="reference internal" href="#decimal.ROUND_HALF_DOWN" title="decimal.ROUND_HALF_DOWN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_DOWN</span></code></a>, <a class="reference internal" href="#decimal.ROUND_HALF_EVEN" title="decimal.ROUND_HALF_EVEN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_EVEN</span></code></a>,
|
||
<a class="reference internal" href="#decimal.ROUND_HALF_UP" title="decimal.ROUND_HALF_UP"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_UP</span></code></a>, <a class="reference internal" href="#decimal.ROUND_UP" title="decimal.ROUND_UP"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_UP</span></code></a>, and <a class="reference internal" href="#decimal.ROUND_05UP" title="decimal.ROUND_05UP"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_05UP</span></code></a>.</p>
|
||
<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: <a class="reference internal" href="#decimal.Clamped" title="decimal.Clamped"><code class="xref py py-const docutils literal notranslate"><span class="pre">Clamped</span></code></a>, <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-const docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a>,
|
||
<a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-const docutils literal notranslate"><span class="pre">DivisionByZero</span></code></a>, <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal notranslate"><span class="pre">Inexact</span></code></a>, <a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal notranslate"><span class="pre">Rounded</span></code></a>, <a class="reference internal" href="#decimal.Subnormal" title="decimal.Subnormal"><code class="xref py py-const docutils literal notranslate"><span class="pre">Subnormal</span></code></a>,
|
||
<a class="reference internal" href="#decimal.Overflow" title="decimal.Overflow"><code class="xref py py-const docutils literal notranslate"><span class="pre">Overflow</span></code></a>, <a class="reference internal" href="#decimal.Underflow" title="decimal.Underflow"><code class="xref py py-const docutils literal notranslate"><span class="pre">Underflow</span></code></a> and <a class="reference internal" href="#decimal.FloatOperation" title="decimal.FloatOperation"><code class="xref py py-const docutils literal notranslate"><span class="pre">FloatOperation</span></code></a>.</p>
|
||
<p>For each signal there is a flag and a trap enabler. When a signal is
|
||
encountered, its flag is set to one, 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="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<ul class="simple">
|
||
<li><p>IBM’s General Decimal Arithmetic Specification, <a class="reference external" href="http://speleotrove.com/decimal/decarith.html">The General Decimal Arithmetic
|
||
Specification</a>.</p></li>
|
||
</ul>
|
||
</div>
|
||
<div class="section" id="quick-start-tutorial">
|
||
<span id="decimal-tutorial"></span><h2>Quick-start Tutorial<a class="headerlink" href="#quick-start-tutorial" title="Permalink to this headline">¶</a></h2>
|
||
<p>The usual start to using decimals is importing the module, viewing the current
|
||
context with <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">getcontext()</span></code></a> and, if necessary, setting new values for
|
||
precision, rounding, or enabled traps:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">decimal</span> <span class="k">import</span> <span class="o">*</span>
|
||
<span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span>
|
||
<span class="go">Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,</span>
|
||
<span class="go"> capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero,</span>
|
||
<span class="go"> InvalidOperation])</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">7</span> <span class="c1"># Set a new precision</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Decimal instances can be constructed from integers, strings, floats, or tuples.
|
||
Construction from an integer or a float performs an exact conversion of the
|
||
value of that integer or float. Decimal numbers include special values such as
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code> which stands for “Not a number”, positive and negative
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">Infinity</span></code>, and <code class="xref py py-const docutils literal notranslate"><span class="pre">-0</span></code>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">28</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
|
||
<span class="go">Decimal('10')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.14'</span><span class="p">)</span>
|
||
<span class="go">Decimal('3.14')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mf">3.14</span><span class="p">)</span>
|
||
<span class="go">Decimal('3.140000000000000124344978758017532527446746826171875')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">),</span> <span class="o">-</span><span class="mi">2</span><span class="p">))</span>
|
||
<span class="go">Decimal('3.14')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="mf">2.0</span> <span class="o">**</span> <span class="mf">0.5</span><span class="p">))</span>
|
||
<span class="go">Decimal('1.4142135623730951')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="o">**</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'0.5'</span><span class="p">)</span>
|
||
<span class="go">Decimal('1.414213562373095048801688724')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">)</span>
|
||
<span class="go">Decimal('NaN')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'-Infinity'</span><span class="p">)</span>
|
||
<span class="go">Decimal('-Infinity')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If the <a class="reference internal" href="#decimal.FloatOperation" title="decimal.FloatOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FloatOperation</span></code></a> signal is trapped, accidental mixing of
|
||
decimals and floats in constructors or ordering comparisons raises
|
||
an exception:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">getcontext</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">traps</span><span class="p">[</span><span class="n">FloatOperation</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mf">3.14</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
|
||
<span class="gr">decimal.FloatOperation</span>: <span class="n">[<class 'decimal.FloatOperation'>]</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.5'</span><span class="p">)</span> <span class="o"><</span> <span class="mf">3.7</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
|
||
<span class="gr">decimal.FloatOperation</span>: <span class="n">[<class 'decimal.FloatOperation'>]</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.5'</span><span class="p">)</span> <span class="o">==</span> <span class="mf">3.5</span>
|
||
<span class="go">True</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
<p>The significance of a new Decimal is determined solely by the number of digits
|
||
input. Context precision and rounding only come into play during arithmetic
|
||
operations.</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">6</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.0'</span><span class="p">)</span>
|
||
<span class="go">Decimal('3.0')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.1415926535'</span><span class="p">)</span>
|
||
<span class="go">Decimal('3.1415926535')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.1415926535'</span><span class="p">)</span> <span class="o">+</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'2.7182818285'</span><span class="p">)</span>
|
||
<span class="go">Decimal('5.85987')</span>
|
||
<span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">rounding</span> <span class="o">=</span> <span class="n">ROUND_UP</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.1415926535'</span><span class="p">)</span> <span class="o">+</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'2.7182818285'</span><span class="p">)</span>
|
||
<span class="go">Decimal('5.85988')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If the internal limits of the C version are exceeded, constructing
|
||
a decimal raises <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-class docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s2">"1e9999999999999999999"</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
|
||
<span class="gr">decimal.InvalidOperation</span>: <span class="n">[<class 'decimal.InvalidOperation'>]</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3.</span></p>
|
||
</div>
|
||
<p>Decimals interact well with much of the rest of Python. Here is a small decimal
|
||
floating point flying circus:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">Decimal</span><span class="p">,</span> <span class="s1">'1.34 1.87 3.45 2.35 1.00 0.03 9.25'</span><span class="o">.</span><span class="n">split</span><span class="p">()))</span>
|
||
<span class="gp">>>> </span><span class="nb">max</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
|
||
<span class="go">Decimal('9.25')</span>
|
||
<span class="gp">>>> </span><span class="nb">min</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.03')</span>
|
||
<span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
|
||
<span class="go">[Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),</span>
|
||
<span class="go"> Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]</span>
|
||
<span class="gp">>>> </span><span class="nb">sum</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
|
||
<span class="go">Decimal('19.29')</span>
|
||
<span class="gp">>>> </span><span class="n">a</span><span class="p">,</span><span class="n">b</span><span class="p">,</span><span class="n">c</span> <span class="o">=</span> <span class="n">data</span><span class="p">[:</span><span class="mi">3</span><span class="p">]</span>
|
||
<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
|
||
<span class="go">'1.34'</span>
|
||
<span class="gp">>>> </span><span class="nb">float</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
|
||
<span class="go">1.34</span>
|
||
<span class="gp">>>> </span><span class="nb">round</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
|
||
<span class="go">Decimal('1.3')</span>
|
||
<span class="gp">>>> </span><span class="nb">int</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
|
||
<span class="go">1</span>
|
||
<span class="gp">>>> </span><span class="n">a</span> <span class="o">*</span> <span class="mi">5</span>
|
||
<span class="go">Decimal('6.70')</span>
|
||
<span class="gp">>>> </span><span class="n">a</span> <span class="o">*</span> <span class="n">b</span>
|
||
<span class="go">Decimal('2.5058')</span>
|
||
<span class="gp">>>> </span><span class="n">c</span> <span class="o">%</span> <span class="n">a</span>
|
||
<span class="go">Decimal('0.77')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>And some mathematical functions are also available to Decimal:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">28</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="o">.</span><span class="n">sqrt</span><span class="p">()</span>
|
||
<span class="go">Decimal('1.414213562373095048801688724')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">exp</span><span class="p">()</span>
|
||
<span class="go">Decimal('2.718281828459045235360287471')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'10'</span><span class="p">)</span><span class="o">.</span><span class="n">ln</span><span class="p">()</span>
|
||
<span class="go">Decimal('2.302585092994045684017991455')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'10'</span><span class="p">)</span><span class="o">.</span><span class="n">log10</span><span class="p">()</span>
|
||
<span class="go">Decimal('1')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">quantize()</span></code> method rounds a number to a fixed exponent. This method is
|
||
useful for monetary applications that often round results to a fixed number of
|
||
places:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'7.325'</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'.01'</span><span class="p">),</span> <span class="n">rounding</span><span class="o">=</span><span class="n">ROUND_DOWN</span><span class="p">)</span>
|
||
<span class="go">Decimal('7.32')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'7.325'</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'1.'</span><span class="p">),</span> <span class="n">rounding</span><span class="o">=</span><span class="n">ROUND_UP</span><span class="p">)</span>
|
||
<span class="go">Decimal('8')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>As shown above, the <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">getcontext()</span></code></a> function accesses the current context and
|
||
allows the settings to be changed. This approach meets the needs of most
|
||
applications.</p>
|
||
<p>For more advanced work, it may be useful to create alternate contexts using the
|
||
Context() constructor. To make an alternate active, use the <a class="reference internal" href="#decimal.setcontext" title="decimal.setcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">setcontext()</span></code></a>
|
||
function.</p>
|
||
<p>In accordance with the standard, the <a class="reference internal" href="#module-decimal" title="decimal: Implementation of the General Decimal Arithmetic Specification."><code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal</span></code></a> module provides two ready to
|
||
use standard contexts, <a class="reference internal" href="#decimal.BasicContext" title="decimal.BasicContext"><code class="xref py py-const docutils literal notranslate"><span class="pre">BasicContext</span></code></a> and <a class="reference internal" href="#decimal.ExtendedContext" title="decimal.ExtendedContext"><code class="xref py py-const docutils literal notranslate"><span class="pre">ExtendedContext</span></code></a>. The
|
||
former is especially useful for debugging because many of the traps are
|
||
enabled:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">myothercontext</span> <span class="o">=</span> <span class="n">Context</span><span class="p">(</span><span class="n">prec</span><span class="o">=</span><span class="mi">60</span><span class="p">,</span> <span class="n">rounding</span><span class="o">=</span><span class="n">ROUND_HALF_DOWN</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">setcontext</span><span class="p">(</span><span class="n">myothercontext</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.142857142857142857142857142857142857142857142857142857142857')</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">ExtendedContext</span>
|
||
<span class="go">Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,</span>
|
||
<span class="go"> capitals=1, clamp=0, flags=[], traps=[])</span>
|
||
<span class="gp">>>> </span><span class="n">setcontext</span><span class="p">(</span><span class="n">ExtendedContext</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.142857143')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="go">Decimal('Infinity')</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">setcontext</span><span class="p">(</span><span class="n">BasicContext</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<pyshell#143>"</span>, line <span class="m">1</span>, in <span class="n">-toplevel-</span>
|
||
<span class="n">Decimal</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="gr">DivisionByZero</span>: <span class="n">x / 0</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Contexts also have signal flags for monitoring exceptional conditions
|
||
encountered during computations. The flags remain set until explicitly cleared,
|
||
so it is best to clear the flags before each set of monitored computations by
|
||
using the <code class="xref py py-meth docutils literal notranslate"><span class="pre">clear_flags()</span></code> method.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">setcontext</span><span class="p">(</span><span class="n">ExtendedContext</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">clear_flags</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">355</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">113</span><span class="p">)</span>
|
||
<span class="go">Decimal('3.14159292')</span>
|
||
<span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span>
|
||
<span class="go">Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,</span>
|
||
<span class="go"> capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[])</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <em>flags</em> entry shows that the rational approximation to <code class="xref py py-const docutils literal notranslate"><span class="pre">Pi</span></code> was
|
||
rounded (digits beyond the context precision were thrown away) and that the
|
||
result is inexact (some of the discarded digits were non-zero).</p>
|
||
<p>Individual traps are set using the dictionary in the <code class="xref py py-attr docutils literal notranslate"><span class="pre">traps</span></code> field of a
|
||
context:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">setcontext</span><span class="p">(</span><span class="n">ExtendedContext</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="go">Decimal('Infinity')</span>
|
||
<span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">traps</span><span class="p">[</span><span class="n">DivisionByZero</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<pyshell#112>"</span>, line <span class="m">1</span>, in <span class="n">-toplevel-</span>
|
||
<span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="gr">DivisionByZero</span>: <span class="n">x / 0</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Most programs adjust the current context only once, at the beginning of the
|
||
program. And, in many applications, data is converted to <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> with
|
||
a single cast inside a loop. With context set and decimals created, the bulk of
|
||
the program manipulates the data no differently than with other Python numeric
|
||
types.</p>
|
||
</div>
|
||
<div class="section" id="decimal-objects">
|
||
<span id="decimal-decimal"></span><h2>Decimal objects<a class="headerlink" href="#decimal-objects" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="class">
|
||
<dt id="decimal.Decimal">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">Decimal</code><span class="sig-paren">(</span><em>value="0"</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Construct a new <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> object based from <em>value</em>.</p>
|
||
<p><em>value</em> can be an integer, string, tuple, <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, or another <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a>
|
||
object. If no <em>value</em> is given, returns <code class="docutils literal notranslate"><span class="pre">Decimal('0')</span></code>. If <em>value</em> is a
|
||
string, it should conform to the decimal numeric string syntax after leading
|
||
and trailing whitespace characters, as well as underscores throughout, are removed:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">sign</span> <span class="p">::</span><span class="o">=</span> <span class="s1">'+'</span> <span class="o">|</span> <span class="s1">'-'</span>
|
||
<span class="n">digit</span> <span class="p">::</span><span class="o">=</span> <span class="s1">'0'</span> <span class="o">|</span> <span class="s1">'1'</span> <span class="o">|</span> <span class="s1">'2'</span> <span class="o">|</span> <span class="s1">'3'</span> <span class="o">|</span> <span class="s1">'4'</span> <span class="o">|</span> <span class="s1">'5'</span> <span class="o">|</span> <span class="s1">'6'</span> <span class="o">|</span> <span class="s1">'7'</span> <span class="o">|</span> <span class="s1">'8'</span> <span class="o">|</span> <span class="s1">'9'</span>
|
||
<span class="n">indicator</span> <span class="p">::</span><span class="o">=</span> <span class="s1">'e'</span> <span class="o">|</span> <span class="s1">'E'</span>
|
||
<span class="n">digits</span> <span class="p">::</span><span class="o">=</span> <span class="n">digit</span> <span class="p">[</span><span class="n">digit</span><span class="p">]</span><span class="o">...</span>
|
||
<span class="n">decimal</span><span class="o">-</span><span class="n">part</span> <span class="p">::</span><span class="o">=</span> <span class="n">digits</span> <span class="s1">'.'</span> <span class="p">[</span><span class="n">digits</span><span class="p">]</span> <span class="o">|</span> <span class="p">[</span><span class="s1">'.'</span><span class="p">]</span> <span class="n">digits</span>
|
||
<span class="n">exponent</span><span class="o">-</span><span class="n">part</span> <span class="p">::</span><span class="o">=</span> <span class="n">indicator</span> <span class="p">[</span><span class="n">sign</span><span class="p">]</span> <span class="n">digits</span>
|
||
<span class="n">infinity</span> <span class="p">::</span><span class="o">=</span> <span class="s1">'Infinity'</span> <span class="o">|</span> <span class="s1">'Inf'</span>
|
||
<span class="n">nan</span> <span class="p">::</span><span class="o">=</span> <span class="s1">'NaN'</span> <span class="p">[</span><span class="n">digits</span><span class="p">]</span> <span class="o">|</span> <span class="s1">'sNaN'</span> <span class="p">[</span><span class="n">digits</span><span class="p">]</span>
|
||
<span class="n">numeric</span><span class="o">-</span><span class="n">value</span> <span class="p">::</span><span class="o">=</span> <span class="n">decimal</span><span class="o">-</span><span class="n">part</span> <span class="p">[</span><span class="n">exponent</span><span class="o">-</span><span class="n">part</span><span class="p">]</span> <span class="o">|</span> <span class="n">infinity</span>
|
||
<span class="n">numeric</span><span class="o">-</span><span class="n">string</span> <span class="p">::</span><span class="o">=</span> <span class="p">[</span><span class="n">sign</span><span class="p">]</span> <span class="n">numeric</span><span class="o">-</span><span class="n">value</span> <span class="o">|</span> <span class="p">[</span><span class="n">sign</span><span class="p">]</span> <span class="n">nan</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Other Unicode decimal digits are also permitted where <code class="docutils literal notranslate"><span class="pre">digit</span></code>
|
||
appears above. These include decimal digits from various other
|
||
alphabets (for example, Arabic-Indic and Devanāgarī digits) along
|
||
with the fullwidth digits <code class="docutils literal notranslate"><span class="pre">'\uff10'</span></code> through <code class="docutils literal notranslate"><span class="pre">'\uff19'</span></code>.</p>
|
||
<p>If <em>value</em> is a <a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>, it should have three components, a sign
|
||
(<code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code> for positive or <code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code> for negative), a <a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> of
|
||
digits, and an integer exponent. For example, <code class="docutils literal notranslate"><span class="pre">Decimal((0,</span> <span class="pre">(1,</span> <span class="pre">4,</span> <span class="pre">1,</span> <span class="pre">4),</span> <span class="pre">-3))</span></code>
|
||
returns <code class="docutils literal notranslate"><span class="pre">Decimal('1.414')</span></code>.</p>
|
||
<p>If <em>value</em> is a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, the binary floating point value is losslessly
|
||
converted to its exact decimal equivalent. This conversion can often require
|
||
53 or more digits of precision. For example, <code class="docutils literal notranslate"><span class="pre">Decimal(float('1.1'))</span></code>
|
||
converts to
|
||
<code class="docutils literal notranslate"><span class="pre">Decimal('1.100000000000000088817841970012523233890533447265625')</span></code>.</p>
|
||
<p>The <em>context</em> precision does not affect how many digits are stored. That is
|
||
determined exclusively by the number of digits in <em>value</em>. For example,
|
||
<code class="docutils literal notranslate"><span class="pre">Decimal('3.00000')</span></code> records all five zeros even if the context precision is
|
||
only three.</p>
|
||
<p>The purpose of the <em>context</em> argument is determining what to do if <em>value</em> is a
|
||
malformed string. If the context traps <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-const docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a>, an exception
|
||
is raised; otherwise, the constructor returns a new Decimal with the value of
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code>.</p>
|
||
<p>Once constructed, <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> objects are immutable.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>The argument to the constructor is now permitted to be a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>
|
||
instance.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span><a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> arguments raise an exception if the <a class="reference internal" href="#decimal.FloatOperation" title="decimal.FloatOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FloatOperation</span></code></a>
|
||
trap is set. By default the trap is off.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Underscores are allowed for grouping, as with integral and floating-point
|
||
literals in code.</p>
|
||
</div>
|
||
<p>Decimal floating point objects share many properties with the other built-in
|
||
numeric types such as <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> and <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>. All of the usual math
|
||
operations and special methods apply. Likewise, decimal objects can be
|
||
copied, pickled, printed, used as dictionary keys, used as set elements,
|
||
compared, sorted, and coerced to another type (such as <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> or
|
||
<a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>).</p>
|
||
<p>There are some small differences between arithmetic on Decimal objects and
|
||
arithmetic on integers and floats. When the remainder operator <code class="docutils literal notranslate"><span class="pre">%</span></code> is
|
||
applied to Decimal objects, the sign of the result is the sign of the
|
||
<em>dividend</em> rather than the sign of the divisor:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="p">(</span><span class="o">-</span><span class="mi">7</span><span class="p">)</span> <span class="o">%</span> <span class="mi">4</span>
|
||
<span class="go">1</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="o">-</span><span class="mi">7</span><span class="p">)</span> <span class="o">%</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>
|
||
<span class="go">Decimal('-3')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The integer division operator <code class="docutils literal notranslate"><span class="pre">//</span></code> behaves analogously, returning the
|
||
integer part of the true quotient (truncating towards zero) rather than its
|
||
floor, so as to preserve the usual identity <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">(x</span> <span class="pre">//</span> <span class="pre">y)</span> <span class="pre">*</span> <span class="pre">y</span> <span class="pre">+</span> <span class="pre">x</span> <span class="pre">%</span> <span class="pre">y</span></code>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="o">-</span><span class="mi">7</span> <span class="o">//</span> <span class="mi">4</span>
|
||
<span class="go">-2</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="o">-</span><span class="mi">7</span><span class="p">)</span> <span class="o">//</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>
|
||
<span class="go">Decimal('-1')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">%</span></code> and <code class="docutils literal notranslate"><span class="pre">//</span></code> operators implement the <code class="docutils literal notranslate"><span class="pre">remainder</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">divide-integer</span></code> operations (respectively) as described in the
|
||
specification.</p>
|
||
<p>Decimal objects cannot generally be combined with floats or
|
||
instances of <a class="reference internal" href="fractions.html#fractions.Fraction" title="fractions.Fraction"><code class="xref py py-class docutils literal notranslate"><span class="pre">fractions.Fraction</span></code></a> in arithmetic operations:
|
||
an attempt to add a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> to a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, for
|
||
example, will raise a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>. However, it is possible to
|
||
use Python’s comparison operators to compare a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a>
|
||
instance <code class="docutils literal notranslate"><span class="pre">x</span></code> with another number <code class="docutils literal notranslate"><span class="pre">y</span></code>. This avoids confusing results
|
||
when doing equality comparisons between numbers of different types.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Mixed-type comparisons between <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instances and other
|
||
numeric types are now fully supported.</p>
|
||
</div>
|
||
<p>In addition to the standard numeric properties, decimal floating point
|
||
objects also have a number of specialized methods:</p>
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.adjusted">
|
||
<code class="descname">adjusted</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.adjusted" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the adjusted exponent after shifting out the coefficient’s
|
||
rightmost digits until only the lead digit remains:
|
||
<code class="docutils literal notranslate"><span class="pre">Decimal('321e+5').adjusted()</span></code> returns seven. Used for determining the
|
||
position of the most significant digit with respect to the decimal point.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.as_integer_ratio">
|
||
<code class="descname">as_integer_ratio</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.as_integer_ratio" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a pair <code class="docutils literal notranslate"><span class="pre">(n,</span> <span class="pre">d)</span></code> of integers that represent the given
|
||
<a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instance as a fraction, in lowest terms and
|
||
with a positive denominator:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'-3.14'</span><span class="p">)</span><span class="o">.</span><span class="n">as_integer_ratio</span><span class="p">()</span>
|
||
<span class="go">(-157, 50)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The conversion is exact. Raise OverflowError on infinities and ValueError
|
||
on NaNs.</p>
|
||
</dd></dl>
|
||
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6.</span></p>
|
||
</div>
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.as_tuple">
|
||
<code class="descname">as_tuple</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.as_tuple" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a> representation of the number:
|
||
<code class="docutils literal notranslate"><span class="pre">DecimalTuple(sign,</span> <span class="pre">digits,</span> <span class="pre">exponent)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.canonical">
|
||
<code class="descname">canonical</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.canonical" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the canonical encoding of the argument. Currently, the encoding of
|
||
a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instance is always canonical, so this operation returns
|
||
its argument unchanged.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.compare">
|
||
<code class="descname">compare</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.compare" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compare the values of two Decimal instances. <a class="reference internal" href="#decimal.Decimal.compare" title="decimal.Decimal.compare"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compare()</span></code></a> returns a
|
||
Decimal instance, and if either operand is a NaN then the result is a
|
||
NaN:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">a</span> <span class="ow">or</span> <span class="n">b</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">NaN</span> <span class="o">==></span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'NaN'</span><span class="p">)</span>
|
||
<span class="n">a</span> <span class="o"><</span> <span class="n">b</span> <span class="o">==></span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'-1'</span><span class="p">)</span>
|
||
<span class="n">a</span> <span class="o">==</span> <span class="n">b</span> <span class="o">==></span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'0'</span><span class="p">)</span>
|
||
<span class="n">a</span> <span class="o">></span> <span class="n">b</span> <span class="o">==></span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'1'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.compare_signal">
|
||
<code class="descname">compare_signal</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.compare_signal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This operation is identical to the <a class="reference internal" href="#decimal.Decimal.compare" title="decimal.Decimal.compare"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compare()</span></code></a> method, except that all
|
||
NaNs signal. That is, if neither operand is a signaling NaN then any
|
||
quiet NaN operand is treated as though it were a signaling NaN.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.compare_total">
|
||
<code class="descname">compare_total</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.compare_total" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compare two operands using their abstract representation rather than their
|
||
numerical value. Similar to the <a class="reference internal" href="#decimal.Decimal.compare" title="decimal.Decimal.compare"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compare()</span></code></a> method, but the result
|
||
gives a total ordering on <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instances. Two
|
||
<a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instances with the same numeric value but different
|
||
representations compare unequal in this ordering:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'12.0'</span><span class="p">)</span><span class="o">.</span><span class="n">compare_total</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'12'</span><span class="p">))</span>
|
||
<span class="go">Decimal('-1')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Quiet and signaling NaNs are also included in the total ordering. The
|
||
result of this function is <code class="docutils literal notranslate"><span class="pre">Decimal('0')</span></code> if both operands have the same
|
||
representation, <code class="docutils literal notranslate"><span class="pre">Decimal('-1')</span></code> if the first operand is lower in the
|
||
total order than the second, and <code class="docutils literal notranslate"><span class="pre">Decimal('1')</span></code> if the first operand is
|
||
higher in the total order than the second operand. See the specification
|
||
for details of the total order.</p>
|
||
<p>This operation is unaffected by context and is quiet: no flags are changed
|
||
and no rounding is performed. As an exception, the C version may raise
|
||
InvalidOperation if the second operand cannot be converted exactly.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.compare_total_mag">
|
||
<code class="descname">compare_total_mag</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.compare_total_mag" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compare two operands using their abstract representation rather than their
|
||
value as in <a class="reference internal" href="#decimal.Decimal.compare_total" title="decimal.Decimal.compare_total"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compare_total()</span></code></a>, but ignoring the sign of each operand.
|
||
<code class="docutils literal notranslate"><span class="pre">x.compare_total_mag(y)</span></code> is equivalent to
|
||
<code class="docutils literal notranslate"><span class="pre">x.copy_abs().compare_total(y.copy_abs())</span></code>.</p>
|
||
<p>This operation is unaffected by context and is quiet: no flags are changed
|
||
and no rounding is performed. As an exception, the C version may raise
|
||
InvalidOperation if the second operand cannot be converted exactly.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.conjugate">
|
||
<code class="descname">conjugate</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.conjugate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Just returns self, this method is only to comply with the Decimal
|
||
Specification.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.copy_abs">
|
||
<code class="descname">copy_abs</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.copy_abs" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the absolute value of the argument. This operation is unaffected
|
||
by the context and is quiet: no flags are changed and no rounding is
|
||
performed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.copy_negate">
|
||
<code class="descname">copy_negate</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.copy_negate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the negation of the argument. This operation is unaffected by the
|
||
context and is quiet: no flags are changed and no rounding is performed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.copy_sign">
|
||
<code class="descname">copy_sign</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.copy_sign" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a copy of the first operand with the sign set to be the same as the
|
||
sign of the second operand. For example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'2.3'</span><span class="p">)</span><span class="o">.</span><span class="n">copy_sign</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'-1.5'</span><span class="p">))</span>
|
||
<span class="go">Decimal('-2.3')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This operation is unaffected by context and is quiet: no flags are changed
|
||
and no rounding is performed. As an exception, the C version may raise
|
||
InvalidOperation if the second operand cannot be converted exactly.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.exp">
|
||
<code class="descname">exp</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.exp" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the value of the (natural) exponential function <code class="docutils literal notranslate"><span class="pre">e**x</span></code> at the
|
||
given number. The result is correctly rounded using the
|
||
<a class="reference internal" href="#decimal.ROUND_HALF_EVEN" title="decimal.ROUND_HALF_EVEN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_EVEN</span></code></a> rounding mode.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">exp</span><span class="p">()</span>
|
||
<span class="go">Decimal('2.718281828459045235360287471')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">321</span><span class="p">)</span><span class="o">.</span><span class="n">exp</span><span class="p">()</span>
|
||
<span class="go">Decimal('2.561702493119680037517373933E+139')</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.from_float">
|
||
<code class="descname">from_float</code><span class="sig-paren">(</span><em>f</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.from_float" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Classmethod that converts a float to a decimal number, exactly.</p>
|
||
<p>Note <cite>Decimal.from_float(0.1)</cite> is not the same as <cite>Decimal(‘0.1’)</cite>.
|
||
Since 0.1 is not exactly representable in binary floating point, the
|
||
value is stored as the nearest representable value which is
|
||
<cite>0x1.999999999999ap-4</cite>. That equivalent value in decimal is
|
||
<cite>0.1000000000000000055511151231257827021181583404541015625</cite>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>From Python 3.2 onwards, a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instance
|
||
can also be constructed directly from a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>.</p>
|
||
</div>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_float</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.1000000000000000055511151231257827021181583404541015625')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_float</span><span class="p">(</span><span class="nb">float</span><span class="p">(</span><span class="s1">'nan'</span><span class="p">))</span>
|
||
<span class="go">Decimal('NaN')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_float</span><span class="p">(</span><span class="nb">float</span><span class="p">(</span><span class="s1">'inf'</span><span class="p">))</span>
|
||
<span class="go">Decimal('Infinity')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="o">.</span><span class="n">from_float</span><span class="p">(</span><span class="nb">float</span><span class="p">(</span><span class="s1">'-inf'</span><span class="p">))</span>
|
||
<span class="go">Decimal('-Infinity')</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.1.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.fma">
|
||
<code class="descname">fma</code><span class="sig-paren">(</span><em>other</em>, <em>third</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.fma" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Fused multiply-add. Return self*other+third with no rounding of the
|
||
intermediate product self*other.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="o">.</span><span class="n">fma</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>
|
||
<span class="go">Decimal('11')</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.is_canonical">
|
||
<code class="descname">is_canonical</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_canonical" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is canonical and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>
|
||
otherwise. Currently, a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instance is always canonical, so
|
||
this operation always returns <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.is_finite">
|
||
<code class="descname">is_finite</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_finite" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a finite number, and
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> if the argument is an infinity or a NaN.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.is_infinite">
|
||
<code class="descname">is_infinite</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_infinite" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is either positive or negative
|
||
infinity and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> otherwise.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.is_nan">
|
||
<code class="descname">is_nan</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_nan" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a (quiet or signaling) NaN and
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> otherwise.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.is_normal">
|
||
<code class="descname">is_normal</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_normal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a <em>normal</em> finite number. Return
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> if the argument is zero, subnormal, infinite or a NaN.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.is_qnan">
|
||
<code class="descname">is_qnan</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_qnan" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a quiet NaN, and
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> otherwise.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.is_signed">
|
||
<code class="descname">is_signed</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_signed" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument has a negative sign and
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> otherwise. Note that zeros and NaNs can both carry signs.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.is_snan">
|
||
<code class="descname">is_snan</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_snan" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a signaling NaN and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>
|
||
otherwise.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.is_subnormal">
|
||
<code class="descname">is_subnormal</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_subnormal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is subnormal, and <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>
|
||
otherwise.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.is_zero">
|
||
<code class="descname">is_zero</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.is_zero" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the argument is a (positive or negative) zero and
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> otherwise.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.ln">
|
||
<code class="descname">ln</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.ln" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the natural (base e) logarithm of the operand. The result is
|
||
correctly rounded using the <a class="reference internal" href="#decimal.ROUND_HALF_EVEN" title="decimal.ROUND_HALF_EVEN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_EVEN</span></code></a> rounding mode.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.log10">
|
||
<code class="descname">log10</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.log10" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the base ten logarithm of the operand. The result is correctly
|
||
rounded using the <a class="reference internal" href="#decimal.ROUND_HALF_EVEN" title="decimal.ROUND_HALF_EVEN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_EVEN</span></code></a> rounding mode.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.logb">
|
||
<code class="descname">logb</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.logb" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>For a nonzero number, return the adjusted exponent of its operand as a
|
||
<a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instance. If the operand is a zero then
|
||
<code class="docutils literal notranslate"><span class="pre">Decimal('-Infinity')</span></code> is returned and the <a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-const docutils literal notranslate"><span class="pre">DivisionByZero</span></code></a> flag
|
||
is raised. If the operand is an infinity then <code class="docutils literal notranslate"><span class="pre">Decimal('Infinity')</span></code> is
|
||
returned.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.logical_and">
|
||
<code class="descname">logical_and</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.logical_and" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p><a class="reference internal" href="#decimal.Decimal.logical_and" title="decimal.Decimal.logical_and"><code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_and()</span></code></a> is a logical operation which takes two <em>logical
|
||
operands</em> (see <a class="reference internal" href="#logical-operands-label"><span class="std std-ref">Logical operands</span></a>). The result is the
|
||
digit-wise <code class="docutils literal notranslate"><span class="pre">and</span></code> of the two operands.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.logical_invert">
|
||
<code class="descname">logical_invert</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.logical_invert" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p><a class="reference internal" href="#decimal.Decimal.logical_invert" title="decimal.Decimal.logical_invert"><code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_invert()</span></code></a> is a logical operation. The
|
||
result is the digit-wise inversion of the operand.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.logical_or">
|
||
<code class="descname">logical_or</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.logical_or" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p><a class="reference internal" href="#decimal.Decimal.logical_or" title="decimal.Decimal.logical_or"><code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_or()</span></code></a> is a logical operation which takes two <em>logical
|
||
operands</em> (see <a class="reference internal" href="#logical-operands-label"><span class="std std-ref">Logical operands</span></a>). The result is the
|
||
digit-wise <code class="docutils literal notranslate"><span class="pre">or</span></code> of the two operands.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.logical_xor">
|
||
<code class="descname">logical_xor</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.logical_xor" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p><a class="reference internal" href="#decimal.Decimal.logical_xor" title="decimal.Decimal.logical_xor"><code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_xor()</span></code></a> is a logical operation which takes two <em>logical
|
||
operands</em> (see <a class="reference internal" href="#logical-operands-label"><span class="std std-ref">Logical operands</span></a>). The result is the
|
||
digit-wise exclusive or of the two operands.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.max">
|
||
<code class="descname">max</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.max" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Like <code class="docutils literal notranslate"><span class="pre">max(self,</span> <span class="pre">other)</span></code> except that the context rounding rule is applied
|
||
before returning and that <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code> values are either signaled or
|
||
ignored (depending on the context and whether they are signaling or
|
||
quiet).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.max_mag">
|
||
<code class="descname">max_mag</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.max_mag" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Similar to the <a class="reference internal" href="#decimal.Decimal.max" title="decimal.Decimal.max"><code class="xref py py-meth docutils literal notranslate"><span class="pre">max()</span></code></a> method, but the comparison is done using the
|
||
absolute values of the operands.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.min">
|
||
<code class="descname">min</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.min" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Like <code class="docutils literal notranslate"><span class="pre">min(self,</span> <span class="pre">other)</span></code> except that the context rounding rule is applied
|
||
before returning and that <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code> values are either signaled or
|
||
ignored (depending on the context and whether they are signaling or
|
||
quiet).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.min_mag">
|
||
<code class="descname">min_mag</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.min_mag" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Similar to the <a class="reference internal" href="#decimal.Decimal.min" title="decimal.Decimal.min"><code class="xref py py-meth docutils literal notranslate"><span class="pre">min()</span></code></a> method, but the comparison is done using the
|
||
absolute values of the operands.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.next_minus">
|
||
<code class="descname">next_minus</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.next_minus" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the largest number representable in the given context (or in the
|
||
current thread’s context if no context is given) that is smaller than the
|
||
given operand.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.next_plus">
|
||
<code class="descname">next_plus</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.next_plus" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the smallest number representable in the given context (or in the
|
||
current thread’s context if no context is given) that is larger than the
|
||
given operand.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.next_toward">
|
||
<code class="descname">next_toward</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.next_toward" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If the two operands are unequal, return the number closest to the first
|
||
operand in the direction of the second operand. If both operands are
|
||
numerically equal, return a copy of the first operand with the sign set to
|
||
be the same as the sign of the second operand.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.normalize">
|
||
<code class="descname">normalize</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.normalize" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Normalize the number by stripping the rightmost trailing zeros and
|
||
converting any result equal to <code class="xref py py-const docutils literal notranslate"><span class="pre">Decimal('0')</span></code> to
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">Decimal('0e0')</span></code>. Used for producing canonical values for attributes
|
||
of an equivalence class. For example, <code class="docutils literal notranslate"><span class="pre">Decimal('32.100')</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">Decimal('0.321000e+2')</span></code> both normalize to the equivalent value
|
||
<code class="docutils literal notranslate"><span class="pre">Decimal('32.1')</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.number_class">
|
||
<code class="descname">number_class</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.number_class" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a string describing the <em>class</em> of the operand. The returned value
|
||
is one of the following ten strings.</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"-Infinity"</span></code>, indicating that the operand is negative infinity.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"-Normal"</span></code>, indicating that the operand is a negative normal number.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"-Subnormal"</span></code>, indicating that the operand is negative and subnormal.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"-Zero"</span></code>, indicating that the operand is a negative zero.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"+Zero"</span></code>, indicating that the operand is a positive zero.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"+Subnormal"</span></code>, indicating that the operand is positive and subnormal.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"+Normal"</span></code>, indicating that the operand is a positive normal number.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"+Infinity"</span></code>, indicating that the operand is positive infinity.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"NaN"</span></code>, indicating that the operand is a quiet NaN (Not a Number).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"sNaN"</span></code>, indicating that the operand is a signaling NaN.</p></li>
|
||
</ul>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.quantize">
|
||
<code class="descname">quantize</code><span class="sig-paren">(</span><em>exp</em>, <em>rounding=None</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.quantize" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a value equal to the first operand after rounding and having the
|
||
exponent of the second operand.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'1.41421356'</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'1.000'</span><span class="p">))</span>
|
||
<span class="go">Decimal('1.414')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Unlike other operations, if the length of the coefficient after the
|
||
quantize operation would be greater than precision, then an
|
||
<a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-const docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a> is signaled. This guarantees that, unless there
|
||
is an error condition, the quantized exponent is always equal to that of
|
||
the right-hand operand.</p>
|
||
<p>Also unlike other operations, quantize never signals Underflow, even if
|
||
the result is subnormal and inexact.</p>
|
||
<p>If the exponent of the second operand is larger than that of the first
|
||
then rounding may be necessary. In this case, the rounding mode is
|
||
determined by the <code class="docutils literal notranslate"><span class="pre">rounding</span></code> argument if given, else by the given
|
||
<code class="docutils literal notranslate"><span class="pre">context</span></code> argument; if neither argument is given the rounding mode of
|
||
the current thread’s context is used.</p>
|
||
<p>An error is returned whenever the resulting exponent is greater than
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">Emax</span></code> or less than <code class="xref py py-attr docutils literal notranslate"><span class="pre">Etiny</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.radix">
|
||
<code class="descname">radix</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.radix" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">Decimal(10)</span></code>, the radix (base) in which the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a>
|
||
class does all its arithmetic. Included for compatibility with the
|
||
specification.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.remainder_near">
|
||
<code class="descname">remainder_near</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.remainder_near" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the remainder from dividing <em>self</em> by <em>other</em>. This differs from
|
||
<code class="docutils literal notranslate"><span class="pre">self</span> <span class="pre">%</span> <span class="pre">other</span></code> in that the sign of the remainder is chosen so as to
|
||
minimize its absolute value. More precisely, the return value is
|
||
<code class="docutils literal notranslate"><span class="pre">self</span> <span class="pre">-</span> <span class="pre">n</span> <span class="pre">*</span> <span class="pre">other</span></code> where <code class="docutils literal notranslate"><span class="pre">n</span></code> is the integer nearest to the exact
|
||
value of <code class="docutils literal notranslate"><span class="pre">self</span> <span class="pre">/</span> <span class="pre">other</span></code>, and if two integers are equally near then the
|
||
even one is chosen.</p>
|
||
<p>If the result is zero then its sign will be the sign of <em>self</em>.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">18</span><span class="p">)</span><span class="o">.</span><span class="n">remainder_near</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">))</span>
|
||
<span class="go">Decimal('-2')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">25</span><span class="p">)</span><span class="o">.</span><span class="n">remainder_near</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">))</span>
|
||
<span class="go">Decimal('5')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="mi">35</span><span class="p">)</span><span class="o">.</span><span class="n">remainder_near</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">))</span>
|
||
<span class="go">Decimal('-5')</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.rotate">
|
||
<code class="descname">rotate</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.rotate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the result of rotating the digits of the first operand by an amount
|
||
specified by the second operand. The second operand must be an integer in
|
||
the range -precision through precision. The absolute value of the second
|
||
operand gives the number of places to rotate. If the second operand is
|
||
positive then rotation is to the left; otherwise rotation is to the right.
|
||
The coefficient of the first operand is padded on the left with zeros to
|
||
length precision if necessary. The sign and exponent of the first operand
|
||
are unchanged.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.same_quantum">
|
||
<code class="descname">same_quantum</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.same_quantum" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Test whether self and other have the same exponent or whether both are
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code>.</p>
|
||
<p>This operation is unaffected by context and is quiet: no flags are changed
|
||
and no rounding is performed. As an exception, the C version may raise
|
||
InvalidOperation if the second operand cannot be converted exactly.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.scaleb">
|
||
<code class="descname">scaleb</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.scaleb" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the first operand with exponent adjusted by the second.
|
||
Equivalently, return the first operand multiplied by <code class="docutils literal notranslate"><span class="pre">10**other</span></code>. The
|
||
second operand must be an integer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.shift">
|
||
<code class="descname">shift</code><span class="sig-paren">(</span><em>other</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.shift" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the result of shifting the digits of the first operand by an amount
|
||
specified by the second operand. The second operand must be an integer in
|
||
the range -precision through precision. The absolute value of the second
|
||
operand gives the number of places to shift. If the second operand is
|
||
positive then the shift is to the left; otherwise the shift is to the
|
||
right. Digits shifted into the coefficient are zeros. The sign and
|
||
exponent of the first operand are unchanged.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.sqrt">
|
||
<code class="descname">sqrt</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.sqrt" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the square root of the argument to full precision.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.to_eng_string">
|
||
<code class="descname">to_eng_string</code><span class="sig-paren">(</span><em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.to_eng_string" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Convert to a string, using engineering notation if an exponent is needed.</p>
|
||
<p>Engineering notation has an exponent which is a multiple of 3. This
|
||
can leave up to 3 digits to the left of the decimal place and may
|
||
require the addition of either one or two trailing zeros.</p>
|
||
<p>For example, this converts <code class="docutils literal notranslate"><span class="pre">Decimal('123E+1')</span></code> to <code class="docutils literal notranslate"><span class="pre">Decimal('1.23E+3')</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.to_integral">
|
||
<code class="descname">to_integral</code><span class="sig-paren">(</span><em>rounding=None</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.to_integral" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Identical to the <a class="reference internal" href="#decimal.Decimal.to_integral_value" title="decimal.Decimal.to_integral_value"><code class="xref py py-meth docutils literal notranslate"><span class="pre">to_integral_value()</span></code></a> method. The <code class="docutils literal notranslate"><span class="pre">to_integral</span></code>
|
||
name has been kept for compatibility with older versions.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.to_integral_exact">
|
||
<code class="descname">to_integral_exact</code><span class="sig-paren">(</span><em>rounding=None</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.to_integral_exact" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Round to the nearest integer, signaling <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal notranslate"><span class="pre">Inexact</span></code></a> or
|
||
<a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal notranslate"><span class="pre">Rounded</span></code></a> as appropriate if rounding occurs. The rounding mode is
|
||
determined by the <code class="docutils literal notranslate"><span class="pre">rounding</span></code> parameter if given, else by the given
|
||
<code class="docutils literal notranslate"><span class="pre">context</span></code>. If neither parameter is given then the rounding mode of the
|
||
current context is used.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Decimal.to_integral_value">
|
||
<code class="descname">to_integral_value</code><span class="sig-paren">(</span><em>rounding=None</em>, <em>context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Decimal.to_integral_value" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Round to the nearest integer without signaling <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal notranslate"><span class="pre">Inexact</span></code></a> or
|
||
<a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal notranslate"><span class="pre">Rounded</span></code></a>. If given, applies <em>rounding</em>; otherwise, uses the
|
||
rounding method in either the supplied <em>context</em> or the current context.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<div class="section" id="logical-operands">
|
||
<span id="logical-operands-label"></span><h3>Logical operands<a class="headerlink" href="#logical-operands" title="Permalink to this headline">¶</a></h3>
|
||
<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_and()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_invert()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_or()</span></code>,
|
||
and <code class="xref py py-meth docutils literal notranslate"><span class="pre">logical_xor()</span></code> methods expect their arguments to be <em>logical
|
||
operands</em>. A <em>logical operand</em> is a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instance whose
|
||
exponent and sign are both zero, and whose digits are all either
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code> or <code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="context-objects">
|
||
<span id="decimal-context"></span><h2>Context objects<a class="headerlink" href="#context-objects" title="Permalink to this headline">¶</a></h2>
|
||
<p>Contexts are environments for arithmetic operations. They govern precision, set
|
||
rules for rounding, determine which signals are treated as exceptions, and limit
|
||
the range for exponents.</p>
|
||
<p>Each thread has its own current context which is accessed or changed using the
|
||
<a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">getcontext()</span></code></a> and <a class="reference internal" href="#decimal.setcontext" title="decimal.setcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">setcontext()</span></code></a> functions:</p>
|
||
<dl class="function">
|
||
<dt id="decimal.getcontext">
|
||
<code class="descclassname">decimal.</code><code class="descname">getcontext</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.getcontext" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the current context for the active thread.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="decimal.setcontext">
|
||
<code class="descclassname">decimal.</code><code class="descname">setcontext</code><span class="sig-paren">(</span><em>c</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.setcontext" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the current context for the active thread to <em>c</em>.</p>
|
||
</dd></dl>
|
||
|
||
<p>You can also use the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement and the <a class="reference internal" href="#decimal.localcontext" title="decimal.localcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">localcontext()</span></code></a>
|
||
function to temporarily change the active context.</p>
|
||
<dl class="function">
|
||
<dt id="decimal.localcontext">
|
||
<code class="descclassname">decimal.</code><code class="descname">localcontext</code><span class="sig-paren">(</span><em>ctx=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.localcontext" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a context manager that will set the current context for the active thread
|
||
to a copy of <em>ctx</em> on entry to the with-statement and restore the previous context
|
||
when exiting the with-statement. If no context is specified, a copy of the
|
||
current context is used.</p>
|
||
<p>For example, the following code sets the current decimal precision to 42 places,
|
||
performs a calculation, and then automatically restores the previous context:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">decimal</span> <span class="k">import</span> <span class="n">localcontext</span>
|
||
|
||
<span class="k">with</span> <span class="n">localcontext</span><span class="p">()</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>
|
||
<span class="n">ctx</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">42</span> <span class="c1"># Perform a high precision calculation</span>
|
||
<span class="n">s</span> <span class="o">=</span> <span class="n">calculate_something</span><span class="p">()</span>
|
||
<span class="n">s</span> <span class="o">=</span> <span class="o">+</span><span class="n">s</span> <span class="c1"># Round the final result back to the default precision</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>New contexts can also be created using the <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> constructor
|
||
described below. In addition, the module provides three pre-made contexts:</p>
|
||
<dl class="class">
|
||
<dt id="decimal.BasicContext">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">BasicContext</code><a class="headerlink" href="#decimal.BasicContext" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This is a standard context defined by the General Decimal Arithmetic
|
||
Specification. Precision is set to nine. Rounding is set to
|
||
<a class="reference internal" href="#decimal.ROUND_HALF_UP" title="decimal.ROUND_HALF_UP"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_UP</span></code></a>. All flags are cleared. All traps are enabled (treated
|
||
as exceptions) except <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal notranslate"><span class="pre">Inexact</span></code></a>, <a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-const docutils literal notranslate"><span class="pre">Rounded</span></code></a>, and
|
||
<a class="reference internal" href="#decimal.Subnormal" title="decimal.Subnormal"><code class="xref py py-const docutils literal notranslate"><span class="pre">Subnormal</span></code></a>.</p>
|
||
<p>Because many of the traps are enabled, this context is useful for debugging.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.ExtendedContext">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">ExtendedContext</code><a class="headerlink" href="#decimal.ExtendedContext" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This is a standard context defined by the General Decimal Arithmetic
|
||
Specification. Precision is set to nine. Rounding is set to
|
||
<a class="reference internal" href="#decimal.ROUND_HALF_EVEN" title="decimal.ROUND_HALF_EVEN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_EVEN</span></code></a>. All flags are cleared. No traps are enabled (so that
|
||
exceptions are not raised during computations).</p>
|
||
<p>Because the traps are disabled, this context is useful for applications that
|
||
prefer to have result value of <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code> or <code class="xref py py-const docutils literal notranslate"><span class="pre">Infinity</span></code> instead of
|
||
raising exceptions. This allows an application to complete a run in the
|
||
presence of conditions that would otherwise halt the program.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.DefaultContext">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">DefaultContext</code><a class="headerlink" href="#decimal.DefaultContext" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This context is used by the <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> constructor as a prototype for new
|
||
contexts. Changing a field (such a precision) has the effect of changing the
|
||
default for new contexts created by the <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> constructor.</p>
|
||
<p>This context is most useful in multi-threaded environments. Changing one of the
|
||
fields before threads are started has the effect of setting system-wide
|
||
defaults. Changing the fields after threads have started is not recommended as
|
||
it would require thread synchronization to prevent race conditions.</p>
|
||
<p>In single threaded environments, it is preferable to not use this context at
|
||
all. Instead, simply create contexts explicitly as described below.</p>
|
||
<p>The default values are <code class="xref py py-attr docutils literal notranslate"><span class="pre">prec</span></code>=<code class="xref py py-const docutils literal notranslate"><span class="pre">28</span></code>,
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">rounding</span></code>=<a class="reference internal" href="#decimal.ROUND_HALF_EVEN" title="decimal.ROUND_HALF_EVEN"><code class="xref py py-const docutils literal notranslate"><span class="pre">ROUND_HALF_EVEN</span></code></a>,
|
||
and enabled traps for <a class="reference internal" href="#decimal.Overflow" title="decimal.Overflow"><code class="xref py py-class docutils literal notranslate"><span class="pre">Overflow</span></code></a>, <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-class docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a>, and
|
||
<a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-class docutils literal notranslate"><span class="pre">DivisionByZero</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<p>In addition to the three supplied contexts, new contexts can be created with the
|
||
<a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> constructor.</p>
|
||
<dl class="class">
|
||
<dt id="decimal.Context">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">Context</code><span class="sig-paren">(</span><em>prec=None</em>, <em>rounding=None</em>, <em>Emin=None</em>, <em>Emax=None</em>, <em>capitals=None</em>, <em>clamp=None</em>, <em>flags=None</em>, <em>traps=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Creates a new context. If a field is not specified or is <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>, the
|
||
default values are copied from the <a class="reference internal" href="#decimal.DefaultContext" title="decimal.DefaultContext"><code class="xref py py-const docutils literal notranslate"><span class="pre">DefaultContext</span></code></a>. If the <em>flags</em>
|
||
field is not specified or is <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>, all flags are cleared.</p>
|
||
<p><em>prec</em> is an integer in the range [<code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code>, <a class="reference internal" href="#decimal.MAX_PREC" title="decimal.MAX_PREC"><code class="xref py py-const docutils literal notranslate"><span class="pre">MAX_PREC</span></code></a>] that sets
|
||
the precision for arithmetic operations in the context.</p>
|
||
<p>The <em>rounding</em> option is one of the constants listed in the section
|
||
<a class="reference internal" href="#rounding-modes">Rounding Modes</a>.</p>
|
||
<p>The <em>traps</em> and <em>flags</em> fields list any signals to be set. Generally, new
|
||
contexts should only set traps and leave the flags clear.</p>
|
||
<p>The <em>Emin</em> and <em>Emax</em> fields are integers specifying the outer limits allowable
|
||
for exponents. <em>Emin</em> must be in the range [<a class="reference internal" href="#decimal.MIN_EMIN" title="decimal.MIN_EMIN"><code class="xref py py-const docutils literal notranslate"><span class="pre">MIN_EMIN</span></code></a>, <code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code>],
|
||
<em>Emax</em> in the range [<code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code>, <a class="reference internal" href="#decimal.MAX_EMAX" title="decimal.MAX_EMAX"><code class="xref py py-const docutils literal notranslate"><span class="pre">MAX_EMAX</span></code></a>].</p>
|
||
<p>The <em>capitals</em> field is either <code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code> or <code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code> (the default). If set to
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code>, exponents are printed with a capital <code class="xref py py-const docutils literal notranslate"><span class="pre">E</span></code>; otherwise, a
|
||
lowercase <code class="xref py py-const docutils literal notranslate"><span class="pre">e</span></code> is used: <code class="xref py py-const docutils literal notranslate"><span class="pre">Decimal('6.02e+23')</span></code>.</p>
|
||
<p>The <em>clamp</em> field is either <code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code> (the default) or <code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code>.
|
||
If set to <code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code>, the exponent <code class="docutils literal notranslate"><span class="pre">e</span></code> of a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a>
|
||
instance representable in this context is strictly limited to the
|
||
range <code class="docutils literal notranslate"><span class="pre">Emin</span> <span class="pre">-</span> <span class="pre">prec</span> <span class="pre">+</span> <span class="pre">1</span> <span class="pre"><=</span> <span class="pre">e</span> <span class="pre"><=</span> <span class="pre">Emax</span> <span class="pre">-</span> <span class="pre">prec</span> <span class="pre">+</span> <span class="pre">1</span></code>. If <em>clamp</em> is
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code> then a weaker condition holds: the adjusted exponent of
|
||
the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instance is at most <code class="docutils literal notranslate"><span class="pre">Emax</span></code>. When <em>clamp</em> is
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code>, a large normal number will, where possible, have its
|
||
exponent reduced and a corresponding number of zeros added to its
|
||
coefficient, in order to fit the exponent constraints; this
|
||
preserves the value of the number but loses information about
|
||
significant trailing zeros. For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Context</span><span class="p">(</span><span class="n">prec</span><span class="o">=</span><span class="mi">6</span><span class="p">,</span> <span class="n">Emax</span><span class="o">=</span><span class="mi">999</span><span class="p">,</span> <span class="n">clamp</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">create_decimal</span><span class="p">(</span><span class="s1">'1.23e999'</span><span class="p">)</span>
|
||
<span class="go">Decimal('1.23000E+999')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>A <em>clamp</em> value of <code class="xref py py-const docutils literal notranslate"><span class="pre">1</span></code> allows compatibility with the
|
||
fixed-width decimal interchange formats specified in IEEE 754.</p>
|
||
<p>The <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> class defines several general purpose methods as well as
|
||
a large number of methods for doing arithmetic directly in a given context.
|
||
In addition, for each of the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> methods described above (with
|
||
the exception of the <code class="xref py py-meth docutils literal notranslate"><span class="pre">adjusted()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">as_tuple()</span></code> methods) there is
|
||
a corresponding <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> method. For example, for a <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a>
|
||
instance <code class="docutils literal notranslate"><span class="pre">C</span></code> and <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> instance <code class="docutils literal notranslate"><span class="pre">x</span></code>, <code class="docutils literal notranslate"><span class="pre">C.exp(x)</span></code> is
|
||
equivalent to <code class="docutils literal notranslate"><span class="pre">x.exp(context=C)</span></code>. Each <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> method accepts a
|
||
Python integer (an instance of <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) anywhere that a
|
||
Decimal instance is accepted.</p>
|
||
<dl class="method">
|
||
<dt id="decimal.Context.clear_flags">
|
||
<code class="descname">clear_flags</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.clear_flags" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Resets all of the flags to <code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.clear_traps">
|
||
<code class="descname">clear_traps</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.clear_traps" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Resets all of the traps to <code class="xref py py-const docutils literal notranslate"><span class="pre">0</span></code>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.copy">
|
||
<code class="descname">copy</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.copy" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a duplicate of the context.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.copy_decimal">
|
||
<code class="descname">copy_decimal</code><span class="sig-paren">(</span><em>num</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.copy_decimal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a copy of the Decimal instance num.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.create_decimal">
|
||
<code class="descname">create_decimal</code><span class="sig-paren">(</span><em>num</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.create_decimal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Creates a new Decimal instance from <em>num</em> but using <em>self</em> as
|
||
context. Unlike the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> constructor, the context precision,
|
||
rounding method, flags, and traps are applied to the conversion.</p>
|
||
<p>This is useful because constants are often given to a greater precision
|
||
than is needed by the application. Another benefit is that rounding
|
||
immediately eliminates unintended effects from digits beyond the current
|
||
precision. In the following example, using unrounded inputs means that
|
||
adding zero to a sum can change the result:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">3</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.4445'</span><span class="p">)</span> <span class="o">+</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'1.0023'</span><span class="p">)</span>
|
||
<span class="go">Decimal('4.45')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.4445'</span><span class="p">)</span> <span class="o">+</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="o">+</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'1.0023'</span><span class="p">)</span>
|
||
<span class="go">Decimal('4.44')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This method implements the to-number operation of the IBM specification.
|
||
If the argument is a string, no leading or trailing whitespace or
|
||
underscores are permitted.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.create_decimal_from_float">
|
||
<code class="descname">create_decimal_from_float</code><span class="sig-paren">(</span><em>f</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.create_decimal_from_float" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Creates a new Decimal instance from a float <em>f</em> but rounding using <em>self</em>
|
||
as the context. Unlike the <a class="reference internal" href="#decimal.Decimal.from_float" title="decimal.Decimal.from_float"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Decimal.from_float()</span></code></a> class method,
|
||
the context precision, rounding method, flags, and traps are applied to
|
||
the conversion.</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">context</span> <span class="o">=</span> <span class="n">Context</span><span class="p">(</span><span class="n">prec</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span> <span class="n">rounding</span><span class="o">=</span><span class="n">ROUND_DOWN</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">context</span><span class="o">.</span><span class="n">create_decimal_from_float</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">pi</span><span class="p">)</span>
|
||
<span class="go">Decimal('3.1415')</span>
|
||
<span class="gp">>>> </span><span class="n">context</span> <span class="o">=</span> <span class="n">Context</span><span class="p">(</span><span class="n">prec</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span> <span class="n">traps</span><span class="o">=</span><span class="p">[</span><span class="n">Inexact</span><span class="p">])</span>
|
||
<span class="gp">>>> </span><span class="n">context</span><span class="o">.</span><span class="n">create_decimal_from_float</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">pi</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="o">...</span>
|
||
<span class="gr">decimal.Inexact</span>: <span class="n">None</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.1.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.Etiny">
|
||
<code class="descname">Etiny</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.Etiny" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns a value equal to <code class="docutils literal notranslate"><span class="pre">Emin</span> <span class="pre">-</span> <span class="pre">prec</span> <span class="pre">+</span> <span class="pre">1</span></code> which is the minimum exponent
|
||
value for subnormal results. When underflow occurs, the exponent is set
|
||
to <a class="reference internal" href="#decimal.Context.Etiny" title="decimal.Context.Etiny"><code class="xref py py-const docutils literal notranslate"><span class="pre">Etiny</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.Etop">
|
||
<code class="descname">Etop</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.Etop" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns a value equal to <code class="docutils literal notranslate"><span class="pre">Emax</span> <span class="pre">-</span> <span class="pre">prec</span> <span class="pre">+</span> <span class="pre">1</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<p>The usual approach to working with decimals is to create <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a>
|
||
instances and then apply arithmetic operations which take place within the
|
||
current context for the active thread. An alternative approach is to use
|
||
context methods for calculating within a specific context. The methods are
|
||
similar to those for the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> class and are only briefly
|
||
recounted here.</p>
|
||
<dl class="method">
|
||
<dt id="decimal.Context.abs">
|
||
<code class="descname">abs</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.abs" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the absolute value of <em>x</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.add">
|
||
<code class="descname">add</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.add" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the sum of <em>x</em> and <em>y</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.canonical">
|
||
<code class="descname">canonical</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.canonical" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the same Decimal object <em>x</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.compare">
|
||
<code class="descname">compare</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.compare" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compares <em>x</em> and <em>y</em> numerically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.compare_signal">
|
||
<code class="descname">compare_signal</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.compare_signal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compares the values of the two operands numerically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.compare_total">
|
||
<code class="descname">compare_total</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.compare_total" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compares two operands using their abstract representation.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.compare_total_mag">
|
||
<code class="descname">compare_total_mag</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.compare_total_mag" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compares two operands using their abstract representation, ignoring sign.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.copy_abs">
|
||
<code class="descname">copy_abs</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.copy_abs" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns a copy of <em>x</em> with the sign set to 0.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.copy_negate">
|
||
<code class="descname">copy_negate</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.copy_negate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns a copy of <em>x</em> with the sign inverted.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.copy_sign">
|
||
<code class="descname">copy_sign</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.copy_sign" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Copies the sign from <em>y</em> to <em>x</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.divide">
|
||
<code class="descname">divide</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.divide" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <em>x</em> divided by <em>y</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.divide_int">
|
||
<code class="descname">divide_int</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.divide_int" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <em>x</em> divided by <em>y</em>, truncated to an integer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.divmod">
|
||
<code class="descname">divmod</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.divmod" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Divides two numbers and returns the integer part of the result.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.exp">
|
||
<code class="descname">exp</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.exp" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <cite>e ** x</cite>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.fma">
|
||
<code class="descname">fma</code><span class="sig-paren">(</span><em>x</em>, <em>y</em>, <em>z</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.fma" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <em>x</em> multiplied by <em>y</em>, plus <em>z</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.is_canonical">
|
||
<code class="descname">is_canonical</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.is_canonical" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is canonical; otherwise returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.is_finite">
|
||
<code class="descname">is_finite</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.is_finite" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is finite; otherwise returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.is_infinite">
|
||
<code class="descname">is_infinite</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.is_infinite" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is infinite; otherwise returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.is_nan">
|
||
<code class="descname">is_nan</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.is_nan" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is a qNaN or sNaN; otherwise returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.is_normal">
|
||
<code class="descname">is_normal</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.is_normal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is a normal number; otherwise returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.is_qnan">
|
||
<code class="descname">is_qnan</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.is_qnan" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is a quiet NaN; otherwise returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.is_signed">
|
||
<code class="descname">is_signed</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.is_signed" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is negative; otherwise returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.is_snan">
|
||
<code class="descname">is_snan</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.is_snan" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is a signaling NaN; otherwise returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.is_subnormal">
|
||
<code class="descname">is_subnormal</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.is_subnormal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is subnormal; otherwise returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.is_zero">
|
||
<code class="descname">is_zero</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.is_zero" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>x</em> is a zero; otherwise returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.ln">
|
||
<code class="descname">ln</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.ln" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the natural (base e) logarithm of <em>x</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.log10">
|
||
<code class="descname">log10</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.log10" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the base 10 logarithm of <em>x</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.logb">
|
||
<code class="descname">logb</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.logb" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the exponent of the magnitude of the operand’s MSD.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.logical_and">
|
||
<code class="descname">logical_and</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.logical_and" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Applies the logical operation <em>and</em> between each operand’s digits.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.logical_invert">
|
||
<code class="descname">logical_invert</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.logical_invert" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Invert all the digits in <em>x</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.logical_or">
|
||
<code class="descname">logical_or</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.logical_or" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Applies the logical operation <em>or</em> between each operand’s digits.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.logical_xor">
|
||
<code class="descname">logical_xor</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.logical_xor" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Applies the logical operation <em>xor</em> between each operand’s digits.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.max">
|
||
<code class="descname">max</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.max" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compares two values numerically and returns the maximum.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.max_mag">
|
||
<code class="descname">max_mag</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.max_mag" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compares the values numerically with their sign ignored.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.min">
|
||
<code class="descname">min</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.min" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compares two values numerically and returns the minimum.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.min_mag">
|
||
<code class="descname">min_mag</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.min_mag" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compares the values numerically with their sign ignored.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.minus">
|
||
<code class="descname">minus</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.minus" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Minus corresponds to the unary prefix minus operator in Python.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.multiply">
|
||
<code class="descname">multiply</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.multiply" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the product of <em>x</em> and <em>y</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.next_minus">
|
||
<code class="descname">next_minus</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.next_minus" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the largest representable number smaller than <em>x</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.next_plus">
|
||
<code class="descname">next_plus</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.next_plus" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the smallest representable number larger than <em>x</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.next_toward">
|
||
<code class="descname">next_toward</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.next_toward" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the number closest to <em>x</em>, in direction towards <em>y</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.normalize">
|
||
<code class="descname">normalize</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.normalize" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Reduces <em>x</em> to its simplest form.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.number_class">
|
||
<code class="descname">number_class</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.number_class" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns an indication of the class of <em>x</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.plus">
|
||
<code class="descname">plus</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.plus" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Plus corresponds to the unary prefix plus operator in Python. This
|
||
operation applies the context precision and rounding, so it is <em>not</em> an
|
||
identity operation.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.power">
|
||
<code class="descname">power</code><span class="sig-paren">(</span><em>x</em>, <em>y</em>, <em>modulo=None</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.power" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">x</span></code> to the power of <code class="docutils literal notranslate"><span class="pre">y</span></code>, reduced modulo <code class="docutils literal notranslate"><span class="pre">modulo</span></code> if given.</p>
|
||
<p>With two arguments, compute <code class="docutils literal notranslate"><span class="pre">x**y</span></code>. If <code class="docutils literal notranslate"><span class="pre">x</span></code> is negative then <code class="docutils literal notranslate"><span class="pre">y</span></code>
|
||
must be integral. The result will be inexact unless <code class="docutils literal notranslate"><span class="pre">y</span></code> is integral and
|
||
the result is finite and can be expressed exactly in ‘precision’ digits.
|
||
The rounding mode of the context is used. Results are always correctly-rounded
|
||
in the Python version.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>The C module computes <a class="reference internal" href="#decimal.Context.power" title="decimal.Context.power"><code class="xref py py-meth docutils literal notranslate"><span class="pre">power()</span></code></a> in terms of the correctly-rounded
|
||
<a class="reference internal" href="#decimal.Context.exp" title="decimal.Context.exp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">exp()</span></code></a> and <a class="reference internal" href="#decimal.Context.ln" title="decimal.Context.ln"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ln()</span></code></a> functions. The result is well-defined but
|
||
only “almost always correctly-rounded”.</p>
|
||
</div>
|
||
<p>With three arguments, compute <code class="docutils literal notranslate"><span class="pre">(x**y)</span> <span class="pre">%</span> <span class="pre">modulo</span></code>. For the three argument
|
||
form, the following restrictions on the arguments hold:</p>
|
||
<blockquote>
|
||
<div><ul class="simple">
|
||
<li><p>all three arguments must be integral</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">y</span></code> must be nonnegative</p></li>
|
||
<li><p>at least one of <code class="docutils literal notranslate"><span class="pre">x</span></code> or <code class="docutils literal notranslate"><span class="pre">y</span></code> must be nonzero</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">modulo</span></code> must be nonzero and have at most ‘precision’ digits</p></li>
|
||
</ul>
|
||
</div></blockquote>
|
||
<p>The value resulting from <code class="docutils literal notranslate"><span class="pre">Context.power(x,</span> <span class="pre">y,</span> <span class="pre">modulo)</span></code> is
|
||
equal to the value that would be obtained by computing <code class="docutils literal notranslate"><span class="pre">(x**y)</span>
|
||
<span class="pre">%</span> <span class="pre">modulo</span></code> with unbounded precision, but is computed more
|
||
efficiently. The exponent of the result is zero, regardless of
|
||
the exponents of <code class="docutils literal notranslate"><span class="pre">x</span></code>, <code class="docutils literal notranslate"><span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">modulo</span></code>. The result is
|
||
always exact.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.quantize">
|
||
<code class="descname">quantize</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.quantize" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns a value equal to <em>x</em> (rounded), having the exponent of <em>y</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.radix">
|
||
<code class="descname">radix</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.radix" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Just returns 10, as this is Decimal, :)</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.remainder">
|
||
<code class="descname">remainder</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.remainder" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the remainder from integer division.</p>
|
||
<p>The sign of the result, if non-zero, is the same as that of the original
|
||
dividend.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.remainder_near">
|
||
<code class="descname">remainder_near</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.remainder_near" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">-</span> <span class="pre">y</span> <span class="pre">*</span> <span class="pre">n</span></code>, where <em>n</em> is the integer nearest the exact value
|
||
of <code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">/</span> <span class="pre">y</span></code> (if the result is 0 then its sign will be the sign of <em>x</em>).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.rotate">
|
||
<code class="descname">rotate</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.rotate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns a rotated copy of <em>x</em>, <em>y</em> times.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.same_quantum">
|
||
<code class="descname">same_quantum</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.same_quantum" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if the two operands have the same exponent.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.scaleb">
|
||
<code class="descname">scaleb</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.scaleb" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the first operand after adding the second value its exp.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.shift">
|
||
<code class="descname">shift</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.shift" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns a shifted copy of <em>x</em>, <em>y</em> times.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.sqrt">
|
||
<code class="descname">sqrt</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.sqrt" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Square root of a non-negative number to context precision.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.subtract">
|
||
<code class="descname">subtract</code><span class="sig-paren">(</span><em>x</em>, <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.subtract" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the difference between <em>x</em> and <em>y</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.to_eng_string">
|
||
<code class="descname">to_eng_string</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.to_eng_string" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Convert to a string, using engineering notation if an exponent is needed.</p>
|
||
<p>Engineering notation has an exponent which is a multiple of 3. This
|
||
can leave up to 3 digits to the left of the decimal place and may
|
||
require the addition of either one or two trailing zeros.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.to_integral_exact">
|
||
<code class="descname">to_integral_exact</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.to_integral_exact" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Rounds to an integer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="decimal.Context.to_sci_string">
|
||
<code class="descname">to_sci_string</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#decimal.Context.to_sci_string" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Converts a number to a string using scientific notation.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="constants">
|
||
<span id="decimal-rounding-modes"></span><h2>Constants<a class="headerlink" href="#constants" title="Permalink to this headline">¶</a></h2>
|
||
<p>The constants in this section are only relevant for the C module. They
|
||
are also included in the pure Python version for compatibility.</p>
|
||
<table class="docutils align-center">
|
||
<colgroup>
|
||
<col style="width: 29%" />
|
||
<col style="width: 29%" />
|
||
<col style="width: 42%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"></th>
|
||
<th class="head"><p>32-bit</p></th>
|
||
<th class="head"><p>64-bit</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><dl class="data">
|
||
<dt id="decimal.MAX_PREC">
|
||
<code class="descclassname">decimal.</code><code class="descname">MAX_PREC</code><a class="headerlink" href="#decimal.MAX_PREC" title="Permalink to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
</td>
|
||
<td><p><code class="xref py py-const docutils literal notranslate"><span class="pre">425000000</span></code></p></td>
|
||
<td><p><code class="xref py py-const docutils literal notranslate"><span class="pre">999999999999999999</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><dl class="data">
|
||
<dt id="decimal.MAX_EMAX">
|
||
<code class="descclassname">decimal.</code><code class="descname">MAX_EMAX</code><a class="headerlink" href="#decimal.MAX_EMAX" title="Permalink to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
</td>
|
||
<td><p><code class="xref py py-const docutils literal notranslate"><span class="pre">425000000</span></code></p></td>
|
||
<td><p><code class="xref py py-const docutils literal notranslate"><span class="pre">999999999999999999</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><dl class="data">
|
||
<dt id="decimal.MIN_EMIN">
|
||
<code class="descclassname">decimal.</code><code class="descname">MIN_EMIN</code><a class="headerlink" href="#decimal.MIN_EMIN" title="Permalink to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
</td>
|
||
<td><p><code class="xref py py-const docutils literal notranslate"><span class="pre">-425000000</span></code></p></td>
|
||
<td><p><code class="xref py py-const docutils literal notranslate"><span class="pre">-999999999999999999</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><dl class="data">
|
||
<dt id="decimal.MIN_ETINY">
|
||
<code class="descclassname">decimal.</code><code class="descname">MIN_ETINY</code><a class="headerlink" href="#decimal.MIN_ETINY" title="Permalink to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
</td>
|
||
<td><p><code class="xref py py-const docutils literal notranslate"><span class="pre">-849999999</span></code></p></td>
|
||
<td><p><code class="xref py py-const docutils literal notranslate"><span class="pre">-1999999999999999997</span></code></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<dl class="data">
|
||
<dt id="decimal.HAVE_THREADS">
|
||
<code class="descclassname">decimal.</code><code class="descname">HAVE_THREADS</code><a class="headerlink" href="#decimal.HAVE_THREADS" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The default value is <code class="docutils literal notranslate"><span class="pre">True</span></code>. If Python is compiled without threads, the
|
||
C version automatically disables the expensive thread local context
|
||
machinery. In this case, the value is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="rounding-modes">
|
||
<h2>Rounding modes<a class="headerlink" href="#rounding-modes" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="data">
|
||
<dt id="decimal.ROUND_CEILING">
|
||
<code class="descclassname">decimal.</code><code class="descname">ROUND_CEILING</code><a class="headerlink" href="#decimal.ROUND_CEILING" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Round towards <code class="xref py py-const docutils literal notranslate"><span class="pre">Infinity</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="decimal.ROUND_DOWN">
|
||
<code class="descclassname">decimal.</code><code class="descname">ROUND_DOWN</code><a class="headerlink" href="#decimal.ROUND_DOWN" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Round towards zero.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="decimal.ROUND_FLOOR">
|
||
<code class="descclassname">decimal.</code><code class="descname">ROUND_FLOOR</code><a class="headerlink" href="#decimal.ROUND_FLOOR" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Round towards <code class="xref py py-const docutils literal notranslate"><span class="pre">-Infinity</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="decimal.ROUND_HALF_DOWN">
|
||
<code class="descclassname">decimal.</code><code class="descname">ROUND_HALF_DOWN</code><a class="headerlink" href="#decimal.ROUND_HALF_DOWN" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Round to nearest with ties going towards zero.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="decimal.ROUND_HALF_EVEN">
|
||
<code class="descclassname">decimal.</code><code class="descname">ROUND_HALF_EVEN</code><a class="headerlink" href="#decimal.ROUND_HALF_EVEN" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Round to nearest with ties going to nearest even integer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="decimal.ROUND_HALF_UP">
|
||
<code class="descclassname">decimal.</code><code class="descname">ROUND_HALF_UP</code><a class="headerlink" href="#decimal.ROUND_HALF_UP" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Round to nearest with ties going away from zero.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="decimal.ROUND_UP">
|
||
<code class="descclassname">decimal.</code><code class="descname">ROUND_UP</code><a class="headerlink" href="#decimal.ROUND_UP" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Round away from zero.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="decimal.ROUND_05UP">
|
||
<code class="descclassname">decimal.</code><code class="descname">ROUND_05UP</code><a class="headerlink" href="#decimal.ROUND_05UP" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Round away from zero if last digit after rounding towards zero would have
|
||
been 0 or 5; otherwise round towards zero.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="signals">
|
||
<span id="decimal-signals"></span><h2>Signals<a class="headerlink" href="#signals" title="Permalink to this headline">¶</a></h2>
|
||
<p>Signals represent conditions that arise during computation. Each corresponds to
|
||
one context flag and one context trap enabler.</p>
|
||
<p>The context flag is set 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>
|
||
<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 <a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-class docutils literal notranslate"><span class="pre">DivisionByZero</span></code></a> trap
|
||
is set, then a <a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DivisionByZero</span></code></a> exception is raised upon encountering the
|
||
condition.</p>
|
||
<dl class="class">
|
||
<dt id="decimal.Clamped">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">Clamped</code><a class="headerlink" href="#decimal.Clamped" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Altered an exponent to fit representation constraints.</p>
|
||
<p>Typically, clamping occurs when an exponent falls outside the context’s
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">Emin</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">Emax</span></code> limits. If possible, the exponent is reduced to
|
||
fit by adding zeros to the coefficient.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.DecimalException">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">DecimalException</code><a class="headerlink" href="#decimal.DecimalException" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Base class for other signals and a subclass of <a class="reference internal" href="exceptions.html#ArithmeticError" title="ArithmeticError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ArithmeticError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.DivisionByZero">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">DivisionByZero</code><a class="headerlink" href="#decimal.DivisionByZero" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Signals the division of a non-infinite number by zero.</p>
|
||
<p>Can occur with division, modulo division, or when raising a number to a negative
|
||
power. If this signal is not trapped, returns <code class="xref py py-const docutils literal notranslate"><span class="pre">Infinity</span></code> or
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">-Infinity</span></code> with the sign determined by the inputs to the calculation.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.Inexact">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">Inexact</code><a class="headerlink" href="#decimal.Inexact" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Indicates that rounding occurred and the result is not exact.</p>
|
||
<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.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.InvalidOperation">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">InvalidOperation</code><a class="headerlink" href="#decimal.InvalidOperation" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>An invalid operation was performed.</p>
|
||
<p>Indicates that an operation was requested that does not make sense. If not
|
||
trapped, returns <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code>. Possible causes include:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Infinity</span> <span class="o">-</span> <span class="n">Infinity</span>
|
||
<span class="mi">0</span> <span class="o">*</span> <span class="n">Infinity</span>
|
||
<span class="n">Infinity</span> <span class="o">/</span> <span class="n">Infinity</span>
|
||
<span class="n">x</span> <span class="o">%</span> <span class="mi">0</span>
|
||
<span class="n">Infinity</span> <span class="o">%</span> <span class="n">x</span>
|
||
<span class="n">sqrt</span><span class="p">(</span><span class="o">-</span><span class="n">x</span><span class="p">)</span> <span class="ow">and</span> <span class="n">x</span> <span class="o">></span> <span class="mi">0</span>
|
||
<span class="mi">0</span> <span class="o">**</span> <span class="mi">0</span>
|
||
<span class="n">x</span> <span class="o">**</span> <span class="p">(</span><span class="n">non</span><span class="o">-</span><span class="n">integer</span><span class="p">)</span>
|
||
<span class="n">x</span> <span class="o">**</span> <span class="n">Infinity</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.Overflow">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">Overflow</code><a class="headerlink" href="#decimal.Overflow" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Numerical overflow.</p>
|
||
<p>Indicates the exponent is larger than <code class="xref py py-attr docutils literal notranslate"><span class="pre">Emax</span></code> 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 <code class="xref py py-const docutils literal notranslate"><span class="pre">Infinity</span></code>. In either case, <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-class docutils literal notranslate"><span class="pre">Inexact</span></code></a> and <a class="reference internal" href="#decimal.Rounded" title="decimal.Rounded"><code class="xref py py-class docutils literal notranslate"><span class="pre">Rounded</span></code></a>
|
||
are also signaled.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.Rounded">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">Rounded</code><a class="headerlink" href="#decimal.Rounded" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Rounding occurred though possibly no information was lost.</p>
|
||
<p>Signaled whenever rounding discards digits; even if those digits are zero
|
||
(such as rounding <code class="xref py py-const docutils literal notranslate"><span class="pre">5.00</span></code> to <code class="xref py py-const docutils literal notranslate"><span class="pre">5.0</span></code>). If not trapped, returns
|
||
the result unchanged. This signal is used to detect loss of significant
|
||
digits.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.Subnormal">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">Subnormal</code><a class="headerlink" href="#decimal.Subnormal" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exponent was lower than <code class="xref py py-attr docutils literal notranslate"><span class="pre">Emin</span></code> prior to rounding.</p>
|
||
<p>Occurs when an operation result is subnormal (the exponent is too small). If
|
||
not trapped, returns the result unchanged.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.Underflow">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">Underflow</code><a class="headerlink" href="#decimal.Underflow" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Numerical underflow with result rounded to zero.</p>
|
||
<p>Occurs when a subnormal result is pushed to zero by rounding. <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-class docutils literal notranslate"><span class="pre">Inexact</span></code></a>
|
||
and <a class="reference internal" href="#decimal.Subnormal" title="decimal.Subnormal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Subnormal</span></code></a> are also signaled.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="decimal.FloatOperation">
|
||
<em class="property">class </em><code class="descclassname">decimal.</code><code class="descname">FloatOperation</code><a class="headerlink" href="#decimal.FloatOperation" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Enable stricter semantics for mixing floats and Decimals.</p>
|
||
<p>If the signal is not trapped (default), mixing floats and Decimals is
|
||
permitted in the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> constructor,
|
||
<a class="reference internal" href="#decimal.Context.create_decimal" title="decimal.Context.create_decimal"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_decimal()</span></code></a> and all comparison operators.
|
||
Both conversion and comparisons are exact. Any occurrence of a mixed
|
||
operation is silently recorded by setting <a class="reference internal" href="#decimal.FloatOperation" title="decimal.FloatOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FloatOperation</span></code></a> in the
|
||
context flags. Explicit conversions with <a class="reference internal" href="#decimal.Decimal.from_float" title="decimal.Decimal.from_float"><code class="xref py py-meth docutils literal notranslate"><span class="pre">from_float()</span></code></a>
|
||
or <a class="reference internal" href="#decimal.Context.create_decimal_from_float" title="decimal.Context.create_decimal_from_float"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_decimal_from_float()</span></code></a> do not set the flag.</p>
|
||
<p>Otherwise (the signal is trapped), only equality comparisons and explicit
|
||
conversions are silent. All other mixed operations raise <a class="reference internal" href="#decimal.FloatOperation" title="decimal.FloatOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FloatOperation</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<p>The following table summarizes the hierarchy of signals:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">exceptions</span><span class="o">.</span><span class="n">ArithmeticError</span><span class="p">(</span><span class="n">exceptions</span><span class="o">.</span><span class="n">Exception</span><span class="p">)</span>
|
||
<span class="n">DecimalException</span>
|
||
<span class="n">Clamped</span>
|
||
<span class="n">DivisionByZero</span><span class="p">(</span><span class="n">DecimalException</span><span class="p">,</span> <span class="n">exceptions</span><span class="o">.</span><span class="n">ZeroDivisionError</span><span class="p">)</span>
|
||
<span class="n">Inexact</span>
|
||
<span class="n">Overflow</span><span class="p">(</span><span class="n">Inexact</span><span class="p">,</span> <span class="n">Rounded</span><span class="p">)</span>
|
||
<span class="n">Underflow</span><span class="p">(</span><span class="n">Inexact</span><span class="p">,</span> <span class="n">Rounded</span><span class="p">,</span> <span class="n">Subnormal</span><span class="p">)</span>
|
||
<span class="n">InvalidOperation</span>
|
||
<span class="n">Rounded</span>
|
||
<span class="n">Subnormal</span>
|
||
<span class="n">FloatOperation</span><span class="p">(</span><span class="n">DecimalException</span><span class="p">,</span> <span class="n">exceptions</span><span class="o">.</span><span class="n">TypeError</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="floating-point-notes">
|
||
<span id="decimal-notes"></span><h2>Floating Point Notes<a class="headerlink" href="#floating-point-notes" title="Permalink to this headline">¶</a></h2>
|
||
<div class="section" id="mitigating-round-off-error-with-increased-precision">
|
||
<h3>Mitigating round-off error with increased precision<a class="headerlink" href="#mitigating-round-off-error-with-increased-precision" title="Permalink to this headline">¶</a></h3>
|
||
<p>The use of decimal floating point eliminates decimal representation error
|
||
(making it possible to represent <code class="xref py py-const docutils literal notranslate"><span class="pre">0.1</span></code> exactly); however, some operations
|
||
can still incur round-off error when non-zero digits exceed the fixed precision.</p>
|
||
<p>The effects of round-off error can be amplified by the addition or subtraction
|
||
of nearly offsetting quantities resulting in loss of significance. Knuth
|
||
provides two instructive examples where rounded floating point arithmetic with
|
||
insufficient precision causes the breakdown of the associative and distributive
|
||
properties of addition:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="go"># Examples from Seminumerical Algorithms, Section 4.2.2.</span>
|
||
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">decimal</span> <span class="k">import</span> <span class="n">Decimal</span><span class="p">,</span> <span class="n">getcontext</span>
|
||
<span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">8</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">u</span><span class="p">,</span> <span class="n">v</span><span class="p">,</span> <span class="n">w</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">11111113</span><span class="p">),</span> <span class="n">Decimal</span><span class="p">(</span><span class="o">-</span><span class="mi">11111111</span><span class="p">),</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'7.51111111'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="p">(</span><span class="n">u</span> <span class="o">+</span> <span class="n">v</span><span class="p">)</span> <span class="o">+</span> <span class="n">w</span>
|
||
<span class="go">Decimal('9.5111111')</span>
|
||
<span class="gp">>>> </span><span class="n">u</span> <span class="o">+</span> <span class="p">(</span><span class="n">v</span> <span class="o">+</span> <span class="n">w</span><span class="p">)</span>
|
||
<span class="go">Decimal('10')</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">u</span><span class="p">,</span> <span class="n">v</span><span class="p">,</span> <span class="n">w</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">20000</span><span class="p">),</span> <span class="n">Decimal</span><span class="p">(</span><span class="o">-</span><span class="mi">6</span><span class="p">),</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'6.0000003'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="p">(</span><span class="n">u</span><span class="o">*</span><span class="n">v</span><span class="p">)</span> <span class="o">+</span> <span class="p">(</span><span class="n">u</span><span class="o">*</span><span class="n">w</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.01')</span>
|
||
<span class="gp">>>> </span><span class="n">u</span> <span class="o">*</span> <span class="p">(</span><span class="n">v</span><span class="o">+</span><span class="n">w</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.0060000')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <a class="reference internal" href="#module-decimal" title="decimal: Implementation of the General Decimal Arithmetic Specification."><code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal</span></code></a> module makes it possible to restore the identities by
|
||
expanding the precision sufficiently to avoid loss of significance:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">20</span>
|
||
<span class="gp">>>> </span><span class="n">u</span><span class="p">,</span> <span class="n">v</span><span class="p">,</span> <span class="n">w</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">11111113</span><span class="p">),</span> <span class="n">Decimal</span><span class="p">(</span><span class="o">-</span><span class="mi">11111111</span><span class="p">),</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'7.51111111'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="p">(</span><span class="n">u</span> <span class="o">+</span> <span class="n">v</span><span class="p">)</span> <span class="o">+</span> <span class="n">w</span>
|
||
<span class="go">Decimal('9.51111111')</span>
|
||
<span class="gp">>>> </span><span class="n">u</span> <span class="o">+</span> <span class="p">(</span><span class="n">v</span> <span class="o">+</span> <span class="n">w</span><span class="p">)</span>
|
||
<span class="go">Decimal('9.51111111')</span>
|
||
<span class="go">>>></span>
|
||
<span class="gp">>>> </span><span class="n">u</span><span class="p">,</span> <span class="n">v</span><span class="p">,</span> <span class="n">w</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">20000</span><span class="p">),</span> <span class="n">Decimal</span><span class="p">(</span><span class="o">-</span><span class="mi">6</span><span class="p">),</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'6.0000003'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="p">(</span><span class="n">u</span><span class="o">*</span><span class="n">v</span><span class="p">)</span> <span class="o">+</span> <span class="p">(</span><span class="n">u</span><span class="o">*</span><span class="n">w</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.0060000')</span>
|
||
<span class="gp">>>> </span><span class="n">u</span> <span class="o">*</span> <span class="p">(</span><span class="n">v</span><span class="o">+</span><span class="n">w</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.0060000')</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="special-values">
|
||
<h3>Special values<a class="headerlink" href="#special-values" title="Permalink to this headline">¶</a></h3>
|
||
<p>The number system for the <a class="reference internal" href="#module-decimal" title="decimal: Implementation of the General Decimal Arithmetic Specification."><code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal</span></code></a> module provides special values
|
||
including <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">sNaN</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">-Infinity</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">Infinity</span></code>,
|
||
and two zeros, <code class="xref py py-const docutils literal notranslate"><span class="pre">+0</span></code> and <code class="xref py py-const docutils literal notranslate"><span class="pre">-0</span></code>.</p>
|
||
<p>Infinities can be constructed directly with: <code class="docutils literal notranslate"><span class="pre">Decimal('Infinity')</span></code>. Also,
|
||
they can arise from dividing by zero when the <a class="reference internal" href="#decimal.DivisionByZero" title="decimal.DivisionByZero"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DivisionByZero</span></code></a> signal is
|
||
not trapped. Likewise, when the <a class="reference internal" href="#decimal.Overflow" title="decimal.Overflow"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Overflow</span></code></a> signal is not trapped, infinity
|
||
can result from rounding beyond the limits of the largest representable number.</p>
|
||
<p>The infinities are signed (affine) and can be used in arithmetic operations
|
||
where they get treated as very large, indeterminate numbers. For instance,
|
||
adding a constant to infinity gives another infinite result.</p>
|
||
<p>Some operations are indeterminate and return <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code>, or if the
|
||
<a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a> signal is trapped, raise an exception. For example,
|
||
<code class="docutils literal notranslate"><span class="pre">0/0</span></code> returns <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code> which means “not a number”. This variety of
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code> is quiet and, once created, will flow through other computations
|
||
always resulting in another <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code>. This behavior can be useful for a
|
||
series of computations that occasionally have missing inputs — it allows the
|
||
calculation to proceed while flagging specific results as invalid.</p>
|
||
<p>A variant is <code class="xref py py-const docutils literal notranslate"><span class="pre">sNaN</span></code> which signals rather than remaining quiet after every
|
||
operation. This is a useful return value when an invalid result needs to
|
||
interrupt a calculation for special handling.</p>
|
||
<p>The behavior of Python’s comparison operators can be a little surprising where a
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code> is involved. A test for equality where one of the operands is a
|
||
quiet or signaling <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code> always returns <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> (even when doing
|
||
<code class="docutils literal notranslate"><span class="pre">Decimal('NaN')==Decimal('NaN')</span></code>), while a test for inequality always returns
|
||
<a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>. An attempt to compare two Decimals using any of the <code class="docutils literal notranslate"><span class="pre"><</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre"><=</span></code>, <code class="docutils literal notranslate"><span class="pre">></span></code> or <code class="docutils literal notranslate"><span class="pre">>=</span></code> operators will raise the <a class="reference internal" href="#decimal.InvalidOperation" title="decimal.InvalidOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InvalidOperation</span></code></a> signal
|
||
if either operand is a <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code>, and return <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> if this signal is
|
||
not trapped. Note that the General Decimal Arithmetic specification does not
|
||
specify the behavior of direct comparisons; these rules for comparisons
|
||
involving a <code class="xref py py-const docutils literal notranslate"><span class="pre">NaN</span></code> were taken from the IEEE 854 standard (see Table 3 in
|
||
section 5.7). To ensure strict standards-compliance, use the <code class="xref py py-meth docutils literal notranslate"><span class="pre">compare()</span></code>
|
||
and <code class="xref py py-meth docutils literal notranslate"><span class="pre">compare-signal()</span></code> methods instead.</p>
|
||
<p>The signed zeros can result from calculations that underflow. They keep the sign
|
||
that would have resulted if the calculation had been carried out to greater
|
||
precision. Since their magnitude is zero, both positive and negative zeros are
|
||
treated as equal and their sign is informational.</p>
|
||
<p>In addition to the two signed zeros which are distinct yet equal, there are
|
||
various representations of zero with differing precisions yet equivalent in
|
||
value. This takes a bit of getting used to. For an eye accustomed to
|
||
normalized floating point representations, it is not immediately obvious that
|
||
the following calculation returns a value equal to zero:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="mi">1</span> <span class="o">/</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'Infinity'</span><span class="p">)</span>
|
||
<span class="go">Decimal('0E-1000026')</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="working-with-threads">
|
||
<span id="decimal-threads"></span><h2>Working with threads<a class="headerlink" href="#working-with-threads" title="Permalink to this headline">¶</a></h2>
|
||
<p>The <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">getcontext()</span></code></a> function accesses a different <a class="reference internal" href="#decimal.Context" title="decimal.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> object for
|
||
each thread. Having separate thread contexts means that threads may make
|
||
changes (such as <code class="docutils literal notranslate"><span class="pre">getcontext().prec=10</span></code>) without interfering with other threads.</p>
|
||
<p>Likewise, the <a class="reference internal" href="#decimal.setcontext" title="decimal.setcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">setcontext()</span></code></a> function automatically assigns its target to
|
||
the current thread.</p>
|
||
<p>If <a class="reference internal" href="#decimal.setcontext" title="decimal.setcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">setcontext()</span></code></a> has not been called before <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">getcontext()</span></code></a>, then
|
||
<a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">getcontext()</span></code></a> will automatically create a new context for use in the
|
||
current thread.</p>
|
||
<p>The new context is copied from a prototype context called <em>DefaultContext</em>. To
|
||
control the defaults so that each thread will use the same values throughout the
|
||
application, directly modify the <em>DefaultContext</em> object. This should be done
|
||
<em>before</em> any threads are started so that there won’t be a race condition between
|
||
threads calling <a class="reference internal" href="#decimal.getcontext" title="decimal.getcontext"><code class="xref py py-func docutils literal notranslate"><span class="pre">getcontext()</span></code></a>. For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Set applicationwide defaults for all threads about to be launched</span>
|
||
<span class="n">DefaultContext</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">12</span>
|
||
<span class="n">DefaultContext</span><span class="o">.</span><span class="n">rounding</span> <span class="o">=</span> <span class="n">ROUND_DOWN</span>
|
||
<span class="n">DefaultContext</span><span class="o">.</span><span class="n">traps</span> <span class="o">=</span> <span class="n">ExtendedContext</span><span class="o">.</span><span class="n">traps</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
|
||
<span class="n">DefaultContext</span><span class="o">.</span><span class="n">traps</span><span class="p">[</span><span class="n">InvalidOperation</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span>
|
||
<span class="n">setcontext</span><span class="p">(</span><span class="n">DefaultContext</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Afterwards, the threads can be started</span>
|
||
<span class="n">t1</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
|
||
<span class="n">t2</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
|
||
<span class="n">t3</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
|
||
<span class="o">.</span> <span class="o">.</span> <span class="o">.</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="recipes">
|
||
<span id="decimal-recipes"></span><h2>Recipes<a class="headerlink" href="#recipes" title="Permalink to this headline">¶</a></h2>
|
||
<p>Here are a few recipes that serve as utility functions and that demonstrate ways
|
||
to work with the <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a> class:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">moneyfmt</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">places</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">curr</span><span class="o">=</span><span class="s1">''</span><span class="p">,</span> <span class="n">sep</span><span class="o">=</span><span class="s1">','</span><span class="p">,</span> <span class="n">dp</span><span class="o">=</span><span class="s1">'.'</span><span class="p">,</span>
|
||
<span class="n">pos</span><span class="o">=</span><span class="s1">''</span><span class="p">,</span> <span class="n">neg</span><span class="o">=</span><span class="s1">'-'</span><span class="p">,</span> <span class="n">trailneg</span><span class="o">=</span><span class="s1">''</span><span class="p">):</span>
|
||
<span class="sd">"""Convert Decimal to a money formatted string.</span>
|
||
|
||
<span class="sd"> places: required number of places after the decimal point</span>
|
||
<span class="sd"> curr: optional currency symbol before the sign (may be blank)</span>
|
||
<span class="sd"> sep: optional grouping separator (comma, period, space, or blank)</span>
|
||
<span class="sd"> dp: decimal point indicator (comma or period)</span>
|
||
<span class="sd"> only specify as blank when places is zero</span>
|
||
<span class="sd"> pos: optional sign for positive numbers: '+', space or blank</span>
|
||
<span class="sd"> neg: optional sign for negative numbers: '-', '(', space or blank</span>
|
||
<span class="sd"> trailneg:optional trailing minus indicator: '-', ')', space or blank</span>
|
||
|
||
<span class="sd"> >>> d = Decimal('-1234567.8901')</span>
|
||
<span class="sd"> >>> moneyfmt(d, curr='$')</span>
|
||
<span class="sd"> '-$1,234,567.89'</span>
|
||
<span class="sd"> >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')</span>
|
||
<span class="sd"> '1.234.568-'</span>
|
||
<span class="sd"> >>> moneyfmt(d, curr='$', neg='(', trailneg=')')</span>
|
||
<span class="sd"> '($1,234,567.89)'</span>
|
||
<span class="sd"> >>> moneyfmt(Decimal(123456789), sep=' ')</span>
|
||
<span class="sd"> '123 456 789.00'</span>
|
||
<span class="sd"> >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')</span>
|
||
<span class="sd"> '<0.02>'</span>
|
||
|
||
<span class="sd"> """</span>
|
||
<span class="n">q</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span> <span class="o">**</span> <span class="o">-</span><span class="n">places</span> <span class="c1"># 2 places --> '0.01'</span>
|
||
<span class="n">sign</span><span class="p">,</span> <span class="n">digits</span><span class="p">,</span> <span class="n">exp</span> <span class="o">=</span> <span class="n">value</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">q</span><span class="p">)</span><span class="o">.</span><span class="n">as_tuple</span><span class="p">()</span>
|
||
<span class="n">result</span> <span class="o">=</span> <span class="p">[]</span>
|
||
<span class="n">digits</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="n">digits</span><span class="p">))</span>
|
||
<span class="n">build</span><span class="p">,</span> <span class="nb">next</span> <span class="o">=</span> <span class="n">result</span><span class="o">.</span><span class="n">append</span><span class="p">,</span> <span class="n">digits</span><span class="o">.</span><span class="n">pop</span>
|
||
<span class="k">if</span> <span class="n">sign</span><span class="p">:</span>
|
||
<span class="n">build</span><span class="p">(</span><span class="n">trailneg</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">places</span><span class="p">):</span>
|
||
<span class="n">build</span><span class="p">(</span><span class="nb">next</span><span class="p">()</span> <span class="k">if</span> <span class="n">digits</span> <span class="k">else</span> <span class="s1">'0'</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">places</span><span class="p">:</span>
|
||
<span class="n">build</span><span class="p">(</span><span class="n">dp</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="ow">not</span> <span class="n">digits</span><span class="p">:</span>
|
||
<span class="n">build</span><span class="p">(</span><span class="s1">'0'</span><span class="p">)</span>
|
||
<span class="n">i</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="k">while</span> <span class="n">digits</span><span class="p">:</span>
|
||
<span class="n">build</span><span class="p">(</span><span class="nb">next</span><span class="p">())</span>
|
||
<span class="n">i</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
<span class="k">if</span> <span class="n">i</span> <span class="o">==</span> <span class="mi">3</span> <span class="ow">and</span> <span class="n">digits</span><span class="p">:</span>
|
||
<span class="n">i</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="n">build</span><span class="p">(</span><span class="n">sep</span><span class="p">)</span>
|
||
<span class="n">build</span><span class="p">(</span><span class="n">curr</span><span class="p">)</span>
|
||
<span class="n">build</span><span class="p">(</span><span class="n">neg</span> <span class="k">if</span> <span class="n">sign</span> <span class="k">else</span> <span class="n">pos</span><span class="p">)</span>
|
||
<span class="k">return</span> <span class="s1">''</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">reversed</span><span class="p">(</span><span class="n">result</span><span class="p">))</span>
|
||
|
||
<span class="k">def</span> <span class="nf">pi</span><span class="p">():</span>
|
||
<span class="sd">"""Compute Pi to the current precision.</span>
|
||
|
||
<span class="sd"> >>> print(pi())</span>
|
||
<span class="sd"> 3.141592653589793238462643383</span>
|
||
|
||
<span class="sd"> """</span>
|
||
<span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">+=</span> <span class="mi">2</span> <span class="c1"># extra digits for intermediate steps</span>
|
||
<span class="n">three</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span> <span class="c1"># substitute "three=3.0" for regular floats</span>
|
||
<span class="n">lasts</span><span class="p">,</span> <span class="n">t</span><span class="p">,</span> <span class="n">s</span><span class="p">,</span> <span class="n">n</span><span class="p">,</span> <span class="n">na</span><span class="p">,</span> <span class="n">d</span><span class="p">,</span> <span class="n">da</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">three</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">24</span>
|
||
<span class="k">while</span> <span class="n">s</span> <span class="o">!=</span> <span class="n">lasts</span><span class="p">:</span>
|
||
<span class="n">lasts</span> <span class="o">=</span> <span class="n">s</span>
|
||
<span class="n">n</span><span class="p">,</span> <span class="n">na</span> <span class="o">=</span> <span class="n">n</span><span class="o">+</span><span class="n">na</span><span class="p">,</span> <span class="n">na</span><span class="o">+</span><span class="mi">8</span>
|
||
<span class="n">d</span><span class="p">,</span> <span class="n">da</span> <span class="o">=</span> <span class="n">d</span><span class="o">+</span><span class="n">da</span><span class="p">,</span> <span class="n">da</span><span class="o">+</span><span class="mi">32</span>
|
||
<span class="n">t</span> <span class="o">=</span> <span class="p">(</span><span class="n">t</span> <span class="o">*</span> <span class="n">n</span><span class="p">)</span> <span class="o">/</span> <span class="n">d</span>
|
||
<span class="n">s</span> <span class="o">+=</span> <span class="n">t</span>
|
||
<span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">-=</span> <span class="mi">2</span>
|
||
<span class="k">return</span> <span class="o">+</span><span class="n">s</span> <span class="c1"># unary plus applies the new precision</span>
|
||
|
||
<span class="k">def</span> <span class="nf">exp</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
|
||
<span class="sd">"""Return e raised to the power of x. Result type matches input type.</span>
|
||
|
||
<span class="sd"> >>> print(exp(Decimal(1)))</span>
|
||
<span class="sd"> 2.718281828459045235360287471</span>
|
||
<span class="sd"> >>> print(exp(Decimal(2)))</span>
|
||
<span class="sd"> 7.389056098930650227230427461</span>
|
||
<span class="sd"> >>> print(exp(2.0))</span>
|
||
<span class="sd"> 7.38905609893</span>
|
||
<span class="sd"> >>> print(exp(2+0j))</span>
|
||
<span class="sd"> (7.38905609893+0j)</span>
|
||
|
||
<span class="sd"> """</span>
|
||
<span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">+=</span> <span class="mi">2</span>
|
||
<span class="n">i</span><span class="p">,</span> <span class="n">lasts</span><span class="p">,</span> <span class="n">s</span><span class="p">,</span> <span class="n">fact</span><span class="p">,</span> <span class="n">num</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span>
|
||
<span class="k">while</span> <span class="n">s</span> <span class="o">!=</span> <span class="n">lasts</span><span class="p">:</span>
|
||
<span class="n">lasts</span> <span class="o">=</span> <span class="n">s</span>
|
||
<span class="n">i</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
<span class="n">fact</span> <span class="o">*=</span> <span class="n">i</span>
|
||
<span class="n">num</span> <span class="o">*=</span> <span class="n">x</span>
|
||
<span class="n">s</span> <span class="o">+=</span> <span class="n">num</span> <span class="o">/</span> <span class="n">fact</span>
|
||
<span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">-=</span> <span class="mi">2</span>
|
||
<span class="k">return</span> <span class="o">+</span><span class="n">s</span>
|
||
|
||
<span class="k">def</span> <span class="nf">cos</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
|
||
<span class="sd">"""Return the cosine of x as measured in radians.</span>
|
||
|
||
<span class="sd"> The Taylor series approximation works best for a small value of x.</span>
|
||
<span class="sd"> For larger values, first compute x = x % (2 * pi).</span>
|
||
|
||
<span class="sd"> >>> print(cos(Decimal('0.5')))</span>
|
||
<span class="sd"> 0.8775825618903727161162815826</span>
|
||
<span class="sd"> >>> print(cos(0.5))</span>
|
||
<span class="sd"> 0.87758256189</span>
|
||
<span class="sd"> >>> print(cos(0.5+0j))</span>
|
||
<span class="sd"> (0.87758256189+0j)</span>
|
||
|
||
<span class="sd"> """</span>
|
||
<span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">+=</span> <span class="mi">2</span>
|
||
<span class="n">i</span><span class="p">,</span> <span class="n">lasts</span><span class="p">,</span> <span class="n">s</span><span class="p">,</span> <span class="n">fact</span><span class="p">,</span> <span class="n">num</span><span class="p">,</span> <span class="n">sign</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span>
|
||
<span class="k">while</span> <span class="n">s</span> <span class="o">!=</span> <span class="n">lasts</span><span class="p">:</span>
|
||
<span class="n">lasts</span> <span class="o">=</span> <span class="n">s</span>
|
||
<span class="n">i</span> <span class="o">+=</span> <span class="mi">2</span>
|
||
<span class="n">fact</span> <span class="o">*=</span> <span class="n">i</span> <span class="o">*</span> <span class="p">(</span><span class="n">i</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="n">num</span> <span class="o">*=</span> <span class="n">x</span> <span class="o">*</span> <span class="n">x</span>
|
||
<span class="n">sign</span> <span class="o">*=</span> <span class="o">-</span><span class="mi">1</span>
|
||
<span class="n">s</span> <span class="o">+=</span> <span class="n">num</span> <span class="o">/</span> <span class="n">fact</span> <span class="o">*</span> <span class="n">sign</span>
|
||
<span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">-=</span> <span class="mi">2</span>
|
||
<span class="k">return</span> <span class="o">+</span><span class="n">s</span>
|
||
|
||
<span class="k">def</span> <span class="nf">sin</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
|
||
<span class="sd">"""Return the sine of x as measured in radians.</span>
|
||
|
||
<span class="sd"> The Taylor series approximation works best for a small value of x.</span>
|
||
<span class="sd"> For larger values, first compute x = x % (2 * pi).</span>
|
||
|
||
<span class="sd"> >>> print(sin(Decimal('0.5')))</span>
|
||
<span class="sd"> 0.4794255386042030002732879352</span>
|
||
<span class="sd"> >>> print(sin(0.5))</span>
|
||
<span class="sd"> 0.479425538604</span>
|
||
<span class="sd"> >>> print(sin(0.5+0j))</span>
|
||
<span class="sd"> (0.479425538604+0j)</span>
|
||
|
||
<span class="sd"> """</span>
|
||
<span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">+=</span> <span class="mi">2</span>
|
||
<span class="n">i</span><span class="p">,</span> <span class="n">lasts</span><span class="p">,</span> <span class="n">s</span><span class="p">,</span> <span class="n">fact</span><span class="p">,</span> <span class="n">num</span><span class="p">,</span> <span class="n">sign</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="mi">1</span>
|
||
<span class="k">while</span> <span class="n">s</span> <span class="o">!=</span> <span class="n">lasts</span><span class="p">:</span>
|
||
<span class="n">lasts</span> <span class="o">=</span> <span class="n">s</span>
|
||
<span class="n">i</span> <span class="o">+=</span> <span class="mi">2</span>
|
||
<span class="n">fact</span> <span class="o">*=</span> <span class="n">i</span> <span class="o">*</span> <span class="p">(</span><span class="n">i</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="n">num</span> <span class="o">*=</span> <span class="n">x</span> <span class="o">*</span> <span class="n">x</span>
|
||
<span class="n">sign</span> <span class="o">*=</span> <span class="o">-</span><span class="mi">1</span>
|
||
<span class="n">s</span> <span class="o">+=</span> <span class="n">num</span> <span class="o">/</span> <span class="n">fact</span> <span class="o">*</span> <span class="n">sign</span>
|
||
<span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">-=</span> <span class="mi">2</span>
|
||
<span class="k">return</span> <span class="o">+</span><span class="n">s</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="decimal-faq">
|
||
<span id="id1"></span><h2>Decimal FAQ<a class="headerlink" href="#decimal-faq" title="Permalink to this headline">¶</a></h2>
|
||
<p>Q. It is cumbersome to type <code class="docutils literal notranslate"><span class="pre">decimal.Decimal('1234.5')</span></code>. Is there a way to
|
||
minimize typing when using the interactive interpreter?</p>
|
||
<p>A. Some users abbreviate the constructor to just a single letter:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">D</span> <span class="o">=</span> <span class="n">decimal</span><span class="o">.</span><span class="n">Decimal</span>
|
||
<span class="gp">>>> </span><span class="n">D</span><span class="p">(</span><span class="s1">'1.23'</span><span class="p">)</span> <span class="o">+</span> <span class="n">D</span><span class="p">(</span><span class="s1">'3.45'</span><span class="p">)</span>
|
||
<span class="go">Decimal('4.68')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Q. In a fixed-point application with two decimal places, some inputs have many
|
||
places and need to be rounded. Others are not supposed to have excess digits
|
||
and need to be validated. What methods should be used?</p>
|
||
<p>A. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">quantize()</span></code> method rounds to a fixed number of decimal places. If
|
||
the <a class="reference internal" href="#decimal.Inexact" title="decimal.Inexact"><code class="xref py py-const docutils literal notranslate"><span class="pre">Inexact</span></code></a> trap is set, it is also useful for validation:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">TWOPLACES</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span> <span class="o">**</span> <span class="o">-</span><span class="mi">2</span> <span class="c1"># same as Decimal('0.01')</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># Round to two places</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.214'</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">TWOPLACES</span><span class="p">)</span>
|
||
<span class="go">Decimal('3.21')</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># Validate that a number does not exceed two places</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.21'</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">TWOPLACES</span><span class="p">,</span> <span class="n">context</span><span class="o">=</span><span class="n">Context</span><span class="p">(</span><span class="n">traps</span><span class="o">=</span><span class="p">[</span><span class="n">Inexact</span><span class="p">]))</span>
|
||
<span class="go">Decimal('3.21')</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.214'</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">TWOPLACES</span><span class="p">,</span> <span class="n">context</span><span class="o">=</span><span class="n">Context</span><span class="p">(</span><span class="n">traps</span><span class="o">=</span><span class="p">[</span><span class="n">Inexact</span><span class="p">]))</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="c">...</span>
|
||
<span class="gr">Inexact</span>: <span class="n">None</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Q. Once I have valid two place inputs, how do I maintain that invariant
|
||
throughout an application?</p>
|
||
<p>A. Some operations like addition, subtraction, and multiplication by an integer
|
||
will automatically preserve fixed point. Others operations, like division and
|
||
non-integer multiplication, will change the number of decimal places and need to
|
||
be followed-up with a <code class="xref py py-meth docutils literal notranslate"><span class="pre">quantize()</span></code> step:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'102.72'</span><span class="p">)</span> <span class="c1"># Initial fixed-point values</span>
|
||
<span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.17'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">a</span> <span class="o">+</span> <span class="n">b</span> <span class="c1"># Addition preserves fixed-point</span>
|
||
<span class="go">Decimal('105.89')</span>
|
||
<span class="gp">>>> </span><span class="n">a</span> <span class="o">-</span> <span class="n">b</span>
|
||
<span class="go">Decimal('99.55')</span>
|
||
<span class="gp">>>> </span><span class="n">a</span> <span class="o">*</span> <span class="mi">42</span> <span class="c1"># So does integer multiplication</span>
|
||
<span class="go">Decimal('4314.24')</span>
|
||
<span class="gp">>>> </span><span class="p">(</span><span class="n">a</span> <span class="o">*</span> <span class="n">b</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">TWOPLACES</span><span class="p">)</span> <span class="c1"># Must quantize non-integer multiplication</span>
|
||
<span class="go">Decimal('325.62')</span>
|
||
<span class="gp">>>> </span><span class="p">(</span><span class="n">b</span> <span class="o">/</span> <span class="n">a</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">TWOPLACES</span><span class="p">)</span> <span class="c1"># And quantize division</span>
|
||
<span class="go">Decimal('0.03')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In developing fixed-point applications, it is convenient to define functions
|
||
to handle the <code class="xref py py-meth docutils literal notranslate"><span class="pre">quantize()</span></code> step:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">def</span> <span class="nf">mul</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">fp</span><span class="o">=</span><span class="n">TWOPLACES</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="p">(</span><span class="n">x</span> <span class="o">*</span> <span class="n">y</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">fp</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="k">def</span> <span class="nf">div</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">fp</span><span class="o">=</span><span class="n">TWOPLACES</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="p">(</span><span class="n">x</span> <span class="o">/</span> <span class="n">y</span><span class="p">)</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">fp</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mul</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span> <span class="c1"># Automatically preserve fixed-point</span>
|
||
<span class="go">Decimal('325.62')</span>
|
||
<span class="gp">>>> </span><span class="n">div</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">a</span><span class="p">)</span>
|
||
<span class="go">Decimal('0.03')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Q. There are many ways to express the same value. The numbers <code class="xref py py-const docutils literal notranslate"><span class="pre">200</span></code>,
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">200.000</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">2E2</span></code>, and <code class="xref py py-const docutils literal notranslate"><span class="pre">02E+4</span></code> all have the same value at
|
||
various precisions. Is there a way to transform them to a single recognizable
|
||
canonical value?</p>
|
||
<p>A. The <code class="xref py py-meth docutils literal notranslate"><span class="pre">normalize()</span></code> method maps all equivalent values to a single
|
||
representative:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">values</span> <span class="o">=</span> <span class="nb">map</span><span class="p">(</span><span class="n">Decimal</span><span class="p">,</span> <span class="s1">'200 200.000 2E2 .02E+4'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
|
||
<span class="gp">>>> </span><span class="p">[</span><span class="n">v</span><span class="o">.</span><span class="n">normalize</span><span class="p">()</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">values</span><span class="p">]</span>
|
||
<span class="go">[Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Q. Some decimal values always print with exponential notation. Is there a way
|
||
to get a non-exponential representation?</p>
|
||
<p>A. For some values, exponential notation is the only way to express the number
|
||
of significant places in the coefficient. For example, expressing
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">5.0E+3</span></code> as <code class="xref py py-const docutils literal notranslate"><span class="pre">5000</span></code> keeps the value constant but cannot show the
|
||
original’s two-place significance.</p>
|
||
<p>If an application does not care about tracking significance, it is easy to
|
||
remove the exponent and trailing zeroes, losing significance, but keeping the
|
||
value unchanged:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">def</span> <span class="nf">remove_exponent</span><span class="p">(</span><span class="n">d</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="n">d</span><span class="o">.</span><span class="n">quantize</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="mi">1</span><span class="p">))</span> <span class="k">if</span> <span class="n">d</span> <span class="o">==</span> <span class="n">d</span><span class="o">.</span><span class="n">to_integral</span><span class="p">()</span> <span class="k">else</span> <span class="n">d</span><span class="o">.</span><span class="n">normalize</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">remove_exponent</span><span class="p">(</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'5E+3'</span><span class="p">))</span>
|
||
<span class="go">Decimal('5000')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Q. Is there a way to convert a regular float to a <a class="reference internal" href="#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decimal</span></code></a>?</p>
|
||
<p>A. Yes, any binary floating point number can be exactly expressed as a
|
||
Decimal though an exact conversion may take more precision than intuition would
|
||
suggest:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">pi</span><span class="p">)</span>
|
||
<span class="go">Decimal('3.141592653589793115997963468544185161590576171875')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Q. Within a complex calculation, how can I make sure that I haven’t gotten a
|
||
spurious result because of insufficient precision or rounding anomalies.</p>
|
||
<p>A. The decimal module makes it easy to test results. A best practice is to
|
||
re-run calculations using greater precision and with various rounding modes.
|
||
Widely differing results indicate insufficient precision, rounding mode issues,
|
||
ill-conditioned inputs, or a numerically unstable algorithm.</p>
|
||
<p>Q. I noticed that context precision is applied to the results of operations but
|
||
not to the inputs. Is there anything to watch out for when mixing values of
|
||
different precisions?</p>
|
||
<p>A. Yes. The principle is that all values are considered to be exact and so is
|
||
the arithmetic on those values. Only the results are rounded. The advantage
|
||
for inputs is that “what you type is what you get”. A disadvantage is that the
|
||
results can look odd if you forget that the inputs haven’t been rounded:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">3</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.104'</span><span class="p">)</span> <span class="o">+</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'2.104'</span><span class="p">)</span>
|
||
<span class="go">Decimal('5.21')</span>
|
||
<span class="gp">>>> </span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'3.104'</span><span class="p">)</span> <span class="o">+</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'0.000'</span><span class="p">)</span> <span class="o">+</span> <span class="n">Decimal</span><span class="p">(</span><span class="s1">'2.104'</span><span class="p">)</span>
|
||
<span class="go">Decimal('5.20')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The solution is either to increase precision or to force rounding of inputs
|
||
using the unary plus operation:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">getcontext</span><span class="p">()</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="mi">3</span>
|
||
<span class="gp">>>> </span><span class="o">+</span><span class="n">Decimal</span><span class="p">(</span><span class="s1">'1.23456789'</span><span class="p">)</span> <span class="c1"># unary plus triggers rounding</span>
|
||
<span class="go">Decimal('1.23')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Alternatively, inputs can be rounded upon creation using the
|
||
<a class="reference internal" href="#decimal.Context.create_decimal" title="decimal.Context.create_decimal"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Context.create_decimal()</span></code></a> method:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">Context</span><span class="p">(</span><span class="n">prec</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span> <span class="n">rounding</span><span class="o">=</span><span class="n">ROUND_DOWN</span><span class="p">)</span><span class="o">.</span><span class="n">create_decimal</span><span class="p">(</span><span class="s1">'1.2345678'</span><span class="p">)</span>
|
||
<span class="go">Decimal('1.2345')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Q. Is the CPython implementation fast for large numbers?</p>
|
||
<p>A. Yes. In the CPython and PyPy3 implementations, the C/CFFI versions of
|
||
the decimal module integrate the high speed <a class="reference external" href="https://www.bytereef.org/mpdecimal/doc/libmpdec/index.html">libmpdec</a> library for
|
||
arbitrary precision correctly-rounded decimal floating point arithmetic.
|
||
<code class="docutils literal notranslate"><span class="pre">libmpdec</span></code> uses <a class="reference external" href="https://en.wikipedia.org/wiki/Karatsuba_algorithm">Karatsuba multiplication</a>
|
||
for medium-sized numbers and the <a class="reference external" href="https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general)#Number-theoretic_transform">Number Theoretic Transform</a>
|
||
for very large numbers. However, to realize this performance gain, the
|
||
context needs to be set for unrounded calculations.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">getcontext</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">prec</span> <span class="o">=</span> <span class="n">MAX_PREC</span>
|
||
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">Emax</span> <span class="o">=</span> <span class="n">MAX_EMAX</span>
|
||
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">Emin</span> <span class="o">=</span> <span class="n">MIN_EMIN</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">decimal</span></code> — Decimal fixed point and floating point arithmetic</a><ul>
|
||
<li><a class="reference internal" href="#quick-start-tutorial">Quick-start Tutorial</a></li>
|
||
<li><a class="reference internal" href="#decimal-objects">Decimal objects</a><ul>
|
||
<li><a class="reference internal" href="#logical-operands">Logical operands</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#context-objects">Context objects</a></li>
|
||
<li><a class="reference internal" href="#constants">Constants</a></li>
|
||
<li><a class="reference internal" href="#rounding-modes">Rounding modes</a></li>
|
||
<li><a class="reference internal" href="#signals">Signals</a></li>
|
||
<li><a class="reference internal" href="#floating-point-notes">Floating Point Notes</a><ul>
|
||
<li><a class="reference internal" href="#mitigating-round-off-error-with-increased-precision">Mitigating round-off error with increased precision</a></li>
|
||
<li><a class="reference internal" href="#special-values">Special values</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#working-with-threads">Working with threads</a></li>
|
||
<li><a class="reference internal" href="#recipes">Recipes</a></li>
|
||
<li><a class="reference internal" href="#decimal-faq">Decimal FAQ</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="cmath.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cmath</span></code> — Mathematical functions for complex numbers</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="fractions.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">fractions</span></code> — Rational numbers</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/decimal.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="fractions.html" title="fractions — Rational numbers"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="cmath.html" title="cmath — Mathematical functions for complex numbers"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="numeric.html" >Numeric and Mathematical Modules</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |