Example

int logFloor = LongMath.log2(n, FLOOR);

int mustNotOverflow = IntMath.checkedMultiply(x, y);

long quotient = LongMath.divide(knownMultipleOfThree, 3, RoundingMode.UNNECESSARY); // fail fast on non-multiple of 3

BigInteger nearestInteger = DoubleMath.roundToBigInteger(d, RoundingMode.HALF_EVEN);

BigInteger sideLength = BigIntegerMath.sqrt(area, CEILING);

Why?

• Guava's math utilities are already exhaustively tested for unusual overflow conditions. Overflow semantics, if relevant, are clearly specified in the associated documentation. When a precondition fails, it fails fast.
• Guava's math utilities have been painstakingly benchmarked and optimized. While performance inevitably varies depending on particular hardware details, their speed is competitive with -- and in some cases, significantly better than -- analogous functions in Apache Commons MathUtils.
  • Guava's math utilities are designed to encourage readable, correct programming habits. The meaning of IntMath.log2(x, CEILING) is unambiguous and obvious even on a casual read-through. The meaning of 32 - Integer.numberOfLeadingZeros(x - 1) is not.

Note: Guava's math utilities are not especially compatible with GWT, nor are they optimized for GWT, due to differing overflow logic.

Math on Integral Types

Guava's math utilities deal primarily with three integral types: int, long, and BigInteger. The math utilities on these types are conveniently named IntMath, LongMath, and BigIntegerMath.

Checked Arithmetic

Guava provides arithmetic methods for IntMath and LongMath that fail fast on overflow instead of silently ignoring it.

IntMath.checkedAdd(Integer.MAX_VALUE, Integer.MAX_VALUE); // throws ArithmeticException

Real-valued methods

IntMath, LongMath, and BigIntegerMath have support for a variety of methods with a "precise real value," but that round their result to an integer. These methods accept a java.math.RoundingMode. This is the same RoundingMode used in the JDK, and is an enum with the following values:

• DOWN: round towards 0. (This is the behavior of Java division.)
• UP: round away from 0.
  • FLOOR: round towards negative infinity.
  • CEILING: round towards positive infinity.
  • UNNECESSARY: rounding should not be necessary; if it is, fail fast by throwing an ArithmeticException.
  • HALF_UP: round to the nearest half, rounding x.5 away from 0.
  • HALF_DOWN: round to the nearest half, rounding x.5 towards 0.
  • HALF_EVEN: round to the nearest half, rounding x.5 to its nearest even neighbor.

These methods are meant to be readable when used: for example, divide(x, 3, CEILING) is completely unambiguous even on a casual read-through.

Additionally, each of these functions internally use only integer arithmetic, except in constructing initial approximations for use in sqrt.

BigIntegerMath.sqrt(BigInteger.TEN.pow(99), RoundingMode.HALF_EVEN);
   // returns 31622776601683793319988935444327185337195551393252

Additional functions

We provide support for a few other mathematical functions we've found useful.

Floating-point arithmetic

Floating point arithmetic is pretty thoroughly covered by the JDK, but we added a few useful methods to DoubleMath.