decimal.js-light API
Author: MMclaughlin

# decimal.js-light

The light version of decimal.js, an arbitrary-precision Decimal type for JavaScript.

Hosted on GitHub.

## API

See the README on GitHub for a quick-start introduction.

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.

When the library is loaded, it defines a single function object, `Decimal`, the constructor of Decimal instances.

If necessary, multiple Decimal constructors can be created, each with their own independent configuration, e.g. precision and range, which applies to all Decimal instances created from it.

A new Decimal constructor is created by calling the `clone` method of an already existing Decimal constructor.

### CONSTRUCTOR

##### Decimal`Decimal(value) ⇒ Decimal`

`value`: number|string|Decimal
  Integer or float.
  The number of digits is not limited, except by JavaScript's maximum array size and, in practice, the processing time required.
  The maximum permissible exponent magnitude is approximately `9007199254740991`.
  String values may be in exponential (floating-point), as well as normal (fixed-point) notation.
  In exponential notation, `e` or `E` defines a power-of-ten exponent.

Returns a new Decimal object instance.

Throws on an invalid `value`.

    x = new Decimal(9)                       // '9'
    y = new Decimal(x)                       // '9'

    new Decimal('5032485723458348569331745.33434346346912144534543')
    new Decimal('4.321e+4')                  // '43210'
    new Decimal('-735.0918e-430')            // '-7.350918e-428'
    new Decimal('5.6700000')                 // '5.67'
    new Decimal('.5')                        // '0.5'

    new Decimal(0.046875)                    // '0.046875'
    new Decimal('0.046875000000')            // '0.046875'

    new Decimal(4.6875e-2)                   // '0.046875'
    new Decimal('468.75e-4')                 // '0.046875'

#### Methods

The methods of a Decimal constructor.

##### clone `.clone([object]) ⇒ Decimal constructor`

`object`: object

Returns a new independent Decimal constructor with configuration settings as described by `object` (see `config`), or with the same settings as `this` Decimal constructor if `object` is omitted.

    Decimal.config({ precision: 5 })
    D9 = Decimal.clone({ precision: 9 })

    a = new Decimal(1)
    b = new D9(1)

    a.div(3)                           // 0.33333
    b.div(3)                           // 0.333333333

    // D9 = Decimal.clone({ precision: 9 }) is equivalent to:
    D9 = Decimal.clone()
    D9.config({ precision: 9 })

It is not inefficient in terms of memory usage to use multiple Decimal constructors as functions are shared between them.

##### config`.set(object) ⇒ Decimal constructor`

`object`: object

Configures the 'global' settings for `this` particular Decimal constructor, i.e. the settings which apply to operations performed on the Decimal instances created by it.

Returns `this` Decimal constructor.

The configuration object, `object`, can contain some or all of the properties described in detail at Properties and shown in the example below.

The values of the configuration object properties are checked for validity and then stored as equivalently-named properties of `this` Decimal constructor.

Throws on an invalid `object` or configuration property value.

    // Defaults
    Decimal.config({
        precision: 20,
        rounding: 4,
        toExpNeg: -7,
        toExpPos: 21,
        LN10: new Decimal('2.30258509299404568401799145468436...')
    })

    Decimal.set({ rounding: Decimal.ROUND_CEIL })

The properties of a Decimal constructor can also be set by direct assignment, but that will by-pass the validity checking that this method performs - which is not a problem if the user knows that the checks are unnecessary.

#### Properties

The properties of a Decimal constructor.

###### Configuration properties

The values of the configuration properties `precision`, `rounding`, `toExpNeg` and `toExpPos` are set using the `config` method.

As simple object properties they can be set directly without using `config`, and it is fine to do so, but the values assigned will not then be checked for validity. For example:

    Decimal.config({ precision: 0 })
    // '[DecimalError] Invalid argument: precision: 0'

    Decimal.precision = 0
    // No error is thrown and the results of calculations are unreliable

##### precision

number: integer, `1` to `1e+9` inclusive
Default value: `20`

The maximum number of significant digits of the result of an operation.

All functions which return a Decimal will return the value to `precision` significant digits except `Decimal`, `absoluteValue`, `negated`, `toInteger`, and `toDecimalPlaces`.

    Decimal.config({ precision: 5 })
    Decimal.precision                  // 5

##### rounding

number: integer, `0` to `8` inclusive
Default value: `4` (`ROUND_HALF_UP`)

The default rounding mode used by `toInteger`, `toDecimalPlaces`, `toExponential`, `toFixed`, `toPrecision` and `toSignificantDigits`.

The rounding modes are available as enumerated properties of the constructor.

    Decimal.config({ rounding: Decimal.ROUND_UP })
    Decimal.config({ rounding: 0 })    // equivalent
    Decimal.rounding                   // 0

##### toExpNeg

number: integer, `-9e15` to `0` inclusive
Default value: `-7`

The negative exponent value at and below which `toString` returns exponential notation.

    Decimal.config({ toExpNeg: -7 })
    Decimal.toExpNeg                   // -7
    new Decimal(0.00000123)            // '0.00000123'       e is -6
    new Decimal(0.000000123)           // '1.23e-7'

    // Always return exponential notation:
    Decimal.config({ toExpNeg: 0 })

JavaScript numbers use exponential notation for negative exponents of `-7` and below.

Regardless of the value of `toExpNeg`, the `toFixed` method will always return a value in normal notation and the `toExponential` method will always return a value in exponential form.

##### toExpPos

number: integer, `0` to `9e15` inclusive
Default value: `20`

The positive exponent value at and above which `toString` returns exponential notation.

    Decimal.config({ toExpPos: 2 })
    Decimal.toExpPos                   // 2
    new Decimal(12.3)                  // '12.3'        e is 1
    new Decimal(123)                   // '1.23e+2'

    // Always return exponential notation:
    Decimal.config({ toExpPos: 0 })

JavaScript numbers use exponential notation for positive exponents of `20` and above.

Regardless of the value of `toExpPos`, the `toFixed` method will always return a value in normal notation and the `toExponential` method will always return a value in exponential form.

##### LN10

string|Decimal: the natural logarithm of `10`
The default value has `115` digits

The maximum precision of the `naturalExponential`, `naturalLogarithm`, `logarithm`, and `toPower` methods is determined by the precision of the value of `LN10`.

The default value of `LN10` enables a maximum precision of about `100` digits. To increase this, assign a new value to `LN10` using a string or Decimal value with about 15 digits more than the maximum precision required.

An error will be thrown if the `LN10` value does not have sufficient precision to enable an operation to be performed.

    Decimal.config({ LN10: '2.3025850929940456840179914546843642076011014886287729760333279009' })

    Decimal.LN10.toFixed(5)             // ''2.30259'

###### Rounding modes

The library's enumerated rounding modes are stored as properties of the Decimal 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

    Decimal.config({ rounding: Decimal.ROUND_CEIL })
    Decimal.config({ rounding: 2 })    // equivalent
    Decimal.rounding                   // 2

### INSTANCE

#### Methods

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

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

Methods that return a Decimal can be chained:

    x = new Decimal(2).times('999.999999999999999').dividedBy(4).toFixed(2)

Methods do not round their arguments before execution.

Many method names have a shorter alias. (Internally, the library always uses the shorter method names.)

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

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

The return value is not affected by the value of the `precision` setting.

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

##### comparedTo`.cmp(x) ⇒ number`

`x`: number|string|Decimal

Returns |
--- | ---
`1` | if the value of this Decimal is greater than the value of `x`
`-1` | if the value of this Decimal is less than the value of `x`
`0` | if this Decimal and `x` have the same value

    x = new Decimal(4)
    y = new Decimal(5)
    x.comparedTo(y)                // -1
    x.comparedTo(x.plus(1))        // 0

##### decimalPlaces`.dp() ⇒ number`

Returns the number of decimal places, i.e. the number of digits after the decimal point, of the value of this Decimal.

    x = new Decimal(1.234)
    x.decimalPlaces()              // '3'
    y = new Decimal(987.654321)
    y.dp()                         // '6'

##### dividedBy`.div(x) ⇒ Decimal`

`x`: number|string|Decimal

Returns a new Decimal whose value is the value of this Decimal divided by `x`, truncated to `precision` significant digits.

    x = new Decimal(355)
    y = new Decimal(113)
    x.dividedBy(y)             // '3.14159292035398230088'
    x.div(5)                   // '71'

##### dividedToIntegerBy`.idiv(x) ⇒ Decimal`

`x`: number|string|Decimal

Return a new Decimal whose value is the integer part of dividing this Decimal by `x`, truncated to `precision` significant digits.

    x = new Decimal(5)
    y = new Decimal(3)
    x.dividedToIntegerBy(y)     // '1'
    x.idiv(0.7)             // '7'

##### equals`.eq(x) ⇒ boolean`

`x`: number|string|Decimal

Returns `true` if the value of this Decimal equals the value of `x`, otherwise returns `false`.

Note: This method uses the `cmp` method internally.

    0 === 1e-324                     // true
    x = new Decimal(0)
    x.equals('1e-324')               // false

##### exponent`.exponent() ⇒ number`

Returns the exponent value of this Decimal.

    x = new Decimal(1234.567)
    x.exponent()                     // 3

##### greaterThan`.gt(x) ⇒ boolean`

`x`: number|string|Decimal

Returns `true` if the value of this Decimal is greater than the value of `x`, otherwise returns `false`.

Note: This method uses the `cmp` method internally.

    0.1 > (0.3 - 0.2)                            // true
    x = new Decimal(0.1)
    x.greaterThan(Decimal(0.3).minus(0.2))       // false
    new Decimal(0).gt(x)                         // false

##### greaterThanOrEqualTo`.gte(x) ⇒ boolean`

`x`: number|string|Decimal

Returns `true` if the value of this Decimal is greater than or equal to the value of `x`, otherwise returns `false`.

Note: This method uses the `cmp` method internally.

    (0.3 - 0.2) >= 0.1                       // false
    x = new Decimal(0.3).minus(0.2)
    x.greaterThanOrEqualTo(0.1)              // true
    new Decimal(1).gte(x)                    // true

##### isInteger`.isint() ⇒ boolean`

Returns `true` if the value of this Decimal is a whole number, otherwise returns `false`.

    x = new Decimal(1)
    x.isInteger()                            // true
    y = new Decimal(123.456)
    y.isint()                                // false

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

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

    x = new Decimal(0)
    x.isNegative()                           // false
    y = new Decimal(2)
    y.isneg                                  // false

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

##### isPositive`.ispos() ⇒ boolean`

Returns `true` if the value of this Decimal is positive, otherwise returns `false`.

    x = new Decimal(0)
    x.isPositive()                           // false
    y = new Decimal(-2)
    y.ispos                                  // false

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

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

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

    x = new Decimal(0)
    x.isZero()                               // true

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

##### lessThan`.lt(x) ⇒ boolean`

`x`: number|string|Decimal

Returns `true` if the value of this Decimal is less than the value of `x`, otherwise returns `false`.

Note: This method uses the `cmp` method internally.

    (0.3 - 0.2) < 0.1                        // true
    x = new Decimal(0.3).minus(0.2)
    x.lessThan(0.1)                          // false
    new Decimal(0).lt(x)                     // true

##### lessThanOrEqualTo`.lte(x) ⇒ boolean`

`x`: number|string|Decimal

Returns `true` if the value of this Decimal is less than or equal to the value of `x`, otherwise returns `false`.

Note: This method uses the `cmp` method internally.

    0.1 <= (0.3 - 0.2)                              // false
    x = new Decimal(0.1)
    x.lessThanOrEqualTo(Decimal(0.3).minus(0.2))    // true
    new Decimal(-1).lte(x)                          // true

##### logarithm`.log(x) ⇒ Decimal`

`x`: number|string|Decimal

Returns a new Decimal whose value is the base `x` logarithm of the value of this Decimal, truncated to `precision` significant digits.

If `x` is omitted, the base 10 logarithm of the value of this Decimal will be returned.

    x = new Decimal(1000)
    x.logarithm()                            // '3'
    y = new Decimal(256)
    y.log(2)                                 // '8'

The maximum error will be `1` ulp (unit in the last place).

Logarithms to base `2` or `10` will always be correct.

The performance of this method degrades exponentially with increasing digits.

##### minus`.minus(x) ⇒ Decimal`

`x`: number|string|Decimal

Returns a new Decimal whose value is the value of this Decimal minus `x`, truncated to `precision` significant digits.

    0.3 - 0.1                                // 0.19999999999999998
    x = new Decimal(0.3)
    x.minus(0.1)                             // '0.2'

##### modulo`.mod(x) ⇒ Decimal`

`x`: number|string|Decimal

Returns a new Decimal whose value is the value of this Decimal modulo `x`, truncated to `precision` significant digits.

    1 % 0.9                                  // 0.09999999999999998
    x = new Decimal(1)
    y = x.modulo(0.9)                            // '0.1'

##### naturalExponential`.exp() ⇒ Decimal`

Returns a new Decimal whose value is the base `e` (Euler's number, the base of the natural logarithm) exponential of the value of this Decimal, truncated to `precision` significant digits.

The `naturalLogarithm` function is the inverse of this function.

    x = new Decimal(1)
    x.naturalExponential()                   // '2.7182818284590452354'
    y = new Decimal(2)
    y.exp()                                  // '7.3890560989306502272'

The maximum error will be `1` ulp (unit in the last place).

The performance of this method degrades exponentially with increasing digits.

##### naturalLogarithm`.ln() ⇒ Decimal`

Returns a new Decimal whose value is the natural logarithm of the value of this Decimal, truncated to `precision` significant digits.

The natural logarithm is the inverse of the `naturalExponential` function.

    x = new Decimal(10)
    x.naturalLogarithm()                     // '2.3026'
    y = new Decimal('1.23e+30')
    y.ln()                                   // '69.28'

The mathematical result of the natural logarithm function is non-terminating, unless its argument is `1`.

The time-taken by this method increases exponentially with increasing digits.

See LN10 to configure the maximum precision available.

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

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

The return value is not affected by the value of the `precision` setting.

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

##### plus`.plus(x) ⇒ Decimal`

`x`: number|string|Decimal

Returns a new Decimal whose value is the value of this Decimal plus `x`, truncated to `precision` significant digits.

    0.1 + 0.2                                // 0.30000000000000004
    x = new Decimal(0.1)
    y = x.plus(0.2)                          // '0.3'
    new Decimal(0.7).plus(x).plus(y)         // '1.1'

##### precision`.sd([include_zeros]) ⇒ number`

Returns the number of significant digits of the value of this Decimal.

If `include_zeros` is `true` or `1` then any trailing zeros of the integer part of a number are counted as significant digits, otherwise they are not.

    x = new Decimal(1.234)
    x.precision()                            // '4'
    y = new Decimal(987000)
    y.sd()                                   // '3'
    y.sd(true)                               // '6'

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

Returns a new Decimal whose value is the square root of this Decimal, truncated to `precision` significant digits.

This method is much faster than using the `toPower` method with an exponent of `0.5`.

    x = new Decimal(16)
    x.squareRoot()                           // '4'
    y = new Decimal(3)
    y.sqrt()                                 // '1.73205080756887729353'
    y.sqrt().eq( y.pow(0.5) )                // true

##### times`.times(x) ⇒ Decimal`

`x`: number|string|Decimal

Returns a new Decimal whose value is the value of this Decimal times `x`, truncated to `precision` significant digits.

    0.6 * 3                                  // 1.7999999999999998
    x = new Decimal(0.6)
    y = x.times(3)                           // '1.8'
    new Decimal('7e+500').times(y)           // '1.26e+501'

##### toDecimalPlaces`.todp([dp [, rm]]) ⇒ Decimal`

`dp`: number: integer, `0` to `1e+9` inclusive
`rm`: number: integer, `0` to `8` inclusive.

Returns a new Decimal whose value is the value of this Decimal rounded to a maximum of `dp` decimal places using rounding mode `rm`.

If `dp` is omitted, the return value will have the same value as this Decimal.

If `rm` is omitted, rounding mode `rounding` is used.

Throws on an invalid `dp` or `rm` value.

    x = new Decimal(12.24567)
    x.toDecimalPlaces(0)                // '12'
    x.toDecimalPlaces(1, 0)             // '12.3'

    y = new Decimal(9876.54321)
    y.todp(3)                           // '9876.543'
    y.todp(1, 0)                        // '9876.6'
    y.todp(1, Decimal.ROUND_DOWN)       // '9876.5'

##### toExponential`.toExponential([dp [, rm]]) ⇒ string`

`dp`: number: integer, `0` to `1e+9` inclusive
`rm`: number: integer, `0` to `8` inclusive

Returns a string representing the value of this Decimal in exponential notation rounded using rounding mode `rm` to `dp` decimal places, i.e with one digit before the decimal point and `dp` digits after it.

If the value of this Decimal in exponential notation has fewer than `dp` fraction digits, the return value will be appended with zeros accordingly.

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

If `rm` is omitted, rounding mode `rounding` is used.

Throws on an invalid `dp` or `rm` value.

    x = 45.6
    b = new Decimal(x)
    x.toExponential()              // '4.56e+1'
    y.toExponential()              // '4.56e+1'
    x.toExponential(0)             // '5e+1'
    y.toExponential(0)             // '5e+1'
    x.toExponential(1)             // '4.6e+1'
    y.toExponential(1)             // '4.6e+1'
    y.toExponential(1, 1)          // '4.5e+1'  (ROUND_DOWN)
    x.toExponential(3)             // '4.560e+1'
    y.toExponential(3)             // '4.560e+1'

##### toFixed`.toFixed([dp [, rm]]) ⇒ string`

`dp`: number: integer, `0` to `1e+9` inclusive
`rm`: number: integer, `0` to `8` inclusive

Returns a string representing the value of this Decimal in normal (fixed-point) notation rounded to `dp` decimal places using rounding mode `rm`.

If the value of this Decimal in normal notation has fewer than `dp` fraction digits, 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 `dp` is omitted, the return value will be unrounded and in normal notation. This is unlike `Number.prototype.toFixed`, which returns the value to zero decimal places, but is useful when because of the current `toExpNeg` or `toExpNeg` values, `toString` returns exponential notation.

If `rm` is omitted, rounding mode `rounding` is used.

Throws on an invalid `dp` or `rm` value.

    x = 3.456
    b = new Decimal(x)
    x.toFixed()              // '3'
    y.toFixed()              // '3.456'
    y.toFixed(0)             // '3'
    x.toFixed(2)             // '3.46'
    y.toFixed(2)             // '3.46'
    y.toFixed(2, 1)          // '3.45'  (ROUND_DOWN)
    x.toFixed(5)             // '3.45600'
    y.toFixed(5)             // '3.45600'

##### toInteger`.toint() ⇒ Decimal`

Returns a new Decimal whose value is the value of this Decimal rounded to a whole number using rounding mode `rounding`.

To emulate `Math.round`, set `rounding` to `7`, i.e. `ROUND_HALF_CEIL`.

    Decimal.config({ rounding: 4 })
    x = 1234.5
    x.toInteger()                            // '1235'

    Decimal.rounding = Decimal.ROUND_DOWN
    x.toint()                                // '1234'
    x                                        // '1234.5'

##### toJSON`.toJSON() ⇒ string`

As `toString`.

##### toNumber`.toNumber() ⇒ number`

Returns the value of this Decimal converted to a primitive number.

Type coercion with, for example, JavaScript's unary plus operator will also work, except that a Decimal with the value minus zero will convert to positive zero.

    x = new Decimal(456.789)
    x.toNumber()                   // 456.789
    +x                             // 456.789

    y = new Decimal('45987349857634085409857349856430985')
    y.toNumber()                   // 4.598734985763409e+34

##### toPower`.pow(x) ⇒ Decimal`

`x`: number|string|Decimal: integer or non-integer

Returns a new Decimal whose value is the value of this Decimal raised to the power `x`, truncated to `precision` significant digits.

The performance of this method degrades exponentially with increasing digits.
For non-integer exponents in particular, the performance of this method may not be adequate.

The maximum error will be `1` ulp (unit in the last place).

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

    new Decimal(1217652.23).pow('98765.489305603941')
    // '4.8227010515242461181e+601039'

##### toPrecision`.toPrecision([sd [, rm]]) ⇒ string`

`sd`: number: integer, `1` to `1e+9` inclusive
`rm`: number: integer, `0` to `8` inclusive

Returns a string representing the value of this Decimal rounded to `sd` significant digits using rounding mode `rm`.

If `sd` is less than the number of digits necessary to represent the integer part of the value in normal (fixed-point) notation, then exponential notation is used.

If `sd` is omitted, the return value is the same as `toString`.

If `rm` is omitted, rounding mode `rounding` is used.

Throws on an invalid `sd` or `rm` value.

    x = 45.6
    b = new Decimal(x)
    x.toPrecision()                          // '45.6'
    y.toPrecision()                          // '45.6'
    x.toPrecision(1)                         // '5e+1'
    y.toPrecision(1)                         // '5e+1'
    y.toPrecision(2, 0)                      // '4.6e+1'  (ROUND_UP)
    y.toPrecision(2, 1)                      // '4.5e+1'  (ROUND_DOWN)
    x.toPrecision(5)                         // '45.600'
    y.toPrecision(5)                         // '45.600'

##### toSignificantDigits`.tosd([sd [, rm]]) ⇒ Decimal`

`sd`: number: integer, `1` to `1e+9` inclusive.
`rm`: number: integer, `0` to `8` inclusive.

Returns a new Decimal whose value is the value of this Decimal rounded to a maximum of `sd` significant digits using rounding mode `rm`.

If `sd` is omitted, the return value will be rounded to `precision` significant digits.

If `rm` is omitted, rounding mode `rounding` will be used.

Throws on an invalid `sd` or `rm` value.

    Decimal.config({ precision: 5, rounding: 4 })
    x = new Decimal(9876.54321)

    x.toSignificantDigits()                          // '9876.5'
    x.toSignificantDigits(6)                         // '9876.54'
    x.toSignificantDigits(6, Decimal.ROUND_UP)       // '9876.55'
    x.tosd(2)                                        // '9900'
    x.tosd(2, 1)                                     // '9800'
    x                                                // '9876.54321'

##### toString`.toString() ⇒ string`

Returns a string representing the value of this Decimal.

If this Decimal has a positive exponent that is equal to or greater than `toExpPos`, or a negative exponent equal to or less than `toExpNeg`, then exponential notation will be returned.

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

    Decimal.config({ precision: 4 });
    y = new Decimal('1.23456789')
    y.toString()                             // '1.23456789'

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

As `toString`.

#### Properties

The value of a Decimal is stored in a normalised base `10000000` floating point format.

A Decimal instance is an object with three properties:

Property | Description | Type | Value
--- | --- | --- | ---
d | digits | number`[]` | Array of integers, each `0` - `1e7`
e | exponent* | number | Integer, `-1286742750677284` to `1286742750677284` inclusive
s | sign | number | `-1`, `0`, or `1`

*This is the exponent in base `10000000`. To get the base 10 exponent, use the `exponent` method.

The properties are best considered to be read-only.

As with JavaScript numbers, the original exponent and fractional trailing zeros of a number are not preserved.

    x = new Decimal(0.123)                   // '0.123'
    x.toExponential()                        // '1.23e-1'
    x.d                                      // [ 1230000 ]
    x.e                                      // -1
    x.s                                      // 1

    y = new Number(-123.4567000e+2)          // '-12345.67'
    y.toExponential()                        // '-1.234567e+4'
    z = new Decimal('-123.4567000e+2')       // '-12345.67'
    z.toExponential()                        // '-1.234567e+4'
    z.d                                      // [ 12345, 6700000 ]
    z.e                                      // 4
    z.s                                      // -1

#### Errors

The errors that are thrown are generic `Error` objects whose `message` property begins with `"[DecimalError]"`.

To determine if an exception is a Decimal Error:

    try {
        // ...
    } catch (e) {
        if ( e instanceof Error && /DecimalError/.test(e.message) ) {
            // ...
        }
    }

## FAQ

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

Some 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 have, `0.95 + 1.09995 = 2.04995`, and if we add the two highest values we have, `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 may be 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 may be misleading.

This library, like binary floating point 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.