|
|
|
|
<!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:0.8em;padding:0.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:0px}
|
|
|
|
|
#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="#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="#toSD" >toSignificantDigits </a><span>toSD</span> </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>
|
|
|
|
|
|
|
|
|
|
<h2>API</h2>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
See the <a href='https://github.com/MikeMcl/decimal.js'>README</a> on GitHub for a quick-start
|
|
|
|
|
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><br />
|
|
|
|
|
<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'</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, <code>object</code>, 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>
|
|
|
|
|
<p>
|
|
|
|
|
The properties of a Decimal constructor can also be set by direct assignment, but that will
|
|
|
|
|
obviously by-pass the validity checking that this method performs.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
It is not inefficient in terms of memory usage to use multiple Decimal constructors as
|
|
|
|
|
functions are shared between them.
|
|
|
|
|
</p>
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<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 />
|
|
|
|
|
<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, 9e9999999999)
|
|
|
|
|
Decimal.random('9e99999999999') // A 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='#modulo'><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 return value 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>, <a href='#toNear'><code>toNearest</code></a>
|
|
|
|
|
and <a href='#trunc'><code>truncated</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 the result of a calculation or base conversion to
|
|
|
|
|
<code><a href='#precision'>precision</a></code> significant digits, and when rounding the
|
|
|
|
|
return value of the <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>, <a href='#toNear'><code>toNearest</code></a>,
|
|
|
|
|
<a href='#toP'><code>toPrecision</code></a> and
|
|
|
|
|
<a href='#toSD'><code>toSignificantDigits</code></a> methods.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The <a href='#modes'>rounding modes</a> 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 -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 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 -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 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 rounding/modulo 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 })</pre>
|
|
|
|
|
<p>
|
|
|
|
|
If <code>crypto.getRandomValues</code> and <code>crypto.randomBytes</code> are undefined, the
|
|
|
|
|
crypto property will remain <code>false</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<pre>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() <i>⇒ Decimal</i></code></h5>
|
|
|
|
|
<p>
|
|
|
|
|
Returns a new Decimal whose value is the value of this Decimal rounded to a whole number in
|
|
|
|
|
the direction of positive <code>Infinity</code>.
|
|
|
|
|
</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'><code>1</code></td>
|
|
|
|
|
<td>If the value of this Decimal is greater than the value of <code>n</code></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td class='centre'><code>-1</code></td>
|
|
|
|
|
<td>If the value of this Decimal is less than the value of <code>n</code></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td class='centre'><code>0</code></td>
|
|
|
|
|
<td>If this Decimal and <code>n</code> have the same value</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td class='centre'><code>null</code></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() <i>⇒ Decimal</i></code></h5>
|
|
|
|
|
<p>
|
|
|
|
|
Returns a new Decimal whose value is the value of this Decimal rounded to a whole number in
|
|
|
|
|
the direction of negative <code>Infinity</code>.
|
|
|
|
|
</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 <code>NaN</code>, 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='#modulo'><code>modulo</code></a> property of this Decimal's constructor. 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='#modulo'><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'
|
|
|
|
|
|
|
|
|
|
x = new Decimal(8)
|
|
|
|
|
y = new Decimal(-3)
|
|
|
|
|
Decimal.modulo = 1
|
|
|
|
|
x.mod(y) // '2'
|
|
|
|
|
Decimal.modulo = 3
|
|
|
|
|
x.mod(y) // '-1'</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 whose value is the natural logarithm of
|
|
|
|
|
<code>10</code>. 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 <code>1000</code> 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() <i>⇒ Decimal</i></code></h5>
|
|
|
|
|
<p>
|
|
|
|
|
Returns a new Decimal whose value is the value of this Decimal rounded to a whole number using
|
|
|
|
|
rounding mode <a href='#rounding'><code>rounding</code></a>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
To emulate <code>Math.round</code>, set <a href='#rounding'><code>rounding</code></a> to
|
|
|
|
|
<code>7</code>, i.e. <a href='#modes'><code>ROUND_HALF_CEIL</code></a>.
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
Decimal.config({ rounding: 4 })
|
|
|
|
|
x = 1234.5
|
|
|
|
|
x.round() // '1235'
|
|
|
|
|
|
|
|
|
|
Decimal.rounding = Decimal.ROUND_DOWN
|
|
|
|
|
x.round() // '1234'
|
|
|
|
|
x // '1234.5'</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>
|
|
|
|
|
This 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, Decimal.ROUND_DOWN) // '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 <code>10<sup>21</sup></code>, 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 will
|
|
|
|
|
be 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="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 <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.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
In this context, rounding mode <a href='#rounding'><code>ROUND_HALF_UP</code></a> is
|
|
|
|
|
interpreted the same as rounding mode <a href='#rounding'><code>ROUND_UP</code></a>, and so
|
|
|
|
|
on. I.e. the rounding is either up, down, to ceil, to floor or to even.
|
|
|
|
|
</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
|
|
|
|
|
<code>5</code> or <code>4</code> 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="toSD">
|
|
|
|
|
toSignificantDigits<code class='inset'>.toSD([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>
|
|
|
|
|
<pre>
|
|
|
|
|
Decimal.config({ precision: 5, rounding: 4 })
|
|
|
|
|
x = new Decimal(9876.54321)
|
|
|
|
|
|
|
|
|
|
x.toSignificantDigits() // '9876.5'
|
|
|
|
|
x.toSignificantDigits(6) // '9876.54'
|
|
|
|
|
x.toSignificantDigits(6, Decimal.ROUND_UP) // '9876.55'
|
|
|
|
|
x.toSD(2) // '9900'
|
|
|
|
|
x.toSD(2, 1) // '9800'
|
|
|
|
|
x // '9876.54321'</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 or is <code>null</code> or undefined.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
For bases above 10, values from 10 to 35 are represented by <code>a-z</code> (as with
|
|
|
|
|
<code>Number.prototype.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() <i>⇒ Decimal</i></code></h5>
|
|
|
|
|
<p>
|
|
|
|
|
Returns a new Decimal whose 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=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=16><code>config</code></td>
|
|
|
|
|
<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 or binary digit</td>
|
|
|
|
|
<td>Ignore</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>crypto</code> not a boolean 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 or binary digit</td>
|
|
|
|
|
<td>Ignore</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td rowspan=4>
|
|
|
|
|
<code>
|
|
|
|
|
toDecimalPlaces<br />
|
|
|
|
|
toExponential<br />
|
|
|
|
|
toFixed<br />
|
|
|
|
|
toPrecision<br />
|
|
|
|
|
toSignificantDigits
|
|
|
|
|
</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 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>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
