Home

What is the difference between big.js, bignumber.js and decimal.js?

big.js is a minimalist arbitrary-precision library. It is the simplest and smallest of the three, less than half the size of bignumber.js and with only half the number of methods. It doesn't accept NaN or Infinity as legitimate values, it doesn't work with numbers of other bases, and the runtime configuration opions are limited to setting the number of decimal places and rounding mode of operations involving division. (As of v3.1.0, the exponent values at which toString produces exponential notation can also be set.)

Big.DP = 7;
Big.RM = 4;             // round half-up
var x = new Big(5);
x.div(3).toString();    // '1.6666667' 

All three ibraries include the toExponential, toFixed and toPrecision methods.

bignumber.js and decimal.js store values in a higher base than big.js so they will be faster when performing operations on values with a large number of digits. However, because big.js stores values in base 10, it is easy to change the properties of a Big number directly if required

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

bignumber.js and decimal.js can work with values in other bases, and support the prefixes such as '0x' for hexdecimal. decimal.js can also handle binary, octal and hexdecimal values in binary exponential notation, such as found in the C programming language.

var x = new BigNumber('ff.8', 16);
x.toString();          // '255.5'
x.toString(16);        // 'ff.8'

var x = new Decimal('0xff.8');
x.toString();          // '255.5'
x.toHexadecimal();     // '0xff.8'
x.toHex(3);            // '0x1.ffp+7'

Among the various runtime configuration options of bignumber.js and decimal.js is the ability to set the exponent value at which toString produces exponential notation.

var x = new Decimal(987654321);
x.toString();          // '987654321'
Decimal.config({ toExpPos: 4 });
x.toString();          // '9.87654321e+8'

decimal.js was orginally intended to be version two of bignumber.js but I decided to make them separate libraries. The main difference between them is that with decimal.js precision is specified in terms of significant digits instead of decimal places, and all calculations are rounded to the precision (similar to Python's decimal module) rather than just those involving division.

Bignumber.config({ DECIMAL_PLACES: 3, ROUNDING_MODE; 1 });
var x = new BigNumber('123.456789');
x.plus(1).toString();    // '124.456789'

Decimal.config({ precision: 7, rounding: 4 });
var y = new Decimal('123.456789');
y.plus(1).toString();    // '124.4568'

This could be considered to make bignumber.js easier to use than decimal.js, and perhaps more suitable for financial applications, because the user doesn't need to worry about losing precision unless an operation involving division is used.

Conversely, decimal.js may be considered better for more scientific applications as it can handle very small or large values more efficiently: for example, it does not have the limitation of bignumber.js that if adding a BigNumber value with a small exponent to one with a large exponent, bignumber.js will attempt to perform the operation to full precision which may make the operation unviable in terms of time taken.

decimal.js also supports non-integer powers and adds the trigonometric functions and exp, ln, and log methods. These additions make decimal.js significantly larger than bignumber.js.