Implementation:Apache Paimon MathUtils
| Knowledge Sources | |
|---|---|
| Domains | Mathematics, Utilities |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
MathUtils provides a collection of simple mathematical utility routines for power-of-two calculations, logarithms, and safe arithmetic operations.
Description
MathUtils is a utility class offering mathematical helper methods commonly needed in systems programming and data structure implementation. It provides power-of-two operations including roundDownToPowerOf2() and roundUpToPowerOf2() for aligning values to power-of-two boundaries (useful for buffer sizing and hash table capacity calculation), isPowerOf2() for validation, and log2strict() for computing base-2 logarithms of power-of-two values.
The class includes null-safe comparison methods max() and min() that handle Integer objects, treating null values specially (returning the non-null value or null if both are null). This is particularly useful when working with optional or nullable configuration values where null represents "no limit" or "unspecified".
MathUtils also provides overflow-safe arithmetic operations: incrementSafely() ensures incrementing doesn't overflow by returning Integer.MAX_VALUE if already at maximum, addSafely() performs addition that saturates at Integer.MAX_VALUE rather than wrapping around, and multiplySafely() does the same for multiplication. These methods use Math.addExact() and Math.multiplyExact() internally, catching ArithmeticException and returning safe maximum values, crucial for preventing integer overflow bugs in size calculations and capacity planning.
Usage
Use MathUtils for power-of-two calculations in hash table and buffer implementations, for safe integer arithmetic that prevents overflow in size/capacity computations, and for null-safe comparison operations in configuration handling.
Code Reference
Source Location
- Repository: Apache_Paimon
- File: paimon-api/src/main/java/org/apache/paimon/utils/MathUtils.java
Signature
public class MathUtils {
public static int roundDownToPowerOf2(int value)
public static int roundUpToPowerOf2(int value)
public static boolean isPowerOf2(long value)
public static int log2strict(int value) throws ArithmeticException, IllegalArgumentException
public static Integer max(Integer v1, Integer v2)
public static Integer min(Integer v1, Integer v2)
public static int incrementSafely(int a)
public static int addSafely(int a, int b)
public static int multiplySafely(int a, int b)
}
Import
import org.apache.paimon.utils.MathUtils;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| value | int/long | Context-dependent | Value for power-of-two operations |
| v1, v2 | Integer | Context-dependent | Values for comparison (nullable) |
| a, b | int | Context-dependent | Values for safe arithmetic |
Outputs
| Name | Type | Description |
|---|---|---|
| Rounded value | int | Value adjusted to power-of-two boundary |
| Boolean result | boolean | Whether value is power of two |
| Logarithm | int | Base-2 logarithm of the value |
| Comparison result | Integer | Max/min value (possibly null) |
| Safe arithmetic result | int | Result saturated at Integer.MAX_VALUE |
Usage Examples
// Round down to power of 2
int rounded = MathUtils.roundDownToPowerOf2(100); // 64
int exact = MathUtils.roundDownToPowerOf2(128); // 128 (unchanged)
// Round up to power of 2
int roundedUp = MathUtils.roundUpToPowerOf2(100); // 128
int small = MathUtils.roundUpToPowerOf2(1); // 2
// Check if power of 2
boolean isPow2_64 = MathUtils.isPowerOf2(64); // true
boolean isPow2_100 = MathUtils.isPowerOf2(100); // false
// Calculate log base 2 (strict - value must be power of 2)
int log = MathUtils.log2strict(256); // 8
int log2 = MathUtils.log2strict(1024); // 10
try {
int invalid = MathUtils.log2strict(100); // throws IllegalArgumentException
} catch (IllegalArgumentException e) {
System.out.println("Not a power of 2");
}
// Null-safe max/min
Integer max1 = MathUtils.max(10, 20); // 20
Integer max2 = MathUtils.max(10, null); // 10
Integer max3 = MathUtils.max(null, 20); // 20
Integer max4 = MathUtils.max(null, null); // null
Integer min1 = MathUtils.min(10, 20); // 10
Integer min2 = MathUtils.min(10, null); // 10
// Safe increment (prevents overflow)
int incremented = MathUtils.incrementSafely(100); // 101
int maxInc = MathUtils.incrementSafely(Integer.MAX_VALUE); // Integer.MAX_VALUE
// Safe addition (saturates at max)
int sum = MathUtils.addSafely(100, 200); // 300
int overflowSum = MathUtils.addSafely(Integer.MAX_VALUE, 100); // Integer.MAX_VALUE
// Safe multiplication (saturates at max)
int product = MathUtils.multiplySafely(100, 200); // 20000
int overflowProduct = MathUtils.multiplySafely(Integer.MAX_VALUE / 2, 3);
// Returns Integer.MAX_VALUE instead of overflow
// Example: Hash table capacity calculation
int desiredCapacity = 1000;
int actualCapacity = MathUtils.roundUpToPowerOf2(desiredCapacity);
// Returns 1024, ensuring power-of-2 capacity
// Example: Buffer size alignment
int bufferSize = 1500;
int alignedSize = MathUtils.roundDownToPowerOf2(bufferSize);
// Returns 1024, aligned to power of 2
// Example: Safe size calculation
public int calculateTotalSize(int itemCount, int itemSize) {
int totalSize = MathUtils.multiplySafely(itemCount, itemSize);
int withOverhead = MathUtils.addSafely(totalSize, 1024);
return withOverhead;
}
// Example: Configuration with optional limits
Integer userLimit = getUserConfig("maxSize"); // might be null
Integer systemLimit = 10000;
Integer effectiveLimit = MathUtils.min(userLimit, systemLimit);
// Returns userLimit if specified and smaller, otherwise systemLimit