mirror of
https://github.com/MikeMcl/big.js.git
synced 2026-01-25 16:04:15 +00:00
0b79acd7aa
Refactor error messaging. Throw if null is passed to toFixed etc. and amend tests accordingly. Clean-up and reformat.
1229 lines
37 KiB
HTML
1229 lines
37 KiB
HTML
<!DOCTYPE HTML>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="Author" content="M Mclaughlin">
|
|
<title>big.js API</title>
|
|
<style>
|
|
html{font-family:sans-serif;font-size:100%}
|
|
body{font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-size:14px;
|
|
line-height:1.65em;background:#fefff5;color:#000;min-height:100%;margin:0}
|
|
.nav{background:#fff;position:fixed;top:0;bottom:0;left:0;width:130px;
|
|
overflow-y:auto;padding:15px 0 30px 20px; border-right: 1px solid #69d2e7}
|
|
div.container{width:700px;margin:30px 0 50px 190px}
|
|
p{margin:0 0 1em;width:700px}
|
|
pre,ul{margin:1em 0}
|
|
h1,h2,h3,h4,h5{margin:0;padding:1.5em 0 0}
|
|
h1,h2{padding:.75em 0 1em}
|
|
h1{font-size:2.75em;color:#fa6900}
|
|
h2{font-size:2.25em;color:#fa6900}
|
|
h3{font-size:1.75em;color:#69d2e7}
|
|
h4{font-size:1.75em;color:#fa6900;padding-bottom:.75em}
|
|
h5{font-size:1.2em;padding-bottom:.3em}
|
|
h6{font-size:1.1em;margin:0;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:#444;text-decoration:none}
|
|
a:active,a:hover{outline:0;color:#000}
|
|
a:hover{text-decoration:underline}
|
|
.nav a,.nav b,.nav a:visited{display:block;color:#fa6900;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{display:inline;color:#000;font-family:Verdana,
|
|
Geneva,sans-serif;font-size:11px;font-weight:400;margin:0}
|
|
.inset,ul.inset{margin-left:20px}
|
|
code.inset{font-size:.9em}
|
|
.nav li{cursor:pointer;width:auto;margin:0 0 3px}
|
|
span.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 10px;border:1px dotted #a7dbd8}
|
|
th{border-top:2px solid #a7dbd8;border-bottom:2px solid #a7dbd8;color:#f38630}
|
|
pre{background:#fff;white-space:pre-wrap;word-wrap:break-word;
|
|
border-left:5px solid #a7dbd8;padding:1px 0 1px 15px;margin:1.2em 0}
|
|
code,pre{font-family:Monaco,Consolas,"Lucida Console",monospace;
|
|
font-weight:400}
|
|
.end{margin-bottom:25px}
|
|
.nav-title{color:#fa6900}
|
|
.centre{text-align:center}
|
|
.error{color:#f00}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<div class="nav">
|
|
|
|
<a class='nav-title' href="#">big.js</a>
|
|
|
|
<b> CONSTRUCTOR </b>
|
|
<ul>
|
|
<li><a href="#big">Big</a></li>
|
|
</ul>
|
|
|
|
<a href="#constructor-properties">Properties</a>
|
|
<ul>
|
|
<li><a href="#dp" >DP</a></li>
|
|
<li><a href="#rm" >RM</a></li>
|
|
<li><a href="#eneg">NE</a></li>
|
|
<li><a href="#epos">PE</a></li>
|
|
</ul>
|
|
|
|
<b> INSTANCE </b>
|
|
|
|
<a href="#prototype-methods">Methods</a>
|
|
<ul>
|
|
<li><a href="#abs" >abs</a></li>
|
|
<li><a href="#cmp" >cmp</a></li>
|
|
<li><a href="#div" >div</a></li>
|
|
<li><a href="#eq" >eq</a></li>
|
|
<li><a href="#gt" >gt</a></li>
|
|
<li><a href="#gte" >gte</a></li>
|
|
<li><a href="#lt" >lt</a></li>
|
|
<li><a href="#lte" >lte</a></li>
|
|
<li><a href="#minus" >minus</a></li>
|
|
<li><a href="#mod" >mod</a></li>
|
|
<li><a href="#plus" >plus</a></li>
|
|
<li><a href="#pow" >pow</a></li>
|
|
<li><a href="#round" >round</a></li>
|
|
<li><a href="#sqrt" >sqrt</a></li>
|
|
<li><a href="#times" >times</a></li>
|
|
<li><a href="#toE" >toExponential</a></li>
|
|
<li><a href="#toF" >toFixed</a></li>
|
|
<li><a href="#toP" >toPrecision</a></li>
|
|
<li><a href="#toS" >toString</a></li>
|
|
<li><a href="#valueOf">valueOf</a></li>
|
|
<li><a href="#toJSON" >toJSON</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="#Errors">Errors</a>
|
|
|
|
<a class='end' href="#faq">FAQ</a>
|
|
|
|
</div>
|
|
|
|
<div class="container">
|
|
|
|
<h1>big.js</h1>
|
|
|
|
<p>
|
|
A small, fast, easy-to-use library for arbitrary-precision decimal
|
|
arithmetic.
|
|
</p>
|
|
|
|
<p><a href="https://github.com/MikeMcl/big.js/">Hosted on GitHub</a>.</p>
|
|
|
|
<h2>API</h2>
|
|
|
|
<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>
|
|
|
|
|
|
|
|
<h3>CONSTRUCTOR</h3>
|
|
|
|
<h5 id="big">
|
|
Big<code class='inset'>Big( value ) ⇒ <i>Big</i></code>
|
|
</h5>
|
|
<dl>
|
|
<dt><code>value</code></dt>
|
|
<dd>
|
|
<i>number|string|Big</i>
|
|
</dd>
|
|
<dd>
|
|
A decimal value.
|
|
</dd>
|
|
<dd>
|
|
String values may be in exponential, as well as normal (non-exponential)
|
|
notation.
|
|
</dd>
|
|
<dd>
|
|
There is no limit to the number of digits of a <em>string</em> value
|
|
(other than that of Javascript's maximum array size), but the largest
|
|
recommended exponent magnitude is 1e+6.
|
|
</dd>
|
|
<dd>
|
|
<code>Infinity</code>, <code>NaN</code> and hexadecimal literal
|
|
strings, e.g. '0xff', are <u>not</u> valid.<br>
|
|
String values in octal literal form will be interpreted as decimals,
|
|
e.g. '011' is 11, not 9.
|
|
</dd>
|
|
</dl>
|
|
<p>Returns a new instance of a Big number object.</p>
|
|
<p>
|
|
Throws <code class='error'>NaN</code> on an invalid <code>value</code>.
|
|
</p>
|
|
<pre>
|
|
x = new Big(9) // '9'
|
|
y = new Big(x) // '9'
|
|
Big(435.345) // 'new' is optional
|
|
new Big('5032485723458348569331745.33434346346912144534543')
|
|
new Big('4.321e+4') // '43210'
|
|
new Big('-735.0918e-430') // '-7.350918e-428'</pre>
|
|
|
|
|
|
|
|
<h4 id="constructor-properties">Properties</h4>
|
|
|
|
<h5 id="dp">DP</h5>
|
|
<p>
|
|
<i>number</i> : integer, 0 to 1e+6 inclusive<br />
|
|
Default value: <code>20</code>
|
|
</p>
|
|
<p>
|
|
The <u>maximum</u> number of decimal places of the results of operations
|
|
involving division.<br />
|
|
It is relevant only to the <code>div</code> and <code>sqrt</code> methods,
|
|
and the <code>pow</code> method when the exponent is negative.
|
|
</p>
|
|
<p>
|
|
The value will be checked for validity when one of the above methods is
|
|
called.<br /> An error will be thrown if the value is found to be invalid.
|
|
</p>
|
|
<pre>Big.DP = 40</pre>
|
|
|
|
|
|
|
|
<h5 id="rm">RM</h5>
|
|
<p>
|
|
<i>number</i> : 0, 1, 2 or 3<br />
|
|
Default value: <code>1</code>
|
|
</p>
|
|
<p>
|
|
The rounding mode used in the above operations and by
|
|
<a href='#round'><code>round</code></a>,
|
|
<a href='#toE'><code>toExponential</code></a>,
|
|
<a href='#toF'><code>toFixed</code></a> and
|
|
<a href='#toP'><code>toPrecision</code></a>.
|
|
</p>
|
|
<table>
|
|
<tr>
|
|
<th>Value</th>
|
|
<th>Description</th>
|
|
<th>BigDecimal equivalent</th>
|
|
</tr>
|
|
<tr>
|
|
<td class='centre'>0</td>
|
|
<td>
|
|
Rounds towards zero.<br />
|
|
I.e. truncate, no rounding.
|
|
</td>
|
|
<td id="round-down">ROUND_DOWN</td>
|
|
</tr>
|
|
<tr>
|
|
<td class='centre'>1</td>
|
|
<td>
|
|
Rounds towards nearest neighbour.<br />
|
|
If equidistant, rounds away from zero.
|
|
</td>
|
|
<td id="round-half-up">ROUND_HALF_UP</td>
|
|
</tr>
|
|
<tr>
|
|
<td class='centre'>2</td>
|
|
<td>
|
|
Rounds towards nearest neighbour.<br />
|
|
If equidistant, rounds towards even neighbour.
|
|
</td>
|
|
<td id="round-half-even">ROUND_HALF_EVEN</td>
|
|
</tr>
|
|
<tr>
|
|
<td class='centre'>3</td>
|
|
<td>Rounds away from zero.</td>
|
|
<td id="round-up">ROUND_UP</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
The value will be checked for validity when one of the above methods is
|
|
called.<br /> An error will be thrown if the value is found to be invalid.
|
|
</p>
|
|
<pre>Big.RM = 0</pre>
|
|
|
|
|
|
|
|
<h5 id="eneg">NE</h5>
|
|
<p>
|
|
<i>number</i> : integer, -1e+6 to 0 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>
|
|
Big.NE = -7
|
|
x = new Big(0.00000123) // '0.00000123' e is -6
|
|
x = new Big(0.000000123) // '1.23e-7'</pre>
|
|
<p>
|
|
JavaScript numbers use exponential notation for negative exponents of
|
|
<code>-7</code> and below.
|
|
</p>
|
|
<p>
|
|
Regardless of the value of <code>Big.NE</code>, the
|
|
<a href='#toF'><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>
|
|
|
|
|
|
|
|
<h5 id="epos">PE</h5>
|
|
<p>
|
|
<i>number</i> : integer, 0 to 1e+6 inclusive<br />
|
|
Default value: <code>21</code>
|
|
</p>
|
|
<p>
|
|
The positive exponent value at and above which
|
|
<a href='#toS'><code>toString</code></a> returns exponential notation.
|
|
</p>
|
|
<pre>
|
|
Big.PE = 2
|
|
x = new Big(12.3) // '12.3' e is 1
|
|
x = new Big(123) // '1.23e+2'</pre>
|
|
<p>
|
|
JavaScript numbers use exponential notation for positive exponents of
|
|
<code>21</code> and above.
|
|
</p>
|
|
<p>
|
|
Regardless of the value of <code>Big.PE</code>, the
|
|
<a href='#toF'><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>
|
|
|
|
|
|
|
|
<h3>INSTANCE</h3>
|
|
|
|
<h4 id="prototype-methods">Methods</h4>
|
|
<p>
|
|
The methods inherited by a Big number instance from its constructor's
|
|
prototype object.
|
|
</p>
|
|
<p>
|
|
A Big number is immutable in the sense that it is not changed by its
|
|
methods.
|
|
</p>
|
|
|
|
|
|
|
|
<h5 id="abs">abs<code class='inset'>.abs() ⇒ <i>Big</i></code></h5>
|
|
<p>
|
|
Returns a Big number whose value is the absolute value, i.e. the
|
|
magnitude, of this Big number.
|
|
</p>
|
|
<pre>
|
|
x = new Big(-0.8)
|
|
x.abs() // '0.8'</pre>
|
|
|
|
|
|
|
|
<h5 id="cmp">
|
|
cmp<code class='inset'>.cmp( n ) ⇒ <i>number</i></code>
|
|
</h5>
|
|
<p><code>n</code> : <i>number|string|Big</i><br /></p>
|
|
<table>
|
|
<tr>
|
|
<th>Returns</th>
|
|
<th colspan=2> </th>
|
|
</tr>
|
|
<tr>
|
|
<td class='centre'>1</td>
|
|
<td>
|
|
If the value of this Big number is greater than the value of
|
|
<code>n</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class='centre'>-1</td>
|
|
<td>
|
|
If the value of this Big number is less than the value of
|
|
<code>n</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class='centre'>0</td>
|
|
<td>If this Big number and <code>n</code> have the same value</td>
|
|
</tr>
|
|
</table>
|
|
<p>Throws <code class='error'>NaN</code> if <code>n</code> is invalid.</p>
|
|
<pre>
|
|
x = new Big(6)
|
|
y = new Big(5)
|
|
x.cmp(y) // 1
|
|
y.cmp(x.minus(1)) // 0</pre>
|
|
|
|
|
|
|
|
<h5 id="div">div<code class='inset'>.div(n) ⇒ <i>Big</i></code></h5>
|
|
<p><code>n</code> : <i>number|string|Big</i><br /></p>
|
|
<p>
|
|
Returns a Big number whose value is the value of this Big number divided
|
|
by <code>n</code>.
|
|
</p>
|
|
<p>
|
|
If the result has more fraction digits than is specified by
|
|
<a href='#dp'><code>Big.DP</code></a>, it will be rounded to
|
|
<a href='#dp'><code>Big.DP</code></a> decimal places using rounding mode
|
|
<a href='#rm'><code>Big.RM</code></a>.
|
|
</p>
|
|
<p>
|
|
Throws <code class='error'>NaN</code> if <code>n</code> is invalid.<br />
|
|
Throws <code class='error'>±Infinity</code> on division by zero.<br />
|
|
Throws <code class='error'>NaN</code> on division of zero by zero.
|
|
</p>
|
|
<pre>
|
|
x = new Big(355)
|
|
y = new Big(113)
|
|
x.div(y) // '3.14159292035398230088'
|
|
Big.DP = 2
|
|
x.div(y) // '3.14'
|
|
x.div(5) // '71'</pre>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h5 id="eq">eq<code class='inset'>.eq(n) ⇒ <i>boolean</i></code></h5>
|
|
<p><code>n</code> : <i>number|string|Big</i></p>
|
|
<p>
|
|
Returns <code>true</code> if the value of this Big equals the value
|
|
of <code>n</code>, otherwise returns <code>false</code>.
|
|
</p>
|
|
<p>Throws <code class='error'>NaN</code> if <code>n</code> is invalid.</p>
|
|
<pre>
|
|
0 === 1e-324 // true
|
|
x = new Big(0)
|
|
x.eq('1e-324') // false
|
|
Big(-0).eq(x) // true ( -0 === 0 )</pre>
|
|
|
|
|
|
|
|
<h5 id="gt">
|
|
gt<code class='inset'>.gt(n) ⇒ <i>boolean</i></code>
|
|
</h5>
|
|
<p><code>n</code> : <i>number|string|Big</i></p>
|
|
<p>
|
|
Returns <code>true</code> if the value of this Big is greater than
|
|
the value of <code>n</code>, otherwise returns <code>false</code>.
|
|
</p>
|
|
<p>Throws <code class='error'>NaN</code> if <code>n</code> is invalid.</p>
|
|
<pre>
|
|
0.1 > 0.3 - 0.2 // true
|
|
x = new Big(0.1)
|
|
x.gt(Big(0.3).minus(0.2)) // false
|
|
Big(0).gt(x) // false</pre>
|
|
|
|
|
|
|
|
<h5 id="gte">
|
|
gte<code class='inset'>.gte(n) ⇒ <i>boolean</i></code>
|
|
</h5>
|
|
<p><code>n</code> : <i>number|string|Big</i></p>
|
|
<p>
|
|
Returns <code>true</code> if the value of this Big is greater than
|
|
or equal to the value of <code>n</code>, otherwise returns
|
|
<code>false</code>.
|
|
</p>
|
|
<p>Throws <code class='error'>NaN</code> if <code>n</code> is invalid.</p>
|
|
<pre>
|
|
0.3 - 0.2 >= 0.1 // false
|
|
x = new Big(0.3).minus(0.2)
|
|
x.gte(0.1) // true
|
|
Big(1).gte(x) // true</pre>
|
|
|
|
|
|
|
|
<h5 id="lt">
|
|
lt<code class='inset'>.lt(n) ⇒ <i>boolean</i></code>
|
|
</h5>
|
|
<p><code>n</code> : <i>number|string|Big</i></p>
|
|
<p>
|
|
Returns <code>true</code> if the value of this Big is less than the
|
|
value of <code>n</code>, otherwise returns <code>false</code>.
|
|
</p>
|
|
<p>Throws <code class='error'>NaN</code> if <code>n</code> is invalid.</p>
|
|
<pre>
|
|
0.3 - 0.2 < 0.1 // true
|
|
x = new Big(0.3).minus(0.2)
|
|
x.lt(0.1) // false
|
|
Big(0).lt(x) // true</pre>
|
|
|
|
|
|
|
|
<h5 id="lte">
|
|
lte<code class='inset'>.lte(n) ⇒ <i>boolean</i></code>
|
|
</h5>
|
|
<p><code>n</code> : <i>number|string|Big</i></p>
|
|
<p>
|
|
Returns <code>true</code> if the value of this Big is less than or
|
|
equal to the value of <code>n</code>, otherwise returns
|
|
<code>false</code>.
|
|
</p>
|
|
<p>Throws <code class='error'>NaN</code> if <code>n</code> is invalid.</p>
|
|
<pre>
|
|
0.1 <= 0.3 - 0.2 // false
|
|
x = new Big(0.1)
|
|
x.lte(Big(0.3).minus(0.2)) // true
|
|
Big(-1).lte(x) // true</pre>
|
|
|
|
|
|
|
|
<h5 id="minus">
|
|
minus<code class='inset'>.minus(n) ⇒ <i>Big</i></code>
|
|
</h5>
|
|
<p><code>n</code> : <i>number|string|Big</i></p>
|
|
<p>
|
|
Returns a Big number whose value is the value of this Big number minus
|
|
<code>n</code>.
|
|
</p>
|
|
<p>Throws <code class='error'>NaN</code> if <code>n</code> is invalid.</p>
|
|
<pre>
|
|
0.3 - 0.1 // 0.19999999999999998
|
|
x = new Big(0.3)
|
|
x.minus(0.1) // '0.2'</pre>
|
|
|
|
|
|
|
|
<h5 id="mod">mod<code class='inset'>.mod(n) ⇒ <i>Big</i></code></h5>
|
|
<p><code>n</code> : <i>number|string|Big</i></p>
|
|
<p>
|
|
Returns a Big number whose value is the value of this Big number modulo
|
|
<code>n</code>, i.e. the integer remainder of dividing this Big number by
|
|
<code>n</code>.
|
|
</p>
|
|
<p>
|
|
The result will have the same sign as this Big number, and it will match
|
|
that of Javascript's % operator (within the limits of its precision) and
|
|
BigDecimal's remainder method.
|
|
</p>
|
|
<p>
|
|
Throws <code class='error'>NaN</code> if <code>n</code> is negative or
|
|
otherwise invalid.
|
|
</p>
|
|
<pre>
|
|
1 % 0.9 // 0.09999999999999998
|
|
x = new Big(1)
|
|
x.mod(0.9) // '0.1'</pre>
|
|
|
|
|
|
|
|
<h5 id="plus">
|
|
plus<code class='inset'>.plus(n) ⇒ <i>Big</i></code>
|
|
</h5>
|
|
<p><code>n</code> : <i>number|string|Big</i></p>
|
|
<p>
|
|
Returns a Big number whose value is the value of this Big number plus
|
|
<code>n</code>.
|
|
</p>
|
|
<p>Throws <code class='error'>NaN</code> if <code>n</code> is invalid.</p>
|
|
<pre>
|
|
0.1 + 0.2 // 0.30000000000000004
|
|
x = new Big(0.1)
|
|
y = x.plus(0.2) // '0.3'
|
|
Big(0.7).plus(x).plus(y) // '1.1'</pre>
|
|
|
|
|
|
|
|
<h5 id="pow">pow<code class='inset'>.pow( exp ) ⇒ <i>Big</i></code>
|
|
</h5>
|
|
<p>
|
|
<code>exp</code> : <i>number</i> : integer, -1e+6 to 1e+6 inclusive
|
|
</p>
|
|
<p>
|
|
Returns a Big number whose value is the value of this Big number raised to
|
|
the power <code>exp</code>.
|
|
</p>
|
|
<p>
|
|
If <code>exp</code> is negative and the result has more fraction digits
|
|
than is specified by <a href='#dp'><code>Big.DP</code></a>, it will be
|
|
rounded to <a href='#dp'><code>Big.DP</code></a> decimal places using
|
|
rounding mode <a href='#rm'><code>Big.RM</code></a>.
|
|
</p>
|
|
<p>
|
|
Throws if <code>exp</code> is invalid.
|
|
</p>
|
|
<p>
|
|
Note: High value exponents may cause this method to be slow to return.
|
|
</p>
|
|
<pre>
|
|
Math.pow(0.7, 2) // 0.48999999999999994
|
|
x = new Big(0.7)
|
|
x.pow(2) // '0.49'
|
|
Big.DP = 20
|
|
Big(3).pow(-2) // '0.11111111111111111111'
|
|
|
|
new Big(123.456).pow(1000).toString().length // 5099
|
|
new Big(2).pow(1e+6) // Time taken (Node.js): 9 minutes 34 secs.</pre>
|
|
|
|
|
|
|
|
<h5 id="round">
|
|
round<code class='inset'>.round( [dp [, rm]] )
|
|
⇒ <i>Big</i></code>
|
|
</h5>
|
|
<p>
|
|
<code>dp</code> : <i>number</i> : integer, 0 to 1e+6 inclusive
|
|
<br />
|
|
<code>rm</code> : <i>number</i> : 0, 1, 2 or 3
|
|
</p>
|
|
<p>
|
|
Returns a Big number whose value is the value of this Big number rounded
|
|
using rounding mode <code>rm</code> to a maximum of <code>dp</code>
|
|
decimal places.
|
|
</p>
|
|
<p>
|
|
if <code>dp</code> is omitted or is undefined, the return value is
|
|
<code>n</code> rounded to a whole number.<br />
|
|
if <code>rm</code> is omitted or is undefined, the current
|
|
<a href='#rm'><code>Big.RM</code></a> setting is used.
|
|
</p>
|
|
<p>
|
|
Throws if <code>dp</code> or <code>rm</code> is invalid.
|
|
</p>
|
|
<pre>
|
|
x = 123.45
|
|
Math.round(x) // 123
|
|
y = new Big(x)
|
|
y.round() // '123'
|
|
y.round(2) // '123.45'
|
|
y.round(10) // '123.45'
|
|
y.round(1, 0) // '123.4'
|
|
y.round(1, 1) // '123.5'
|
|
y.round(1, 2) // '123.4'
|
|
y.round(1, 3) // '123.5'
|
|
y // '123.45'</pre>
|
|
|
|
|
|
|
|
<h5 id="sqrt">sqrt<code class='inset'>.sqrt() ⇒ <i>Big</i></code></h5>
|
|
<p>
|
|
Returns a Big number whose value is the square root of this Big number.
|
|
</p>
|
|
<p>
|
|
If the result has more fraction digits than is specified by
|
|
<a href='#dp'><code>Big.DP</code></a>, it will be rounded to
|
|
<a href='#dp'><code>Big.DP</code></a> decimal places using rounding mode
|
|
<a href='#rm'><code>Big.RM</code></a>.
|
|
</p>
|
|
<p>Throws <code class='error'>NaN</code> if this Big number is negative.</p>
|
|
<pre>
|
|
x = new Big(16)
|
|
x.sqrt() // '4'
|
|
y = new Big(3)
|
|
y.sqrt() // '1.73205080756887729353'</pre>
|
|
|
|
|
|
|
|
<h5 id="times">
|
|
times<code class='inset'>.times(n) ⇒ <i>Big</i></code>
|
|
</h5>
|
|
<p><code>n</code> : <i>number|string|Big</i><br /></p>
|
|
<p>
|
|
Returns a Big number whose value is the value of this Big number times
|
|
<code>n</code>.
|
|
</p>
|
|
<p>Throws <code class='error'>NaN</code> if <code>n</code> is invalid.</p>
|
|
<pre>
|
|
0.6 * 3 // 1.7999999999999998
|
|
x = new Big(0.6)
|
|
y = x.times(3) // '1.8'
|
|
Big('7e+500').times(y) // '1.26e+501'</pre>
|
|
|
|
|
|
|
|
<h5 id="toE">
|
|
toExponential<code class='inset'>.toExponential( [dp] ) ⇒
|
|
<i>string</i></code>
|
|
</h5>
|
|
<p><code>dp</code> : <i>number</i> : integer, 0 to 1e+6 inclusive</p>
|
|
<p>
|
|
Returns a string representing the value of this Big number in exponential
|
|
notation to a fixed number of decimal places <code>dp</code>.
|
|
</p>
|
|
<p>
|
|
If the value of this Big number in exponential notation has more digits to
|
|
the right of the decimal point than is specified by <code>dp</code>, the
|
|
return value will be rounded to <code>dp</code> decimal places using
|
|
rounding mode <a href='#rm'><code>Big.RM</code></a>.
|
|
</p>
|
|
<p>
|
|
If the value of this Big number in exponential notation has fewer digits
|
|
to the right of the decimal point than is specified by <code>dp</code>,
|
|
the return value will be appended with zeros accordingly.
|
|
</p>
|
|
<p>
|
|
If <code>dp</code> is omitted or is undefined, the number of digits
|
|
after the decimal point defaults to the minimum number of digits
|
|
necessary to represent the value exactly.
|
|
</p>
|
|
<p>
|
|
Throws if <code>dp</code> is invalid.
|
|
</p>
|
|
<pre>
|
|
x = 45.6
|
|
y = new Big(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'
|
|
x.toExponential(3) // '4.560e+1'
|
|
y.toExponential(3) // '4.560e+1'</pre>
|
|
|
|
|
|
|
|
<h5 id="toF">
|
|
toFixed<code class='inset'>.toFixed( [dp] ) ⇒
|
|
<i>string</i></code>
|
|
</h5>
|
|
<p>
|
|
<code>dp</code> : <i>number</i> : integer, 0 to 1e+6 inclusive
|
|
</p>
|
|
<p>
|
|
Returns a string representing the value of this Big number in normal
|
|
notation to a fixed number of decimal places <code>dp</code>.
|
|
</p>
|
|
<p>
|
|
If the value of this Big number in normal notation has more digits to the
|
|
right of the decimal point than is specified by <code>dp</code>, the
|
|
return value will be rounded to <code>dp</code> decimal places using
|
|
rounding mode <a href='#rm'><code>Big.RM</code></a>.
|
|
</p>
|
|
<p>
|
|
If the value of this Big number in normal notation has fewer fraction
|
|
digits then is specified by <code>dp</code>, the return value will be
|
|
appended with zeros accordingly.
|
|
</p>
|
|
<p>
|
|
Unlike <code>Number.prototype.toFixed</code>, which returns
|
|
exponential notation if a number is greater or equal to 10<sup>21</sup>,
|
|
this method will always return normal notation.
|
|
</p>
|
|
<p>
|
|
If <code>dp</code> is omitted or is undefined, the return value is
|
|
simply the value in normal notation. This is also unlike
|
|
<code>Number.prototype.toFixed</code>, which returns the value to zero
|
|
decimal places.
|
|
</p>
|
|
<p>
|
|
Throws if <code>dp</code> is invalid.
|
|
</p>
|
|
<pre>
|
|
x = 45.6
|
|
y = new Big(x)
|
|
x.toFixed() // '46'
|
|
y.toFixed() // '45.6'
|
|
y.toFixed(0) // '46'
|
|
x.toFixed(3) // '45.600'
|
|
y.toFixed(3) // '45.600'</pre>
|
|
|
|
|
|
|
|
<h5 id="toP">
|
|
toPrecision<code class='inset'>.toPrecision( [sd] ) ⇒
|
|
<i>string</i></code>
|
|
</h5>
|
|
<p><code>sd</code> : <i>number</i> : integer, 1 to 1e+6 inclusive</p>
|
|
<p>
|
|
Returns a string representing the value of this Big number to the
|
|
specified number of significant digits <code>sd</code>.
|
|
</p>
|
|
<p>
|
|
If the value of this Big number has more digits than is specified by
|
|
<code>sd</code>, the return value will be rounded to <code>sd</code>
|
|
significant digits using rounding mode
|
|
<a href='#rm'><code>Big.RM</code></a>.
|
|
</p>
|
|
<p>
|
|
If the value of this Big number has fewer digits than is specified by
|
|
<code>sd</code>, the return value will be appended with zeros accordingly.
|
|
</p>
|
|
<p>
|
|
If <code>sd</code> is less than the number of digits necessary to
|
|
represent the integer part of the value in normal notation,
|
|
exponential notation is used.
|
|
</p>
|
|
<p>
|
|
If <code>sd</code> is omitted or is undefined, the return value is
|
|
the same as <code>.toString()</code>.
|
|
</p>
|
|
<p>
|
|
Throws if <code>sd</code> is invalid.
|
|
</p>
|
|
<pre>
|
|
x = 45.6
|
|
y = new Big(x)
|
|
x.toPrecision() // '45.6'
|
|
y.toPrecision() // '45.6'
|
|
x.toPrecision(1) // '5e+1'
|
|
y.toPrecision(1) // '5e+1'
|
|
x.toPrecision(5) // '45.600'
|
|
y.toPrecision(5) // '45.600'</pre>
|
|
|
|
|
|
|
|
<h5 id="toS">
|
|
toString<code class='inset'>.toString() ⇒ <i>string</i></code>
|
|
</h5>
|
|
<p>
|
|
Returns a string representing the value of this Big number.
|
|
</p>
|
|
<p>
|
|
If this Big number has a positive exponent that is equal to or greater
|
|
than 21, or a negative exponent equal to or less than -7, exponential
|
|
notation is returned.
|
|
</p>
|
|
<p>
|
|
The point at which <code>toString</code> returns exponential rather than
|
|
normal notation can be adjusted by changing the value of
|
|
<a href='#epos'><code>Big.PE</code></a> and
|
|
<a href='#eneg'><code>Big.NE</code></a>. By default, Big numbers
|
|
correspond to Javascript's number type in this regard.
|
|
</p>
|
|
<pre>
|
|
x = new Big('9.99e+20')
|
|
x.toString() // '999000000000000000000'
|
|
y = new Big('1E21')
|
|
y.toString() // '1e+21'
|
|
</pre>
|
|
|
|
|
|
|
|
<h5 id="valueOf">
|
|
valueOf<code class='inset'>.valueOf() ⇒ <i>string</i></code>
|
|
</h5>
|
|
<p>
|
|
As <code>toString</code>.
|
|
</p>
|
|
<pre>
|
|
x = new Big('177.7e+457')
|
|
x.valueOf() // '1.777e+459'</pre>
|
|
|
|
|
|
|
|
<h5 id="toJSON">
|
|
toJSON<code class='inset'>.toJSON() ⇒ <i>string</i></code>
|
|
</h5>
|
|
<p>
|
|
As <code>toString</code>.
|
|
</p>
|
|
<pre>
|
|
x = new Big('177.7e+457')
|
|
y = new Big(235.4325)
|
|
z = new Big('0.0098074')
|
|
str = JSON.stringify( [x, y, z] )
|
|
|
|
JSON.parse( str, function ( k, v ) { return k === '' ? v : new Big(v) } )
|
|
// Returns an array of three Big numbers.</pre>
|
|
|
|
|
|
|
|
<h4 id="instance-properties">Properties</h4>
|
|
<p>
|
|
A Big number 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>[]</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, -1e+6 to 1e+6 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 a Big number is stored in a normalised decimal floating point
|
|
format which corresponds to the value's <code>toExponential</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 Big(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 Big('-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 Big number 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 Big('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>
|
|
<p>
|
|
Minus zero is a valid Big number value, but like Javascript numbers the
|
|
minus sign is not shown.
|
|
</p>
|
|
<pre>
|
|
x = new Number(-0) // 0
|
|
1 / x == -Infinity // true
|
|
|
|
y = new Big(-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 instances of <code>Error</code>.<br />
|
|
The <code>message</code> of the errors always begins with
|
|
<code class='error'>[BigError]</code>.
|
|
</p>
|
|
<table>
|
|
<tr>
|
|
<th>Method(s)</th>
|
|
<th>Error message</th>
|
|
<th>Thrown on</th>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>
|
|
Big<br />cmp<br />div<br />eq gt gte lt lte<br />minus<br />mod
|
|
<br />plus<br />times
|
|
</code>
|
|
</td>
|
|
<td><code>NaN</code></td>
|
|
<td>Invalid number</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan=4><code>div</code></td>
|
|
<td><code>±Infinity</code></td>
|
|
<td>Division by zero</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>NaN</code></td>
|
|
<td>Division of zero by zero</td>
|
|
</tr>
|
|
<tr>
|
|
<td>DP: <i>invalidValue</i></td>
|
|
<td>Invalid Big.DP</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RM: <i>invalidValue</i></td>
|
|
<td>Invalid Big.RM</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>mod</code></td>
|
|
<td><code>NaN</code></td>
|
|
<td>Modulo zero</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan=3><code>pow</code></td>
|
|
<td><i>invalidValue</i></td>
|
|
<td>Invalid exponent</td>
|
|
</tr>
|
|
<tr>
|
|
<td>DP: <i>invalidValue</i></td>
|
|
<td>Invalid Big.DP</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RM: <i>invalidValue</i></td>
|
|
<td>Invalid Big.RM</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan=2><code>round</code></td>
|
|
<td><i>invalidValue</i></td>
|
|
<td>Invalid dp</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RM: <i>invalidValue</i></td>
|
|
<td>Invalid rm/Big.RM</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan=3><code>sqrt</code></td>
|
|
<td><code>NaN</code></td>
|
|
<td>Negative number</td>
|
|
</tr>
|
|
<tr>
|
|
<td>DP: <i>invalidValue</i></td>
|
|
<td>Invalid Big.DP</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RM: <i>invalidValue</i></td>
|
|
<td>Invalid Big.RM</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan=2><code>toExponential</code></td>
|
|
<td><i>invalidValue</i></td>
|
|
<td>Invalid dp</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RM: <i>invalidValue</i></td>
|
|
<td>Invalid Big.RM</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan=2><code>toFixed</code></td>
|
|
<td><i>invalidValue</i></td>
|
|
<td>Invalid dp</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RM: <i>invalidValue</i></td>
|
|
<td>Invalid Big.RM</td>
|
|
</tr>
|
|
<tr>
|
|
<td rowspan=2><code>toPrecision</code></td>
|
|
<td><i>invalidValue</i></td>
|
|
<td>Invalid sd</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RM: <i>invalidValue</i></td>
|
|
<td>Invalid Big.RM</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
|
|
<h4 id='faq'>FAQ</h4>
|
|
<h6>How can I convert a Big number to a primitive JavaScript number?</h6>
|
|
<p>
|
|
To convert a Big number to a primitive number, <code>parseFloat</code> or
|
|
any of the other methods for converting a string to a number can be used.
|
|
</p>
|
|
<pre>
|
|
x = new Big('12345.6789')
|
|
parseFloat(x) // 12345.6789
|
|
Number(x) // 12345.6789
|
|
+x // 12345.6789
|
|
x * 1 // 12345.6789
|
|
x / 1 // 12345.6789
|
|
x - 0 // 12345.6789
|
|
x + 0 // '12345.67890' (string concatenation, do not use!)
|
|
</pre>
|
|
<p>
|
|
If converting to an integer be aware that <code>parseInt</code> doees not
|
|
handle exponential notation.
|
|
<p>
|
|
<pre>
|
|
x = new Big('9.87654e+32')
|
|
parseInt(x) // 9
|
|
parseInt(+x) // 9
|
|
parseInt(x.toFixed()) // 9.87654e+32
|
|
parseInt(x.round()) // 9.87654e+32
|
|
</pre>
|
|
<p>
|
|
The <code>Math</code> methods can also be used.
|
|
<p>
|
|
<pre>
|
|
x = new Big('1234.56')
|
|
Math.floor(x) // 1234
|
|
Math.round(x) // 1235
|
|
</pre>
|
|
<br />
|
|
|
|
<h6>
|
|
How can I round a Big number to a specified number of significant digits?
|
|
</h6>
|
|
<p>
|
|
<a href='#toP'><code>toPrecision</code></a> returns a string representing
|
|
the value of a Big number rounded to a specified number of significant
|
|
digits. Or, the number of significant digits of a Big number can be set by
|
|
truncating the array that stores its coefficient. For example, using the
|
|
array's length property:
|
|
</p>
|
|
<pre>
|
|
x = new Big('987.654321')
|
|
len = x.c.length // 9
|
|
if (len > 6) x.c.length = 6
|
|
x // 987.654
|
|
</pre>
|
|
<br />
|
|
|
|
<h6>
|
|
How can I set the decimal places and/or rounding mode for just one
|
|
operation?
|
|
</h6>
|
|
<p>
|
|
This library uses a global configuration for the decimal places and
|
|
rounding mode used by division operations, so it is just a matter of
|
|
altering this as required.
|
|
</p>
|
|
<pre>
|
|
Big.DP = 10
|
|
y = x.sqrt()
|
|
Big.DP = 0
|
|
Big.RM = 1
|
|
z = x.div(3)
|
|
</pre>
|
|
<p>
|
|
There is also the ability to create separate Big number constructors each
|
|
with their own particular <code>DP</code> and <code>RM</code> settings.
|
|
See below.
|
|
</p>
|
|
<p>
|
|
Finally, there is the option of redefining the relevant prototype method
|
|
as required. For example, the following would enable a decimal
|
|
places and rounding mode to be passed to the <code>div</code> method.
|
|
</p>
|
|
<pre>
|
|
Big.prototype.div = (function () {
|
|
var div = Big.prototype.div;
|
|
return function (n, dp, rm) {
|
|
var result,
|
|
Big = this.constructor,
|
|
_dp = Big.DP,
|
|
_rm = Big.RM;
|
|
if (dp != undefined) Big.DP = dp;
|
|
if (rm != undefined) Big.RM = rm;
|
|
result = div.call(this, n);
|
|
Big.DP = _dp;
|
|
Big.RM = _rm;
|
|
return result;
|
|
}
|
|
})();
|
|
|
|
var dp = 10;
|
|
var round_up = 2;
|
|
x = x.div(y, dp, round_up);
|
|
</pre>
|
|
<br />
|
|
|
|
<h6>
|
|
How can I simultaneously use different decimal places and/or rounding mode
|
|
settings for different Big numbers?
|
|
</h6>
|
|
<p>
|
|
From <i>v3.0.0</i>, it is possible to have multiple Big number
|
|
constructors each with their own particular <code>DP</code> and
|
|
<code>RM</code> settings which apply to all Big numbers created from it.
|
|
</p>
|
|
<pre>
|
|
/*
|
|
Create an additional Big number constructor by calling the original Big
|
|
number constructor without using new and without any argument.
|
|
*/
|
|
Big10 = Big();
|
|
|
|
// Set the decimal places of division operations for each constructor.
|
|
Big.DP = 3;
|
|
Big10.DP = 10;
|
|
|
|
x = Big(5);
|
|
y = Big10(5);
|
|
|
|
x.div(3) // 1.667
|
|
y.div(3) // 1.6666666667
|
|
</pre>
|
|
<p>
|
|
Big numbers created by different constructors can be used together in
|
|
operations, and it is the <code>DP</code> and <code>RM</code> setting of
|
|
the Big number that an operation is called upon that will apply.
|
|
</p>
|
|
<p>
|
|
In the interest of memory efficiency, all Big number constructors share
|
|
the same <code>prototype</code> object, so while the <code>DP</code> and
|
|
<code>RM</code> (and any other <i>own</i> properties) of a constructor are
|
|
isolated and untouchable by another, its prototype methods are not.
|
|
</p>
|
|
<br />
|
|
|
|
<h6>Why are trailing fractional zeros removed from Big numbers?</h6>
|
|
<p>
|
|
Many 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 imply that the value lies
|
|
within a certain range.
|
|
</p>
|
|
<p>
|
|
In the first example, <code>x</code> has a value of 1.0. The trailing zero
|
|
shows the precision of the value, implying that the value is in the range
|
|
0.95 to 1.05. Similarly, the precision indicated by the trailing zeros of
|
|
<code>y</code> indicates that the value is in the range 1.09995 to
|
|
1.10005. If we add the two lowest values in the ranges we get 0.95 +
|
|
1.09995 = 2.04995 and if we add the two highest values we get 1.05 +
|
|
1.10005 = 2.15005, so the range of the result of the addition implied by
|
|
the precision of its operands is 2.04995 to 2.15005. The result given by
|
|
BigDecimal of 2.1000 however, indicates that the value is in the range
|
|
2.09995 to 2.10005 and therefore the precision implied by its trailing
|
|
zeros is misleading.
|
|
</p>
|
|
<p>
|
|
In the second example, the true range is 4.122744 to 4.157256 yet the
|
|
BigDecimal answer of 4.1400000 indicates a range of 4.13999995 to
|
|
4.14000005. Again, the precision implied by the trailing zeros is
|
|
misleading.
|
|
</p>
|
|
<p>
|
|
This library, like binary floating-point and most calculators, does not
|
|
retain trailing fractional zeros.<br />
|
|
Instead, the <code>toExponential</code>, <code>toFixed</code> and
|
|
<code>toPrecision</code> methods enable trailing zeros to be added if and
|
|
when required.
|
|
</p>
|
|
<br />
|
|
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|