Class: BigDecimal

Defined in: bigdecimal.ts:473

Methods

abs()

abs(mc?): BigDecimal;

Defined in: bigdecimal.ts:3645

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

Parameters

mc?

MathContext

the context to use.

Returns

BigDecimal

absolute value, rounded as necessary.

---

add()

add(augend, mc?): BigDecimal;

Defined in: bigdecimal.ts:1871

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.

Parameters

augend

string | number | bigint | BigDecimal

value to be added to this BigDecimal. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

mc?

MathContext

the context to use.

Returns

BigDecimal

this + augend, rounded as necessary.

Example

Big('0.1').add('0.2').toString(); // '0.3'
Big('1.0').add('2.00').toString(); // '3.00' (scale is the max of the two)

---

byteValueExact()

byteValueExact(): number;

Defined in: bigdecimal.ts:3416

Converts this BigDecimal to an 8-bit integer number, checking for lost information. Faithful port of the JDK's byteValueExact(): throws if this BigDecimal has a nonzero fractional part or is out of the range [-128, 127].

Returns

number

this BigDecimal converted to a number.

Throws

RangeError if this has a nonzero fractional part or will not fit in an 8-bit integer.

---

clamp()

clamp(min, max): BigDecimal;

Defined in: bigdecimal.ts:4049

Returns this BigDecimal clamped to the range [min, max]: min if this is less than min, max if this is greater than max, and this otherwise. Comparison is by compareTo, so scale is ignored (0.0 fits the range ['0', '1']).

This is a JS-convention convenience with no java.math.BigDecimal equivalent (it mirrors Java 21's Math.clamp).

Parameters

min

string | number | bigint | BigDecimal

lower bound, inclusive. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

max

string | number | bigint | BigDecimal

upper bound, inclusive. Converted like min.

Returns

BigDecimal

this BigDecimal if it is within the range, otherwise the nearer of min and max.

Throws

RangeError if min is greater than max.

Example

Big('11.5').clamp(0, 10).toString(); // '10'
Big('-3').clamp('0.5', '10').toString(); // '0.5'
Big('7').clamp(0n, 10n).toString(); // '7'

---

compareTo()

compareTo(val): number;

Defined in: bigdecimal.ts:3142

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.

Parameters

val

string | number | bigint | BigDecimal

value to which this BigDecimal is to be compared. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

Returns

number

-1, 0, or 1 as this BigDecimal is numerically less than, equal to, or greater than val.

See

• sameValue
• greaterThan
• greaterThanOrEquals
• lowerThan
• lowerThanOrEquals

Example

Big('2.0').compareTo('2.00'); // 0 — equal in value, scale is ignored
Big('1').compareTo('2'); // -1
[Big('3'), Big('1'), Big('2')].sort((a, b) => a.compareTo(b)); // 1, 2, 3

---

divide()

divide(
   divisor, 
   scale?, 
   roundingMode?): BigDecimal;

Defined in: bigdecimal.ts:2044

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.

Parameters

divisor

string | number | bigint | BigDecimal

value by which this BigDecimal is to be divided. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

scale?

number

scale of the BigDecimal quotient to be returned.

roundingMode?

RoundingMode

rounding mode to apply.

Returns

BigDecimal

this / divisor

Throws

RangeError

• If divisor is zero
• If roundingMode==RoundingMode.UNNECESSARY and the specified scale is insufficient to represent the result of the division exactly.
• If scale is given but rounding mode is not given.

Example

Big('1').divide('4').toString(); // '0.25' — exact, terminates
Big('1').divide('3', 5, RoundingMode.HALF_UP).toString(); // '0.33333'
Big('1').divide('3'); // throws RangeError — non-terminating, no scale given

---

divideAndRemainder()

divideAndRemainder(divisor, mc?): [BigDecimal, BigDecimal];

Defined in: bigdecimal.ts:2738

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.

Parameters

divisor

string | number | bigint | BigDecimal

value by which this BigDecimal is to be divided, and the remainder computed. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

mc?

MathContext

the context to use.

Returns

[BigDecimal, BigDecimal]

a two element BigDecimal array: the quotient (the result of divideToIntegralValue) is the initial element and the remainder is the final element.

Throws

RangeError if divisor is 0

Throws

RangeError if the result is inexact but the rounding mode is UNNECESSARY, or mc.precision > 0 and the result of this.divideToIntegralValue(divisor) would require a precision of more than mc.precision digits.

See

• divideToIntegralValue
• remainder

---

divideToIntegralValue()

divideToIntegralValue(divisor, mc?): BigDecimal;

Defined in: bigdecimal.ts:2477

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.

Parameters

divisor

string | number | bigint | BigDecimal

value by which this BigDecimal is to be divided. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

mc?

MathContext

the context to use.

Returns

BigDecimal

The integer part of this / divisor.

Throws

RangeError if divisor is 0

Throws

RangeError if mc.precision > 0 and the result requires a precision of more than mc.precision digits.

---

divideWithMathContext()

divideWithMathContext(divisor, mc?): BigDecimal;

Defined in: bigdecimal.ts:2152

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

Parameters

divisor

string | number | bigint | BigDecimal

value by which this BigDecimal is to be divided. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

mc?

MathContext

the context to use.

Returns

BigDecimal

this / divisor

Throws

RangeError if the exact quotient does not have a terminating decimal expansion, including dividing by zero

Example

Big('1').divideWithMathContext('3', MC(5)).toString(); // '0.33333'
Big('1').divideWithMathContext('3', MC(5, RoundingMode.UP)).toString(); // '0.33334'

---

doubleValue()

doubleValue(): number;

Defined in: bigdecimal.ts:3324

Alias for numberValue under the JDK name BigDecimal.doubleValue(), for drop-in familiarity when porting Java code. JS number is an IEEE 754 double, so the semantics are identical.

Returns

number

this BigDecimal converted to a number.

See

numberValue

---

equals()

equals(value): boolean;

Defined in: bigdecimal.ts:2692

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.

Parameters

value

any

to which this BigDecimal is to be compared.

Returns

boolean

true if and only if the specified value is a BigDecimal whose value and scale are equal to this BigDecimal's.

See

compareTo

---

greaterThan()

greaterThan(val): boolean;

Defined in: bigdecimal.ts:3186

Alias for compareTo(val) > 0.

Parameters

val

string | number | bigint | BigDecimal

value to which this BigDecimal is to be compared. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

Returns

boolean

true if the value is greater than val

See

• compareTo
• gt

---

greaterThanOrEquals()

greaterThanOrEquals(val): boolean;

Defined in: bigdecimal.ts:3207

Alias for compareTo(val) >= 0.

Parameters

val

string | number | bigint | BigDecimal

value to which this BigDecimal is to be compared. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

Returns

boolean

true if the value is greater than or equals to val

See

• compareTo
• gte

---

gt()

gt(val): boolean;

Defined in: bigdecimal.ts:3193

Alias for greaterThan.

Parameters

val

string | number | bigint | BigDecimal

Returns

boolean

---

gte()

gte(val): boolean;

Defined in: bigdecimal.ts:3214

Alias for greaterThanOrEquals.

Parameters

val

string | number | bigint | BigDecimal

Returns

boolean

---

intValueExact()

intValueExact(): number;

Defined in: bigdecimal.ts:3380

Converts this BigDecimal to a 32-bit integer number, checking for lost information. Faithful port of the JDK's intValueExact(): throws if this BigDecimal has a nonzero fractional part or is out of the range [-2³¹, 2³¹-1].

Returns

number

this BigDecimal converted to a number.

Throws

RangeError if this has a nonzero fractional part or will not fit in a 32-bit integer.

Example

Big('42.000').intValueExact(); // 42
Big('42.5').intValueExact(); // throws RangeError

---

isNegative()

isNegative(): boolean;

Defined in: bigdecimal.ts:1391

Checks whether this BigDecimal is negative.

Returns

boolean

true if the value of this BigDecimal is less than zero, false otherwise.

---

isPositive()

isPositive(): boolean;

Defined in: bigdecimal.ts:1382

Checks whether this BigDecimal is positive.

Returns

boolean

true if the value of this BigDecimal is greater than zero, false otherwise.

---

isZero()

isZero(): boolean;

Defined in: bigdecimal.ts:1373

Checks whether this BigDecimal is zero.

Returns

boolean

true if the value of this BigDecimal is zero, false otherwise.

---

longValueExact()

longValueExact(): bigint;

Defined in: bigdecimal.ts:3348

Converts this BigDecimal to a bigint within Java long range, checking for lost information. Faithful port of the JDK's longValueExact(): throws if this BigDecimal has a nonzero fractional part or is out of the range [-2⁶³, 2⁶³-1].

Returns bigint rather than number because Java long exceeds the safe-integer range of number; see intValueExact for a number-returning variant.

Returns

bigint

this BigDecimal converted to a bigint.

Throws

RangeError if this has a nonzero fractional part or will not fit in a Java long.

Example

Big('123').longValueExact(); // 123n
Big('1e30').longValueExact(); // throws RangeError

---

lowerThan()

lowerThan(val): boolean;

Defined in: bigdecimal.ts:3228

Alias for compareTo(val) < 0.

Parameters

val

string | number | bigint | BigDecimal

value to which this BigDecimal is to be compared. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

Returns

boolean

true if the value is lower than val

See

• compareTo
• lt

---

lowerThanOrEquals()

lowerThanOrEquals(val): boolean;

Defined in: bigdecimal.ts:3249

Alias for compareTo(val) <= 0.

Parameters

val

string | number | bigint | BigDecimal

value to which this BigDecimal is to be compared. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

Returns

boolean

true if the value is lower than or equals to val

See

• compareTo
• lte

---

lt()

lt(val): boolean;

Defined in: bigdecimal.ts:3235

Alias for lowerThan.

Parameters

val

string | number | bigint | BigDecimal

Returns

boolean

---

lte()

lte(val): boolean;

Defined in: bigdecimal.ts:3256

Alias for lowerThanOrEquals.

Parameters

val

string | number | bigint | BigDecimal

Returns

boolean

---

max()

max(val): BigDecimal;

Defined in: bigdecimal.ts:4021

Returns the maximum of this BigDecimal and val.

Parameters

val

string | number | bigint | BigDecimal

value with which the maximum is to be computed. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

Returns

BigDecimal

the BigDecimal whose value is the greater of this BigDecimal and val. If they are equal, as defined by the compareTo method, this is returned.

See

compareTo

---

min()

min(val): BigDecimal;

Defined in: bigdecimal.ts:4004

Returns the minimum of this BigDecimal and val.

Parameters

val

string | number | bigint | BigDecimal

value with which the minimum is to be computed. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

Returns

BigDecimal

the BigDecimal whose value is the lesser of this BigDecimal and val. If they are equal, as defined by the compareTo method, this is returned.

See

compareTo

---

movePointLeft()

movePointLeft(n): BigDecimal;

Defined in: bigdecimal.ts:3960

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).

Parameters

n

number

number of places to move the decimal point to the left.

Returns

BigDecimal

a BigDecimal which is equivalent to this one with the decimal point moved n places to the left.

Throws

RangeError if scale overflows.

---

movePointRight()

movePointRight(n): BigDecimal;

Defined in: bigdecimal.ts:3983

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).

Parameters

n

number

number of places to move the decimal point to the right.

Returns

BigDecimal

a BigDecimal which is equivalent to this one with the decimal point moved n places to the right.

Throws

RangeError if scale overflows.

---

multiply()

multiply(multiplicand, mc?): BigDecimal;

Defined in: bigdecimal.ts:1986

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

Parameters

multiplicand

string | number | bigint | BigDecimal

value to be multiplied by this BigDecimal. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

mc?

MathContext

the context to use.

Returns

BigDecimal

this * multiplicand, rounded as necessary.

Example

Big('19.99').multiply(3).toString(); // '59.97'
Big('1.5').multiply('1.5').toString(); // '2.25' (scale is the sum of the two)

---

negate()

negate(mc?): BigDecimal;

Defined in: bigdecimal.ts:1841

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

Parameters

mc?

MathContext

the context to use.

Returns

BigDecimal

-this, rounded as necessary.

---

numberValue()

numberValue(): number;

Defined in: bigdecimal.ts:3267

Converts this BigDecimal to number.

Returns

number

number for of this BigDecimal

---

numberValueExact()

numberValueExact(): number;

Defined in: bigdecimal.ts:3308

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

number

a number that converts back to a BigDecimal equal to this one.

Throws

RangeError if this BigDecimal has no exact number representation.

---

plus()

plus(mc?): BigDecimal;

Defined in: bigdecimal.ts:3545

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.

Parameters

mc?

MathContext

the context to use.

Returns

BigDecimal

this, rounded as necessary. A zero result will have a scale of 0.

See

round

---

pow()

pow(n, mc?): BigDecimal;

Defined in: bigdecimal.ts:3594

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.

Parameters

n

number

power to raise this BigDecimal to.

mc?

MathContext

the context to use.

Returns

BigDecimal

thisn using the ANSI standard X3.274-1996 algorithm

Throws

RangeError if the result is inexact but the rounding mode is UNNECESSARY, or n is out of range.

---

precision()

precision(): number;

Defined in: bigdecimal.ts:1521

Returns

number

---

remainder()

remainder(divisor, mc?): BigDecimal;

Defined in: bigdecimal.ts:2594

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).

Parameters

divisor

string | number | bigint | BigDecimal

value by which this BigDecimal is to be divided. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

mc?

MathContext

the context to use.

Returns

BigDecimal

this % divisor, rounded as necessary.

Throws

RangeError if divisor is 0

Throws

RangeError if the result is inexact but the rounding mode is UNNECESSARY, or mc.precision > 0 and the result of this.divideToIntegralValue(divisor) would require a precision of more than mc.precision digits.

See

divideToIntegralValue

---

round()

round(mc): BigDecimal;

Defined in: bigdecimal.ts:3445

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.

Parameters

mc

MathContext

the context to use.

Returns

BigDecimal

a BigDecimal rounded according to the MathContext settings.

See

plus

Example

Big('123.456').round(MC(4)).toString(); // '123.5' — 4 significant digits
Big('123.456').round(MC(2, RoundingMode.FLOOR)).toString(); // '1.2E+2'

---

sameValue()

sameValue(val): boolean;

Defined in: bigdecimal.ts:3172

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

Parameters

val

string | number | bigint | BigDecimal

Returns

boolean

true if the value is the same as val

See

• equals
• compareTo

---

scale()

scale(): number;

Defined in: bigdecimal.ts:3090

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

number

the scale of this BigDecimal.

---

scaleByPowerOfTen()

scaleByPowerOfTen(n): BigDecimal;

Defined in: bigdecimal.ts:3104

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

Parameters

n

number

the exponent power of ten to scale by

Returns

BigDecimal

a BigDecimal whose numerical value is equal to (this * 10ⁿ)

Throws

RangeError if the scale would be outside the range of a safe integer.

---

setScale()

setScale(newScale, roundingMode?): BigDecimal;

Defined in: bigdecimal.ts:3477

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.

Parameters

newScale

number

scale of the BigDecimal value to be returned.

roundingMode?

RoundingMode = RoundingMode.UNNECESSARY

The rounding mode to apply. By default it is set to UNNECESSARY.

Returns

BigDecimal

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.

Throws

RangeError if roundingMode is UNNECESSARY and the specified scaling operation would require rounding.

See

RoundingMode

Example

Big('2.345').setScale(2, RoundingMode.HALF_UP).toString(); // '2.35'
Big('2').setScale(2).toString(); // '2.00' — add trailing zeros (exact, no rounding)
Big('2.345').setScale(2, RoundingMode.HALF_EVEN).toString(); // '2.34'

---

shortValueExact()

shortValueExact(): number;

Defined in: bigdecimal.ts:3398

Converts this BigDecimal to a 16-bit integer number, checking for lost information. Faithful port of the JDK's shortValueExact(): throws if this BigDecimal has a nonzero fractional part or is out of the range [-32768, 32767].

Returns

number

this BigDecimal converted to a number.

Throws

RangeError if this has a nonzero fractional part or will not fit in a 16-bit integer.

---

signum()

signum(): number;

Defined in: bigdecimal.ts:1358

Returns the signum function of this BigDecimal.

Returns

number

-1, 0, or 1 as the value of this BigDecimal is negative, zero, or positive.

---

sqrt()

sqrt(mc): BigDecimal;

Defined in: bigdecimal.ts:2772

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.

Parameters

mc

MathContext

the context to use.

Returns

BigDecimal

the square root of this.

Throws

RangeError if this is less than zero.

Throws

RangeError if an exact result is requested mc.getPrecision() is 0 and there is no finite decimal expansion of the exact result

Throws

RangeError if mc.getRoundingMode() is RoundingMode.UNNECESSARY and the exact result cannot fit in mc.getPrecision() digits.

---

stripTrailingZeros()

stripTrailingZeros(): BigDecimal;

Defined in: bigdecimal.ts:3049

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

BigDecimal

a numerically equal BigDecimal with any trailing zeros removed.

Throws

RangeError if scale from max or min safe integer range.

---

subtract()

subtract(subtrahend, mc?): BigDecimal;

Defined in: bigdecimal.ts:1943

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).

Parameters

subtrahend

string | number | bigint | BigDecimal

value to be subtracted from this BigDecimal. This value will be converted to a BigDecimal before the operation. See the constructor to learn more about the conversion.

mc?

MathContext

the context to use.

Returns

BigDecimal

this - subtrahend, rounded as necessary.

Example

Big('0.3').subtract('0.1').toString(); // '0.2'

---

toBigInt()

toBigInt(): bigint;

Defined in: bigdecimal.ts:4578

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.

Returns

bigint

this BigDecimal converted to a BigInt.

---

toBigInteger()

toBigInteger(): bigint;

Defined in: bigdecimal.ts:4604

Alias for toBigInt under the JDK name BigDecimal.toBigInteger(), for drop-in familiarity when porting Java code.

Returns

bigint

this BigDecimal converted to a BigInt.

See

toBigInt

---

toBigIntegerExact()

toBigIntegerExact(): bigint;

Defined in: bigdecimal.ts:4617

Alias for toBigIntExact under the JDK name BigDecimal.toBigIntegerExact(), for drop-in familiarity when porting Java code.

Returns

bigint

this BigDecimal converted to a BigInt.

Throws

RangeError if this has a nonzero fractional part.

See

toBigIntExact

---

toBigIntExact()

toBigIntExact(): bigint;

Defined in: bigdecimal.ts:4591

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

Returns

bigint

this BigDecimal converted to a BigInt.

Throws

RangeError if this has a nonzero fractional part.

---

toEngineeringString()

toEngineeringString(): string;

Defined in: bigdecimal.ts:4199

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

string

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

---

toExponential()

toExponential(fractionDigits?, roundingMode?): string;

Defined in: bigdecimal.ts:4462

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).

Parameters

fractionDigits?

number

number of digits after the decimal point; a non-negative integer. If omitted, minimal digits are used.

roundingMode?

RoundingMode = RoundingMode.HALF_UP

rounding mode to apply. Defaults to RoundingMode.HALF_UP.

Returns

string

an exponential-notation string representation of this BigDecimal.

Throws

RangeError if fractionDigits is given and is not a non-negative integer.

---

toFixed()

toFixed(fractionDigits?, roundingMode?): string;

Defined in: bigdecimal.ts:4442

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).

Parameters

fractionDigits?

number = 0

number of digits after the decimal point; a non-negative integer. Defaults to 0.

roundingMode?

RoundingMode = RoundingMode.HALF_UP

rounding mode to apply. Defaults to RoundingMode.HALF_UP.

Returns

string

a fixed-point string representation of this BigDecimal.

Throws

RangeError if fractionDigits is not a non-negative integer.

Example

Big('1234.56789').toFixed(2); // '1234.57'
Big('2.5').toFixed(0, RoundingMode.HALF_EVEN); // '2' — banker's rounding
Big('1').toFixed(3); // '1.000'

---

toFormat()

toFormat(locales?, options?): string;

Defined in: bigdecimal.ts:4552

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.

Parameters

locales?

string | string[]

BCP 47 locale string(s), as accepted by Intl.NumberFormat.

options?

NumberFormatOptions

Intl.NumberFormatOptions; values here override the defaults above.

Returns

string

a locale-formatted string representation of this BigDecimal.

Example

Big('1234.5').toFormat('en-US'); // '1,234.5'
Big('1234.5').toFormat('de-DE'); // '1.234,5'
Big('1234.5').toFormat('en-US', { style: 'currency', currency: 'USD' }); // '$1,234.50'

---

toJSON()

toJSON(): string;

Defined in: bigdecimal.ts:4651

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

string

a string representation of this BigDecimal without an exponent field.

See

• toPlainString
• toString
• toEngineeringString

---

toPlainString()

toPlainString(): string;

Defined in: bigdecimal.ts:4342

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

string

a string representation of this BigDecimal without an exponent field.

See

• toString
• toEngineeringString

---

toPrecision()

toPrecision(precision?, roundingMode?): string;

Defined in: bigdecimal.ts:4503

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).

Parameters

precision?

number

number of significant digits; a positive integer. If omitted, toString is returned.

roundingMode?

RoundingMode = RoundingMode.HALF_UP

rounding mode to apply. Defaults to RoundingMode.HALF_UP.

Returns

string

a string representation of this BigDecimal with precision significant digits.

Throws

RangeError if precision is given and is not a positive integer.

---

toString()

toString(): string;

Defined in: bigdecimal.ts:4147

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

string

string representation of this BigDecimal.

---

ulp()

ulp(): BigDecimal;

Defined in: bigdecimal.ts:3023

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

BigDecimal

the size of an ulp of this

---

unscaledValue()

unscaledValue(): bigint;

Defined in: bigdecimal.ts:3074

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

Returns

bigint

the unscaled value of this BigDecimal.