<!DOCTYPE html><html><head>
<title>math::decimal - Tcl Decimal Arithmetic Library</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
--></style>
</head>
<!-- Generated from file 'decimal.man' by tcllib/doctools with format 'html'
-->
<!-- Copyright &copy; 2011 Mark Alston &lt;mark at beernut dot com&gt;
-->
<!-- math::decimal.n
-->
<body><hr> [
<a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">math::decimal(n) 1.0.3 tcllib "Tcl Decimal Arithmetic Library"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>math::decimal - General decimal arithmetic</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">EXAMPLES</a></li>
<li class="doctools_section"><a href="#section3">API</a></li>
<li class="doctools_section"><a href="#section4">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl <span class="opt">?8.5?</span></b></li>
<li>package require <b class="pkgname">math::decimal 1.0.3</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd">::math::decimal::fromstr</b> <i class="arg">string</i></a></li>
<li><a href="#2"><b class="cmd">::math::decimal::tostr</b> <i class="arg">decimal</i></a></li>
<li><a href="#3"><b class="cmd">::math::decimal::setVariable</b> <i class="arg">variable</i> <i class="arg">setting</i></a></li>
<li><a href="#4"><b class="cmd">::math::decimal::add</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#5"><b class="cmd">::math::decimal::+</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#6"><b class="cmd">::math::decimal::subtract</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#7"><b class="cmd">::math::decimal::-</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#8"><b class="cmd">::math::decimal::multiply</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#9"><b class="cmd">::math::decimal::*</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#10"><b class="cmd">::math::decimal::divide</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#11"><b class="cmd">::math::decimal::/</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#12"><b class="cmd">::math::decimal::divideint</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#13"><b class="cmd">::math::decimal::remainder</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#14"><b class="cmd">::math::decimal::abs</b> <i class="arg">decimal</i></a></li>
<li><a href="#15"><b class="cmd">::math::decimal::compare</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#16"><b class="cmd">::math::decimal::max</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#17"><b class="cmd">::math::decimal::maxmag</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#18"><b class="cmd">::math::decimal::min</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#19"><b class="cmd">::math::decimal::minmag</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#20"><b class="cmd">::math::decimal::plus</b> <i class="arg">a</i></a></li>
<li><a href="#21"><b class="cmd">::math::decimal::minus</b> <i class="arg">a</i></a></li>
<li><a href="#22"><b class="cmd">::math::decimal::copynegate</b> <i class="arg">a</i></a></li>
<li><a href="#23"><b class="cmd">::math::decimal::copysign</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#24"><b class="cmd">::math::decimal::is-signed</b> <i class="arg">decimal</i></a></li>
<li><a href="#25"><b class="cmd">::math::decimal::is-zero</b> <i class="arg">decimal</i></a></li>
<li><a href="#26"><b class="cmd">::math::decimal::is-NaN</b> <i class="arg">decimal</i></a></li>
<li><a href="#27"><b class="cmd">::math::decimal::is-infinite</b> <i class="arg">decimal</i></a></li>
<li><a href="#28"><b class="cmd">::math::decimal::is-finite</b> <i class="arg">decimal</i></a></li>
<li><a href="#29"><b class="cmd">::math::decimal::fma</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">c</i></a></li>
<li><a href="#30"><b class="cmd">::math::decimal::round_half_even</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#31"><b class="cmd">::math::decimal::round_half_up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#32"><b class="cmd">::math::decimal::round_half_down</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#33"><b class="cmd">::math::decimal::round_down</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#34"><b class="cmd">::math::decimal::round_up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#35"><b class="cmd">::math::decimal::round_floor</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#36"><b class="cmd">::math::decimal::round_ceiling</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
<li><a href="#37"><b class="cmd">::math::decimal::round_05up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>The decimal package provides decimal arithmetic support for both limited
precision floating point and arbitrary precision floating point.
Additionally, integer arithmetic is supported.</p>
<p>More information and the specifications on which this package depends can be
found on the general decimal arithmetic page at http://speleotrove.com/decimal
This package provides for:</p>
<ul class="doctools_itemized">
<li><p>A new data type decimal which is represented as a list containing sign,
mantissa and exponent.</p></li>
<li><p>Arithmetic operations on those decimal numbers such as addition, subtraction,
multiplication, etc...</p></li>
</ul>
<p>Numbers are converted to decimal format using the operation ::math::decimal::fromstr.</p>
<p>Numbers are converted back to string format using the operation
::math::decimal::tostr.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">EXAMPLES</a></h2>
<p>This section shows some simple examples. Since the purpose of this library
is to perform decimal math operations, examples may be the simplest way
to learn how to work with it and to see the difference between using this
package and sticking with expr. Consult the API section of
this man page for information about individual procedures.</p>
<pre class="doctools_example">
package require math::decimal
# Various operations on two numbers.
# We first convert them to decimal format.
set a [::math::decimal::fromstr 8.2]
set b [::math::decimal::fromstr .2]
# Then we perform our operations. Here we add
set c [::math::decimal::+ $a $b]
# Finally we convert back to string format for presentation to the user.
puts [::math::decimal::tostr $c] ; # => will output 8.4
# Other examples
#
# Subtraction
set c [::math::decimal::- $a $b]
puts [::math::decimal::tostr $c] ; # => will output 8.0
# Why bother using this instead of simply expr?
puts 8.399999999999999 ; # => will output 8.399999999999999
puts 7.999999999999999 ; # => will output 7.999999999999999
# See http://speleotrove.com/decimal to learn more about why this happens.
</pre>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd">::math::decimal::fromstr</b> <i class="arg">string</i></a></dt>
<dd><p>Convert <em>string</em> into a decimal.</p></dd>
<dt><a name="2"><b class="cmd">::math::decimal::tostr</b> <i class="arg">decimal</i></a></dt>
<dd><p>Convert <em>decimal</em> into a string representing the number in base 10.</p></dd>
<dt><a name="3"><b class="cmd">::math::decimal::setVariable</b> <i class="arg">variable</i> <i class="arg">setting</i></a></dt>
<dd><p>Sets the <em>variable</em> to <em>setting</em>. Valid variables are:</p>
<ul class="doctools_itemized">
<li><p><i class="arg">rounding</i> - Method of rounding to use during rescale. Valid
methods are round_half_even, round_half_up, round_half_down,
round_down, round_up, round_floor, round_ceiling.</p></li>
<li><p><i class="arg">precision</i> - Maximum number of digits allowed in mantissa.</p></li>
<li><p><i class="arg">extended</i> - Set to 1 for extended mode. 0 for simplified mode.</p></li>
<li><p><i class="arg">maxExponent</i> - Maximum value for the exponent. Defaults to 999.</p></li>
<li><p><i class="arg">minExponent</i> - Minimum value for the exponent. Default to -998.</p></li>
</ul></dd>
<dt><a name="4"><b class="cmd">::math::decimal::add</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd></dd>
<dt><a name="5"><b class="cmd">::math::decimal::+</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the sum of the two decimals <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="6"><b class="cmd">::math::decimal::subtract</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd></dd>
<dt><a name="7"><b class="cmd">::math::decimal::-</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the differnece of the two decimals <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="8"><b class="cmd">::math::decimal::multiply</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd></dd>
<dt><a name="9"><b class="cmd">::math::decimal::*</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the product of the two decimals <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="10"><b class="cmd">::math::decimal::divide</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd></dd>
<dt><a name="11"><b class="cmd">::math::decimal::/</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the quotient of the division between the two
decimals <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="12"><b class="cmd">::math::decimal::divideint</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return a the integer portion of the quotient of the division between
decimals <em>a</em> and <em>b</em></p></dd>
<dt><a name="13"><b class="cmd">::math::decimal::remainder</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Return the remainder of the division between the two
decimals <em>a</em> and <em>b</em>.</p></dd>
<dt><a name="14"><b class="cmd">::math::decimal::abs</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return the absolute value of the decimal.</p></dd>
<dt><a name="15"><b class="cmd">::math::decimal::compare</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two decimals a and b, returning <em>0</em> if <em>a == b</em>,
<em>1</em> if <em>a > b</em>, and <em>-1</em> if <em>a < b</em>.</p></dd>
<dt><a name="16"><b class="cmd">::math::decimal::max</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two decimals a and b, and return <em>a</em> if <em>a >= b</em>, and <em>b</em> if <em>a < b</em>.</p></dd>
<dt><a name="17"><b class="cmd">::math::decimal::maxmag</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two decimals a and b while ignoring their signs, and return <em>a</em> if <em>abs(a) >= abs(b)</em>, and <em>b</em> if <em>abs(a) < abs(b)</em>.</p></dd>
<dt><a name="18"><b class="cmd">::math::decimal::min</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two decimals a and b, and return <em>a</em> if <em>a <= b</em>, and <em>b</em> if <em>a > b</em>.</p></dd>
<dt><a name="19"><b class="cmd">::math::decimal::minmag</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Compare the two decimals a and b while ignoring their signs, and return <em>a</em> if <em>abs(a) <= abs(b)</em>, and <em>b</em> if <em>abs(a) > abs(b)</em>.</p></dd>
<dt><a name="20"><b class="cmd">::math::decimal::plus</b> <i class="arg">a</i></a></dt>
<dd><p>Return the result from <em>::math::decimal::+ 0 $a</em>.</p></dd>
<dt><a name="21"><b class="cmd">::math::decimal::minus</b> <i class="arg">a</i></a></dt>
<dd><p>Return the result from <em>::math::decimal::- 0 $a</em>.</p></dd>
<dt><a name="22"><b class="cmd">::math::decimal::copynegate</b> <i class="arg">a</i></a></dt>
<dd><p>Returns <em>a</em> with the sign flipped.</p></dd>
<dt><a name="23"><b class="cmd">::math::decimal::copysign</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd><p>Returns <em>a</em> with the sign set to the sign of the <em>b</em>.</p></dd>
<dt><a name="24"><b class="cmd">::math::decimal::is-signed</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return the sign of the decimal.
The procedure returns 0 if the number is positive, 1 if it's negative.</p></dd>
<dt><a name="25"><b class="cmd">::math::decimal::is-zero</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return true if <em>decimal</em> value is zero, otherwise false is returned.</p></dd>
<dt><a name="26"><b class="cmd">::math::decimal::is-NaN</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return true if <em>decimal</em> value is NaN (not a number), otherwise false is returned.</p></dd>
<dt><a name="27"><b class="cmd">::math::decimal::is-infinite</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return true if <em>decimal</em> value is Infinite, otherwise false is returned.</p></dd>
<dt><a name="28"><b class="cmd">::math::decimal::is-finite</b> <i class="arg">decimal</i></a></dt>
<dd><p>Return true if <em>decimal</em> value is finite, otherwise false is returned.</p></dd>
<dt><a name="29"><b class="cmd">::math::decimal::fma</b> <i class="arg">a</i> <i class="arg">b</i> <i class="arg">c</i></a></dt>
<dd><p>Return the result from first multiplying <em>a</em> by <em>b</em> and then adding <em>c</em>. Rescaling only occurs after completion of all operations. In this way the result may vary from that returned by performing the operations individually.</p></dd>
<dt><a name="30"><b class="cmd">::math::decimal::round_half_even</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round to the nearest. If equidistant, round so the final digit is even.</p></dd>
<dt><a name="31"><b class="cmd">::math::decimal::round_half_up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round to the nearest. If equidistant, round up.</p></dd>
<dt><a name="32"><b class="cmd">::math::decimal::round_half_down</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round to the nearest. If equidistant, round down.</p></dd>
<dt><a name="33"><b class="cmd">::math::decimal::round_down</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round toward 0. (Truncate)</p></dd>
<dt><a name="34"><b class="cmd">::math::decimal::round_up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round away from 0</p></dd>
<dt><a name="35"><b class="cmd">::math::decimal::round_floor</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round toward -Infinity.</p></dd>
<dt><a name="36"><b class="cmd">::math::decimal::round_ceiling</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round toward Infinity</p></dd>
<dt><a name="37"><b class="cmd">::math::decimal::round_05up</b> <i class="arg">decimal</i> <i class="arg">digits</i></a></dt>
<dd><p>Rounds <em>decimal</em> to <em>digits</em> number of decimal points with the following rules: Round zero or five away from 0. The same as round-up, except that rounding up only occurs if the digit to be rounded up is 0 or 5, and after overflow
the result is the same as for round-down.</p></dd>
</dl>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>decimal</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#key774">decimal</a>, <a href="../../../../index.html#key71">math</a>, <a href="../../../../index.html#key288">tcl</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Mathematics</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2011 Mark Alston <mark at beernut dot com></p>
</div>
</div></body></html>
