mirror of
https://github.com/MikeMcl/decimal.js.git
synced 2024-10-27 20:34:12 +00:00
2139 lines
99 KiB
HTML
2139 lines
99 KiB
HTML
|
<!DOCTYPE HTML>
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta charset=utf-8>
|
||
|
|
<meta http-equiv=X-UA-Compatible content="IE=edge,chrome=1">
|
||
|
|
<meta name=Author content=MMclaughlin>
|
||
|
|
<title>decimal.js API</title>
|
||
|
|
<style>html{font-size:100%}body{background:#fff;font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-size:13px;line-height:1.65em;min-height:100%;margin:0}body,i{color:#000}.nav{background:#fff;position:fixed;top:0;bottom:0;left:0;width:200px;overflow-y:auto;padding:15px 0 30px 15px}div.container{width:600px;margin:50px 0 50px 240px}p{margin:0 0 1em;width:600px}pre,ul{margin:1em 0}h1,h2,h3,h4,h5{margin:0;padding:1.5em 0 0}h1,h2{padding:.75em 0}h1{font:400 3em Consolas,monaco,monospace;color:#000;margin-bottom:1em}h2{font-size:2.25em;color:#f00}h3{font-size:1.75em;color:#69d2e7}h4{font-size:1.75em;color:#f00;padding-bottom:.75em}h5{font-size:1.2em;margin-bottom:.4em}h6{font-size:1.1em;margin-bottom:.8em;padding:.5em 0}dd dt{font-size:1.2em}dt{padding-top:.5em}dd{padding-top:.35em}b{font-weight:700}a,a:visited{color:#f00;text-decoration:none}a:active,a:hover{outline:0;text-decoration:underline}.nav a,.nav b,.nav a:visited{display:block;color:#f00;font-weight:700;margin-top:15px}.nav b{color:#69d2e7;margin-top:20px;cursor:default;width:auto}ul{list-style-type:none;padding:0 0 0 20px}.nav ul{line-height:14px;padding-left:0;margin:5px 0 0}.nav ul a,.nav ul a:visited,span{display:inline;color:#000;font-family:Verdana,Geneva,sans-serif;font-size:11px;font-weight:400;margin:0}.inset{margin-left:20px;font-size:.9em}.nav li{width:auto;margin:0 0 3px}.alias{font-style:italic;margin-left:20px}table{border-collapse:collapse;border-spacing:0;border:2px solid #a7dbd8;margin:1.75em 0;padding:0}td,th{text-align:left;margin:0;padding:2px 5px;border:1px dotted #a7dbd8}th{border-top:2px solid #a7dbd8;border-bottom:2px solid #a7dbd8;color:#f00}code,pre{font-family:Consolas,monaco,monospace;font-weight:400}pre{background:#f5f5f5;white-space:pre-wrap;word-wrap:break-word;border-left:5px solid #a7dbd8;padding:1px 0 1px 15px;margin:1.2em 0}code,.nav-title{color:#f00}.end{margin-bottom:25px}.centre{text-align:center}.error-table{font-size:13px;width:100%}#modes,#configProps{color:#f00}.spacer{line-height:0}#faq{margin:3em 0 0}li span{float:right;margin-right:10px;color:#c0c0c0}#js{font:inherit;color:#f00}</style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class=nav>
|
||
|
|
<a class=nav-title href=#>API</a>
|
||
|
|
<b>CONSTRUCTOR</b>
|
||
|
|
<ul><li><a href=#decimal>Decimal</a></li></ul>
|
||
|
|
<a href=#methods>Methods</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href=#Dconfig>config</a></li>
|
||
|
|
<li><a href=#Dconstr>constructor</a></li>
|
||
|
|
<li><a href=#Dexp> exp</a></li>
|
||
|
|
<li><a href=#Dln> ln</a></li>
|
||
|
|
<li><a href=#Dlog> log</a></li>
|
||
|
|
<li><a href=#Dmax> max</a></li>
|
||
|
|
<li><a href=#Dmin> min</a></li>
|
||
|
|
<li><a href=#DnoCon> noConflict</a></li>
|
||
|
|
<li><a href=#Dpow> pow</a></li>
|
||
|
|
<li><a href=#Drand> random</a></li>
|
||
|
|
<li><a href=#Dsqrt> sqrt</a></li>
|
||
|
|
</ul>
|
||
|
|
<a href=#constructor-properties>Properties</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href=#one>ONE</a></li>
|
||
|
|
<li class=spacer> </li>
|
||
|
|
<li><a href=#precision>precision</a></li>
|
||
|
|
<li><a href=#rounding>rounding</a></li>
|
||
|
|
<li><a href=#minE>minE</a></li>
|
||
|
|
<li><a href=#maxE>maxE</a></li>
|
||
|
|
<li><a href=#toExpNeg>toExpNeg</a></li>
|
||
|
|
<li><a href=#toExpPos>toExpPos</a></li>
|
||
|
|
<li><a href=#errors>errors</a></li>
|
||
|
|
<li><a href=#modulo>modulo</a></li>
|
||
|
|
<li><a href=#crypto>crypto</a></li>
|
||
|
|
<li class=spacer> </li>
|
||
|
|
<li><a href=#modes>ROUND_UP</a></li>
|
||
|
|
<li><a href=#modes>ROUND_DOWN</a></li>
|
||
|
|
<li><a href=#modes>ROUND_CEIL</a></li>
|
||
|
|
<li><a href=#modes>ROUND_FLOOR</a></li>
|
||
|
|
<li><a href=#modes>ROUND_HALF_UP</a></li>
|
||
|
|
<li><a href=#modes>ROUND_HALF_DOWN</a></li>
|
||
|
|
<li><a href=#modes>ROUND_HALF_EVEN</a></li>
|
||
|
|
<li><a href=#modes>ROUND_HALF_CEIL</a></li>
|
||
|
|
<li><a href=#modes>ROUND_HALF_FLOOR</a></li>
|
||
|
|
<li><a href=#modes>EUCLID</a></li>
|
||
|
|
</ul>
|
||
|
|
<b> INSTANCE </b>
|
||
|
|
<a href=#prototype-methods>Methods</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href=#abs>absoluteValue </a><span>abs</span> </li>
|
||
|
|
<li><a href=#ceil>ceil </a> </li>
|
||
|
|
<li><a href=#cmp>comparedTo </a><span>cmp</span> </li>
|
||
|
|
<li><a href=#dp>decimalPlaces </a><span>dp</span> </li>
|
||
|
|
<li><a href=#div>dividedBy </a><span>div</span> </li>
|
||
|
|
<li><a href=#divInt>dividedToIntegerBy </a><span>divToInt</span></li>
|
||
|
|
<li><a href=#eq>equals </a><span>eq</span> </li>
|
||
|
|
<li><a href=#exp>exponential </a><span>exp</span> </li>
|
||
|
|
<li><a href=#floor>floor </a> </li>
|
||
|
|
<li><a href=#gt>greaterThan </a><span>gt</span> </li>
|
||
|
|
<li><a href=#gte>greaterThanOrEqualTo</a><span>gte</span> </li>
|
||
|
|
<li><a href=#isF>isFinite </a> </li>
|
||
|
|
<li><a href=#isInt>isInteger </a><span>isInt</span> </li>
|
||
|
|
<li><a href=#isNaN>isNaN </a> </li>
|
||
|
|
<li><a href=#isNeg>isNegative </a><span>isNeg</span> </li>
|
||
|
|
<li><a href=#isZ>isZero </a> </li>
|
||
|
|
<li><a href=#lt>lessThan </a><span>lt</span> </li>
|
||
|
|
<li><a href=#lte>lessThanOrEqualTo </a><span>lte</span> </li>
|
||
|
|
<li><a href=#log>logarithm </a><span>log</span> </li>
|
||
|
|
<li><a href=#minus>minus </a> </li>
|
||
|
|
<li><a href=#mod>modulo </a><span>mod</span> </li>
|
||
|
|
<li><a href=#ln>naturalLogarithm </a><span>ln</span> </li>
|
||
|
|
<li><a href=#neg>negated </a><span>neg</span> </li>
|
||
|
|
<li><a href=#plus>plus </a> </li>
|
||
|
|
<li><a href=#sd>precision </a><span>sd</span> </li>
|
||
|
|
<li><a href=#round>round </a> </li>
|
||
|
|
<li><a href=#sqrt>squareRoot </a><span>sqrt</span> </li>
|
||
|
|
<li><a href=#times>times </a> </li>
|
||
|
|
<li><a href=#toDP>toDecimalPlaces </a><span>toDP</span> </li>
|
||
|
|
<li><a href=#toE>toExponential </a> </li>
|
||
|
|
<li><a href=#toFi>toFixed </a> </li>
|
||
|
|
<li><a href=#toFo>toFormat </a> </li>
|
||
|
|
<li><a href=#toFr>toFraction </a> </li>
|
||
|
|
<li><a href=#toInt>toInteger </a><span>toInt</span> </li>
|
||
|
|
<li><a href=#toJSON>toJSON </a> </li>
|
||
|
|
<li><a href=#toNear>toNearest </a> </li>
|
||
|
|
<li><a href=#toNum>toNumber </a> </li>
|
||
|
|
<li><a href=#pow>toPower </a><span>pow</span> </li>
|
||
|
|
<li><a href=#toP>toPrecision </a> </li>
|
||
|
|
<li><a href=#toS>toString </a> </li>
|
||
|
|
<li><a href=#trunc>truncated </a><span>trunc</span> </li>
|
||
|
|
<li><a href=#valueOf>valueOf </a> </li>
|
||
|
|
</ul>
|
||
|
|
<a href=#instance-properties>Properties</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href=#coefficient>c: coefficient</a></li>
|
||
|
|
<li><a href=#exponent>e: exponent</a></li>
|
||
|
|
<li><a href=#sign>s: sign</a></li>
|
||
|
|
</ul>
|
||
|
|
<a href=#zero-nan-infinity>Zero, NaN & Infinity</a>
|
||
|
|
<a href=#Errors>Errors</a>
|
||
|
|
<a class=end href=#faq>FAQ</a>
|
||
|
|
</div>
|
||
|
|
<div class=container>
|
||
|
|
<h1>decimal<span id=js>.js</span></h1>
|
||
|
|
<p>An arbitrary-precision Decimal type for JavaScript.</p>
|
||
|
|
<p><a href=https://github.com/MikeMcl/decimal.js>Hosted on GitHub</a>.</p>
|
||
|
|
<p>
|
||
|
|
<i>
|
||
|
|
The library is incorporated into this page, so it should be available in the console now.
|
||
|
|
</i>
|
||
|
|
</p>
|
||
|
|
<h2>API</h2>
|
||
|
|
<p>
|
||
|
|
See the <a href=https://github.com/MikeMcl/decimal.js>README</a> on GitHub for a quickstart
|
||
|
|
introduction.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
In all examples below, <code>var</code> and semicolons are not shown, and if a commented-out
|
||
|
|
value is in quotes it means <code>toString</code> has been called on the preceding expression.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
When the library is loaded, it defines a single function object,
|
||
|
|
<a href=#decimal><code>Decimal</code></a>, the constructor of Decimal numbers.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Multiple Decimal constructors can be created, each with their own independent configuration,
|
||
|
|
e.g. precision and range, which applies to all Decimal numbers created from it.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
A new Decimal constructor is created by calling the
|
||
|
|
<code><a href=#Dconstr>constructor</a></code> method of an already existing Decimal
|
||
|
|
constructor - when the library is loaded this will be
|
||
|
|
<a href=#decimal><code>Decimal</code></a>.
|
||
|
|
</p>
|
||
|
|
<h3 class=end>CONSTRUCTOR</h3>
|
||
|
|
<h5 id=decimal>
|
||
|
|
Decimal<code class=inset>Decimal(value [, base]) <i>⇒ Decimal</i></code>
|
||
|
|
</h5>
|
||
|
|
<dl>
|
||
|
|
<dt><code>value</code></dt>
|
||
|
|
<dd><i>number|string|Decimal</i></dd>
|
||
|
|
<dd>A numeric value.</dd>
|
||
|
|
<dd>
|
||
|
|
Legitimate values include ±<code>0</code>, ±<code>Infinity</code> and
|
||
|
|
<code>NaN</code>.
|
||
|
|
</dd>
|
||
|
|
<dd>
|
||
|
|
Values of type <em>number</em> with more than 15 significant digits are considered invalid
|
||
|
|
(if <a href=#errors><code>errors</code></a> is true) as calling
|
||
|
|
<code><a href=#toS>toString</a></code> or <code><a href=#valueOf>valueOf</a></code> on
|
||
|
|
such numbers may not result in the intended value.
|
||
|
|
<pre>console.log( 823456789123456.3 ); // 823456789123456.2</pre>
|
||
|
|
</dd>
|
||
|
|
<dd>
|
||
|
|
There is no limit to the number of digits of a value of type <em>string</em> (other than
|
||
|
|
that of JavaScript's maximum array size).
|
||
|
|
</dd>
|
||
|
|
<dd>
|
||
|
|
See <a href=#minE>minE</a> and <a href=#maxE>maxE</a> for the allowable range of a
|
||
|
|
Decimal in terms of exponent limits.
|
||
|
|
</dd>
|
||
|
|
<dd>
|
||
|
|
Decimal string values may be in exponential, as well as normal (fixed-point) notation.
|
||
|
|
Non-decimal values must be in normal notation.
|
||
|
|
</dd>
|
||
|
|
<dd>
|
||
|
|
String values in hexadecimal literal form, e.g. <code>'0xff'</code>, are invalid, and string
|
||
|
|
values in octal literal form will be interpreted as decimals, e.g. <code>'011'</code> is
|
||
|
|
interpreted as 11, not 9.
|
||
|
|
</dd>
|
||
|
|
<dd>Values in any base may have fraction digits.</dd>
|
||
|
|
<dd>
|
||
|
|
For bases from 10 to 36, lower and/or upper case letters can be used to represent values
|
||
|
|
from 10 to 35.
|
||
|
|
</dd>
|
||
|
|
<dd>
|
||
|
|
For bases above 36, <code>a-z</code> represents values from 10 to 35, <code>A-Z</code> from
|
||
|
|
36 to 61, and <code>$</code> and <code>_</code> represent 62 and 63 respectively.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<dl>
|
||
|
|
<dt><code>base</code></dt>
|
||
|
|
<dd>
|
||
|
|
<i>number</i>: integer, <code>2</code> to <code>64</code> inclusive
|
||
|
|
</dd>
|
||
|
|
<dd>The base of <code>value</code>.</dd>
|
||
|
|
<dd>
|
||
|
|
If <code>base</code> is omitted or is <code>null</code> or undefined, base 10 is assumed.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p>Returns a new instance of a Decimal object.</p>
|
||
|
|
<p>
|
||
|
|
If a base is specified, <code>value</code> is rounded according to the current
|
||
|
|
<a href=#precision><code>precision</code></a> and
|
||
|
|
<a href=#rounding><code>rounding</code></a> settings.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
See <a href=#Errors>Errors</a> for the treatment of an invalid <code>value</code> or
|
||
|
|
<code>base</code>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(9) // '9'
|
||
|
|
y = new Decimal(x) // '9'
|
||
|
|
|
||
|
|
// 'new' is optional if errors is false
|
||
|
|
Decimal(435.345)
|
||
|
|
|
||
|
|
new Decimal('5032485723458348569331745.33434346346912144534543')
|
||
|
|
new Decimal('4.321e+4') // '43210'
|
||
|
|
new Decimal('-735.0918e-430') // '-7.350918e-428'
|
||
|
|
new Decimal('5.6700000') // '5.67'
|
||
|
|
new Decimal(Infinity) // 'Infinity'
|
||
|
|
new Decimal(NaN) // 'NaN'
|
||
|
|
new Decimal('.5') // '0.5'
|
||
|
|
new Decimal('+2') // '2'
|
||
|
|
new Decimal(-10110100.1, 2) // '-180.5'
|
||
|
|
new Decimal('123412421.234324', 5) // '607236.557696'
|
||
|
|
new Decimal('ff.8', 16) // '255.5'</pre>
|
||
|
|
<p>
|
||
|
|
The following throws <code>'not a base 2 number'</code> if
|
||
|
|
<a href=#errors><code>errors</code></a> is true, otherwise it returns a Decimal with value
|
||
|
|
<code>NaN</code>.
|
||
|
|
</p>
|
||
|
|
<pre>new Decimal(9, 2)</pre>
|
||
|
|
<p>
|
||
|
|
The following throws <code>'number type has more than 15 significant digits'</code> if
|
||
|
|
<a href=#errors><code>errors</code></a> is true, otherwise it returns a Decimal with value
|
||
|
|
<code>96517860459076820</code>.
|
||
|
|
</p>
|
||
|
|
<pre>new Decimal(96517860459076817.4395)</pre>
|
||
|
|
<p>
|
||
|
|
The following throws <code>'not a number'</code> if <a href=#errors><code>errors</code></a>
|
||
|
|
is true, otherwise it returns a Decimal with value <code>NaN</code>.
|
||
|
|
</p>
|
||
|
|
<pre>new Decimal('blurgh')</pre>
|
||
|
|
<p>
|
||
|
|
A value is rounded only if a base is specified.
|
||
|
|
</p>
|
||
|
|
<pre>Decimal.config({ precision: 5 })
|
||
|
|
new Decimal(1.23456789) // '1.23456789'
|
||
|
|
new Decimal(1.23456789, 10) // '1.2346'
|
||
|
|
new Decimal(1.23456789).round() // '1.2346'</pre>
|
||
|
|
<h4 id=methods>Methods</h4>
|
||
|
|
<p>The static methods of a Decimal constructor.</p>
|
||
|
|
<h5 id=Dconfig>
|
||
|
|
config<code class=inset>.config(object) <i>⇒ Decimal constructor</i></code>
|
||
|
|
</h5>
|
||
|
|
<p><code>object</code>: <i>object</i></p>
|
||
|
|
<p>Configures the 'global' settings for this particular Decimal constructor.</p>
|
||
|
|
<p>Returns this Decimal constructor.</p>
|
||
|
|
<p>
|
||
|
|
The configuration object can contain some or all of the properties described in detail at
|
||
|
|
<a href=#constructor-properties>Properties</a> and shown in the example below.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The values of the configuration object properties are checked for validity and then stored as
|
||
|
|
equivalently-named properties of this Decimal constructor.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If the value to be assigned to any of the properties is <code>null</code> or undefined
|
||
|
|
it is ignored.<br />See <a href=#Errors>Errors</a> for the treatment of invalid values.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
// Defaults
|
||
|
|
Decimal.config({
|
||
|
|
precision: 20,
|
||
|
|
rounding: 4,
|
||
|
|
toExpNeg: -7,
|
||
|
|
toExpPos: 21,
|
||
|
|
minE: -9e15,
|
||
|
|
maxE: 9e15,
|
||
|
|
errors: true,
|
||
|
|
crypto: false,
|
||
|
|
modulo: 1
|
||
|
|
})</pre>
|
||
|
|
<h5 id=Dconstr>
|
||
|
|
constructor
|
||
|
|
<code class=inset>.constructor([object]) <i>⇒ Decimal constructor</i></code>
|
||
|
|
</h5>
|
||
|
|
<p><code>object</code>: <i>object</i></p>
|
||
|
|
<p>
|
||
|
|
Returns a new independent Decimal constructor with configuration settings as described by
|
||
|
|
<code>object</code> (see <a href=#Dconfig><code>config</code></a>).
|
||
|
|
</p>
|
||
|
|
<pre>Decimal.config({ precision: 5 })
|
||
|
|
D9 = Decimal.constructor({ precision: 9 })
|
||
|
|
|
||
|
|
x = new Decimal(1)
|
||
|
|
y = new D9(1)
|
||
|
|
|
||
|
|
x.div(3) // 0.33333
|
||
|
|
y.div(3) // 0.333333333
|
||
|
|
|
||
|
|
// D9 = Decimal.constructor({ precision: 9 }) is equivalent to:
|
||
|
|
D9 = Decimal.constructor()
|
||
|
|
D9.config({ precision: 9 })</pre>
|
||
|
|
<p>
|
||
|
|
<code>constructor</code> is a factory method so it is not necessary or desirable to use
|
||
|
|
<code>new</code> but it will do no harm.
|
||
|
|
</p>
|
||
|
|
<pre>D = new Decimal.constructor()</pre>
|
||
|
|
<p>
|
||
|
|
It is not inefficient in terms of memory usage to use multiple Decimal constructors as
|
||
|
|
functions are shared between them.
|
||
|
|
</p>
|
||
|
|
<h5 id=Dexp>exp<code class=inset>.exp() <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>See <code><a href=#exp>exponential</a></code>.</p>
|
||
|
|
<pre>x = Decimal.exp(3)
|
||
|
|
y = new Decimal(3).exp()
|
||
|
|
x.equals(y) // true</pre>
|
||
|
|
<h5 id=Dln>ln<code class=inset>.ln() <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>See <code><a href=#ln>naturalLogarithm</a></code>.</p>
|
||
|
|
<pre>x = Decimal.ln(4.321)
|
||
|
|
y = new Decimal(4.321).ln()
|
||
|
|
x.equals(y) // true</pre>
|
||
|
|
<h5 id=Dlog>log<code class=inset>.log(arg [, base]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>arg</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>base</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>See <code><a href=#log>logarithm</a></code>.</p>
|
||
|
|
<pre>x = Decimal.log(100, 2.5)
|
||
|
|
y = new Decimal(100).log(2.5)
|
||
|
|
x.equals(y) // true</pre>
|
||
|
|
<h5 id=Dmax>
|
||
|
|
max<code class=inset>.max([arg1 [, arg2, ...]]) <i>⇒ Decimal</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>arg1</code>, <code>arg2</code>, ... : <i>number|string|Decimal</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the maximum of <code>arg1</code>, <code>arg2</code>,... .
|
||
|
|
</p>
|
||
|
|
<p>Alternatively, the argument to this method can be an array of values.</p>
|
||
|
|
<pre>x = new Decimal('3257869345.0378653')
|
||
|
|
Decimal.max(4e9, x, '123456789.9') // '4000000000'
|
||
|
|
|
||
|
|
arr = [12, '13', new Decimal(14)]
|
||
|
|
Decimal.max(arr) // '14'</pre>
|
||
|
|
<h5 id=Dmin>
|
||
|
|
min<code class=inset>.min([arg1 [, arg2, ...]]) <i>⇒ Decimal</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>arg1</code>, <code>arg2</code>, ... : <i>number|string|Decimal</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the minimum of <code>arg1</code>, <code>arg2</code>,... .
|
||
|
|
</p>
|
||
|
|
<p>Alternatively, the argument to this method can be an array of values.</p>
|
||
|
|
<pre>x = new Decimal('3257869345.0378653')
|
||
|
|
Decimal.min(4e9, x, '123456789.9') // '123456789.9'
|
||
|
|
|
||
|
|
arr = [2, new Decimal(-14), '-15.9999', -12]
|
||
|
|
Decimal.min(arr) // '-15.9999'</pre>
|
||
|
|
<h5 id=DnoCon>
|
||
|
|
noConflict<code class=inset>.noConflict() <i>⇒ Decimal constructor</i></code>
|
||
|
|
</h5>
|
||
|
|
<p><i>Browsers only.</i></p>
|
||
|
|
<p>
|
||
|
|
Reverts the <code>Decimal</code> variable to the value it had before this library
|
||
|
|
was loaded and returns a reference to the original Decimal constructor so it can be assigned
|
||
|
|
to a variable with a different name.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
<script> Decimal = 1 </script>
|
||
|
|
<script src='/path/to/decimal.js'></script>
|
||
|
|
<script>
|
||
|
|
x = new Decimal(2) // '2'
|
||
|
|
D = Decimal.noConflict()
|
||
|
|
Decimal // 1
|
||
|
|
y = new D(3) // '3'
|
||
|
|
</script></pre>
|
||
|
|
<h5 id=Dpow>pow<code class=inset>.pow(base, exponent) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>base</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>exponent</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>See <code><a href=#pow>toPower</a></code>.</p>
|
||
|
|
<pre>x = Decimal.pow(3257.4, 17.01)
|
||
|
|
y = new Decimal(3257.4).pow(17.01)
|
||
|
|
x.equals(y) // true</pre>
|
||
|
|
<h5 id=Drand>
|
||
|
|
random<code class=inset>.random([limit [, sd]]) <i>⇒ Decimal</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>limit</code>: <i>number|string|Decimal</i><br /> Default value: <code>1</code><br />
|
||
|
|
<code>sd</code>: <i>number</i>: integer, 1 to 1e+9 inclusive<br />
|
||
|
|
Default value: <code>precision</code><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal with a pseudo-random value equal to or greater in magnitude than
|
||
|
|
<code>0</code> and lower in magnitude than <code>limit</code>, and with the same sign as
|
||
|
|
<code>limit</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>limit</code> is omitted then it will be <code>1</code> and the return value will
|
||
|
|
have <a href=#precision><code>precision</code></a> significant digits (or less if there are
|
||
|
|
trailing zeros produced).
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>limit</code> is included and <code>sd</code> is omitted then the return value
|
||
|
|
will be an integer. If <code>sd</code> is included, the return value will have
|
||
|
|
<code>sd</code> significant digits (or less if there are trailing zeros produced).
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>limit</code> is a high value be sure to include a precision, otherwise this method
|
||
|
|
may be slow to return because all integer digits will be generated.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Depending on the value of a Decimal constructor's <a href=#crypto><code>crypto</code></a>
|
||
|
|
property and the support for the <code>crypto</code> object in the host environment, the
|
||
|
|
random digits of the return value are generated by either <code>Math.random</code> (fastest),
|
||
|
|
<code>crypto.getRandomValues</code> (Web Cryptography API in recent browsers) or
|
||
|
|
<code>crypto.randomBytes</code> (Node.js).
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <a href=#crypto><code>crypto</code></a> is <code>true</code>, i.e. one of the
|
||
|
|
<code>crypto</code> methods is to be used, the value of a returned Decimal should be
|
||
|
|
cryptographically-secure and statistically indistinguishable from a random value.
|
||
|
|
</p>
|
||
|
|
<pre>// A value in the range [0, 1) with precision significant digits
|
||
|
|
Decimal.config({ precision: 10 })
|
||
|
|
Decimal.random() // '0.4117936847'
|
||
|
|
|
||
|
|
// A value in the range [0, 1) with 20 significant digits
|
||
|
|
Decimal.random(1, 20) // '0.48193327636914089007'
|
||
|
|
|
||
|
|
// An integer in the range [0, 1)
|
||
|
|
Decimal.random(1) // '0' (always zero)
|
||
|
|
|
||
|
|
// An integer in the range [0, 10)
|
||
|
|
Decimal.random(10) // '6'
|
||
|
|
|
||
|
|
// An integer in the range (-100, 0]
|
||
|
|
Decimal.random(-100) // '-82'
|
||
|
|
|
||
|
|
// An integer in the range [0, 99.99)
|
||
|
|
Decimal.random('99.99') // '47'
|
||
|
|
|
||
|
|
// An integer in the range [0, 9e9999999999)
|
||
|
|
Decimal.random('9e99999999999') // The browser will hang
|
||
|
|
|
||
|
|
// A value in the range [0, 9e9999999999) with 10 significant digits
|
||
|
|
Decimal.random('9e99999999999', 25) // '1.508652055e+99999999999'
|
||
|
|
|
||
|
|
// A value in the range (-0.0125, 0] with 16 significant digits
|
||
|
|
Decimal.random(-0.0125, 16) // '-0.0001963482803540358'
|
||
|
|
|
||
|
|
// A value in the range [0, 0.9) with 1 significant digit
|
||
|
|
Decimal.random(0.9, 1) // '0.2'</pre>
|
||
|
|
<h5 id=Dsqrt>sqrt<code class=inset>.sqrt() <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>See <a href=#sqrt>squareRoot</a>.</p>
|
||
|
|
<pre>x = Decimal.sqrt('987654321.123456789')
|
||
|
|
y = new Decimal('987654321.123456789').sqrt()
|
||
|
|
x.equals(y) // true</pre>
|
||
|
|
<h4 id=constructor-properties>Properties</h4>
|
||
|
|
<p>
|
||
|
|
The static properties of a Decimal constructor.
|
||
|
|
</p>
|
||
|
|
<h5 id=one>ONE</h5>
|
||
|
|
<p>A Decimal instance with value one.</p>
|
||
|
|
<pre>new Decimal(3).times(Decimal.ONE) // '3'</pre>
|
||
|
|
<h6 id=configProps>Configuration properties</h6>
|
||
|
|
<p>
|
||
|
|
The values of the configuration properties <a href=#precision><code>precision</code></a>,
|
||
|
|
<a href=#rounding><code>rounding</code></a>, <a href=#minE><code>minE</code></a>,
|
||
|
|
<a href=#maxE><code>maxE</code></a>, <a href=#toExpNeg><code>toExpNeg</code></a>,
|
||
|
|
<a href=#toExpPos><code>toExpPos</code></a>, <a href=#errors><code>errors</code></a>,
|
||
|
|
<a href=#mod><code>modulo</code></a> and <a href=#crypto><code>crypto</code></a> are set
|
||
|
|
using the <a href=#Dconfig><code>config</code></a> method.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
As simple object properties they can be set directly without using
|
||
|
|
<a href=#Dconfig><code>config</code></a>, and it is fine to do so, but the values assigned
|
||
|
|
will not then be checked for validity. For example:
|
||
|
|
</p>
|
||
|
|
<pre>Decimal.config({ precision: 0 })
|
||
|
|
// 'Decimal Error: config() precision out of range: 0'
|
||
|
|
|
||
|
|
Decimal.precision = 0
|
||
|
|
// No error is thrown and the results of calculations are unpredictable</pre>
|
||
|
|
<h5 id=precision>precision</h5>
|
||
|
|
<p>
|
||
|
|
<i>number</i>: integer, <code>1</code> to <code>1e+9</code> inclusive<br />
|
||
|
|
Default value: <code>20</code>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The <i>maximum</i> number of significant digits of the result of a calculation or base
|
||
|
|
conversion.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
All methods which return a Decimal will round the value to be returned to
|
||
|
|
<code>precision</code> significant digits except
|
||
|
|
<a href=#abs><code>absoluteValue</code></a>, <a href=#ceil><code>ceil</code></a>,
|
||
|
|
<a href=#floor><code>floor</code></a>, <a href=#neg><code>negated</code></a>,
|
||
|
|
<a href=#round><code>round</code></a>, <a href=#toDP><code>toDecimalPlaces</code></a>
|
||
|
|
and <a href=#toNear><code>toNearest</code></a>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
A Decimal constructor will also not round to <code>precision</code> unless a base is
|
||
|
|
specified.
|
||
|
|
</p>
|
||
|
|
<pre>Decimal.config({ precision: 5 })
|
||
|
|
Decimal.precision // 5</pre>
|
||
|
|
<h5 id=rounding>rounding</h5>
|
||
|
|
<p>
|
||
|
|
<i>number</i>: integer, <code>0</code> to <code>8</code> inclusive<br />
|
||
|
|
Default value: <code>4</code> <a href=#h-up>(<code>ROUND_HALF_UP</code>)</a>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The default rounding mode used when rounding to
|
||
|
|
<code><a href=#precision>precision</a></code> and when rounding
|
||
|
|
<a href=#round><code>round</code></a>, <a href=#toDP><code>toDecimalPlaces</code></a>,
|
||
|
|
<a href=#toE><code>toExponential</code></a>, <a href=#toFi><code>toFixed</code></a>,
|
||
|
|
<a href=#toFo><code>toFormat</code></a>, and <a href=#toP><code>toPrecision</code></a>.
|
||
|
|
</p>
|
||
|
|
<p>The modes are available as enumerated properties of the constructor.</p>
|
||
|
|
<pre>Decimal.config({ rounding: Decimal.ROUND_UP })
|
||
|
|
Decimal.config({ rounding: 0 }) // equivalent
|
||
|
|
Decimal.rounding // 0</pre>
|
||
|
|
<h5 id=minE>minE</h5>
|
||
|
|
<p>
|
||
|
|
<i>number</i>: integer, <code>-9e15</code> to <code>0</code> inclusive<br />
|
||
|
|
Default value: <code>-9e15</code>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The negative exponent limit, i.e. the exponent value below which underflow to zero occurs.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If the <code>Decimal</code> to be returned by a calculation would have an exponent lower than
|
||
|
|
<code>minE</code> then its value becomes zero.
|
||
|
|
<p>
|
||
|
|
JavaScript numbers underflow to zero for exponents below <code>-324</code>.
|
||
|
|
</p>
|
||
|
|
<pre>Decimal.config({ minE: -500 })
|
||
|
|
Decimal.minE // -500
|
||
|
|
new Decimal('1e-500') // '1e-500'
|
||
|
|
new Decimal('9.9e-501') // '0'
|
||
|
|
|
||
|
|
Decimal.config({ minE: -3 })
|
||
|
|
new Decimal(0.001) // '0.01' e is only -3
|
||
|
|
new Decimal(0.0001) // '0' e is -4</pre>
|
||
|
|
<p>
|
||
|
|
The smallest possible magnitude of a non-zero Decimal is <code>1e-9000000000000000</code>
|
||
|
|
</p>
|
||
|
|
<h5 id=maxE>maxE</h5>
|
||
|
|
<p>
|
||
|
|
<i>number</i>: integer, <code>0</code> to <code>9e15</code> inclusive<br />
|
||
|
|
Default value: <code>9e15</code>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The positive exponent limit, i.e. the exponent value above which overflow to
|
||
|
|
<code>Infinity</code> occurs.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If the <code>Decimal</code> to be returned by a calculation would have an exponent higher than
|
||
|
|
<code>maxE</code> then its value becomes <code>Infinity</code>.
|
||
|
|
<p>
|
||
|
|
JavaScript numbers overflow to <code>Infinity</code> for exponents above <code>308</code>.
|
||
|
|
</p>
|
||
|
|
<pre>Decimal.config({ maxE: 500 })
|
||
|
|
Decimal.maxE // 500
|
||
|
|
new Decimal('9.999e500') // '9.999e+500'
|
||
|
|
new Decimal('1e501') // 'Infinity'
|
||
|
|
|
||
|
|
Decimal.config({ maxE: 4 })
|
||
|
|
new Decimal(99999) // '99999' e is only 4
|
||
|
|
new Decimal(100000) // 'Infinity'</pre>
|
||
|
|
<p>
|
||
|
|
The largest possible magnitude of a finite Decimal is <code>9.999...e+9000000000000000</code>
|
||
|
|
</p>
|
||
|
|
<h5 id=toExpNeg>toExpNeg</h5>
|
||
|
|
<p>
|
||
|
|
<i>number</i>: integer, <code>-9e15</code> to <code>0</code> inclusive<br />
|
||
|
|
Default value: <code>-7</code>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The negative exponent value at and below which <a href=#toS><code>toString</code></a>
|
||
|
|
returns exponential notation.
|
||
|
|
</p>
|
||
|
|
<pre>Decimal.config({ toExpNeg: -7 })
|
||
|
|
Decimal.toExpNeg // -7
|
||
|
|
new Decimal(0.00000123) // '0.00000123' e is only -6
|
||
|
|
new Decimal(0.000000123) // '1.23e-7'
|
||
|
|
|
||
|
|
// Always return exponential notation:
|
||
|
|
Decimal.config({ toExpNeg: 0 })</pre>
|
||
|
|
<p>
|
||
|
|
JavaScript numbers use exponential notation for negative exponents of <code>-7</code> and
|
||
|
|
below.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Regardless of the value of <code>toExpNeg</code>, the
|
||
|
|
<a href=#toFi><code>toFixed</code></a> method will always return a value in normal notation
|
||
|
|
and the <a href=#toE><code>toExponential</code></a> method will always return a value in
|
||
|
|
exponential form.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Calling <a href=#toS><code>toString</code></a> with a base argument, e.g.
|
||
|
|
<code>toString(10)</code>, will also always return normal notation.
|
||
|
|
</p>
|
||
|
|
<h5 id=toExpPos>toExpPos</h5>
|
||
|
|
<p>
|
||
|
|
<i>number</i>: integer, <code>0</code> to <code>9e15</code> inclusive<br />
|
||
|
|
Default value: <code>20</code>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The positive exponent value at and above which <a href=#toS><code>toString</code></a>
|
||
|
|
returns exponential notation.
|
||
|
|
</p>
|
||
|
|
<pre>Decimal.config({ toExpPos: 2 })
|
||
|
|
Decimal.toExpPos // 2
|
||
|
|
new Decimal(12.3) // '12.3' e is only 1
|
||
|
|
new Decimal(123) // '1.23e+2'
|
||
|
|
|
||
|
|
// Always return exponential notation:
|
||
|
|
Decimal.config({ toExpPos: 0 })</pre>
|
||
|
|
<p>
|
||
|
|
JavaScript numbers use exponential notation for positive exponents of <code>20</code> and
|
||
|
|
above.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Regardless of the value of <code>toExpPos</code>, the
|
||
|
|
<a href=#toFi><code>toFixed</code></a> method will always return a value in normal notation
|
||
|
|
and the <a href=#toE><code>toExponential</code></a> method will always return a value in
|
||
|
|
exponential form.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Calling <a href=#toS><code>toString</code></a> with a base argument, e.g.
|
||
|
|
<code>toString(10)</code>, will also always return normal notation.
|
||
|
|
</p>
|
||
|
|
<h5 id=errors>errors</h5>
|
||
|
|
<p>
|
||
|
|
<i>boolean/number</i>: <code>true, false, 1 or 0</code><br /> Default value: <code>true</code>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The value that determines whether Decimal Errors are thrown.<br />
|
||
|
|
If <code>errors</code> is false, this library will not throw errors.
|
||
|
|
</p>
|
||
|
|
<p>See <a href=#Errors>Errors</a>.</p>
|
||
|
|
<pre>Decimal.config({ errors: false })
|
||
|
|
Decimal.errors // false</pre>
|
||
|
|
<h5 id=modulo>modulo</h5>
|
||
|
|
<p>
|
||
|
|
<i>number</i>: integer, <code>0</code> to <code>9</code> inclusive<br />
|
||
|
|
Default value: <code>1</code> (<code>ROUND_DOWN</code>)
|
||
|
|
</p>
|
||
|
|
<p>The modulo mode used when calculating the modulus: <code>a mod n</code>.</p>
|
||
|
|
<p>
|
||
|
|
The quotient, <code>q = a / n</code>, is calculated according to the
|
||
|
|
<a href=#rounding><code>rounding</code></a> mode that corresponds to the chosen
|
||
|
|
<code>modulo</code> mode.
|
||
|
|
</p>
|
||
|
|
<p>The remainder, <code>r</code>, is calculated as: <code>r = a - n * q</code>.</p>
|
||
|
|
<p>
|
||
|
|
The modes that are most commonly used for the modulus/remainder operation are shown in the
|
||
|
|
following table. Although the other <a href=#rounding><code>rounding</code></a> modes can
|
||
|
|
be used, they may not give useful results.
|
||
|
|
</p>
|
||
|
|
<table>
|
||
|
|
<tr><th>Property</th><th>Value</th><th>Description</th></tr>
|
||
|
|
<tr>
|
||
|
|
<td>ROUND_UP</td><td class=centre>0</td>
|
||
|
|
<td>The remainder is positive if the dividend is negative, else is negative</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>ROUND_DOWN</td><td class=centre>1</td>
|
||
|
|
<td>
|
||
|
|
The remainder has the same sign as the dividend.<br />
|
||
|
|
This uses truncating division and matches the behaviour of JavaScript's remainder
|
||
|
|
operator <code>%</code>.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>ROUND_FLOOR</td><td class=centre>3</td>
|
||
|
|
<td>
|
||
|
|
The remainder has the same sign as the divisor.<br />
|
||
|
|
(This matches Python's <code>%</code> operator)
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>ROUND_HALF_EVEN</td><td class=centre>6</td>
|
||
|
|
<td>The <i>IEEE 754</i> remainder function</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>EUCLID</td><td class=centre>9</td>
|
||
|
|
<td>
|
||
|
|
The remainder is always positive.<br />
|
||
|
|
Euclidian division: <code>q = sign(n) * floor(a / abs(n))</code>.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<p>
|
||
|
|
The <code>rounding/modulo</code> modes are available as enumerated properties of the Decimal
|
||
|
|
constructor.
|
||
|
|
</p>
|
||
|
|
<pre>Decimal.config({ modulo: Decimal.EUCLID })
|
||
|
|
Decimal.config({ modulo: 9 }) // equivalent
|
||
|
|
Decimal.modulo // 9</pre>
|
||
|
|
<h5 id=crypto>crypto</h5>
|
||
|
|
<p>
|
||
|
|
<i>boolean/number</i>: <code>true, false, 1 or 0</code><br /> Default value:
|
||
|
|
<code>false</code>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The value that determines whether cryptographically-secure pseudo-random number generation
|
||
|
|
is used.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>crypto</code> is truthy then the <a href=#Drand><code>random</code></a> method will
|
||
|
|
generate random digits using <code>crypto.getRandomValues</code> in browsers that support it,
|
||
|
|
or <code>crypto.randomBytes</code> if using a version of Node.js that supports it.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If neither function is supported by the host environment or if <code>crypto</code> is falsey
|
||
|
|
then the source of randomness will be <code>Math.random</code>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
Decimal.crypto // false
|
||
|
|
Decimal.config({ crypto: true })
|
||
|
|
|
||
|
|
// If crypto.getRandomValues and crypto.randomBytes are undefined
|
||
|
|
Decimal.crypto // false</pre>
|
||
|
|
<h6 id=modes>Rounding modes</h6>
|
||
|
|
<p>
|
||
|
|
The library's enumerated rounding modes are stored as properties of a Decimal constructor.
|
||
|
|
<br />They are not referenced internally by the library itself.
|
||
|
|
</p>
|
||
|
|
<p>Rounding modes 0 to 6 (inclusive) are the same as those of Java's BigDecimal class.</p>
|
||
|
|
<table>
|
||
|
|
<tr><th>Property</th><th>Value</th><th>Description</th></tr>
|
||
|
|
<tr><td><b>ROUND_UP</b></td><td class=centre>0</td><td>Rounds away from zero</td></tr>
|
||
|
|
<tr><td><b>ROUND_DOWN</b></td><td class=centre>1</td><td>Rounds towards zero</td></tr>
|
||
|
|
<tr><td><b>ROUND_CEIL</b></td><td class=centre>2</td><td>Rounds towards Infinity</td></tr>
|
||
|
|
<tr><td><b>ROUND_FLOOR</b></td><td class=centre>3</td><td>Rounds towards -Infinity</td></tr>
|
||
|
|
<tr>
|
||
|
|
<td><b>ROUND_HALF_UP</b></td><td class=centre>4</td>
|
||
|
|
<td>Rounds towards nearest neighbour.<br />If equidistant, rounds away from zero</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><b>ROUND_HALF_DOWN</b></td><td class=centre>5</td>
|
||
|
|
<td>Rounds towards nearest neighbour.<br />If equidistant, rounds towards zero</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><b>ROUND_HALF_EVEN</b></td><td class=centre>6</td>
|
||
|
|
<td>
|
||
|
|
Rounds towards nearest neighbour.<br />If equidistant, rounds towards even neighbour
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><b>ROUND_HALF_CEIL</b></td><td class=centre>7</td>
|
||
|
|
<td>Rounds towards nearest neighbour.<br />If equidistant, rounds towards Infinity</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><b>ROUND_HALF_FLOOR</b></td><td class=centre>8</td>
|
||
|
|
<td>Rounds towards nearest neighbour.<br />If equidistant, rounds towards -Infinity</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><b>EUCLID</b></td><td class=centre>9</td>
|
||
|
|
<td>Not a rounding mode, see <a href=#modulo>modulo</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<pre>Decimal.config({ rounding: Decimal.ROUND_CEIL })
|
||
|
|
Decimal.config({ rounding: 2 }) // equivalent
|
||
|
|
Decimal.rounding // 2</pre>
|
||
|
|
<h3>INSTANCE</h3>
|
||
|
|
<h4 id=prototype-methods>Methods</h4>
|
||
|
|
<p>The methods inherited by a Decimal instance from its constructor's prototype object.</p>
|
||
|
|
<p>A Decimal is immutable in the sense that it is not changed by its methods.</p>
|
||
|
|
<p>Methods that return a Decimal can be chained:</p>
|
||
|
|
<pre>x = new Decimal(2).times('999.999999999999999').dividedBy(4).ceil()</pre>
|
||
|
|
<p>Methods do not round their arguments before execution.</p>
|
||
|
|
<p>
|
||
|
|
The treatment of ±<code>0</code>, ±<code>Infinity</code> and <code>NaN</code>
|
||
|
|
is consistent with how JavaScript treats these values.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Some method names have a shorter alias. (Internally, the library always uses the shorter method
|
||
|
|
names.)
|
||
|
|
</p>
|
||
|
|
<h5 id=abs>absoluteValue<code class=inset>.abs() <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the absolute value, i.e. the magnitude, of the value of
|
||
|
|
this Decimal.
|
||
|
|
</p>
|
||
|
|
<p>The return value is not rounded.</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(-0.8)
|
||
|
|
y = x.absoluteValue() // '0.8'
|
||
|
|
z = y.abs() // '0.8'</pre>
|
||
|
|
<h5 id=ceil>ceil<code class=inset>.ceil([sd]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p><code>sd</code>: <i>number</i>: integer, 1 to 1e+9 inclusive.</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal rounded to <code>sd</code>
|
||
|
|
significant digits in the direction of positive <code>Infinity</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>sd</code> is omitted or is <code>null</code> or undefined, the return value is
|
||
|
|
the value of this Decimal rounded to a whole number.
|
||
|
|
</p>
|
||
|
|
<p>The return value is not rounded to <a href=#precision><code>precision</code></a>.</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1.3)
|
||
|
|
x.ceil() // '2'
|
||
|
|
y = new Decimal(-1.8)
|
||
|
|
y.ceil() // '-1'</pre>
|
||
|
|
<h5 id=cmp>comparedTo<code class=inset>.cmp(n [, base]) <i>⇒ number</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<table>
|
||
|
|
<tr><th>Returns</th><th> </th></tr>
|
||
|
|
<tr>
|
||
|
|
<td class=centre>1</td>
|
||
|
|
<td>If the value of this Decimal is greater than the value of <code>n</code></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class=centre>-1</td>
|
||
|
|
<td>If the value of this Decimal is less than the value of <code>n</code></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class=centre>0</td>
|
||
|
|
<td>If this Decimal and <code>n</code> have the same value</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class=centre>null</td>
|
||
|
|
<td>If the value of either this Decimal or <code>n</code> is <code>NaN</code> </td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(Infinity)
|
||
|
|
y = new Decimal(5)
|
||
|
|
x.comparedTo(y) // 1
|
||
|
|
x.comparedTo(x.minus(1)) // 0
|
||
|
|
y.cmp(NaN) // null
|
||
|
|
y.cmp('110', 2) // -1</pre>
|
||
|
|
<h5 id=dp>decimalPlaces<code class=inset>.dp() <i>⇒ number</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns the number of decimal places, i.e. the number of digits after the decimal point, of
|
||
|
|
the value of this Decimal.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1.234)
|
||
|
|
x.decimalPlaces() // '3'
|
||
|
|
y = new Decimal(987.654321)
|
||
|
|
y.dp() // '6'</pre>
|
||
|
|
<h5 id=div>dividedBy<code class=inset>.div(n [, base]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br /><code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal divided by <code>n</code>,
|
||
|
|
rounded to <a href=#precision><code>precision</code></a> significant digits using rounding
|
||
|
|
mode <a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(355)
|
||
|
|
y = new Decimal(113)
|
||
|
|
x.dividedBy(y) // '3.14159292035398230088'
|
||
|
|
x.div(5) // '71'
|
||
|
|
x.div(47, 16) // '5'</pre>
|
||
|
|
<h5 id=divInt>
|
||
|
|
dividedToIntegerBy<code class=inset>.divToInt(n [, base]) <i>⇒ Decimal</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br /><code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Return a new Decimal whose value is the integer part of dividing this Decimal by
|
||
|
|
<code>n</code>, rounded to <code><a href=#precision>precision</a></code> significant digits
|
||
|
|
using rounding mode <a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(5)
|
||
|
|
y = new Decimal(3)
|
||
|
|
x.dividedToIntegerBy(y) // '1'
|
||
|
|
x.divToInt(0.7) // '7'
|
||
|
|
x.divToInt('0.f', 16) // '5'</pre>
|
||
|
|
<h5 id=eq>equals<code class=inset>.eq(n [, base]) <i>⇒ boolean</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br /><code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns <code>true</code> if the value of this Decimal equals the value of <code>n</code>,
|
||
|
|
otherwise returns <code>false</code>.<br /> As with JavaScript, <code>NaN</code> does not
|
||
|
|
equal <code>NaN</code>.
|
||
|
|
</p>
|
||
|
|
<p>Note: This method uses the <code>cmp</code> method internally.</p>
|
||
|
|
<pre>
|
||
|
|
0 === 1e-324 // true
|
||
|
|
x = new Decimal(0)
|
||
|
|
x.equals('1e-324') // false
|
||
|
|
new Decimal(-0).eq(x) // true ( -0 === 0 )
|
||
|
|
new Decimal(255).eq('ff', 16) // true
|
||
|
|
|
||
|
|
y = new Decimal(NaN)
|
||
|
|
y.equals(NaN) // false</pre>
|
||
|
|
<h5 id=exp>exponential<code class=inset>.exp() <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the base <code>e</code> (Euler's number, the base of the
|
||
|
|
natural logarithm) exponential of the value of this Decimal, rounded to
|
||
|
|
<a href=#precision><code>precision</code></a> significant digits using rounding mode
|
||
|
|
<a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The <code><a href=#ln>naturalLogarithm</a></code> function is the inverse of this function.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1)
|
||
|
|
x.exponential() // '2.7182818284590452354'
|
||
|
|
y = new Decimal(2)
|
||
|
|
y.exp() // '7.3890560989306502272'</pre>
|
||
|
|
<p>
|
||
|
|
The return value will be correctly rounded, i.e. rounded as if the result was first calculated
|
||
|
|
to an infinite number of correct digits before rounding. (The mathematical result of the
|
||
|
|
exponential function is non-terminating, unless its argument is <code>0</code>).
|
||
|
|
</p>
|
||
|
|
<p>The performance of this method degrades exponentially with increasing digits.</p>
|
||
|
|
<h5 id=floor>floor<code class=inset>.floor([sd]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p><code>sd</code>: <i>number</i>: integer, 1 to 1e+9 inclusive.</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal rounded to <code>sd</code>
|
||
|
|
significant digits in the direction of negative <code>Infinity</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>sd</code> is omitted or is <code>null</code> or undefined, the return value is
|
||
|
|
the value of this Decimal rounded to a whole number.
|
||
|
|
</p>
|
||
|
|
<p>The return value is not rounded to <a href=#precision><code>precision</code></a>.</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1.8)
|
||
|
|
x.floor() // '1'
|
||
|
|
y = new Decimal(-1.3)
|
||
|
|
y.floor() // '-2'</pre>
|
||
|
|
<h5 id=gt>greaterThan<code class=inset>.gt(n [, base]) <i>⇒ boolean</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns <code>true</code> if the value of this Decimal is greater than the value of
|
||
|
|
<code>n</code>, otherwise returns <code>false</code>.
|
||
|
|
</p>
|
||
|
|
<p>Note: This method uses the <code>cmp</code> method internally.</p>
|
||
|
|
<pre>
|
||
|
|
0.1 > (0.3 - 0.2) // true
|
||
|
|
x = new Decimal(0.1)
|
||
|
|
x.greaterThan(Decimal(0.3).minus(0.2)) // false
|
||
|
|
new Decimal(0).gt(x) // false
|
||
|
|
new Decimal(11, 3).gt(11.1, 2) // true</pre>
|
||
|
|
<h5 id=gte>
|
||
|
|
greaterThanOrEqualTo<code class=inset>.gte(n [, base]) <i>⇒ boolean</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns <code>true</code> if the value of this Decimal is greater than or equal to the value
|
||
|
|
of <code>n</code>, otherwise returns <code>false</code>.
|
||
|
|
</p>
|
||
|
|
<p>Note: This method uses the <code>cmp</code> method internally.</p>
|
||
|
|
<pre>
|
||
|
|
(0.3 - 0.2) >= 0.1 // false
|
||
|
|
x = new Decimal(0.3).minus(0.2)
|
||
|
|
x.greaterThanOrEqualTo(0.1) // true
|
||
|
|
new Decimal(1).gte(x) // true
|
||
|
|
new Decimal(10, 18).gte('i', 36) // true</pre>
|
||
|
|
<h5 id=isF>isFinite<code class=inset>.isFinite() <i>⇒ boolean</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns <code>true</code> if the value of this Decimal is a finite number, otherwise returns
|
||
|
|
<code>false</code>.<br />
|
||
|
|
The only possible non-finite values of a Decimal are <code>NaN</code>, <code>Infinity</code>
|
||
|
|
and <code>-Infinity</code>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1)
|
||
|
|
x.isFinite() // true
|
||
|
|
y = new Decimal(Infinity)
|
||
|
|
y.isFinite() // false</pre>
|
||
|
|
<p>
|
||
|
|
Note: The native method <code>isFinite()</code> can be used if
|
||
|
|
<code>n <= Number.MAX_VALUE</code>.
|
||
|
|
</p>
|
||
|
|
<h5 id=isInt>isInteger<code class=inset>.isInt() <i>⇒ boolean</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns <code>true</code> if the value of this Decimal is a whole number, otherwise returns
|
||
|
|
<code>false</code>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1)
|
||
|
|
x.isInteger() // true
|
||
|
|
y = new Decimal(123.456)
|
||
|
|
y.isInt() // false</pre>
|
||
|
|
<h5 id=isNaN>isNaN<code class=inset>.isNaN() <i>⇒ boolean</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns <code>true</code> if the value of this Decimal is NaN, otherwise returns
|
||
|
|
<code>false</code>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(NaN)
|
||
|
|
x.isNaN() // true
|
||
|
|
y = new Decimal('Infinity')
|
||
|
|
y.isNaN() // false</pre>
|
||
|
|
<p>Note: The native method <code>isNaN()</code> can also be used.</p>
|
||
|
|
<h5 id=isNeg>isNegative<code class=inset>.isNeg() <i>⇒ boolean</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns <code>true</code> if the value of this Decimal is negative, otherwise returns
|
||
|
|
<code>false</code>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(-0)
|
||
|
|
x.isNegative() // true
|
||
|
|
y = new Decimal(2)
|
||
|
|
y.isNeg // false</pre>
|
||
|
|
<p>Note: <code>n < 0</code> can be used if <code>n <= -Number.MIN_VALUE</code>.</p>
|
||
|
|
<h5 id=isZ>isZero<code class=inset>.isZero() <i>⇒ boolean</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns <code>true</code> if the value of this Decimal is zero or minus zero, otherwise
|
||
|
|
returns <code>false</code>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(-0)
|
||
|
|
x.isZero() && x.isNeg() // true
|
||
|
|
y = new Decimal(Infinity)
|
||
|
|
y.isZero() // false</pre>
|
||
|
|
<p>Note: <code>n == 0</code> can be used if <code>n >= Number.MIN_VALUE</code>.</p>
|
||
|
|
<h5 id=lt>lessThan<code class=inset>.lt(n [, base]) <i>⇒ boolean</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br /><code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns <code>true</code> if the value of this Decimal is less than the value of
|
||
|
|
<code>n</code>, otherwise returns <code>false</code>.
|
||
|
|
</p>
|
||
|
|
<p>Note: This method uses the <code>cmp</code> method internally.</p>
|
||
|
|
<pre>
|
||
|
|
(0.3 - 0.2) < 0.1 // true
|
||
|
|
x = new Decimal(0.3).minus(0.2)
|
||
|
|
x.lessThan(0.1) // false
|
||
|
|
new Decimal(0).lt(x) // true
|
||
|
|
new Decimal(11.1, 2).lt(11, 3) // true</pre>
|
||
|
|
<h5 id=lte>
|
||
|
|
lessThanOrEqualTo<code class=inset>.lte(n [, base]) <i>⇒ boolean</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br /><code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details. </i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns <code>true</code> if the value of this Decimal is less than or equal to the value of
|
||
|
|
<code>n</code>, otherwise returns <code>false</code>.
|
||
|
|
</p>
|
||
|
|
<p>Note: This method uses the <code>cmp</code> method internally.</p>
|
||
|
|
<pre>
|
||
|
|
0.1 <= (0.3 - 0.2) // false
|
||
|
|
x = new Decimal(0.1)
|
||
|
|
x.lessThanOrEqualTo(Decimal(0.3).minus(0.2)) // true
|
||
|
|
new Decimal(-1).lte(x) // true
|
||
|
|
new Decimal(10, 18).lte('i', 36) // true</pre>
|
||
|
|
<h5 id=log>logarithm<code class=inset>.log([n [, base]]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>base</code>: <i>number</i> <i>(This is not the base of the logarithm but the base of
|
||
|
|
<code>n</code>)</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details. </i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the base <code>n</code> logarithm of the value of this
|
||
|
|
Decimal, rounded to <a href=#precision><code>precision</code></a> significant digits using
|
||
|
|
rounding mode <a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>n</code> is <code>null</code> or undefined, then the base 10 logarithm of the
|
||
|
|
value of this Decimal will be returned.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1000)
|
||
|
|
x.logarithm() // '3'
|
||
|
|
y = new Decimal(256)
|
||
|
|
y.log(2) // '8'</pre>
|
||
|
|
<p>
|
||
|
|
The return value will <i>almost always</i> be correctly rounded, i.e. rounded as if the result
|
||
|
|
was first calculated to an infinite number of correct digits before rounding. If a result is
|
||
|
|
incorrectly rounded the maximum error will be <code>1</code> <i>ulp</i> (unit in the last
|
||
|
|
place).
|
||
|
|
</p>
|
||
|
|
<p>Logarithms to base <code>2</code> or <code>10</code> will always be correctly rounded.</p>
|
||
|
|
<p>
|
||
|
|
See <a href=#pow><code>toPower</code></a> for the circumstances in which this method may
|
||
|
|
return an incorrectly rounded result.
|
||
|
|
</p>
|
||
|
|
<p>The performance of this method degrades exponentially with increasing digits.</p>
|
||
|
|
<h5 id=minus>minus<code class=inset>.minus(n [, base]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal minus <code>n</code>, rounded
|
||
|
|
to <a href=#precision><code>precision</code></a> significant digits using rounding mode
|
||
|
|
<a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
0.3 - 0.1 // 0.19999999999999998
|
||
|
|
x = new Decimal(0.3)
|
||
|
|
x.minus(0.1) // '0.2'
|
||
|
|
x.minus(0.6, 20) // '0'</pre>
|
||
|
|
<h5 id=mod>modulo<code class=inset>.mod(n [, base]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal modulo <code>n</code>,
|
||
|
|
rounded to <a href=#precision><code>precision</code></a> significant digits using rounding
|
||
|
|
mode <a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The value returned, and in particular its sign, is dependent on the value of the
|
||
|
|
<a href=#mod><code>modulo</code></a> property. If it is <code>1</code> (default value), the
|
||
|
|
result will have the same sign as this Decimal, and it will match that of Javascript's
|
||
|
|
<code>%</code> operator (within the limits of double precision) and BigDecimal's
|
||
|
|
<code>remainder</code> method.
|
||
|
|
</p>
|
||
|
|
<p>See <a href=#mod><code>modulo</code></a> for a description of the other modulo modes.</p>
|
||
|
|
<pre>
|
||
|
|
1 % 0.9 // 0.09999999999999998
|
||
|
|
x = new Decimal(1)
|
||
|
|
x.modulo(0.9) // '0.1'
|
||
|
|
y = new Decimal(33)
|
||
|
|
y.mod('a', 33) // '3'</pre>
|
||
|
|
<h5 id=ln>naturalLogarithm<code class=inset>.ln() <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the natural logarithm of the value of this Decimal,
|
||
|
|
rounded to <a href=#precision><code>precision</code></a> significant digits using rounding
|
||
|
|
mode <a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The natual logarithm is the inverse of the <code><a href=#exp>exponential</a></code>
|
||
|
|
function.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(10)
|
||
|
|
x.naturalLogarithm() // '2.3026'
|
||
|
|
y = new Decimal('1.23e+30')
|
||
|
|
y.ln() // '69.28'</pre>
|
||
|
|
<p>
|
||
|
|
The return value will be correctly rounded, i.e. rounded as if the result was first calculated
|
||
|
|
to an infinite number of correct digits before rounding. (The mathematical result of the
|
||
|
|
natural logarithm function is non-terminating, unless its argument is <code>1</code>).
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Internally, this method is dependent on a constant with value the natural logarithm of
|
||
|
|
10. This <code>LN10</code> variable in the source code currently has a precision of
|
||
|
|
<code>1025</code> digits, meaning that this method can accurately calculate up to
|
||
|
|
<code>1000</code> digits.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If more than <code>1000</code> digits is required then the precision of <code>LN10</code>
|
||
|
|
will need to be increased to <code>25</code> digits more than is required - though, as the
|
||
|
|
time-taken by this method increases exponentially with increasing digits, it is unlikely to be
|
||
|
|
viable to calculate over 1000 digits anyway.
|
||
|
|
</p>
|
||
|
|
<h5 id=neg>negated<code class=inset>.neg() <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal negated, i.e. multiplied by
|
||
|
|
<code>-1</code>.
|
||
|
|
</p>
|
||
|
|
<p>The return value is not rounded.</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1.8)
|
||
|
|
x.negated() // '-1.8'
|
||
|
|
y = new Decimal(-1.3)
|
||
|
|
y.neg() // '1.3'</pre>
|
||
|
|
<h5 id=plus>plus<code class=inset>.plus(n [, base]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal plus <code>n</code>, rounded to
|
||
|
|
<a href=#precision><code>precision</code></a> significant digits using rounding mode
|
||
|
|
<a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
0.1 + 0.2 // 0.30000000000000004
|
||
|
|
x = new Decimal(0.1)
|
||
|
|
y = x.plus(0.2) // '0.3'
|
||
|
|
new Decimal(0.7).plus(x).plus(y) // '1.1'
|
||
|
|
x.plus('0.1', 8) // '0.225'</pre>
|
||
|
|
<h5 id=sd>precision<code class=inset>.sd([include_zeros]) <i>⇒ number</i></code></h5>
|
||
|
|
<p>Returns the number of significant digits of the value of this Decimal.</p>
|
||
|
|
<p>
|
||
|
|
If <code>include_zeros</code> is <code>true</code> or <code>1</code> then any trailing zeros
|
||
|
|
of the integer part of a number are counted as significant digits, otherwise they are not.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1.234)
|
||
|
|
x.precision() // '4'
|
||
|
|
y = new Decimal(987000)
|
||
|
|
y.sd() // '3'
|
||
|
|
y.sd(true) // '6'</pre>
|
||
|
|
<h5 id=round>round<code class=inset>.round([sd [, rm]]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>sd</code>: <i>number</i>: integer, 1 to 1e+9 inclusive.<br />
|
||
|
|
<code>rm</code>: <i>number</i>: integer, 0 to 8 inclusive.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal rounded to <code>sd</code>
|
||
|
|
significant digits using rounding mode <code>rm</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>sd</code> is omitted or is <code>null</code> or undefined, the return value will
|
||
|
|
be rounded to <a href=#precision><code>precision</code></a> significant digits.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
if <code>rm</code> is omitted or is <code>null</code> or undefined, rounding mode
|
||
|
|
<a href=#rounding><code>rounding</code></a> will be used.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
See <a href=#Errors>Errors</a> for the treatment of other non-integer or out of range
|
||
|
|
<code>sd</code> or <code>rm</code> values.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
This method differs completely from <code>Math.round</code>, which rounds to
|
||
|
|
an integer. See <a href=#toInt><code>toInteger</code></a>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
Decimal.config({ precision: 5, rounding: 4 })
|
||
|
|
x = new Decimal(9876.54321)
|
||
|
|
|
||
|
|
x.round() // '9876.5'
|
||
|
|
x.round(6) // '9876.54'
|
||
|
|
x.round(6, Decimal.ROUND_UP) // '9876.55'
|
||
|
|
x.round(2) // '9900'
|
||
|
|
x.round(2, 1) // '9800'
|
||
|
|
x // '9876.54321'</pre>
|
||
|
|
<h5 id=sqrt>squareRoot<code class=inset>.sqrt() <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the square root of this Decimal, rounded to
|
||
|
|
<a href=#precision><code>precision</code></a> significant digits using rounding mode
|
||
|
|
<a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The return value will be correctly rounded, i.e. rounded as if the result was first calculated
|
||
|
|
to an infinite number of correct digits before rounding.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The square root is method is much faster than using the
|
||
|
|
<a href=#pow><code>toPower</code></a> method with an exponent of <code>0.5</code>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(16)
|
||
|
|
x.squareRoot() // '4'
|
||
|
|
y = new Decimal(3)
|
||
|
|
y.sqrt() // '1.73205080756887729353'
|
||
|
|
y.sqrt().eq( y.pow(0.5) ) // true</pre>
|
||
|
|
<h5 id=times>times<code class=inset>.times(n [, base]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal times <code>n</code>,
|
||
|
|
rounded to <a href=#precision><code>precision</code></a> significant digits using rounding
|
||
|
|
mode <a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
0.6 * 3 // 1.7999999999999998
|
||
|
|
x = new Decimal(0.6)
|
||
|
|
y = x.times(3) // '1.8'
|
||
|
|
new Decimal('7e+500').times(y) // '1.26e+501'
|
||
|
|
x.times('-a', 16) // '-6'</pre>
|
||
|
|
<h5 id=toDP>
|
||
|
|
toDecimalPlaces<code class=inset>.toDP([dp [, rm]]) <i>⇒ Decimal</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>dp</code>: <i>number</i>: integer, 0 to 1e+9 inclusive<br />
|
||
|
|
<code>rm</code>: <i>number</i>: integer, 0 to 8 inclusive.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal rounded to <code>dp</code>
|
||
|
|
decimal places using rounding mode <code>rm</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>dp</code> is omitted or is <code>null</code> or undefined, the return value will
|
||
|
|
have the same value as this Decimal.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
if <code>rm</code> is omitted or is <code>null</code> or undefined, rounding mode
|
||
|
|
<a href=#rounding><code>rounding</code></a> is used.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
See <a href=#Errors>Errors</a> for the treatment of other non-integer or out of range
|
||
|
|
<code>dp</code> values.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(12.24567)
|
||
|
|
x.toDecimalPlaces(0) // '12'
|
||
|
|
x.toDecimalPlaces(1, 0) // '12.3'
|
||
|
|
y = new Decimal(9876.54321)
|
||
|
|
y.toDP(3) // '9876.543'
|
||
|
|
y.toDP(1, 0) // '9876.6'
|
||
|
|
y.toDP(1, 1) // '9876.5'</pre>
|
||
|
|
<h5 id=toE>
|
||
|
|
toExponential<code class=inset>.toExponential([dp [, rm]]) <i>⇒ string</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>dp</code>: <i>number</i>: integer, 0 to 1e+9 inclusive<br />
|
||
|
|
<code>rm</code>: <i>number</i>: integer, 0 to 8 inclusive
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a string representing the value of this Decimal in exponential notation rounded
|
||
|
|
using rounding mode <code>rm</code> to <code>dp</code> decimal places, i.e with one digit
|
||
|
|
before the decimal point and <code>dp</code> digits after it.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If the value of this Decimal in exponential notation has fewer than <code>dp</code> fraction
|
||
|
|
digits, the return value will be appended with zeros accordingly.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>dp</code> is omitted, or is <code>null</code> or undefined, the number of digits
|
||
|
|
after the decimal point defaults to the minimum number of digits necessary to represent the
|
||
|
|
value exactly.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>rm</code> is omitted or is <code>null</code> or undefined, rounding mode
|
||
|
|
<a href=#rounding><code>rounding</code></a> is used.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
See <a href=#Errors>Errors</a> for the treatment of other non-integer or out of range
|
||
|
|
<code>decimal_places</code> values.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = 45.6
|
||
|
|
y = new Decimal(x)
|
||
|
|
x.toExponential() // '4.56e+1'
|
||
|
|
y.toExponential() // '4.56e+1'
|
||
|
|
x.toExponential(0) // '5e+1'
|
||
|
|
y.toExponential(0) // '5e+1'
|
||
|
|
x.toExponential(1) // '4.6e+1'
|
||
|
|
y.toExponential(1) // '4.6e+1'
|
||
|
|
y.toExponential(1, 1) // '4.5e+1' (ROUND_DOWN)
|
||
|
|
x.toExponential(3) // '4.560e+1'
|
||
|
|
y.toExponential(3) // '4.560e+1'</pre>
|
||
|
|
<h5 id=toFi>toFixed<code class=inset>.toFixed([dp [, rm]]) <i>⇒ string</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>dp</code>: <i>number</i>: integer, 0 to 1e+9 inclusive<br />
|
||
|
|
<code>rm</code>: <i>number</i>: integer, 0 to 8 inclusive
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a string representing the value of this Decimal in normal (fixed-point) notation
|
||
|
|
rounded to <code>dp</code> decimal places using rounding mode <code>rm</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If the value of this Decimal in normal notation has fewer than <code>dp</code> fraction digits
|
||
|
|
, the return value will be appended with zeros accordingly.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Unlike <code>Number.prototype.toFixed</code>, which returns exponential notation if a number
|
||
|
|
is greater or equal to 10<sup>21</sup>, this method will always return normal notation.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>dp</code> is omitted or is <code>null</code> or undefined, then the return value is
|
||
|
|
unrounded and in normal notation. This is unlike <code>Number.prototype.toFixed</code>,
|
||
|
|
which returns the value to zero decimal places, but is useful when because of the current
|
||
|
|
<a href=#toExpNeg><code>toExpNeg</code></a> or
|
||
|
|
<a href=#toExpPos><code>toExpNeg</code></a> values, <code><a href=#toS>toString</a></code>
|
||
|
|
returns exponential notation.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
if <code>rm</code> is omitted or is <code>null</code> or undefined, rounding mode
|
||
|
|
<a href=#rounding><code>rounding</code></a> is used.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
See <a href=#Errors>Errors</a> for the treatment of other non-integer or out of range
|
||
|
|
<code>dp</code> values.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = 3.456
|
||
|
|
y = new Decimal(x)
|
||
|
|
x.toFixed() // '3'
|
||
|
|
y.toFixed() // '3.456'
|
||
|
|
y.toFixed(0) // '3'
|
||
|
|
x.toFixed(2) // '3.46'
|
||
|
|
y.toFixed(2) // '3.46'
|
||
|
|
y.toFixed(2, 1) // '3.45' (ROUND_DOWN)
|
||
|
|
x.toFixed(5) // '3.45600'
|
||
|
|
y.toFixed(5) // '3.45600'</pre>
|
||
|
|
<h5 id=toFo>
|
||
|
|
toFormat<code class=inset>.toFormat([sep1 [, dp [, sep2]]]) <i>⇒ string</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>sep1</code>: <i>string</i>: the grouping separator of the integer part of the number
|
||
|
|
<br />
|
||
|
|
<code>sep2</code>: <i>string</i>: the grouping separator of the fraction part of the number
|
||
|
|
<br />
|
||
|
|
<code>dp</code>: <i>number</i>: integer, 0 to 8 inclusive
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<i>
|
||
|
|
This method is a placeholder and is likely to be subject to change / further development.
|
||
|
|
</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a string representing the value of this Decimal to <code>dp</code> decimal places,
|
||
|
|
(see <a href=#toFi><code>toFixed</code></a>), but with the integer part of the number
|
||
|
|
separated by <code>sep1</code> into groups of three digits, and the fraction part of the
|
||
|
|
number separated into groups of five digits by <code>sep2</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>sep1</code> is <code>null</code> or undefined, the integer part groupings will be
|
||
|
|
separated by a comma.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>sep2</code> is <code>null</code> or undefined, the fraction part groupings will not
|
||
|
|
be separated.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>dp</code> is omitted or is <code>null</code> or undefined, then the return value is
|
||
|
|
not rounded to a fixed number of decimal places.
|
||
|
|
</p>
|
||
|
|
<p>A useful separator character is the non-breaking thin-space: <code>\u202f</code>.<p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal('1.23456000000000000000789e+9')
|
||
|
|
x.toFormat() // '1,234,560,000.00000000000789'
|
||
|
|
x.toFormat(' ') // '1 234 560 000.00000000000789'
|
||
|
|
x.toFormat(',', 2) // '1,234,560,000.00'
|
||
|
|
x.toFormat(' ', 2) // '1 234 560 000.00'
|
||
|
|
x.toFormat(',', 12, ' ') // '1 ,234,560,000.00000 00000 08'
|
||
|
|
x.toFormat('-', 14, '-') // '1-234-560-000.00000-00000-0789'</pre>
|
||
|
|
<h5 id=toFr>
|
||
|
|
toFraction
|
||
|
|
<code class=inset>.toFraction([max_denominator]) <i>⇒ [string, string]</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>max_denominator</code>: <i>number|string|Decimal</i>: <code>1</code> >= integer <
|
||
|
|
<code>Infinity</code>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a string array representing the value of this Decimal as a simple fraction with an
|
||
|
|
integer numerator and an integer denominator. The denominator will be a positive non-zero
|
||
|
|
value less than or equal to <code>max_denominator</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If a maximum denominator is not specified, or is <code>null</code> or undefined, the
|
||
|
|
denominator will be the lowest value necessary to represent the number exactly.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
See <a href=#Errors>Errors</a> for the treatment of other non-integer or out of range
|
||
|
|
<code>max_denominator</code> values.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1.75)
|
||
|
|
x.toFraction() // '7, 4'
|
||
|
|
|
||
|
|
pi = new Decimal('3.14159265358')
|
||
|
|
pi.toFraction() // '157079632679,50000000000'
|
||
|
|
pi.toFraction(100000) // '312689, 99532'
|
||
|
|
pi.toFraction(10000) // '355, 113'
|
||
|
|
pi.toFraction(100) // '311, 99'
|
||
|
|
pi.toFraction(10) // '22, 7'
|
||
|
|
pi.toFraction(1) // '3, 1'</pre>
|
||
|
|
<h5 id=toInt>toInteger<code class=inset>.toInt([rm]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p><code>rm</code>: <i>number</i>: integer, 0 to 8 inclusive.</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal rounded to a whole number using
|
||
|
|
rounding mode <code>rm</code>, or <a href=#rounding><code>rounding</code></a>
|
||
|
|
if <code>rm</code> is omitted or is <code>null</code> or undefined.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
See <a href=#Errors>Errors</a> for the treatment of other non-integer or out of range
|
||
|
|
<code>rm</code> values.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
Decimal.config({ rounding: 4 })
|
||
|
|
x = 1234.5
|
||
|
|
x.toInteger() // '1235'
|
||
|
|
|
||
|
|
Decimal.config({ rounding: 1 })
|
||
|
|
x.toInt() // '1234'
|
||
|
|
|
||
|
|
x.toInteger(Decimal.ROUND_HALF_CEIL) // '1235'
|
||
|
|
x.toInt(6) // '1234'
|
||
|
|
x // '1234.56'</pre>
|
||
|
|
<h5 id=toJSON>toJSON<code class=inset>.toJSON() <i>⇒ string</i></code></h5>
|
||
|
|
<p>As <code>valueOf</code>.</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal('177.7e+457')
|
||
|
|
y = new Decimal(235.4325)
|
||
|
|
z = new Decimal('0.0098074')
|
||
|
|
|
||
|
|
// Serialize an array of three Decimals
|
||
|
|
str = JSON.stringify( [x, y, z] )
|
||
|
|
// "["1.777e+459","235.4325","0.0098074"]"
|
||
|
|
|
||
|
|
// Return an array of three Decimals
|
||
|
|
JSON.parse(str, function (key, val) {
|
||
|
|
return key === '' ? val : new Decimal(val)
|
||
|
|
})</pre>
|
||
|
|
<p>If the <code>toJSON</code> method was not present, the objects (Decimal instances) themselves
|
||
|
|
would be serialized, rather then the string returned by <code>valueOf</code>:</p>
|
||
|
|
<pre>JSON.stringify( [x, y, z] )
|
||
|
|
/*
|
||
|
|
"[{"s":1,"e":459,"c":[1,7,7,7]},
|
||
|
|
{"s":1,"e":2,"c":[2,3,5,4,3,2,5]},
|
||
|
|
{"s":1,"e":-3,"c":[9,8,0,7,4]}]"
|
||
|
|
*/</pre>
|
||
|
|
<h5 id=toNear>
|
||
|
|
toNearest<code class=inset>.toNearest(n [, rm]) <i>⇒ Decimal</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i><br />
|
||
|
|
<code>rm</code>: <i>number</i>: integer, 0 to 8 inclusive<br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the nearest multiple of the magnitude of <code>n</code>
|
||
|
|
to the value of this Decimal.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If the value of this Decimal is equidistant from two multiples of <code>n</code>, the rounding
|
||
|
|
mode <code>rm</code>, or <a href=#rounding><code>rounding</code></a> if <code>rm</code> is
|
||
|
|
omitted or is <code>null</code> or undefined, determines the direction of the nearest.
|
||
|
|
In this context, rounding mode 4 (<a href=#rounding><code>ROUND_HALF_UP</code></a>) is the
|
||
|
|
same as rounding mode 0 (<a href=#rounding><code>ROUND_UP</code></a>), and so on.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The return value will always have the same sign as this Decimal, unless either this Decimal
|
||
|
|
or <code>n</code> is <code>NaN</code>, in which case the return value will be also be
|
||
|
|
<code>NaN</code>.
|
||
|
|
</p>
|
||
|
|
<p>The return value is not rounded to <a href=#precision><code>precision</code></a>.</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(1.39)
|
||
|
|
x.toNearest(0.25) // '1.5'
|
||
|
|
|
||
|
|
y = new Decimal(0.75) // equidistant from 0.5 and 1
|
||
|
|
y.toNearest(0.5, 0) // '1' (ROUND_UP)
|
||
|
|
y.toNearest(0.5, 1) // '0.5' (ROUND_DOWN)</pre>
|
||
|
|
<h5 id=toNum>toNumber<code class=inset>.toNumber() <i>⇒ number</i></code></h5>
|
||
|
|
<p>Returns the value of this Decimal converted to a number primitive.</p>
|
||
|
|
<p>
|
||
|
|
Type coercion with, for example, JavaScript's unary plus operator will also work, except that
|
||
|
|
a Decimal with the value minus zero will convert to positive zero.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(456.789)
|
||
|
|
x.toNumber() // 456.789
|
||
|
|
+x // 456.789
|
||
|
|
|
||
|
|
y = new Decimal('45987349857634085409857349856430985')
|
||
|
|
y.toNumber() // 4.598734985763409e+34
|
||
|
|
|
||
|
|
z = new Decimal(-0)
|
||
|
|
1 / +z // Infinity
|
||
|
|
1 / z.toNumber() // -Infinity</pre>
|
||
|
|
<h5 id=pow>toPower<code class=inset>.pow(n [, base]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
<code>n</code>: <i>number|string|Decimal</i>: integer or non-integer<br />
|
||
|
|
<code>base</code>: <i>number</i><br />
|
||
|
|
<i>See <code><a href=#decimal>Decimal</a></code> for further parameter details.</i>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal raised to the power
|
||
|
|
<code>n</code>, rounded to <a href=#precision><code>precision</code></a> significant digits
|
||
|
|
using rounding mode <a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The performance of this method degrades exponentially with increasing digits. For
|
||
|
|
non-integer exponents in particular, even when only quite a small number of significant
|
||
|
|
digits is required, the performance of this method may not be adequate.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
Math.pow(0.7, 2) // 0.48999999999999994
|
||
|
|
x = new Decimal(0.7)
|
||
|
|
x.toPower(2) // '0.49'
|
||
|
|
new Decimal(3).pow(-2) // '0.11111111111111111111'
|
||
|
|
|
||
|
|
new Decimal(1217652.23).pow('98765.489305603941')
|
||
|
|
// '4.8227010515242461181e+601039'</pre>
|
||
|
|
<p><i>Is the pow function guaranteed to be correctly rounded?</i></p>
|
||
|
|
<p>
|
||
|
|
The return value will <i>almost always</i> be correctly rounded, i.e. rounded as if the result
|
||
|
|
was first calculated to an infinite number of correct digits before rounding. If a result is
|
||
|
|
incorrectly rounded the maximum error will be <code>1</code> <i>ulp</i> (unit in the last
|
||
|
|
place).
|
||
|
|
</p>
|
||
|
|
<p>For non-integer and larger exponents this method uses the formula</p>
|
||
|
|
<blockquote><code>x<sup>y</sup> = exp(y*ln(x))</code></blockquote>
|
||
|
|
<p>
|
||
|
|
As the mathematical return values of the <code>exp</code> and <code>ln</code> functions are
|
||
|
|
both non-terminating (excluding arguments of <code>0</code> or <code>1</code>), the Decimal
|
||
|
|
return values of the functions as implemented by this library will be rounded approximations,
|
||
|
|
which means that there can be no guarantee of correct rounding when they are combined in the
|
||
|
|
above formula.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The return value may, depending on the rounding mode, be incorrectly rounded only if the first
|
||
|
|
<code>15</code> rounding digits are <code>15</code> zeros (and there are non-zero digits
|
||
|
|
following at some point) or <code>15</code> nines (the first rounding digit may also be 5 or
|
||
|
|
4 respectively).
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Therefore, assuming the first <code>15</code> rounding digits are each equally likely to be
|
||
|
|
any digit, <code>0-9</code>, the probability of an incorrectly rounded result is less than
|
||
|
|
<code>1</code> in <code>250,000,000,000,000</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
An example of incorrect rounding:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
Decimal.config({ precision: 20, rounding: 1 })
|
||
|
|
new Decimal(28).pow('6.166675020000903537297764507632802193308677149')
|
||
|
|
// 839756321.64088511</pre>
|
||
|
|
<p>As the exact mathematical result begins</p>
|
||
|
|
<pre>839756321.6408851099999999999999999999999999998969466049426031167...</pre>
|
||
|
|
<p>
|
||
|
|
and the rounding mode is set to <code><a href=#modes>ROUND_DOWN</a></code>, the correct
|
||
|
|
return value should be
|
||
|
|
</p>
|
||
|
|
<pre>839756321.64088510999</pre>
|
||
|
|
<h5 id=toP>
|
||
|
|
toPrecision<code class=inset>.toPrecision([sd [, rm]]) <i>⇒ string</i></code>
|
||
|
|
</h5>
|
||
|
|
<p>
|
||
|
|
<code>sd</code>: <i>number</i>: integer, 1 to 1e+9 inclusive<br />
|
||
|
|
<code>rm</code>: <i>number</i>: integer, 0 to 8 inclusive
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Returns a string representing the value of this Decimal rounded to <code>sd</code> significant
|
||
|
|
digits using rounding mode <code>rm</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>sd</code> is less than the number of digits necessary to represent the integer part
|
||
|
|
of the value in normal (fixed-point) notation, then exponential notation is used.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>sd</code> is omitted or is <code>null</code> or undefined, then the return value is
|
||
|
|
the same as <code><a href=#toS>toString</a></code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
if <code>rm</code> is omitted or is <code>null</code> or undefined, rounding mode
|
||
|
|
<a href=#rounding><code>rounding</code></a> is used.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
See <a href=#Errors>Errors</a> for the treatment of other non-integer or out of range
|
||
|
|
<code>sd</code> values.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = 45.6
|
||
|
|
y = new Decimal(x)
|
||
|
|
x.toPrecision() // '45.6'
|
||
|
|
y.toPrecision() // '45.6'
|
||
|
|
x.toPrecision(1) // '5e+1'
|
||
|
|
y.toPrecision(1) // '5e+1'
|
||
|
|
y.toPrecision(2, 0) // '4.6e+1' (ROUND_UP)
|
||
|
|
y.toPrecision(2, 1) // '4.5e+1' (ROUND_DOWN)
|
||
|
|
x.toPrecision(5) // '45.600'
|
||
|
|
y.toPrecision(5) // '45.600'</pre>
|
||
|
|
<h5 id=toS>toString<code class=inset>.toString([base]) <i>⇒ string</i></code></h5>
|
||
|
|
<p><code>base</code>: <i>number</i>: integer, 2 to 64 inclusive</p>
|
||
|
|
<p>
|
||
|
|
Returns a string representing the value of this Decimal in the specified base, or base 10 if
|
||
|
|
<code>base</code> is omitted.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
For bases above 10, values from 10 to 35 are represented by <code>a-z</code> (as with
|
||
|
|
<code>Number.toString</code>), 36 to 61 by <code>A-Z</code>, and 62 and 63 by <code>$</code>
|
||
|
|
and <code>_</code> respectively.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If a base is specified the value is rounded to <a href=#precision><code>precision</code></a>
|
||
|
|
significant digits using rounding mode <a href=#rounding><code>rounding</code></a>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If a base is not specified and this Decimal has a positive exponent that is equal to or
|
||
|
|
greater than <a href=#toExpPos><code>toExpPos</code></a>, or a negative exponent equal to
|
||
|
|
or less than <a href=#toExpPos><code>toExpNeg</code></a>, then exponential notation is
|
||
|
|
returned.
|
||
|
|
</p>
|
||
|
|
<p>If <code>base</code> is <code>null</code> or undefined it is ignored.</p>
|
||
|
|
<p>
|
||
|
|
See <a href=#Errors>Errors</a> for the treatment of other non-integer or out of range
|
||
|
|
<code>base</code> values.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(750000)
|
||
|
|
x.toString() // '750000'
|
||
|
|
Decimal.config({ toExpPos: 5 })
|
||
|
|
x.toString() // '7.5e+5'
|
||
|
|
|
||
|
|
y = new Decimal(362.875)
|
||
|
|
y.toString(2) // '101101010.111'
|
||
|
|
y.toString(9) // '442.77777777777777777778'
|
||
|
|
y.toString(32) // 'ba.s'
|
||
|
|
|
||
|
|
Decimal.config({ precision: 4 });
|
||
|
|
z = new Decimal('1.23456789')
|
||
|
|
z.toString() // '1.23456789'
|
||
|
|
z.toString(10) // '1.2346'</pre>
|
||
|
|
<h5 id=trunc>truncated<code class=inset>.trunc([sd]) <i>⇒ Decimal</i></code></h5>
|
||
|
|
<p>
|
||
|
|
Returns a new Decimal whose value is the value of this Decimal truncated to to <code>sd</code>
|
||
|
|
significant digits.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If <code>sd</code> is omitted or is <code>null</code> or undefined, the return value is
|
||
|
|
the value of this Decimal truncated to a whole number.
|
||
|
|
</p>
|
||
|
|
<p>The return value is not rounded to <a href=#precision><code>precision</code></a>.</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(123.456)
|
||
|
|
x.truncated() // '123'
|
||
|
|
y = new Decimal(-12.3)
|
||
|
|
y.trunc() // '-12'</pre>
|
||
|
|
<h5 id=valueOf>valueOf<code class=inset>.valueOf() <i>⇒ string</i></code></h5>
|
||
|
|
<p>As <code>toString</code>, but does not accept a base argument.</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal('1.777e+457')
|
||
|
|
x.valueOf() // '1.777e+457'</pre>
|
||
|
|
<h4 id=instance-properties>Properties</h4>
|
||
|
|
<p>
|
||
|
|
A Decimal is an object with three properties:
|
||
|
|
</p>
|
||
|
|
<table>
|
||
|
|
<tr>
|
||
|
|
<th>Property</th>
|
||
|
|
<th>Description</th>
|
||
|
|
<th>Type</th>
|
||
|
|
<th>Value</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class=centre id=coefficient><b>c</b></td>
|
||
|
|
<td>coefficient<sup>*</sup></td>
|
||
|
|
<td><i>number</i><code style=color:#000>[]</code></td>
|
||
|
|
<td> Array of single digits</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class=centre id=exponent><b>e</b></td>
|
||
|
|
<td>exponent</td>
|
||
|
|
<td><i>number</i></td>
|
||
|
|
<td>Integer, -9e15 to 9e15 inclusive</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class=centre id=sign><b>s</b></td>
|
||
|
|
<td>sign</td>
|
||
|
|
<td><i>number</i></td>
|
||
|
|
<td>-1 or 1</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<p><sup>*</sup>significand</p>
|
||
|
|
<p>
|
||
|
|
The value of any of the three properties may also be <code>null</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The value of a Decimal is stored in a normalised decimal floating point
|
||
|
|
format which corresponds to the value's <code><a href=#toE>toExponential</a></code> form,
|
||
|
|
with the decimal point to be positioned after the most significant
|
||
|
|
(left-most) digit of the coefficient.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Note that, as with JavaScript numbers, the original exponent and
|
||
|
|
fractional trailing zeros are not preserved.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal(0.123) // '0.123'
|
||
|
|
x.toExponential() // '1.23e-1'
|
||
|
|
x.c // '1,2,3'
|
||
|
|
x.e // -1
|
||
|
|
x.s // 1
|
||
|
|
|
||
|
|
y = new Number(-123.4567000e+2) // '-12345.67'
|
||
|
|
y.toExponential() // '-1.234567e+4'
|
||
|
|
z = new Decimal('-123.4567000e+2') // '-12345.67'
|
||
|
|
z.toExponential() // '-1.234567e+4'
|
||
|
|
z.c // '1,2,3,4,5,6,7'
|
||
|
|
z.e // 4
|
||
|
|
z.s // -1</pre>
|
||
|
|
<p>
|
||
|
|
A Decimal is mutable in the sense that the value of its properties can
|
||
|
|
be changed.<br />
|
||
|
|
For example, to rapidly shift a value by a power of 10:
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new Decimal('1234.000') // '1234'
|
||
|
|
x.toExponential() // '1.234e+3'
|
||
|
|
x.c // '1,2,3,4'
|
||
|
|
x.e // 3
|
||
|
|
|
||
|
|
x.e = -5
|
||
|
|
x // '0.00001234'</pre>
|
||
|
|
<p>
|
||
|
|
If changing the coefficient array directly, which is not recommended, be
|
||
|
|
careful to avoid leading or trailing zeros (unless zero itself is being
|
||
|
|
represented).
|
||
|
|
</p>
|
||
|
|
<h4 id=zero-nan-infinity>Zero, NaN and Infinity</h4>
|
||
|
|
<p>
|
||
|
|
The table below shows how ±<code>0</code>, <code>NaN</code> and
|
||
|
|
±<code>Infinity</code> are stored.
|
||
|
|
</p>
|
||
|
|
<table>
|
||
|
|
<tr>
|
||
|
|
<th> </th>
|
||
|
|
<th class=centre>c</th>
|
||
|
|
<th class=centre>e</th>
|
||
|
|
<th class=centre>s</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>±0</td>
|
||
|
|
<td><code>[0]</code></td>
|
||
|
|
<td><code>0</code></td>
|
||
|
|
<td><code>±1</code></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>NaN</td>
|
||
|
|
<td><code>null</code></td>
|
||
|
|
<td><code>null</code></td>
|
||
|
|
<td><code>null</code></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>±Infinity</td>
|
||
|
|
<td><code>null</code></td>
|
||
|
|
<td><code>null</code></td>
|
||
|
|
<td><code>±1</code></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<pre>
|
||
|
|
x = new Number(-0) // 0
|
||
|
|
1 / x == -Infinity // true
|
||
|
|
|
||
|
|
y = new Decimal(-0) // '0'
|
||
|
|
y.c // '0' ( [0].toString() )
|
||
|
|
y.e // 0
|
||
|
|
y.s // -1</pre>
|
||
|
|
<h4 id=Errors>Errors</h4>
|
||
|
|
<p>
|
||
|
|
The errors that are thrown are generic <code>Error</code> objects with <code>name</code>
|
||
|
|
<i>Decimal Error</i>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The table below shows the errors that may be thrown if <code>errors</code> is
|
||
|
|
<code>true</code>, and the action taken if <code>errors</code> is <code>false</code>.
|
||
|
|
</p>
|
||
|
|
<table class=error-table>
|
||
|
|
<tr>
|
||
|
|
<th>Method(s)</th>
|
||
|
|
<th>errors: true<br />Throw Decimal Error</th>
|
||
|
|
<th>errors: false<br />Action on invalid argument</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td rowspan=2>
|
||
|
|
<code>
|
||
|
|
ceil<br />
|
||
|
|
floor<br />
|
||
|
|
truncated
|
||
|
|
</code>
|
||
|
|
</td>
|
||
|
|
<td>argument not an integer</td>
|
||
|
|
<td>Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>argument out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td rowspan=5>
|
||
|
|
<code>
|
||
|
|
comparedTo<br />
|
||
|
|
Decimal<br />
|
||
|
|
dividedBy<br />
|
||
|
|
dividedToIntegerBy<br />
|
||
|
|
equals<br />
|
||
|
|
greaterThan<br />
|
||
|
|
greaterThanOrEqualTo<br />
|
||
|
|
lessThan<br />
|
||
|
|
lessThanOrEqualTo<br />
|
||
|
|
logarithm <br />
|
||
|
|
minus<br />
|
||
|
|
modulo<br />
|
||
|
|
naturalLogarithm<br />
|
||
|
|
plus<br />
|
||
|
|
times<br />
|
||
|
|
toPower
|
||
|
|
</code>
|
||
|
|
</td>
|
||
|
|
<td>number type has more than<br />15 significant digits</td>
|
||
|
|
<td>Accept.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>not a base... number</td>
|
||
|
|
<td>Substitute <code>NaN</code></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>base not an integer</td>
|
||
|
|
<td>Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>base out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>not a number<sup>*</sup></td>
|
||
|
|
<td>Substitute <code>NaN</code></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td rowspan=17><code>config</code></td>
|
||
|
|
<td>object expected</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>precision</code> not an integer</td>
|
||
|
|
<td>Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>precision</code> out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>rounding</code> not an integer</td>
|
||
|
|
<td>Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>rounding</code> out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>toExpNeg</code> not an integer</td>
|
||
|
|
<td>Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>toExpNeg</code> out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>toExpPos</code> not an integer</td>
|
||
|
|
<td>Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>toExpPos</code> out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>minE</code> not an integer</td>
|
||
|
|
<td> Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>minE</code> out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>maxE</code> not an integer</td>
|
||
|
|
<td> Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>maxE</code> out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>errors</code> not a boolean<br />or binary digit</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>crypto</code> not a boolean<br />or binary digit</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>modulo</code> not an integer</td>
|
||
|
|
<td> Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>modulo</code> out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>logarithm<br />naturalLogarithm</code></td>
|
||
|
|
<td>LN10 out of digits</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>precision</code></td>
|
||
|
|
<td>argument not a boolean<br />or binary digit</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td rowspan=4>
|
||
|
|
<code>
|
||
|
|
round<br />
|
||
|
|
toDecimalPlaces<br />
|
||
|
|
toExponential<br />
|
||
|
|
toFixed<br />
|
||
|
|
toPrecision
|
||
|
|
</code>
|
||
|
|
</td>
|
||
|
|
<td>argument not an integer</td>
|
||
|
|
<td>Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>argument out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>rounding mode not an integer</td>
|
||
|
|
<td>Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>rounding mode out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td rowspan=3><code>toFraction</code></td>
|
||
|
|
<td>number type has more than<br />15 significant digits</td>
|
||
|
|
<td>Accept.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>max denominator not an integer</td>
|
||
|
|
<td>Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>max denominator out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><code>toInteger</code></td>
|
||
|
|
<td>rounding mode out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td rowspan=2><code>toNearest</code></td>
|
||
|
|
<td>number type has more than<br />15 significant digits</td>
|
||
|
|
<td>Accept.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>rounding mode out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td rowspan=2><code>toString</code></td>
|
||
|
|
<td>base not an integer</td>
|
||
|
|
<td>Truncate to integer.<br />Ignore if not a number</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>base out of range</td>
|
||
|
|
<td>Ignore</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<p><sup>*</sup>No error is thrown if the value is <code>NaN</code> or 'NaN'.</p>
|
||
|
|
<p>
|
||
|
|
The message of a <i>Decimal Error</i> will also contain the name of the method from which the
|
||
|
|
error originated.
|
||
|
|
</p>
|
||
|
|
<p>To determine if an exception is a <i>Decimal Error</i>:</p>
|
||
|
|
<pre>
|
||
|
|
try {
|
||
|
|
// ...
|
||
|
|
} catch (e) {
|
||
|
|
if ( e instanceof Error && e.name == 'Decimal Error' ) {
|
||
|
|
// ...
|
||
|
|
}
|
||
|
|
}</pre>
|
||
|
|
<h2 id=faq>FAQ</h2>
|
||
|
|
<h6>Why are trailing fractional zeros removed from Decimals?</h6>
|
||
|
|
<p>
|
||
|
|
Some arbitrary-precision libraries retain trailing fractional zeros as they can indicate the
|
||
|
|
precision of a value. This can be useful but the results of arithmetic operations can be
|
||
|
|
misleading.
|
||
|
|
</p>
|
||
|
|
<pre>
|
||
|
|
x = new BigDecimal("1.0")
|
||
|
|
y = new BigDecimal("1.1000")
|
||
|
|
z = x.add(y) // 2.1000
|
||
|
|
|
||
|
|
x = new BigDecimal("1.20")
|
||
|
|
y = new BigDecimal("3.45000")
|
||
|
|
z = x.multiply(y) // 4.1400000</pre>
|
||
|
|
<p>
|
||
|
|
To specify the precision of a value is to specify that the value lies
|
||
|
|
within a certain range.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
In the first example, <code>x</code> has a value of <code>1.0</code>. The trailing zero shows
|
||
|
|
the precision of the value, implying that it is in the range <code>0.95</code> to
|
||
|
|
<code>1.05</code>. Similarly, the precision indicated by the trailing zeros of <code>y</code>
|
||
|
|
indicates that the value is in the range <code>1.09995</code> to <code>1.10005</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
If we add the two lowest values in the ranges we have, <code>0.95 + 1.09995 = 2.04995</code>,
|
||
|
|
and if we add the two highest values we have, <code>1.05 + 1.10005 = 2.15005</code>, so the
|
||
|
|
range of the result of the addition implied by the precision of its operands is
|
||
|
|
<code>2.04995</code> to <code>2.15005</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The result given by BigDecimal of <code>2.1000</code> however, indicates that the value is in
|
||
|
|
the range <code>2.09995</code> to <code>2.10005</code> and therefore the precision implied by
|
||
|
|
its trailing zeros may be misleading.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
In the second example, the true range is <code>4.122744</code> to <code>4.157256</code> yet
|
||
|
|
the BigDecimal answer of <code>4.1400000</code> indicates a range of <code>4.13999995</code>
|
||
|
|
to <code>4.14000005</code>. Again, the precision implied by the trailing zeros may be
|
||
|
|
misleading.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
This library, like binary floating point and most calculators, does not retain trailing
|
||
|
|
fractional zeros. Instead, the <code>toExponential</code>, <code>toFixed</code> and
|
||
|
|
<code>toPrecision</code> methods enable trailing zeros to be added if and when required.<br />
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<script>
|
||
|
|
/* decimal.js v1.0.0 https://github.com/MikeMcl/decimal.js/LICENCE */(function(n){"use strict";function p(n,t,i,r){return(!r&&i>3&&n[t]==4||(r||i<4)&&n[t]==9)&&n[t+1]==9&&n[t+2]==9&&n[t+3]==9&&(r!=null||n[t+4]==9)||r==null&&(n[t]==5||!n[t])&&!n[t+1]&&!n[t+2]&&!n[t+3]&&!n[t+4]}function a(n,t,i){var r=n.constructor;return t==null||((o=t<0||t>8)||t!==0&&(r.errors?parseInt:parseFloat)(t)!=t)&&!f(r,"rounding mode",t,i,0)?r.rounding:t|0}function h(n,t,i,r){var u=n.constructor;return!(o=t<(r||0)||t>=d+1)&&(t===0||(u.errors?parseInt:parseFloat)(t)==t)||f(u,"argument",t,i,0)}function e(n,t,r,u,f,e){var b=n.constructor,k=n.e-t.e,v=n.s==t.s?1:-1,h=n.c,s=t.c;if(!h||!h[0]||!s||!s[0])return new b(!n.s||!t.s||(h?s&&h[0]==s[0]:!s)?NaN:h&&h[0]==0||!s?v*0:v/0);for(var p,w,l,d,y,it=s.slice(),g=y=s.length,rt=h.length,o=h.slice(0,y),c=o.length,nt=new b(v),tt=nt.c=[],a=v=0;s[a]==(h[a]||0);a++);if(s[a]>(h[a]||0)&&(k--,v=1),nt.e=k,r==null?(r=b.precision,u=b.rounding):f&&(r+=k+1),e=e||10,r>=0){for(v+=r;c++<y;o.push(0));it.unshift(a=0);do{for(w=0;w<e;w++){if(y!=(c=o.length))p=y>c?1:-1;else for(l=-1,p=0;++l<y;)if(s[l]!=o[l]){p=s[l]>o[l]?1:-1;break}if(p<0){for(d=c==y?s:it;c;){if(o[--c]<d[c]){for(l=c;l&&!o[--l];o[l]=e-1);--o[l];o[c]+=e}o[c]-=d[c]}for(;!o[0];o.shift());}else break}tt[a++]=p?w:++w;o[0]&&p?o[c]=h[g]||0:o=[h[g]]}while((g++<rt||o[0]!=null)&&v--);!tt[0]&&a>1&&tt.shift();a<=r&&(r=null)}return i(nt,r,u,o[0]!=null,e)}function g(n,t){var h,l,b,c,r,o,s,a=0,k=0,v=0,f=n.constructor,y=f.ONE,d=f.rounding,w=f.precision;if(!n.c||!n.c[0]||n.e>17)return new f(n.c?n.c[0]?n.s<0?0:1/0:y:n.s?n.s<0?0:n:NaN);for(t==null?(u=!1,r=w):r=t,s=new f(.03125);n.e>-2;)n=n.times(s),v+=5;for(l=Math.log(Math.pow(2,v))/Math.LN10*2+5|0,r+=l,h=c=o=new f(y),f.precision=r;;){if(c=i(c.times(n),r,1),h=h.times(++k),s=o.plus(e(c,h,r,1)),s.c.slice(0,r).join("")===o.c.slice(0,r).join("")){for(b=v;b--;)o=i(o.times(o),r,1);if(t==null)if(a<3&&p(o.c,r-l,d,a))f.precision=r+=10,h=c=s=new f(y),k=0,a++;else return i(o,f.precision=w,d,u=!0);else return f.precision=w,o}o=s}}function w(n,t,r,u){var o=n.constructor,e=(n=new o(n)).e,f=n.c;if(!f)return n.toString();for(f.length>++t&&i(n,t,r),e=u?t:t+n.e-e;f.length<e;f.push(0));return e=n.e,u==1||u==2&&(t<=e||e<=o.toExpNeg)?(n.s<0&&f[0]?"-":"")+(f.length>1?f[0]+"."+f.slice(1).join(""):f[0])+(e<0?"e":"e+")+e:n.toString()}function f(n,t,i,u,f){if(n.errors){var e=new Error((u||["new Decimal","cmp","div","eq","gt","gte","lt","lte","minus","mod","plus","times","toFraction","pow","random","log","sqrt","toNearest","divToInt"][r?r<0?-r:r:1/r<0?1:0])+"() "+(["number type has more than 15 significant digits","LN10 out of digits"][t]||t+([o?" out of range":" not an integer"," not a boolean or binary digit"][f]||""))+": "+i);e.name="Decimal Error";o=r=0;throw e;}}function it(n,t,i){var r=new n(n.ONE);for(u=!1;;){if(i&1&&(r=r.times(t)),i>>=1,!i)break;t=t.times(t)}return u=!0,r}function l(n,t){var b,v,y,ut,o,a,k,nt,tt,it=1,d=10,r=n,h=r.c,s=r.constructor,g=s.ONE,rt=s.rounding,w=s.precision;if(r.s<0||!h||!h[0]||!r.e&&h[0]==1&&h.length==1)return new s(h&&!h[0]?-1/0:r.s!=1?NaN:h?0:r);if(t==null?(u=!1,o=w):o=t,s.precision=o+=d,Math.abs(v=r.e)<15e14){while(h[0]<7&&h[0]!=1||h[0]==1&&h[1]>3)r=r.times(n),h=r.c,it++;v=r.e;h[0]>1?(it==1?r=new s("0."+h.join("")):r.e=-1,v++):r=new s("1."+h.slice(1).join(""))}else return r=new s(r),r.e=0,o+2>c.length&&f(s,1,o+2,"ln"),r=l(r,o-d).plus(new s(c.slice(0,o+2)).times(v+"")),s.precision=w,t==null?i(r,w,rt,u=!0):r;for(nt=r,a=y=r=e(r.minus(g),r.plus(g),o,1),tt=i(r.times(r),o,1),b=3;;){if(y=i(y.times(tt),o,1),k=a.plus(e(y,new s(b),o,1)),k.c.slice(0,o).join("")===a.c.slice(0,o).join(""))if(a=a.times(2),v!==0&&(o+2>c.length&&f(s,1,o+2,"ln"),a=a.plus(new s(c.slice(0,o+2)).times(v+""))),a=e(a,new s(it),o,1),t==null)if(p(a.c,o-d,rt,ut))s.precision=o+=d,k=y=r=e(nt.minus(g),nt.plus(g),o,1),tt=i(r.times(r),o,1),b=ut=1;else return i(a,s.precision=w,rt,u=!0);else return s.precision=w,a;a=k;b+=2}}function i(n,t,i,r,f){var o,h,s,e,c=n.constructor;if(t!=o){if(!(e=n.c))return n;if(s=n.s<0,h=(f=f||10)/2,o=e[t],r=r||t<0||e[t+1]!=null,r=i<4?(o!=null
|
||
|
|
</script>
|
||
|
|
</body>
|
||
|
|
</html>
|