+ The light version of decimal.js, an + arbitrary-precision Decimal type for JavaScript. +
+ + ++ 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.
+
+
Decimal(value) ⇒ Decimal
+ value: number|string|Decimal9007199254740991.
+ 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'
+
+
+
+ The methods of a Decimal constructor.
+ + + +.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. +
+ + + +.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. +
+ + + +The properties of a Decimal constructor.
+ + + +
+ 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
+
+
+
+
+ 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
+
+
+
+
+ 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
+
+
+
+
+ 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.
+
+ 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.
+
+ 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'
+
+
+
+
+ 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
+
+
+
+
+ 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.) +
+ + + +.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'+ + + +
.cmp(x) ⇒ numberx: 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+ + + +
.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'+ + + +
.div(x) ⇒ Decimalx: 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'+ + + +
.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'+ + + +
.eq(x) ⇒ booleanx: 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() ⇒ numberReturns the exponent value of this Decimal.
++x = new Decimal(1234.567) +x.exponent() // 3+ + + +
.gt(x) ⇒ booleanx: 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+ + + +
.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+ + + +
.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+ + + +
.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.
.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() ⇒ 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.
.lt(x) ⇒ booleanx: 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+ + + +
.lte(x) ⇒ booleanx: 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+ + + +
.log(x) ⇒ Decimalx: 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(x) ⇒ Decimalx: 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'+ + + +
.mod(x) ⇒ Decimalx: 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'+ + + +
.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.
+ + + +.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. +
+ + + +.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(x) ⇒ Decimalx: 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'+ + + +
.sd([include_zeros]) ⇒ numberReturns 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'+ + + +
.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(x) ⇒ Decimalx: 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'
+
+
+
+ .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([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([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'+ + + +
.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() ⇒ stringAs toString.
.toNumber() ⇒ numberReturns 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
+
+
+
+ .pow(x) ⇒ Decimalx: 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([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'+ + + +
.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() ⇒ stringReturns 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'
+
+
+
+ .val() ⇒ stringAs toString.
+ 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
+
+
+
+
+ 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) ) {
+ // ...
+ }
+}
+
+
+
+ + 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.
+