Package com.google.common.math

Class BigDecimalMath

java.lang.Object

com.google.common.math.BigDecimalMath

@GwtIncompatible
public final class BigDecimalMath
extends java.lang.Object

A class for arithmetic on BigDecimal that is not covered by its built-in methods.

Since:

30.0

Author:

Louis Wasserman

Method Summary

Modifier and Type	Method	Description
static double	roundToDouble(java.math.BigDecimal x, java.math.RoundingMode mode)	Returns x, rounded to a double with the specified rounding mode.
static java.math.BigInteger	toBigInteger(java.math.BigDecimal x, int maxIntegerDigits)	Returns x converted to a BigInteger, ensuring that the magnitude of x does not exceed maxIntegerDigits before performing conversion.
static java.math.BigInteger	toBigIntegerExact(java.math.BigDecimal x, int maxIntegerDigits)	Returns x converted to a BigInteger, checking that x has no fractional part and ensuring that the magnitude of x does not exceed maxIntegerDigits before performing conversion.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

toBigInteger

@Beta
public static java.math.BigInteger toBigInteger(java.math.BigDecimal x,
                                                int maxIntegerDigits)

Returns x converted to a BigInteger, ensuring that the magnitude of x does not exceed maxIntegerDigits before performing conversion.

Converting a BigDecimal with a very large negative scale to a BigInteger requires materializing the unscaled value multiplied by 10^-scale. When x is parsed from uncontrolled string or JSON inputs (such as "1e123456789"), directly calling BigDecimal.toBigInteger() or BigDecimal.toBigIntegerExact() can exhaust CPU and memory. This method safely verifies that the number of decimal digits required for the integer representation fits within maxIntegerDigits before conversion.

Choosing a reasonable value for maxIntegerDigits depends on the range of expected valid values for your input. A value of 100 is generally sufficient for most common use cases and provides a large safety margin against resource exhaustion from malicious inputs.

Parameters:

x - the BigDecimal to convert to a BigInteger

maxIntegerDigits - the maximum allowable number of digits in the integer part (for values where |x| < 1, the integer part is considered to have 0 digits)

Returns:

x converted to a BigInteger

Throws:

java.lang.IllegalArgumentException - if maxIntegerDigits < 0

java.lang.ArithmeticException - if the integer part of x requires more than maxIntegerDigits digits

Since:

33.7.0

toBigIntegerExact

@Beta
public static java.math.BigInteger toBigIntegerExact(java.math.BigDecimal x,
                                                     int maxIntegerDigits)

Returns x converted to a BigInteger, checking that x has no fractional part and ensuring that the magnitude of x does not exceed maxIntegerDigits before performing conversion.

Converting a BigDecimal with a very large negative scale to a BigInteger requires materializing the unscaled value multiplied by 10^-scale. When x is parsed from uncontrolled string or JSON inputs (such as "1e123456789"), directly calling BigDecimal.toBigInteger() or BigDecimal.toBigIntegerExact() can exhaust CPU and memory. This method safely verifies that the number of decimal digits required for the integer representation fits within maxIntegerDigits before conversion.

Choosing a reasonable value for maxIntegerDigits depends on the range of expected valid values for your input. A value of 100 is generally sufficient for most common use cases and provides a large safety margin against resource exhaustion from malicious inputs.

Parameters:

x - the BigDecimal to convert to a BigInteger

maxIntegerDigits - the maximum allowable number of digits in the integer part (for values where |x| < 1, the integer part is considered to have 0 digits)

Returns:

x converted to a BigInteger

Throws:

java.lang.IllegalArgumentException - if maxIntegerDigits < 0

java.lang.ArithmeticException - if x has a nonzero fractional part or if the integer part of x requires more than maxIntegerDigits digits

Since:

33.7.0

roundToDouble

public static double roundToDouble(java.math.BigDecimal x,
                                   java.math.RoundingMode mode)

Returns x, rounded to a double with the specified rounding mode. If x is precisely representable as a double, its double value will be returned; otherwise, the rounding will choose between the two nearest representable values with mode.

For the case of RoundingMode.HALF_DOWN, HALF_UP, and HALF_EVEN, infinite double values are considered infinitely far away. For example, 2^2000 is not representable as a double, but roundToDouble(BigDecimal.valueOf(2).pow(2000), HALF_UP) will return Double.MAX_VALUE, not Double.POSITIVE_INFINITY.

For the case of RoundingMode.HALF_EVEN, this implementation uses the IEEE 754 default rounding mode: if the two nearest representable values are equally near, the one with the least significant bit zero is chosen. (In such cases, both of the nearest representable values are even integers; this method returns the one that is a multiple of a greater power of two.)

Throws:

java.lang.ArithmeticException - if mode is RoundingMode.UNNECESSARY and x is not precisely representable as a double

Since:

30.0