mirror of
https://github.com/MikeMcl/decimal.js.git
synced 2024-10-27 20:34:12 +00:00
b141f3480d
Avoid potential confusion over the round method: ceil, floor, round and trunc no longer accept arguments and so they match their JS Math object equivalents. Removed toInteger as round now handles rounding to integer. Added toSignificantDigits as round no longer rounds to precision. Updated tests accordingly. Calling config without argument no longer throws.
2391 lines
90 KiB
HTML
2391 lines
90 KiB
HTML
<!DOCTYPE HTML>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
|
<meta name="Author" content="MMclaughlin">
|
|
<title>decimal.js API</title>
|
|
<style>
|
|
html{font-size:100%}
|
|
body{background:#fff;font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-size:13px;
|
|
line-height:1.65em;min-height:100%;margin:0}
|
|
body,i{color:#000}
|
|
.nav{background:#fff;position:fixed;top:0;bottom:0;left:0;width:200px;overflow-y:auto;
|
|
padding:15px 0 30px 15px}
|
|
div.container{width:600px;margin:50px 0 50px 240px}
|
|
p{margin:0 0 1em;width:600px}
|
|
pre,ul{margin:1em 0}
|
|
h1,h2,h3,h4,h5{margin:0;padding:1.5em 0 0}
|
|
h1,h2{padding:.75em 0}
|
|
h1{font:400 3em Consolas, monaco, monospace;color:#000;margin-bottom:1em}
|
|
h2{font-size:2.25em;color:#f00}
|
|
h3{font-size:1.75em;color:#69d2e7}
|
|
h4{font-size:1.75em;color:#f00;padding-bottom:.75em}
|
|
h5{font-size:1.2em;margin-bottom:.4em}
|
|
h6{font-size:1.1em;margin-bottom: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='#mod'><code>modulo</code></a> and <a href='#crypto'><code>crypto</code></a> are set
|
|
using the <a href='#Dconfig'><code>config</code></a> method.
|
|
</p>
|
|
<p>
|
|
As simple object properties they can be set directly without using
|
|
<a href='#Dconfig'><code>config</code></a>, and it is fine to do so, but the values assigned
|
|
will not then be checked for validity. For example:
|
|
</p>
|
|
<pre>Decimal.config({ precision: 0 })
|
|
// 'Decimal Error: config() precision out of range: 0'
|
|
|
|
Decimal.precision = 0
|
|
// No error is thrown and the results of calculations are unpredictable</pre>
|
|
|
|
|
|
|
|
<h5 id="precision">precision</h5>
|
|
<p>
|
|
<i>number</i>: integer, <code>1</code> to <code>1e+9</code> inclusive<br />
|
|
Default value: <code>20</code>
|
|
</p>
|
|
<p>
|
|
The <i>maximum</i> number of significant digits of the result of a calculation or base
|
|
conversion.
|
|
</p>
|
|
<p>
|
|
All methods which return a Decimal will round the 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='#mod'><code>modulo</code></a> property. If it is <code>1</code> (default value), the
|
|
result will have the same sign as this Decimal, and it will match that of Javascript's
|
|
<code>%</code> operator (within the limits of double precision) and BigDecimal's
|
|
<code>remainder</code> method.
|
|
</p>
|
|
<p>See <a href='#mod'><code>modulo</code></a> for a description of the other modulo modes.</p>
|
|
<pre>
|
|
1 % 0.9 // 0.09999999999999998
|
|
x = new Decimal(1)
|
|
x.modulo(0.9) // '0.1'
|
|
y = new Decimal(33)
|
|
y.mod('a', 33) // '3'</pre>
|
|
|
|
|
|
|
|
<h5 id="ln">naturalLogarithm<code class='inset'>.ln() <i>⇒ Decimal</i></code></h5>
|
|
<p>
|
|
Returns a new Decimal whose value is the natural logarithm of the value of this Decimal,
|
|
rounded to <a href='#precision'><code>precision</code></a> significant digits using rounding
|
|
mode <a href='#rounding'><code>rounding</code></a>.
|
|
</p>
|
|
<p>
|
|
The natual logarithm is the inverse of the <code><a href='#exp'>exponential</a></code>
|
|
function.
|
|
</p>
|
|
<pre>
|
|
x = new Decimal(10)
|
|
x.naturalLogarithm() // '2.3026'
|
|
y = new Decimal('1.23e+30')
|
|
y.ln() // '69.28'</pre>
|
|
<p>
|
|
The return value will be correctly rounded, i.e. rounded as if the result was first calculated
|
|
to an infinite number of correct digits before rounding. (The mathematical result of the
|
|
natural logarithm function is non-terminating, unless its argument is <code>1</code>).
|
|
</p>
|
|
<p>
|
|
Internally, this method is dependent on a constant 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>
|