File size: 8,329 Bytes
369fac9 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 |
An arbitrary-precision Decimal type for JavaScript.
[](https://www.npmjs.com/package/decimal.js)
[](https://www.npmjs.com/package/decimal.js)
[](https://travis-ci.org/MikeMcl/decimal.js)
[](https://cdnjs.com/libraries/decimal.js)
<br>
## Features
- Integers and floats
- Simple but full-featured API
- Replicates many of the methods of JavaScript's `Number.prototype` and `Math` objects
- Also handles hexadecimal, binary and octal values
- Faster, smaller, and perhaps easier to use than JavaScript versions of Java's BigDecimal
- No dependencies
- Wide platform compatibility: uses JavaScript 1.5 (ECMAScript 3) features only
- Comprehensive [documentation](https://mikemcl.github.io/decimal.js/) and test set
- Used under the hood by [math.js](https://github.com/josdejong/mathjs)
- Includes a TypeScript declaration file: *decimal.d.ts*
The library is similar to [bignumber.js](https://github.com/MikeMcl/bignumber.js/), but here
precision is specified in terms of significant digits rather than decimal places, and all
calculations are rounded to the precision (similar to Python's decimal module) rather than just
those involving division.
This library also adds the trigonometric functions, among others, and supports non-integer powers,
which makes it a significantly larger library than *bignumber.js* and the even smaller
[big.js](https://github.com/MikeMcl/big.js/).
For a lighter version of this library without the trigonometric functions see
[decimal.js-light](https://github.com/MikeMcl/decimal.js-light/).
## Load
The library is the single JavaScript file *decimal.js* or ES module *decimal.mjs*.
Browser:
```html
<script src='path/to/decimal.js'></script>
<script type="module">
import Decimal from './path/to/decimal.mjs';
...
</script>
```
[Node.js](https://nodejs.org):
```bash
npm install decimal.js
```
```js
const Decimal = require('decimal.js');
import Decimal from 'decimal.js';
import {Decimal} from 'decimal.js';
```
## Use
*In all examples below, semicolons and `toString` calls are not shown.
If a commented-out value is in quotes it means `toString` has been called on the preceding expression.*
The library exports a single constructor function, `Decimal`, which expects a single argument that is a number, string or Decimal instance.
```js
x = new Decimal(123.4567)
y = new Decimal('123456.7e-3')
z = new Decimal(x)
x.equals(y) && y.equals(z) && x.equals(z) // true
```
If using values with more than a few digits, it is recommended to pass strings rather than numbers to avoid a potential loss of precision.
```js
// Precision loss from using numeric literals with more than 15 significant digits.
new Decimal(1.0000000000000001) // '1'
new Decimal(88259496234518.57) // '88259496234518.56'
new Decimal(99999999999999999999) // '100000000000000000000'
// Precision loss from using numeric literals outside the range of Number values.
new Decimal(2e+308) // 'Infinity'
new Decimal(1e-324) // '0'
// Precision loss from the unexpected result of arithmetic with Number values.
new Decimal(0.7 + 0.1) // '0.7999999999999999'
```
As with JavaScript numbers, strings can contain underscores as separators to improve readability.
```js
x = new Decimal('2_147_483_647')
```
String values in binary, hexadecimal or octal notation are also accepted if the appropriate prefix is included.
```js
x = new Decimal('0xff.f') // '255.9375'
y = new Decimal('0b10101100') // '172'
z = x.plus(y) // '427.9375'
z.toBinary() // '0b110101011.1111'
z.toBinary(13) // '0b1.101010111111p+8'
// Using binary exponential notation to create a Decimal with the value of `Number.MAX_VALUE`.
x = new Decimal('0b1.1111111111111111111111111111111111111111111111111111p+1023')
// '1.7976931348623157081e+308'
```
Decimal instances are immutable in the sense that they are not changed by their methods.
```js
0.3 - 0.1 // 0.19999999999999998
x = new Decimal(0.3)
x.minus(0.1) // '0.2'
x // '0.3'
```
The methods that return a Decimal can be chained.
```js
x.dividedBy(y).plus(z).times(9).floor()
x.times('1.23456780123456789e+9').plus(9876.5432321).dividedBy('4444562598.111772').ceil()
```
Many method names have a shorter alias.
```js
x.squareRoot().dividedBy(y).toPower(3).equals(x.sqrt().div(y).pow(3)) // true
x.comparedTo(y.modulo(z).negated() === x.cmp(y.mod(z).neg()) // true
```
Most of the methods of JavaScript's `Number.prototype` and `Math` objects are replicated.
```js
x = new Decimal(255.5)
x.toExponential(5) // '2.55500e+2'
x.toFixed(5) // '255.50000'
x.toPrecision(5) // '255.50'
Decimal.sqrt('6.98372465832e+9823') // '8.3568682281821340204e+4911'
Decimal.pow(2, 0.0979843) // '1.0702770511687781839'
// Using `toFixed()` to avoid exponential notation:
x = new Decimal('0.0000001')
x.toString() // '1e-7'
x.toFixed() // '0.0000001'
```
And there are `isNaN` and `isFinite` methods, as `NaN` and `Infinity` are valid `Decimal` values.
```js
x = new Decimal(NaN) // 'NaN'
y = new Decimal(Infinity) // 'Infinity'
x.isNaN() && !y.isNaN() && !x.isFinite() && !y.isFinite() // true
```
There is also a `toFraction` method with an optional *maximum denominator* argument.
```js
z = new Decimal(355)
pi = z.dividedBy(113) // '3.1415929204'
pi.toFraction() // [ '7853982301', '2500000000' ]
pi.toFraction(1000) // [ '355', '113' ]
```
All calculations are rounded according to the number of significant digits and rounding mode specified
by the `precision` and `rounding` properties of the Decimal constructor.
For advanced usage, multiple Decimal constructors can be created, each with their own independent
configuration which applies to all Decimal numbers created from it.
```js
// Set the precision and rounding of the default Decimal constructor
Decimal.set({ precision: 5, rounding: 4 })
// Create another Decimal constructor, optionally passing in a configuration object
Dec = Decimal.clone({ precision: 9, rounding: 1 })
x = new Decimal(5)
y = new Dec(5)
x.div(3) // '1.6667'
y.div(3) // '1.66666666'
```
The value of a Decimal is stored in a floating point format in terms of its digits, exponent and sign, but these properties should be considered read-only.
```js
x = new Decimal(-12345.67);
x.d // [ 12345, 6700000 ] digits (base 10000000)
x.e // 4 exponent (base 10)
x.s // -1 sign
```
For further information see the [API](http://mikemcl.github.io/decimal.js/) reference in the *doc* directory.
## Test
To run the tests using Node.js from the root directory:
```bash
npm test
```
Each separate test module can also be executed individually, for example:
```bash
node test/modules/toFraction
```
To run the tests in a browser, open *test/test.html*.
## Minify
Two minification examples:
Using [uglify-js](https://github.com/mishoo/UglifyJS) to minify the *decimal.js* file:
```bash
npm install uglify-js -g
uglifyjs decimal.js --source-map url=decimal.min.js.map -c -m -o decimal.min.js
```
Using [terser](https://github.com/terser/terser) to minify the ES module version, *decimal.mjs*:
```bash
npm install terser -g
terser decimal.mjs --source-map url=decimal.min.mjs.map -c -m --toplevel -o decimal.min.mjs
```
```js
import Decimal from './decimal.min.mjs';
```
## Licence
[The MIT Licence (Expat).](LICENCE.md)
|