Class BigDecimalMath

java.lang.Object
com.google.common.math.BigDecimalMath
@GwtIncompatible public final class BigDecimalMath extends Object
A class for arithmetic on BigDecimal that is not covered by its built-in methods.
Since:
30.0
Author:
Louis Wasserman

  • Method Details

    • toBigInteger

      @Beta public static BigInteger toBigInteger(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:
      IllegalArgumentException - if maxIntegerDigits < 0
      ArithmeticException - if the integer part of x requires more than maxIntegerDigits digits
      Since:
      NEXT

    • toBigIntegerExact

      @Beta public static BigInteger toBigIntegerExact(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:
      IllegalArgumentException - if maxIntegerDigits < 0
      ArithmeticException - if x has a nonzero fractional part or if the integer part of x requires more than maxIntegerDigits digits
      Since:
      NEXT

    • roundToDouble

      public static double roundToDouble(BigDecimal x, 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:
      ArithmeticException - if mode is RoundingMode.UNNECESSARY and x is not precisely representable as a double
      Since:
      30.0