# How to Use Guava's Math Utilities: IntMath, LongMath, and BigIntegerMath

> Learn how to use Guava's math utilities like IntMath, LongMath, and BigIntegerMath for overflow-safe arithmetic, rounding division, and combinatorial operations. Enhance your Java code with these powerful tools.

- Repository: [Google/guava](https://github.com/google/guava)
- Tags: how-to-guide
- Published: 2026-08-08

---

**Guava's math utilities provide overflow-safe arithmetic, rounding-mode aware division, and combinatorial operations for `int`, `long`, and `BigInteger` types through the static classes `IntMath`, `LongMath`, and `BigIntegerMath` in the `com.google.common.math` package.**

The `google/guava` library extends Java's standard mathematical capabilities with production-grade utilities designed to prevent integer overflow and support precise rounding control. Guava's math utilities target the three primary integer representations—primitive `int`, primitive `long`, and arbitrary-precision `BigInteger`—through immutable, stateless utility classes that implement algorithms from *Hacker's Delight* for maximum performance.

## Core Classes in the Math Package

The `com.google.common.math` package organizes functionality into three final classes with private constructors, enforcing static usage patterns:

- **`IntMath`** – Located in [`IntMath.java`](https://github.com/google/guava/blob/main/IntMath.java), this class provides safe `int` arithmetic including checked addition, saturated multiplication, binomial coefficients, factorials, and base-2 logarithms. It delegates prime testing operations to `LongMath`.
- **`LongMath`** – Implemented in [`LongMath.java`](https://github.com/google/guava/blob/main/LongMath.java), this class mirrors the `IntMath` API across the 64-bit `long` range and adds Miller-Rabin primality testing via the `isPrime(long)` method.
- **`BigIntegerMath`** – Found in [`BigIntegerMath.java`](https://github.com/google/guava/blob/main/BigIntegerMath.java), this class offers unlimited-precision mathematics including `sqrt`, `log2`, and power operations that accept `RoundingMode` parameters while relying on `java.math.BigInteger` for underlying calculations.

## Overflow-Safe Arithmetic Operations

All three classes provide **overflow-aware APIs** that eliminate ambiguity when calculations exceed type limits. The utilities offer two distinct safety strategies:

- **Checked operations** – Methods like `checkedAdd`, `checkedMultiply`, and `checkedPow` throw an `ArithmeticException` immediately when detecting overflow.
- **Saturated operations** – Methods like `saturatedAdd` and `saturatedMultiply` return `Integer.MAX_VALUE` or `Integer.MIN_VALUE` (and their `long` equivalents) instead of throwing, matching the behavior of Google’s C++ math utilities.

In [`IntMath.java`](https://github.com/google/guava/blob/main/IntMath.java), the `binomial(int n, int k)` method exemplifies this safety by returning `Integer.MAX_VALUE` when the result overflows, while `LongMath.factorial(int n)` returns `Long.MAX_VALUE` for out-of-range results.

## Rounding-Mode Aware Division and Roots

Unlike Java’s standard division operators, Guava’s math utilities accept `java.math.RoundingMode` arguments to specify exact rounding behavior. The `divide(int, int, RoundingMode)` method in [`IntMath.java`](https://github.com/google/guava/blob/main/IntMath.java) and its counterparts in `LongMath` and `BigIntegerMath` implement the same rounding rules as `java.math.BigDecimal`.

Available rounding strategies include `CEILING`, `FLOOR`, `DOWN`, `UP`, `HALF_EVEN`, `HALF_UP`, and `HALF_DOWN`. For example, dividing 7 by 3 with `RoundingMode.CEILING` yields 3, while `RoundingMode.FLOOR` yields 2.

## Combinatorial and Logarithmic Functions

The utilities provide optimized implementations of computationally expensive operations:

- **`factorial(int n)`** – Computes n! with overflow checking, available in all three classes.
- **`binomial(int n, int k)`** – Calculates binomial coefficients using multiplicative formulas that avoid intermediate overflow where possible.
- **`log2(int x, RoundingMode mode)`** – Computes base-2 logarithms with specified rounding, implemented using bit manipulation tricks from [`IntMath.java`](https://github.com/google/guava/blob/main/IntMath.java) and [`LongMath.java`](https://github.com/google/guava/blob/main/LongMath.java).
- **`sqrt(BigInteger x, RoundingMode mode)`** – Provides integer square roots with exact rounding control in [`BigIntegerMath.java`](https://github.com/google/guava/blob/main/BigIntegerMath.java).

## Practical Code Examples

```java
import com.google.common.math.IntMath;
import com.google.common.math.LongMath;
import com.google.common.math.BigIntegerMath;
import java.math.BigInteger;
import java.math.RoundingMode;

// 1. Basic overflow-checked arithmetic with int
int a = Integer.MAX_VALUE - 10;
int b = 20;
int sum = IntMath.checkedAdd(a, b); // throws ArithmeticException

// 2. Compute a binomial coefficient safely
int binom = IntMath.binomial(30, 5); // Returns Integer.MAX_VALUE if overflow occurs

// 3. Rounding division with specific mode
int ceilDiv = IntMath.divide(7, 3, RoundingMode.CEILING); // → 3

// 4. Long-wide factorial with overflow handling
long fact20 = LongMath.factorial(20); // Returns actual value or Long.MAX_VALUE if overflow

// 5. Prime testing for long values
boolean isPrime = LongMath.isPrime(1_000_003L); // Miller-Rabin implementation

// 6. Unlimited-precision operations
BigInteger big = new BigInteger("12345678901234567890");
BigInteger sqrt = BigIntegerMath.sqrt(big, RoundingMode.FLOOR);
BigInteger pow = BigIntegerMath.pow(BigInteger.valueOf(2), 100); // 2^100

```

## Source Implementation Details

The concrete implementations in the `google/guava` repository reveal performance optimizations and safety checks:

- **[`IntMath.java`](https://github.com/google/guava/blob/main/IntMath.java)** – Uses branch-free bit tricks like `lessThanBranchFree` and `isPowerOfTwo` for speed. All public methods validate inputs via `MathPreconditions` before performing calculations.
- **[`LongMath.java`](https://github.com/google/guava/blob/main/LongMath.java)** – Implements Miller-Rabin primality testing with deterministic bases for 64-bit values. The `factorial` method switches to precomputed tables for small inputs.
- **[`BigIntegerMath.java`](https://github.com/google/guava/blob/main/BigIntegerMath.java)** – Delegates heavy computation to `java.math.BigInteger` while adding rounding logic that mirrors the primitive math classes, ensuring API consistency across type boundaries.

## Summary

- **Guava's math utilities** in `com.google.common.math` provide `IntMath`, `LongMath`, and `BigIntegerMath` for type-specific arithmetic.
- **Overflow handling** comes in two flavors: checked (throws exception) and saturated (returns max/min value).
- **Rounding control** via `RoundingMode` parameters enables precise division and root operations consistent with `BigDecimal` semantics.
- **Performance optimizations** include bit-level tricks from *Hacker's Delight* and precomputed tables for factorials.
- **Thread safety** is guaranteed by final classes with static methods and no mutable state.

## Frequently Asked Questions

### What is the difference between checked and saturated arithmetic in Guava?

**Checked operations** like `IntMath.checkedAdd()` throw an `ArithmeticException` when overflow is detected, immediately signaling calculation errors. **Saturated operations** like `IntMath.saturatedAdd()` return the maximum or minimum value for the type (`Integer.MAX_VALUE` or `Integer.MIN_VALUE`) instead of throwing, allowing computations to continue with boundary values.

### Which Guava math class should I use for my data type?

Use **`IntMath`** when working with `int` values that require fast operations without boxing overhead. Choose **`LongMath`** when values might exceed the 32-bit `int` range but fit within 64-bit `long` primitives, especially for prime testing or larger combinatorial calculations. Select **`BigIntegerMath`** when dealing with arbitrarily large integers such as cryptographic keys or massive combinatorial results that exceed `long` capacity.

### How do rounding modes work in Guava's division methods?

Guava's `divide` methods in all three classes accept a `java.math.RoundingMode` parameter that specifies how to handle fractional results. For example, `RoundingMode.CEILING` always rounds toward positive infinity, while `RoundingMode.HALF_UP` rounds toward the nearest neighbor unless both neighbors are equidistant, in which case it rounds up. These implementations follow the exact same rounding rules as `java.math.BigDecimal` according to the source code in [`IntMath.java`](https://github.com/google/guava/blob/main/IntMath.java) and [`BigIntegerMath.java`](https://github.com/google/guava/blob/main/BigIntegerMath.java).

### Are Guava's math classes thread-safe?

Yes. **`IntMath`**, **`LongMath`**, and **`BigIntegerMath`** are all declared as `final` with private constructors, exposing only static methods that operate on immutable inputs. Because they maintain no instance state, these classes are inherently thread-safe and can be used concurrently without synchronization overhead.