Class BigDecimal

Returns a BigDecimal whose value is the absolute value of this BigDecimal, with rounding according to the context settings.

Returns a BigDecimal whose value is (this + augend), with rounding according to the context settings.

If either number is zero and the precision setting is nonzero then the other number, rounded if necessary, is used as the result.

Compares this BigDecimal numerically with the specified BigDecimal. Two BigDecimal objects that are equal in value but have a different scale (like 2.0 and 2.00) are considered equal by this method. Such values are in the same cohort.

This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=). The suggested idiom for performing these comparisons is: (x.compareTo(y) <op> 0), where <op> is one of the six comparison operators.

Returns a BigDecimal whose value is (this / divisor), and whose scale is as specified. If rounding must be performed to generate a result with the specified scale, the specified rounding mode is applied.

Returns a two-element BigDecimal array containing the result of divideToIntegralValue followed by the result of remainder on the two operands calculated with rounding according to the context settings.

Note that if both the quotient and remainder are needed, this method is faster than using the divideToIntegralValue and remainder methods separately because the division need only be carried out once.

Returns a BigDecimal whose value is the integer part of (this / divisor). Since the integer part of the exact quotient does not depend on the rounding mode, the rounding mode does not affect the values returned by this method. The preferred scale of the result is (this.scale() - divisor.scale()). A RangeError is thrown if the integer part of the exact quotient needs more than mc.precision digits.

Returns a BigDecimal whose value is (this / divisor), with rounding according to the context settings.

Compares this BigDecimal with the specified object for equality. Unlike compareTo, this method considers two BigDecimal objects equal only if they are equal in value and scale. Therefore 2.0 is not equal to 2.00 when compared by this method since the former has [BigInt, scale] components equal to [20, 1] while the latter has components equal to [200, 2].

One example that shows how 2.0 and 2.00 are not substitutable for each other under some arithmetic operations are the two expressions:

Big("2.0" ).divide(Big(3), undefined, HALF_UP) // which evaluates to 0.7

Big("2.00").divide(Big(3), undefined, HALF_UP) // which evaluates to 0.67.
Copy

Alias for compareTo(val) > 0.

Alias for compareTo(val) >= 0.

Alias for greaterThan.

Alias for greaterThanOrEquals.

Checks whether this BigDecimal is negative.

Checks whether this BigDecimal is positive.

Checks whether this BigDecimal is zero.

Alias for compareTo(val) < 0.

Alias for compareTo(val) <= 0.

Alias for lowerThan.

Alias for lowerThanOrEquals.

Returns the maximum of this BigDecimal and val.

Returns the minimum of this BigDecimal and val.

Returns a BigDecimal which is equivalent to this one with the decimal point moved n places to the left. If n is non-negative, the call merely adds n to the scale. If n is negative, the call is equivalent to movePointRight(-n). The BigDecimal returned by this call has value (this × 10-n) and scale max(this.scale()+n, 0).

Returns a BigDecimal which is equivalent to this one with the decimal point moved n places to the right. If n is non-negative, the call merely subtracts n from the scale. If n is negative, the call is equivalent to movePointLeft(-n). The BigDecimal returned by this call has value (this × 10n) and scale max(this.scale()-n, 0).

Returns a BigDecimal whose value is (this × multiplicand), with rounding according to the context settings.

Returns a BigDecimal whose value is (-this), with rounding according to the context settings.

Converts this BigDecimal to number.

Converts this BigDecimal to a number, throwing an error if any information would be lost. This is the safe counterpart of numberValue, which silently rounds to the nearest number; analogous to Java's *ValueExact family (compare toBigIntExact).

The conversion is considered exact when converting the returned number back to a BigDecimal yields a value equal to this one, i.e. Big(this.numberValueExact()) equals this by compareTo.

Returns a BigDecimal whose value is (+this), with rounding according to the context settings.

The effect of this method is identical to that of the round method.

Returns a BigDecimal whose value is (thisn). The current implementation uses the core algorithm defined in ANSI standard X3.274-1996 with rounding according to the context settings. In general, the returned numerical value is within two ulps of the exact numerical value for the chosen precision.

The X3.274-1996 algorithm is:

• An RangeError exception is thrown if

  • abs(n) > 999999999
  • mc.precision == 0 and n < 0
  • mc.precision > 0 and n has more than mc.precision decimal digits

• if n is zero, a BigDecimal with value 1 is returned even if this is zero, otherwise

  • if n is positive, the result is calculated via the repeated squaring technique into a single accumulator. The individual multiplications with the accumulator use the same math context settings as in mc except for a precision increased to mc.precision + elength + 1 where elength is the number of decimal digits in n.

  • if n is negative, the result is calculated as if n were positive; this value is then divided into one using the working precision specified above.

  • The final value from either the positive or negative case is then rounded to the destination precision.

Returns a BigDecimal whose value is (this % divisor), with rounding according to the context settings. The MathContext settings affect the implicit divide used to compute the remainder. The remainder computation itself is by definition exact. Therefore, the remainder may contain more than mc.getPrecision() digits.

The remainder is given by this.subtract(this.divideToIntegralValue(divisor, mc).multiply(divisor)). Note that this is not the modulo operation (the result can be negative).

Returns a BigDecimal rounded according to the MathContext settings. If the precision setting is 0 then no rounding takes place.

The effect of this method is identical to that of the plus method.

Alias for compareTo(val) === 0. Consider using equals in case the scale needs to be considered.

Returns the scale of this BigDecimal. If zero or positive, the scale is the number of digits to the right of the decimal point. If negative, the unscaled value of the number is multiplied by ten to the power of the negation of the scale. For example, a scale of -3 means the unscaled value is multiplied by 1000.

The scale will be kept in the integer range, if cannot error will be thrown.

Returns a BigDecimal whose numerical value is equal to (this * 10ⁿ). The scale of the result is (this.scale() - n).

Returns a BigDecimal whose scale is the specified value, and whose unscaled value is determined by multiplying or dividing this BigDecimal's unscaled value by the appropriate power of ten to maintain its overall value. If the scale is reduced by the operation, the unscaled value must be divided (rather than multiplied), and the value may be changed; in this case, the specified rounding mode is applied to the division.

Returns the signum function of this BigDecimal.

Returns an approximation to the square root of this with rounding according to the context settings.

The preferred scale of the returned result is equal to this.scale()/2. The value of the returned result is always within one ulp of the exact decimal value for the precision in question. If the rounding mode is RoundingMode.HALF_UP, RoundingMode.HALF_DOWN, or RoundingMode.HALF_EVEN, the result is within one half an ulp of the exact decimal value.

Returns a BigDecimal which is numerically equal to this one but with any trailing zeros removed from the representation. For example, stripping the trailing zeros from the BigDecimal value 600.0, which has [BigInt, scale] components equal to [6000n, 1], yields 6E2 with [BigInt, scale] components equal to [6n, -2].

Returns a BigDecimal whose value is (this - subtrahend), with rounding according to the context settings.

If subtrahend is zero then this, rounded if necessary, is used as the result. If this is zero then the result is subtrahend.negate(mc).

Converts this BigDecimal to a BigInt. Any fractional part of this will be discarded. Note that this conversion can lose information about the precision of the BigDecimal value.

To have an exception thrown if the conversion is inexact (in other words if a nonzero fractional part is discarded), use the toBigIntExact method.

Converts this BigDecimal to a BigInt, checking for lost information. An exception is thrown if this BigDecimal has a nonzero fractional part.

Returns a string representation of this BigDecimal, using engineering notation if an exponent is needed.

Returns a string that represents the BigDecimal as described in the toString method, except that if exponential notation is used, the power of ten is adjusted to be a multiple of three (engineering notation) such that the integer part of nonzero values will be in the range 1 through 999. If exponential notation is used for zero values, a decimal point and one or two fractional zero digits are used so that the scale of the zero value is preserved. Note that unlike the output of toString, the output of this method is not guaranteed to recover the same [number, scale] pair of this BigDecimal if the output string is converting back to a BigDecimal using the string constructor. The result of this method meets the weaker constraint of always producing a numerically equal result from applying the string constructor to the method's output.

Returns this BigDecimal in JS exponential notation, e.g. "1.2345e+3" (mirrors Number.prototype.toExponential, but exact). If fractionDigits is given there are exactly that many digits after the point; if omitted, as many digits as needed to represent the value uniquely are used. Rounding uses roundingMode (default HALF_UP).

Returns a string with exactly fractionDigits digits after the decimal point, never using exponent notation (mirrors Number.prototype.toFixed, but exact). Rounding uses roundingMode (default HALF_UP).

Formats this BigDecimal for humans using the built-in Intl.NumberFormat, so grouping separators, decimal marks, currency and percent formatting all follow the given locale. The value is passed to Intl as a string, so no precision is lost on the integer part.

By default every decimal place the value has is shown (Intl otherwise caps at 3). When options.style is 'currency' or 'percent', Intl's own fraction-digit rules apply instead. Anything you set in options overrides these defaults.

Note: full-precision string formatting requires a modern runtime (Node >= 20 or a current browser); older engines than the library's stated floor may format the string as a float.

Returns a string representation of this BigDecimal without an exponent field. For values with a positive scale, the number of digits to the right of the decimal point is used to indicate scale. For values with a zero or negative scale, the resulting string is generated as if the value were converted to a numerically equal value with zero scale and as if all the trailing zeros of the zero scale value were present in the result.

The entire string is prefixed by a minus sign character '-' ('\u002D') if the unscaled value is less than zero. No sign character is prefixed if the unscaled value is zero or positive.

Note that if the result of this method is passed to the string constructor, only the numerical value of this BigDecimal will necessarily be recovered; the representation of the new BigDecimal may have a different scale. In particular, if this BigDecimal has a negative scale, the string resulting from this method will have a scale of zero when processed by the string constructor.

Returns a string representation of this BigDecimal without an exponent field. For values with a positive scale, the number of digits to the right of the decimal point is used to indicate scale. For values with a zero or negative scale, the resulting string is generated as if the value were converted to a numerically equal value with zero scale and as if all the trailing zeros of the zero scale value were present in the result.

The entire string is prefixed by a minus sign character '-' ('\u002D') if the unscaled value is less than zero. No sign character is prefixed if the unscaled value is zero or positive.

Note that if the result of this method is passed to the string constructor, only the numerical value of this BigDecimal will necessarily be recovered; the representation of the new BigDecimal may have a different scale. In particular, if this BigDecimal has a negative scale, the string resulting from this method will have a scale of zero when processed by the string constructor.

Returns this BigDecimal rounded to precision significant digits, using fixed or exponential notation as Number.prototype.toPrecision would (exact rounding, no float error). If precision is omitted, this is equivalent to toString. Rounding uses roundingMode (default HALF_UP).

Returns the string representation of this BigDecimal, using scientific notation if an exponent is needed.

A standard canonical string form of the BigDecimal is created as though by the following steps: first, the absolute value of the unscaled value of the BigDecimal is converted to a string in base ten using the characters '0' through '9' with no leading zeros (except if its value is zero, in which case a single '0' character is used).

Next, an adjusted exponent is calculated; this is the negated scale, plus the number of characters in the converted unscaled value, less one. That is, -scale+(ulength-1), where ulength is the length of the absolute value of the unscaled value in decimal digits (its precision).

If the scale is greater than or equal to zero and the adjusted exponent is greater than or equal to -6, the number will be converted to a character form without using exponential notation. In this case, if the scale is zero then no decimal point is added and if the scale is positive a decimal point will be inserted with the scale specifying the number of characters to the right of the decimal point. '0' characters are added to the left of the converted unscaled value as necessary. If no character precedes the decimal point after this insertion then a conventional '0' character is prefixed.

Otherwise (that is, if the scale is negative, or the adjusted exponent is less than -6), the number will be converted to a character form using exponential notation. In this case, if the converted BigInt has more than one digit a decimal point is inserted after the first digit. An exponent in character form is then suffixed to the converted unscaled value (perhaps with inserted decimal point); this comprises the letter 'E' followed immediately by the adjusted exponent converted to a character form. The latter is in base ten, using the characters '0' through '9' with no leading zeros, and is always prefixed by a sign character '-' ('\u002D') if the adjusted exponent is negative, '+' ('\u002B') otherwise).

Finally, the entire string is prefixed by a minus sign character '-' ('\u002D') if the unscaled value is less than zero. No sign character is prefixed if the unscaled value is zero or positive.

Examples: For each representation [unscaled value, scale] on the left, the resulting string is shown on the right.

[123,0]      "123"
[-123,0]     "-123"
[123,-1]     "1.23E+3"
[123,-3]     "1.23E+5"
[123,1]      "12.3"
[123,5]      "0.00123"
[123,10]     "1.23E-8"
[-123,12]    "-1.23E-10"

Notes:

• There is a one-to-one mapping between the distinguishable BigDecimal values and the result of this conversion. That is, every distinguishable BigDecimal value (unscaled value and scale) has a unique string representation as a result of using toString. If that string representation is converted back to a BigDecimal using the string constructor, then the original value will be recovered.

• The toEngineeringString method may be used for presenting numbers with exponents in engineering notation, and the setScale method may be used for rounding a BigDecimal so it has a known number of digits after the decimal point.

Returns the size of an ulp, a unit in the last place, of this BigDecimal. An ulp of a nonzero BigDecimal value is the positive distance between this value and the BigDecimal value next larger in magnitude with the same number of digits. An ulp of a zero value is numerically equal to 1 with the scale of this. The result is stored with the same scale as this so the result for zero and nonzero values is equal to [1, this.scale()].

Returns a BigInt whose value is the unscaled value of this BigDecimal. (Computes (this * 10this.scale()).)