big.js

If you are using TypeScript, you can install type definitions from the DefinitelyTyped project:

$ npm install --save-dev @types/big.js

The bigtime.js application is a Node.js command-line tool used to test big.js against the GWT version of BigDecimal from the npm registry.

To run a benchmark, use the following syntax: node bigtime <method> <iterations> <digits>

This will execute the specified number of calls to the given method using operands with up to the specified number of random digits, and verify that the results match.

You can install big.js for various environments:

Node.js

Install via npm:

$ npm install big.js

Use with CommonJS:

const Big = require('big.js');

Use with ES modules:

import Big from 'big.js';

Deno

Import directly from a URL:

import Big from 'https://raw.githubusercontent.com/mikemcl/big.js/v7.0.1/big.mjs';
// or
import Big from 'https://unpkg.com/big.js@latest/big.mjs';

Browsers

Add to global scope via script tag:

<script src='path/to/big.js'></script>

Use as an ES module:

<script type='module'>
import Big from './path/to/big.mjs';
</script>

Use a minified version from a CDN:

<script src='https://cdn.jsdelivr.net/npm/big.js@7.0.1/big.min.js'></script>

Big numbers are immutable; methods return a new Big number rather than modifying the original. Methods can be chained for complex calculations.

Note: Arithmetic methods return exact results except for div, sqrt, and pow (with negative exponent), which involve division. The precision and rounding for these methods are controlled by the Big.DP (decimal places) and Big.RM (rounding mode) properties of the constructor.

x = new Big(0.3)
x.minus(0.1) // "0.2"

// Chaining
x.div(y).plus(z).times(9)

// Configuring precision
Big.DP = 10
Big.RM = Big.roundHalfUp
x.div(y) // result rounded to 10 decimal places

x.div(y).plus(z).times(9).minus('1.234567801234567e+8').plus(976.54321).div('2598.11772')

To view the help documentation for the bigtime.js command-line application, run the command with the -h flag.

$ node bigtime -h

When Big.strict is set to true, creating a Big number from a primitive number is disallowed to prevent precision issues. This will throw a TypeError.

Big.strict = true
x = new Big(1) // TypeError: [big.js] Invalid number

A Big number's value is stored in a decimal floating point format consisting of a coefficient, exponent, and sign.

• x.c: coefficient (significand)
• x.e: exponent
• x.s: sign

x = new Big(-123.456)
x.c // [1,2,3,4,5,6]
x.e // 2
x.s // -1

x = new Big(-123.456);
x.c                                    // [1,2,3,4,5,6]    coefficient (i.e. significand)
x.e                                    // 2                exponent
x.s                                    // -1               sign

The library exports a single constructor function, Big. You can create a Big number from a primitive number, string, or another Big number. Note that the new keyword is optional.

x = new Big(123.4567)
y = Big('123456.7e-3')
z = new Big(x)

big.js replicates the standard JavaScript Number methods for formatting: toExponential, toFixed, and toPrecision.

x = new Big(255.5)
x.toExponential(5) // "2.55500e+2"
x.toFixed(5)       // "255.50000"
x.toPrecision(5)   // "255.50"

Use these methods to convert a Big instance into a string representation.

• toString() / toJSON(): Returns the value in normal or exponential notation based on Big.NE and Big.PE.
• toFixed(dp, rm?): Returns a string in normal notation with exactly dp decimal places. Uses Big.RM if rm is not provided.
• toExponential(dp, rm?): Returns a string in exponential notation with dp decimal places.
• toPrecision(sd, rm?): Returns a string rounded to sd significant digits.
• valueOf(): Returns a string representation (Note: if Big.strict is true, this throws an error).