bignumber.js API

# bignumber.js

A Javascript library for arbitrary-precision arithmetic.

Hosted on GitHub.

## API

In all examples below, `var` and semicolons are not shown, and if a commented-out value is in quotes it means `toString` has been called on the preceding expression.

### CONSTRUCTOR

##### BigNumber`BigNumber(value [, base]) ⇒ BigNumber`

`value`
  number|string|BigNumber : See RANGE for range.
  A numeric value.
  Legitimate values include `±0`, `±Infinity` and `NaN`.
  Values of type number with more than 15 significant digits are considered invalid as calling `toString` or `valueOf` on such numbers may not result in the intended value.
  There is no limit to the number of digits of a value of type string (other than that of Javascript's maximum array size).
  Decimal string values may be in exponential, as well as normal (non-exponential) notation. Non-decimal values must be in normal notation.
  String values in hexadecimal literal form, e.g. '0xff', are invalid, and string values in octal literal form will be interpreted as decimals, e.g. '011' is 11, not 9.
  Values in any base may have fraction digits.
  In bases above 10, numerals above 9 are represented by lower-case letters.

`base`
  number : integer, `2` to `36` inclusive
  The base of `value`.
  If `base` is omitted, or is `null` or undefined, base 10 is assumed.

Returns a new instance of a BigNumber object.

If a base is specified, the value is rounded according to the current `DECIMAL_PLACES` and `ROUNDING_MODE` settings. Usefully, this means the decimal places of a decimal value passed to the constructor can be limited by explicitly specifying base 10.

See Errors for the treatment of an invalid `value` or `base`.

    x = new BigNumber(9)                       // '9'
    y = new BigNumber(x)                       // '9'
    BigNumber(435.345)                         // 'new' is optional
    new BigNumber('5032485723458348569331745.33434346346912144534543')
    new BigNumber('4.321e+4')                  // '43210'
    new BigNumber('-735.0918e-430')            // '-7.350918e-428'
    new BigNumber(Infinity)                    // 'Infinity'
    new BigNumber(NaN)                         // 'NaN'
    new BigNumber('.5')                        // '0.5'
    new BigNumber('+2')                        // '2'
    new BigNumber(-10110100.1, 2)              // '-180.5'
    new BigNumber('123412421.234324', 5)       // '607236.557696'
    new BigNumber('ff.8', 16)                  // '255.5'

    new BigNumber(9, 2)
    // Throws 'not a base 2 number' if ERRORS is true, otherwise 'NaN'

    new BigNumber(96517860459076817.4395)
    // Throws 'number type has more than 15 significant digits'
    // if ERRORS is true, otherwise '96517860459076820'

    new BigNumber('blurgh')
    // Throws 'not a number' if ERRORS is true, otherwise 'NaN'

    BigNumber.config({DECIMAL_PLACES : 5})
    new BigNumber(1.23456789)                  // '1.23456789'
    new BigNumber(1.23456789, 10)              // '1.23457'

#### Methods

The `BigNumber` constructor has one added method, `config`, which configures the library-wide settings for arithmetic, formatting and errors.

##### config`config([settings]) ⇒ object`

Note: the settings can also be supplied as an argument list, see below.

`settings`
  object
  An object that contains some or all of the following properties:
  `DECIMAL_PLACES`
    number : integer, `0` to `1e+9` inclusive
    Default value: `20`
    The maximum number of decimal places of the results of division, square root and base conversion operations, and power operations with negative exponents.
    I.e. aside from the base conversion which may be involved with any method that accepts a base argument, the value is only relevant to the `dividedBy`, `squareRoot` and `toPower` methods.

        BigNumber.config({ DECIMAL_PLACES : 5 })
        BigNumber.config(5)    // equivalent

  `ROUNDING_MODE`
    number : integer, `0` to `8` inclusive
    Default value: `4` (`ROUND_HALF_UP`)
    The rounding mode used in the above operations and by `round`, `toExponential`, `toFixed` and `toPrecision`.
    The modes are available as enumerated properties of the BigNumber constructor.

        BigNumber.config({ ROUNDING_MODE : 0 })
        BigNumber.config(null, BigNumber.ROUND_UP)    // equivalent

  `EXPONENTIAL_AT`
    number : integer, magnitude `0` to `1e+9` inclusive, or
    number[] : [ integer -1e+9 to 0 inclusive, integer 0 to 1e+9 inclusive ]
    Default value: `[-7, 20]`
    The exponent value(s) at which `toString` returns exponential notation.
    If a single number is assigned, the value is the exponent magnitude.
    If an array of two numbers is assigned then the first number is the negative exponent value at and beneath which exponential notation is used, and the second number is the positive exponent value at and above which the same.
    For example, to emulate Javascript numbers in terms of the exponent values at which they begin to use exponential notation, use `[-7, 20]`.

        BigNumber.config({ EXPONENTIAL_AT : 2 })
        new BigNumber(12.3)         // '12.3'        e is only 1
        new BigNumber(123)          // '1.23e+2'
        new BigNumber(0.123)        // '0.123'       e is only -1
        new BigNumber(0.0123)       // '1.23e-2'

        BigNumber.config({ EXPONENTIAL_AT : [-7, 20] })
        new BigNumber(123456789)    // '123456789'   e is only 8
        new BigNumber(0.000000123)  // '1.23e-7'

        // Almost never return exponential notation:
        BigNumber.config({ EXPONENTIAL_AT : 1e+9 })

        // Always return exponential notation:
        BigNumber.config({ EXPONENTIAL_AT : 0 })

    Regardless of the value of `EXPONENTIAL_AT`, the `toFixed` method will always return a value in normal notation and the `toExponential` method will always return a value in exponential form.
    Calling `toString` with a base argument, e.g. `toString(10)`, will also always return normal notation.
  `RANGE`
    number : integer, magnitude `1` to `1e+9` inclusive, or
    number[] : [ integer -1e+9 to -1 inclusive, integer 1 to 1e+9 inclusive ]
    Default value: `[-1e+9, 1e+9]`
    The exponent value(s) beyond which overflow to Infinity and underflow to zero occurs.
    If a single number is assigned, it is the maximum exponent magnitude: values wth a positive exponent of greater magnitude become Infinity and those with a negative exponent of greater magnitude become zero.
    If an array of two numbers is assigned then the first number is the negative exponent limit and the second number is the positive exponent limit.
    For example, to emulate Javascript numbers in terms of the exponent values at which they become zero and Infinity, use `[-324, 308]`.

        BigNumber.config({ RANGE : 500 })
        BigNumber.config().RANGE     // [ -500, 500 ]
        new BigNumber('9.999e499')   // '9.999e+499'
        new BigNumber('1e500')       // 'Infinity'
        new BigNumber('1e-499')      // '1e-499'
        new BigNumber('1e-500')      // '0'

        BigNumber.config({ RANGE : [-3, 4] })
        new BigNumber(99999)         // '99999'      e is only 4
        new BigNumber(100000)        // 'Infinity'   e is 5
        new BigNumber(0.001)         // '0.01'       e is only -3
        new BigNumber(0.0001)        // '0'          e is -4

    The largest possible magnitude of a finite BigNumber is
    9.999...e+1000000000
    The smallest possible magnitude of a non-zero BigNumber is
    1e-1000000000
  `ERRORS`
    boolean/number : `true, false, 1 or 0`
    Default value: `true`
    The value that determines whether BigNumber Errors are thrown.
    If `ERRORS` is false, this library will not throw errors.
    See Errors.

        BigNumber.config({ ERRORS : false })

Returns an object with the above properties and their current values.

If the value to be assigned to any of the above properties is `null` or undefined it is ignored. See Errors for the treatment of invalid values.

    BigNumber.config({
        DECIMAL_PLACES : 40,
        ROUNDING_MODE : BigNumber.ROUND_HALF_CEIL,
        EXPONENTIAL_AT : [-10, 20],
        RANGE : [-500, 500],
        ERRORS : true
    });

    // Alternatively but equivalently:
    BigNumber.config( 40, 7, [-10, 20], 500, 1 )

    obj = BigNumber.config();
    obj.ERRORS       // true
    obj.RANGE        // [-500, 500]

#### Properties

The library's enumerated rounding modes are stored as properties of the constructor.
They are not referenced internally by the library itself.

Rounding modes 0 to 6 (inclusive) are the same as those of Java's BigDecimal class.

Property | Value | Description
--- | --- | ---
ROUND_UP | 0 | Rounds away from zero
ROUND_DOWN | 1 | Rounds towards zero
ROUND_CEIL | 2 | Rounds towards Infinity
ROUND_FLOOR | 3 | Rounds towards -Infinity
ROUND_HALF_UP | 4 | Rounds towards nearest neighbour. If equidistant, rounds away from zero
ROUND_HALF_DOWN | 5 | Rounds towards nearest neighbour. If equidistant, rounds towards zero
ROUND_HALF_EVEN | 6 | Rounds towards nearest neighbour. If equidistant, rounds towards even neighbour
ROUND_HALF_CEIL | 7 | Rounds towards nearest neighbour. If equidistant, rounds towards Infinity
ROUND_HALF_FLOOR | 8 | Rounds towards nearest neighbour. If equidistant, rounds towards -Infinity

    BigNumber.config({ ROUNDING_MODE : BigNumber.ROUND_CEIL })
    BigNumber.config({ ROUNDING_MODE : 2 })     // equivalent

### INSTANCE

#### Methods

The methods inherited by a BigNumber instance from its constructor's prototype object.

A BigNumber is immutable in the sense that it is not changed by its methods.

The treatment of ±`0`, ±`Infinity` and `NaN` is consistent with how Javascript treats these values.

Method names over 5 letters in length have a shorter alias (except `valueOf`).
Internally, the library always uses the shorter method names.

##### absoluteValue`.abs() ⇒ BigNumber`

Returns a BigNumber whose value is the absolute value, i.e. the magnitude, of this BigNumber.

    x = new BigNumber(-0.8)
    y = x.absoluteValue()         // '0.8'
    z = y.abs()                   // '0.8'

##### ceil`.ceil() ⇒ BigNumber`

Returns a BigNumber whose value is the value of this BigNumber rounded to a whole number in the direction of Infinity.

    x = new BigNumber(1.3)
    x.ceil()                      // '2'
    y = new BigNumber(-1.8)
    y.ceil()                      // '-1'

##### floor`.floor() ⇒ BigNumber`

Returns a BigNumber whose value is the value of this BigNumber rounded to a whole number in the direction of -Infinity.

    x = new BigNumber(1.8)
    x.floor()                     // '1'
    y = new BigNumber(-1.3)
    y.floor()                     // '-2'

##### negated`.neg() ⇒ BigNumber`

Returns a BigNumber whose value is the value of this BigNumber negated, i.e. multiplied by -1.

    x = new BigNumber(1.8)
    x.negated()                   // '-1.8'
    y = new BigNumber(-1.3)
    y.neg()                       // '1.3'

##### squareRoot`.sqrt() ⇒ BigNumber`

Returns a BigNumber whose value is the square root of this BigNumber, rounded according to the current `DECIMAL_PLACES` and `ROUNDING_MODE` settings.

    x = new BigNumber(16)
    x.squareRoot()                // '4'
    y = new BigNumber(3)
    y.sqrt()                      // '1.73205080756887729353'

##### isFinite`.isF() ⇒ boolean`

Returns `true` if the value of this BigNumber is a finite number, otherwise returns `false`.
The only possible non-finite values of a BigNumber are NaN, Infinity and -Infinity.

    x = new BigNumber(1)
    x.isFinite()                  // true
    y = new BigNumber(Infinity)
    y.isF()                       // false

Note: The native method `isFinite()` can be used if `n <= Number.MAX_VALUE`.

##### isNaN`.isNaN() ⇒ boolean`

Returns `true` if the value of this BigNumber is NaN, otherwise returns `false`.

    x = new BigNumber(NaN)
    x.isNaN()                     // true
    y = new BigNumber('Infinity')
    y.isNaN()                     // false

Note: The native method `isNaN()` can also be used.

##### isNegative`.isNeg() ⇒ boolean`

Returns `true` if the value of this BigNumber is negative, otherwise returns `false`.

    x = new BigNumber(-0)
    x.isNegative()                // true
    y = new BigNumber(2)
    y.isNeg                       // false

Note: `n < 0` can be used if `n <= -Number.MIN_VALUE`.

##### isZero`.isZ() ⇒ boolean`

Returns `true` if the value of this BigNumber is zero or minus zero, otherwise returns `false`.

    x = new BigNumber(-0)
    x.isZero() && x.isNeg()        // true
    y = new BigNumber(Infinity)
    y.isZ()                        // false

Note: `n == 0` can be used if `n >= Number.MIN_VALUE`.

##### comparedTo`.cmp(n [, base]) ⇒ number`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns |
--- | ---
1 | If the value of this BigNumber is greater than the value of `n`
-1 | If the value of this BigNumber is less than the value of `n`
0 | If this BigNumber and `n` have the same value
null | if the value of either this BigNumber or `n` is `NaN`

    x = new BigNumber(Infinity)
    y = new BigNumber(5)
    x.comparedTo(y)                // 1
    x.comparedTo(x.minus(1))       // 0
    y.cmp(NaN)                     // null
    y.cmp('110', 2)                // -1

##### dividedBy`.div(n [, base]) ⇒ BigNumber`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns a BigNumber whose value is the value of this BigNumber divided by `n`, rounded according to the current `DECIMAL_PLACES` and `ROUNDING_MODE` settings.

    x = new BigNumber(355)
    y = new BigNumber(113)
    x.dividedBy(y)             // '3.14159292035398230088'
    x.div(5)                   // '71'
    x.div(47, 16)              // '5'

##### minus`.minus(n [, base]) ⇒ BigNumber`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns a BigNumber whose value is the value of this BigNumber minus `n`.

    0.3 - 0.1                  // 0.19999999999999998
    x = new BigNumber(0.3)
    x.minus(0.1)               // '0.2'
    x.minus(0.6, 20)           // '0'

##### modulo`.mod(n [, base]) ⇒ BigNumber`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns a BigNumber whose value is the value of this BigNumber modulo `n`, i.e. the integer remainder of dividing this BigNumber by `n`.

The result will have the same sign as this BigNumber, and it will match that of Javascript's % operator (within the limits of its precision) and BigDecimal's remainder method.

    1 % 0.9                    // 0.09999999999999998
    x = new BigNumber(1)
    x.modulo(0.9)              // '0.1'
    y = new BigNumber(33)
    y.mod('a', 33)             // '3'

##### plus`.plus(n [, base]) ⇒ BigNumber`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns a BigNumber whose value is the value of this BigNumber plus `n`.

    0.1 + 0.2                       // 0.30000000000000004
    x = new BigNumber(0.1)
    y = x.plus(0.2)                 // '0.3'
    BigNumber(0.7).plus(x).plus(y)  // '1'
    x.plus('0.1', 8)                // '0.225'

##### times`.times(n [, base]) ⇒ BigNumber`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns a BigNumber whose value is the value of this BigNumber times `n`.

    0.6 * 3                         // 1.7999999999999998
    x = new BigNumber(0.6)
    y = x.times(3)                  // '1.8'
    BigNumber('7e+500').times(y)    // '1.26e+501'
    x.times('-a', 16)               // '-6'

##### toPower`.pow(exp) ⇒ BigNumber`

`exp` : number : integer, -1e+6 to 1e+6 inclusive

Returns a BigNumber whose value is the value of this BigNumber raised to the power `exp`.

If `exp` is negative the result is rounded according to the current `DECIMAL_PLACES` and `ROUNDING_MODE` settings.

If `exp` is not an integer or is out of range:

If `ERRORS` is `true` a BigNumber Error is thrown,
else if `exp` is greater than 1e+6, it is interpreted as `Infinity`;
else if `exp` is less than -1e+6, it is interpreted as `-Infinity`;
else if `exp` is otherwise a number, it is truncated to an integer;
else it is interpreted as `NaN`.

Note: High value exponents may cause this method to be slow to return.

    Math.pow(0.7, 2)             // 0.48999999999999994
    x = new BigNumber(0.7)
    x.toPower(2)                 // '0.49'
    BigNumber(3).pow(-2)         // '0.11111111111111111111'

    new BigNumber(123.456).toPower(1000).toString().length     // 5099
    new BigNumber(2).pow(1e+6)   // Time taken (Node.js): 9 minutes 34 secs.

##### equals`.eq(n [, base]) ⇒ boolean`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns `true` if the value of this BigNumber equals the value of `n`, otherwise returns `false`.
As with Javascript, NaN does not equal NaN.
Note : This method uses the `comparedTo` method internally.

    0 === 1e-324                    // true
    x = new BigNumber(0)
    x.equals('1e-324')              // false
    BigNumber(-0).eq(x)             // true  ( -0 === 0 )
    BigNumber(255).eq('ff', 16)     // true

    y = new BigNumber(NaN)
    y.equals(NaN)                   // false

##### greaterThan`.gt(n [, base]) ⇒ boolean`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns `true` if the value of this BigNumber is greater than the value of `n`, otherwise returns `false`.
Note : This method uses the `comparedTo` method internally.

    0.1 > (0.3 - 0.2)                           // true
    x = new BigNumber(0.1)
    x.greaterThan(BigNumber(0.3).minus(0.2))    // false
    BigNumber(0).gt(x)                          // false
    BigNumber(11, 3).gt(11.1, 2)                // true

##### greaterThanOrEqualTo`.gte(n [, base]) ⇒ boolean`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns `true` if the value of this BigNumber is greater than or equal to the value of `n`, otherwise returns `false`.
Note : This method uses the `comparedTo` method internally.

    (0.3 - 0.2) >= 0.1                   // false
    x = new BigNumber(0.3).minus(0.2)
    x.greaterThanOrEqualTo(0.1)          // true
    BigNumber(1).gte(x)                  // true
    BigNumber(10, 18).gte('i', 36)       // true

##### lessThan`.lt(n [, base]) ⇒ boolean`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns `true` if the value of this BigNumber is less than the value of `n`, otherwise returns `false`.
Note : This method uses the `comparedTo` method internally.

    (0.3 - 0.2) < 0.1                    // true
    x = new BigNumber(0.3).minus(0.2)
    x.lessThan(0.1)                      // false
    BigNumber(0).lt(x)                   // true
    BigNumber(11.1, 2).lt(11, 3)         // true

##### lessThanOrEqualTo`.lte(n [, base]) ⇒ boolean`

`n` : number|string|BigNumber
`base` : number
See constructor for further parameter details.

Returns `true` if the value of this BigNumber is less than or equal to the value of `n`, otherwise returns `false`.
Note : This method uses the `comparedTo` method internally.

    0.1 <= (0.3 - 0.2)                                // false
    x = new BigNumber(0.1)
    x.lessThanOrEqualTo(BigNumber(0.3).minus(0.2))    // true
    BigNumber(-1).lte(x)                              // true
    BigNumber(10, 18).lte('i', 36)                    // true

##### toExponential`.toE([decimal_places]) ⇒ string`

`decimal_places` : number : integer, 0 to 1e+9 inclusive

Returns a string representing the value of this BigNumber in exponential notation to the specified decimal places, i.e with one digit before the decimal point and `decimal_places` digits after it. If rounding is necessary, the current `ROUNDING_MODE` is used.

If the value of this BigNumber in exponential notation has fewer fraction digits then is specified by `decimal_places`, the return value will be appended with zeros accordingly.

If `decimal_places` is omitted, or is `null` or undefined, the number of digits after the decimal point defaults to the minimum number of digits necessary to represent the value exactly.

See Errors for the treatment of other non-integer or out of range `decimal_places` values.

    x = 45.6
    y = new BigNumber(x)
    x.toExponential()         // '4.56e+1'
    y.toExponential()         // '4.56e+1'
    x.toExponential(0)        // '5e+1'
    y.toE(0)                  // '5e+1'
    x.toExponential(1)        // '4.6e+1'
    y.toE(1)                  // '4.6e+1'
    x.toExponential(3)        // '4.560e+1'
    y.toE(3)                  // '4.560e+1'

##### toFixed`.toF([decimal_places]) ⇒ string`

`decimal_places` : number : integer, 0 to 1e+9 inclusive

Returns a string representing the value of this BigNumber in normal notation to the specified fixed number of decimal places, i.e. with `decimal_places` digits after the decimal point. If rounding is necessary, the current `ROUNDING_MODE` setting is used.

If the value of this BigNumber in normal notation has fewer fraction digits then is specified by `decimal_places`, the return value will be appended with zeros accordingly.

Unlike `Number.prototype.toFixed`, which returns exponential notation if a number is greater or equal to 1021, this method will always return normal notation.

If `decimal_places` is omitted, or is `null` or undefined, then the return value is the same as `n.toString()`. This is also unlike `Number.prototype.toFixed`, which returns the value to zero decimal places.

See Errors for the treatment of other non-integer or out of range `decimal_places` values.

    x = 45.6
    y = new BigNumber(x)
    x.toFixed()              // '46'
    y.toFixed()              // '45.6'
    y.toF(0)                 // '46'
    x.toFixed(3)             // '45.600'
    y.toF(3)                 // '45.600'

##### toPrecision`.toP([significant_figures]) ⇒ string`

`significant_figures` : number : integer, 1 to 1e+9 inclusive

Returns a string representing the value of this BigNumber to the specified number of significant digits. If rounding is necessary, the current `ROUNDING_MODE` setting is used.

If `significant_figures` is less than the number of digits necessary to represent the integer part of the value in normal notation, then exponential notation is used.

If `significant_figures` is omitted, or is `null` or undefined, then the return value is the same as `n.toString()`.

See Errors for the treatment of other non-integer or out of range `significant_figures` values.

    x = 45.6
    y = new BigNumber(x)
    x.toPrecision()           // '45.6'
    y.toPrecision()           // '45.6'
    x.toPrecision(1)          // '5e+1'
    y.toP(1)                  // '5e+1'
    x.toPrecision(5)          // '45.600'
    y.toP(5)                  // '45.600'

##### toString`.toS([base]) ⇒ string`

`base` : number : integer, 2 to 36 inclusive

Returns a string representing the value of this BigNumber in the specified base, or base 10 if `base` is omitted. Like `Number.toString`, in bases above 10, numerals above 9 are represented by lower-case letters.

If a base is specified the value is rounded according to the current `DECIMAL_PLACES` and `ROUNDING_MODE` settings.

If a base is not specified, and this BigNumber has a positive exponent that is equal to or greater than the positive component of the current `EXPONENTIAL_AT` setting, or a negative exponent equal to or less than the negative component of the setting, then exponential notation is returned.

If `base` is `null` or undefined it is ignored.
See Errors for the treatment of other non-integer or out of range `base` values.

    x = new BigNumber(750000)
    x.toString()                    // '750000'
    BigNumber.config({ EXPONENTIAL_AT : 5 })
    x.toString()                    // '7.5e+5'

    y = new BigNumber(362.875)
    y.toString(2)                   // '101101010.111'
    y.toString(9)                   // '442.77777777777777777778'
    y.toString(32)                  // 'ba.s'

    BigNumber.config({ DECIMAL_PLACES : 4 });
    z = new BigNumber('1.23456789')
    z.toString()                    // '1.23456789'
    z.toString(10)                  // '1.2346'

##### valueOf`.valueOf() ⇒ string`

As `toString`, but does not accept a base argument.

    x = new BigNumber('1.777e+457')
    x.valueOf()                      // '1.777e+457'

##### toFraction`.toFr([max_denominator]) ⇒ [string, string]`

`max_denominator` : number|string|BigNumber : integer >= 1 and < Infinity

Returns a string array representing the value of this BigNumber as a simple fraction with an integer numerator and an integer denominator. The denominator will be a positive non-zero value less than or equal to `max_denominator`.

If a maximum denominator is not specified, or is `null` or undefined, the denominator will be the lowest value necessary to represent the number exactly.

See Errors for the treatment of other non-integer or out of range `max_denominator` values.

    x = new BigNumber(1.75)
    x.toFraction()            // '7, 4'

    pi = new BigNumber('3.14159265358')
    pi.toFr()                 // '157079632679,50000000000'
    pi.toFr(100000)           // '312689, 99532'
    pi.toFr(10000)            // '355, 113'
    pi.toFr(100)              // '311, 99'
    pi.toFr(10)               // '22, 7'
    pi.toFr(1)                // '3, 1'

##### round`.round([decimal_places [, rounding_mode]]) ⇒ BigNumber`

`decimal_places` : number : integer, 0 to 1e+9 inclusive
`rounding_mode` : number : integer, 0 to 8 inclusive

Returns a BigNumber whose value is the value of this BigNumber rounded by the specified `rounding_mode` to a maximum of `decimal_places` digits after the decimal point.

if `decimal_places` is omitted, or is `null` or undefined, the return value is `n` rounded to a whole number.

if `rounding_mode` is omitted, or is `null` or undefined, the current `ROUNDING_MODE` setting is used.

See Errors for the treatment of other non-integer or out of range `decimal_places` or `rounding_mode` values.

    x = 1234.56
    Math.round(x)                             // 1235

    y = new BigNumber(x)
    y.round()                                 // '1235'
    y.round(1)                                // '1234.6'
    y.round(2)                                // '1234.56'
    y.round(10)                               // '1234.56'
    y.round(0, 1)                             // '1234'
    y.round(0, 6)                             // '1235'
    y.round(1, 1)                             // '1234.5'
    y.round(1, BigNumber.ROUND_HALF_EVEN)     // '1234.6'
    y                                         // '1234.56'

#### Properties

A BigNumber is an object with three properties:

Property | Description | Type | Value
--- | --- | --- | ---
c | coefficient* | number`[]` | Array of single digits
e | exponent | number | Integer, -1e+9 to 1e+9 inclusive
s | sign | number | -1 or 1

*significand

The value of any of the three properties may also be `null`.

The value of a BigNumber is stored in a normalised decimal floating point format which corresponds to the value's `toExponential` form, with the decimal point to be positioned after the most significant (left-most) digit of the coefficient.

Note that, as with Javascript numbers, the original exponent and fractional trailing zeros are not preserved.

    x = new BigNumber(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 BigNumber('-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

A BigNumber is mutable in the sense that the value of its properties can be changed.
For example, to rapidly shift a value by a power of 10:

    x = new BigNumber('1234.000')      // '1234'
    x.toExponential()                  // '1.234e+3'
    x.c                                // '1,2,3,4'
    x.e                                // 3

    x.e = -5
    x                                  // '0.00001234'

If changing the coefficient array directly, which is not recommended, be careful to avoid leading or trailing zeros (unless zero itself is being represented).

#### Zero, NaN and Infinity

The table below shows how ±0, NaN and ±Infinity are stored.

| c | e | s
--- | --- | --- | ---
±0 | `[0]` | `0` | `±1`
NaN | `null` | `null` | `null`
±Infinity | `null` | `null` | `±1`

    x = new Number(-0)      // 0
    1 / x == -Infinity     // true

    y = new BigNumber(-0)   // '0'
    y.c                     // '0' ( [0].toString() )
    y.e                     // 0
    y.s                     // -1

#### Errors

The table below shows the BigNumber Errors that may be thrown if `ERRORS` is `true`, and what happens if `ERRORS` is `false`.

Method(s) | ERRORS : true Throw BigNumber Error | ERRORS : false Action on invalid argument
--- | --- | ---

`BigNumber
comparedTo
dividedBy
equals
greaterThan
greaterThanOrEqualTo
lessThan
lessThanOrEqualTo
minus
mod
plus
times`

number type has more than
15 significant digits

Accept.

not a base... number | Substitute `NaN`.
base not an integer | Truncate to integer. Ignore if not a number.
base out of range | Ignore.
not a number* | Substitute `NaN`.
`config` | `DECIMAL_PLACES` not an integer | Truncate to integer. Ignore if not a number.
`DECIMAL_PLACES` out of range | Ignore.
`ROUNDING_MODE` not an integer | Truncate to integer. Ignore if not a number.
`ROUNDING_MODE` out of range | Ignore.
`EXPONENTIAL_AT` not an integer or not [integer, integer] | Truncate to integer(s). Ignore if not number(s).
`EXPONENTIAL_AT` out of range or not [negative, positive] | Ignore.
`RANGE` not a non-zero integer or not [integer, integer] | Truncate to integer(s). Ignore if zero or not number(s).
`RANGE` out of range or not [negative, positive] | Ignore.
`ERRORS` not a boolean or binary digit | Ignore.
`toPower` | exponent not an integer | Truncate to integer. Substitute `NaN` if not a number.
exponent out of range | Substitute `±Infinity`.
`round` | decimal places not an integer | Truncate to integer. Ignore if not a number.
decimal places out of range | Ignore.
mode not an integer | Truncate to integer. Ignore if not a number.
mode out of range | Ignore.
`toExponential` | decimal places not an integer | Truncate to integer. Ignore if not a number.
decimal places out of range | Ignore.
`toFixed` | decimal places not an integer | Truncate to integer. Ignore if not a number.
decimal places out of range | Ignore.
`toFraction` | max denominator not an integer | Truncate to integer. Ignore if not a number.
max denominator out of range | Ignore.
`toPrecision` | precision not an integer | Truncate to integer. Ignore if not a number.
precision out of range | Ignore.
`toString` | base not an integer | Truncate to integer. Ignore if not a number.
base out of range | Ignore.

*No error is thrown if the value is `NaN` or 'NaN'

The message of a BigNumber Error will also contain the name of the method from which the error originated.

To determine if an exception is a BigNumber Error:

    try {
        // do something with BigNumbers
    } catch (e) {
        if (e.name == 'BigNumber Error') {
            // do something
        }
    }

#### FAQ

###### Why are trailing fractional zeros removed from BigNumbers?

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.

    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

To specify the precision of a value is to specify that the value lies within a certain range.

In the first example, `x` has a value of 1.0. The trailing zero shows the precision of the value, implying that it is in the range 0.95 to 1.05. Similarly, the precision indicated by the trailing zeros of `y` 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.

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.

This library, like Javascript and most calculators, does not retain trailing fractional zeros. Instead, the `toExponential`, `toFixed` and `toPrecision` methods enable trailing zeros to be added if and when required.