Archives/MikeMcl_decimal.js
1
0
Fork 0
mirror of https://github.com/MikeMcl/decimal.js.git synced 2024-10-27 20:34:12 +00:00
Code Issues Projects Releases Wiki Activity

Minor doc clean-up. v1.0.1

Browse Source
This commit is contained in:
Michael Mclaughlin 2014-04-07 17:17:26 +01:00
parent b92f900a93
commit 714eb63369
5 changed files with 119 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
README.md
View File

@ -11,7 +11,7 @@ An arbitrary-precision Decimal type for JavaScript.
- Includes a `toFraction` and correctly-rounded `exp`, `ln`, `log` and `sqrt` functions
- Supports non-integer powers (although performance is limited)
- Works with numbers with or without fraction digits in bases from 2 to 64 inclusive
- Stores values in an accessible decimal floating point format
- Stores values in an accessible decimal floating-point format
- No dependencies
- Uses JavaScript 1.5 (ECMAScript 3) features only
- Comprehensive [documentation](http://mikemcl.github.io/decimal.js/) and test set
@ -40,13 +40,7 @@ It can be loaded via a script tag in an HTML document for the browser
or as a CommonJS, [Node.js](http://nodejs.org) or AMD module using `require`.
For Node, put the *decimal.js* file into the same directory as the file that is requiring it and use
var Decimal = require('./decimal');
or put it in a *node_modules* directory within the directory and use `require('decimal')`.
The library is also available from the [npm](https://npmjs.org/) registry
For Node, the library is also available from the [npm](https://npmjs.org/) registry
$ npm install decimal.js
@ -104,11 +98,24 @@ Like JavaScript's Number type, there are `toExponential`, `toFixed` and `toPreci
x.toString(16) // 'ff.8'
There is a `toFraction` method with an optional *maximum denominator* argument
y = new Decimal(355)
pi = y.dividedBy(113) // '3.1415929204'
pi.toFraction() // [ '7853982301', '2500000000' ]
pi.toFraction(1000) // [ '355', '113' ]
and `isNaN` and `isFinite` methods, as `NaN` and `Infinity` are valid `Decimal` values.
x = new Decimal(NaN) // 'NaN'
y = new Decimal(Infinity) // 'Infinity'
x.isNaN() && !y.isNaN() && !x.isFinite() && !y.isFinite() // true
As mentioned above, multiple Decimal constructors can be created, each with their own independent
configuration which applies to all Decimal numbers created from it.
All calculations are rounded to the number of significant digits specified by the `precision` property
of a Decimal constructor and rounded using the rounding mode specified by the `rounding` property.
of each Decimal constructor and rounded using the rounding mode specified by the `rounding` property.
Decimal.config({ precision: 5, rounding: 4 })
@ -124,24 +131,11 @@ of a Decimal constructor and rounded using the rounding mode specified by the `r
Decimal.precision // 5
D.precision // 10
Many of the methods of JavaScript's Math object are replicated as static methods of a Decimal constructor
Many of the methods of JavaScript's Math object are also replicated
Decimal.sqrt('6.98372465832e+9823') // '8.3568682281821340204e+4911'
Decimal.pow(2, 0.0979843) // '1.0702770511687781839'
There is a `toFraction` method with an optional *maximum denominator* argument
y = new Decimal(355)
pi = y.dividedBy(113) // '3.1415929204'
pi.toFraction() // [ '7853982301', '2500000000' ]
pi.toFraction(1000) // [ '355', '113' ]
and `isNaN` and `isFinite` methods, as `NaN` and `Infinity` are valid `Decimal` values.
x = new Decimal(NaN) // 'NaN'
y = new Decimal(Infinity) // 'Infinity'
x.isNaN() && !y.isNaN() && !x.isFinite() && !y.isFinite() // true
The value of a Decimal is stored in a decimal floating point format in terms of a coefficient, exponent and sign.
x = new Decimal(-123.456);
@ -184,15 +178,15 @@ then
will create *decimal.min.js*.
The *decimal.min.js* already present was created with *Microsoft Ajax Minifier 5.8*.
The *decimal.min.js* already present was created with *Microsoft Ajax Minifier 5.8* (in protest at
uglify-js failing to preserve licensing comments).
## Feedback
Open an issue, or email
Michael <a href='mailto:M8ch88l@gmail.com'>M8ch88l@gmail.com</a>
Many hours of work have gone into this library.
A [bitcoin](https://bitcoin.org/en/getting-started) donation would be gratefully received:
[Bitcoin](https://bitcoin.org/en/getting-started) donations gratefully received:
**1PjzRBjGJycti49AXTiKsdC4PRCnTbyUyf**
Thank you
@ -205,5 +199,8 @@ See LICENCE.
## Change Log
####1.0.1
* 07/04/2014 Minor documentation clean-up.
####1.0.0
* 02/04/2014 Initial release

4
decimal.js
View File

@ -1,10 +1,10 @@
/*! decimal.js v1.0.0 https://github.com/MikeMcl/decimal.js/LICENCE */
/*! decimal.js v1.0.1 https://github.com/MikeMcl/decimal.js/LICENCE */
;(function (global) {
'use strict';
/*
* decimal.js v1.0.0
* decimal.js v1.0.1
* An arbitrary-precision Decimal type for JavaScript.
* https://github.com/MikeMcl/decimal.js
* Copyright (c) 2014 Michael Mclaughlin <M8ch88l@gmail.com>

2
decimal.min.js vendored
View File

File diff suppressed because one or more lines are too long

98
doc/API.html
View File

@ -176,13 +176,13 @@ li span{float:right;margin-right:10px;color:#c0c0c0}
<h2>API</h2>
<p>
See the <a href='https://github.com/MikeMcl/decimal.js'>README</a> on GitHub for a quickstart
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>
</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.
@ -326,8 +326,9 @@ new Decimal(1.23456789).round() // '1.2346'</pre>
<p>Configures the 'global' settings for this particular Decimal constructor.</p>
<p>Returns this Decimal constructor.</p>
<p>
The configuration object can contain some or all of the properties described in detail at
<a href="#constructor-properties">Properties</a> and shown in the example below.
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
@ -350,6 +351,10 @@ Decimal.config({
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>
@ -493,7 +498,6 @@ x.equals(y) // true</pre>
<p>
<code>limit</code>: <i>number|string|Decimal</i><br /> Default value: <code>1</code><br />
<code>sd</code>: <i>number</i>: integer, 1 to 1e+9 inclusive<br />
Default value: <code>precision</code><br />
<i>See <code><a href="#decimal">Decimal</a></code> for further parameter details.</i>
</p>
<p>
@ -543,11 +547,8 @@ Decimal.random(10) // '6'
// An integer in the range (-100, 0]
Decimal.random(-100) // '-82'
// An integer in the range [0, 99.99)
Decimal.random('99.99') // '47'
// An integer in the range [0, 9e9999999999)
Decimal.random('9e99999999999') // The browser will hang
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'
@ -619,8 +620,8 @@ Decimal.precision = 0
<code>precision</code> significant digits except
<a href='#abs'><code>absoluteValue</code></a>, <a href='#ceil'><code>ceil</code></a>,
<a href='#floor'><code>floor</code></a>, <a href='#neg'><code>negated</code></a>,
<a href='#round'><code>round</code></a>, <a href='#toDP'><code>toDecimalPlaces</code></a>
and <a href='#toNear'><code>toNearest</code></a>.
<a href='#toDP'><code>toDecimalPlaces</code></a> and
<a href='#toNear'><code>toNearest</code></a>.
</p>
<p>
A Decimal constructor will also not round to <code>precision</code> unless a base is
@ -643,7 +644,10 @@ Decimal.precision // 5</pre>
<a href='#toE'><code>toExponential</code></a>, <a href='#toFi'><code>toFixed</code></a>,
<a href='#toFo'><code>toFormat</code></a>, and <a href='#toP'><code>toPrecision</code></a>.
</p>
<p>The modes are available as enumerated properties of the constructor.</p>
<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>
@ -670,7 +674,7 @@ new Decimal('1e-500') // '1e-500'
new Decimal('9.9e-501') // '0'
Decimal.config({ minE: -3 })
new Decimal(0.001) // '0.01' e is only -3
new Decimal(0.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>
@ -699,7 +703,7 @@ new Decimal('9.999e500') // '9.999e+500'
new Decimal('1e501') // 'Infinity'
Decimal.config({ maxE: 4 })
new Decimal(99999) // '99999' e is only 4
new Decimal(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>
@ -718,7 +722,7 @@ new Decimal(100000) // 'Infinity'</pre>
</p>
<pre>Decimal.config({ toExpNeg: -7 })
Decimal.toExpNeg // -7
new Decimal(0.00000123) // '0.00000123' e is only -6
new Decimal(0.00000123) // '0.00000123' e is -6
new Decimal(0.000000123) // '1.23e-7'
// Always return exponential notation:
@ -751,7 +755,7 @@ Decimal.config({ toExpNeg: 0 })</pre>
</p>
<pre>Decimal.config({ toExpPos: 2 })
Decimal.toExpPos // 2
new Decimal(12.3) // '12.3' e is only 1
new Decimal(12.3) // '12.3' e is 1
new Decimal(123) // '1.23e+2'
// Always return exponential notation:
@ -838,7 +842,7 @@ Decimal.errors // false</pre>
</tr>
</table>
<p>
The <code>rounding/modulo</code> modes are available as enumerated properties of the Decimal
The rounding/modulo modes are available as enumerated properties of the Decimal
constructor.
</p>
<pre>Decimal.config({ modulo: Decimal.EUCLID })
@ -867,10 +871,12 @@ Decimal.modulo // 9</pre>
</p>
<pre>
Decimal.crypto // false
Decimal.config({ crypto: true })
// If crypto.getRandomValues and crypto.randomBytes are undefined
Decimal.crypto // false</pre>
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>
@ -981,19 +987,19 @@ y.ceil() // '-1'</pre>
<table>
<tr><th>Returns</th><th>&nbsp;</th></tr>
<tr>
<td class='centre'>1</td>
<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'>-1</td>
<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'>0</td>
<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'>null</td>
<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>
@ -1202,7 +1208,7 @@ y.isInt() // false</pre>
<h5 id="isNaN">isNaN<code class='inset'>.isNaN() <i>&rArr; boolean</i></code></h5>
<p>
Returns <code>true</code> if the value of this Decimal is NaN, otherwise returns
Returns <code>true</code> if the value of this Decimal is <code>NaN</code>, otherwise returns
<code>false</code>.
</p>
<pre>
@ -1386,16 +1392,16 @@ y.ln() // '69.28'</pre>
natural logarithm function is non-terminating, unless its argument is <code>1</code>).
</p>
<p>
Internally, this method is dependent on a constant with value the natural logarithm of
10. This <code>LN10</code> variable in the source code currently has a precision of
<code>1025</code> digits, meaning that this method can accurately calculate up to
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 1000 digits anyway.
viable to calculate over <code>1000</code> digits anyway.
</p>
@ -1498,8 +1504,8 @@ x // '9876.54321'</pre>
to an infinite number of correct digits before rounding.
</p>
<p>
The square root is method is much faster than using the
<a href='#pow'><code>toPower</code></a> method with an exponent of <code>0.5</code>.
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)
@ -1623,11 +1629,12 @@ y.toExponential(3) // '4.560e+1'</pre>
</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.
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 is
unrounded and in normal notation. This is unlike <code>Number.prototype.toFixed</code>,
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>
@ -1794,15 +1801,18 @@ JSON.parse(str, function (key, val) {
<i>See <code><a href="#decimal">Decimal</a></code> for further parameter details.</i>
</p>
<p>
Returns a new Decimal whose value is the nearest multiple of the magnitude of <code>n</code>
to the value of this Decimal.
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.
In this context, rounding mode 4 (<a href='#rounding'><code>ROUND_HALF_UP</code></a>) is the
same as rounding mode 0 (<a href='#rounding'><code>ROUND_UP</code></a>), and so on.
</p>
<p>
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. 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
@ -1883,8 +1893,8 @@ new Decimal(1217652.23).pow('98765.489305603941')
<p>
The return value may, depending on the rounding mode, be incorrectly rounded only if the first
<code>15</code> rounding digits are <code>15</code> zeros (and there are non-zero digits
following at some point) or <code>15</code> nines (the first rounding digit may also be 5 or
4 respectively).
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
@ -1953,12 +1963,12 @@ y.toPrecision(5) // '45.600'</pre>
<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.
<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.toString</code>), 36 to 61 by <code>A-Z</code>, and 62 and 63 by <code>$</code>
and <code>_</code> respectively.
<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>

2
package.json
View File

@ -1,7 +1,7 @@
{
"name": "decimal.js",
"description": "An arbitrary-precision Decimal type for JavaScript.",
"version": "1.0.0",
"version": "1.0.1",
"keywords": [
"arbitrary",
"precision",