...

The built-in integer operators do not indicate overflow or underflow in any way. Integer operators can throw a NullPointerException if unboxing conversion of a null reference is required. Other than that, the only integer operators that can throw an exception are the integer divide operator / and the integer remainder operator %, which throw an ArithmeticException if the right-hand operand is zero, and the increment and decrement operators ++ and -- which can throw an OutOfMemoryError if boxing conversion is required and there is not sufficient insufficient memory available to perform the conversion.

The integral types in Java, representation, and inclusive ranges are shown in the following table taken from the JLS, §4.2.1, "Integral Types and Values":

The following table below shows the integer overflow behavior of the integral operators.

...

Because the ranges of Java types are not symmetrical symmetric (the negation of minimum value is one more than each maximum value), even operations like unary negation can overflow , if applied to a minimum value. Because the java.lang.math.abs() function method returns the absolute value on any number, it can also overflow if given the minimum int or long as an argument.

When a mathematical operation cannot be represented using the supplied integer types, Java's built-in integer operators silently wrap the result, without indicating overflow. This can result in incorrect computations and unanticipated outcomes. Failure to account for integer overflow has resulted in failures of real systems, for example, when implementing the {{compareTo()}} method. The meaning of the return value of the {{compareTo()}} method is defined only in terms of its sign and whether it is zero; the magnitude of the return value is irrelevant. Consequently, an apparent but incorrect optimization would be to subtract the operands and return the result. For operands of opposite signs, this can result in integer overflow, consequently violating the {{compareTo()}} contract \[[Bloch 2008|AA. Bibliography#Bloch 08], Item 12\].

Comparison of Compliant Techniques

The Following are the three main techniques for detecting unintended integer overflow are:

• Pre-condition Precondition testing. Check the inputs to each arithmetic operator to ensure that overflow cannot occur. Throw an ArithmeticException when the operation would overflow if it were performed; otherwise, perform the operation.

• Upcasting. Cast the inputs to the next larger primitive integer type and perform the arithmetic in the larger size. Check each intermediate result for overflow of the original smaller type and throw an ArithmeticException if the range check fails. Note that the range check must be performed after each arithmetic operation; larger expressions without per-operation bounds checking can overflow the larger type. Downcast the final result to the original smaller type before assigning to the result variablea variable of the original smaller type. This approach cannot be used for type long because long is already the largest primitive integer type.

• BigInteger. Convert the inputs into objects of type BigInteger and perform all arithmetic using BigInteger methods. Type BigInteger is the standard arbitrary-precision integer type provided by the Java standard libraries. The arithmetic operations implemented as methods of this type cannot overflow; instead, they produce the numerically correct result. Consequently, compliant code performs only performs a single range check just before converting the final result to the original smaller type and throwing throws an ArithmeticException if the final result is outside the range of the original smaller type.

The pre-condition precondition testing technique requires different pre-condition precondition tests for each arithmetic operation. This can be somewhat more difficult to implement and to audit than either of the other two approaches.

The upcast technique is the preferred approach when applicable. The checks it requires are simpler than those of the previous technique; it is substantially more efficient than using BigInteger. Unfortunately, it cannot be applied to operations involving the biggest type long, as there is no bigger type to upcast to.

The BigInteger technique is conceptually the simplest of the three techniques because arithmetic operations on BigInteger cannot overflow. However, it requires the use of method calls for each operation in place of primitive arithmetic operators; this can obscure the intended meaning of the code. Operations on objects of type BigInteger can also be significantly less efficient than operations on the original primitive integer type.

...

Precondition Testing

The following code example shows the necessary pre-condition checks required for each arithmetic operation on arguments of type int. The checks for the other integral types are analogous. In this example, we choose to These methods throw an exception when an integer overflow would otherwise occur; any other conforming error handling is also acceptable.

static final int safeAdd(int left, int right)
 throws ArithmeticException {
              throws ArithmeticException {
  if (right > 0 ? left > Integer.MAX_VALUE - right
                : left < Integer.MIN_VALUE - right) {
    throw new ArithmeticException("Integer overflow");
  }
  return left + right;
}

static final int safeSubtract(int left, int right) 
                 throws ArithmeticException {
  if (right > 0 ? left < Integer.MIN_VALUE + right :
 left > Integer.MAX_VALUE + right) {
    throw       : left > Integer.MAX_VALUE + right) {
    throw new ArithmeticException("Integer overflow");
  }
  return left - right;
}

static final int safeMultiply(int left, int right)
                 throws ArithmeticException {
  if (right > 0 ? left > Integer.MAX_VALUE/right
                  || left < Integer.MIN_VALUE/right :
       (right          : (right < -1 ? left > Integer.MIN_VALUE/right 
                                || left < Integer.MAX_VALUE/right :
         right == -1 && left == Integer.MIN_VALUE) ) {
    throw new ArithmeticException("Integer overflow");
  }
  return left *: right;
}

static final int safeDivide(int left, int right) throws ArithmeticException {
  if ((left == Integer.MIN_VALUE) && (right == -1)) {
 == -1 
                       throw new ArithmeticException("Integer overflow");

  }
  return left / right;
}

static final int safeNegate(int a) throws ArithmeticException {
  if (a && left == Integer.MIN_VALUE) ) {
    throw new ArithmeticException("Integer overflow");
  }
  return -a left * right;
}

static final int safeAbssafeDivide(int a)left, throws int right)
                 throws ArithmeticException {
  if (a(left == Integer.MIN_VALUE) && (right == -1)) {
    throw new ArithmeticException("Integer overflow");
  }
  return Math.abs(a)left / right;
}


static final int safeNegate(int a) throws ArithmeticException {
  if (a == Integer.MIN_VALUE) {
    throw new ArithmeticException("Integer overflow");
  }
  return -a;
}
static final int safeAbs(int a) throws ArithmeticException {
  if (a == Integer.MIN_VALUE) {
    throw new ArithmeticException("Integer overflow");
  }
  return Math.abs(a);
}

These method calls are likely to be inlined by most just-in-time systems (JITs)These method calls are likely to be inlined by most JITs.

These checks can be simplified when the original type is char. Because the range of type char includes only positive values, all comparisons with negative values may be omitted.

...

public static int multAccum(int oldAcc, int newVal, int scale) {
  // May result in overflow
  return oldAcc + (newVal * scale);
}

Compliant Solution (

...

Precondition Testing)

This compliant solution uses the safeAdd() and safeMultiply() methods defined in the Pre-Condition Precondition Testing section to perform secure integral operations or throw ArithmeticException on overflow.

public static int multAccum(int oldAcc, int newVal, int scale)
                  throws ArithmeticException {
  return safeAdd(oldAcc, safeMultiply(newVal, scale));
}

...

This compliant solution shows the implementation of a method for checking whether a long value falls within the representable range of an int using the upcasting technique. The implementations of range checks for the smaller primitive integer types are similar.

public static long intRangeCheck(long value)
                  
public static long intRangeCheck(long value) throws ArithmeticException {
  if ((value < Integer.MIN_VALUE) || (value > Integer.MAX_VALUE)) {
    throw new ArithmeticException("Integer overflow");
  }
  return value;
}

public static int multAccum(int oldAcc, int newVal, int scale)
                  throws ArithmeticException {
  final long res = intRangeCheck(
    intRangeCheck(((long) oldAcc) + intRangeCheck((long) newVal * (long) scale)
  );
  return (int) res; // safe down-cast
}

Note that this approach cannot be applied for to type long because long is the largest primitive integral type. When Use the BigInteger technique instead when the original variables are of type long, use the BigInteger technique instead.

Compliant Solution (BigInteger)

...

private static final BigInteger bigMaxInt = 
  BigInteger.valueOf(Integer.MAX_VALUE);
private static final BigInteger bigMinInt =bigMinInt =    
  BigInteger.valueOf(Integer.MIN_VALUE);

public static BigInteger intRangeCheck(BigInteger val)
                         throws ArithmeticException {
  if (val.compareTo(bigMaxInt) == 1 ||
      val.compareTo(bigMinInt) == -1) {
    throw new ArithmeticException("Integer overflow");
  }
  return val;
}


public static int multAccum(int oldAcc, int newVal, int scale)public static int multAccum(int oldAcc, int newVal, int scale)
                            throws ArithmeticException {
  BigInteger product =
    BigInteger.valueOf(newVal).multiply(BigInteger.valueOf(scale));
  BigInteger res = 
    intRangeCheck(BigInteger.valueOf(oldAcc).add(product));
  return res.intValue(); // safe conversion
}

...

Operations on objects of type AtomicInteger suffer from the same overflow issues as other integer types. The solutions are generally similar to the solutions already presented; however, concurrency issues add additional complications. First, potential issues with time-of-check-, time-of-use (TOCTOU) must be avoided; see rule VNA02-J . Ensure that compound operations on shared variables are atomic for more information. Second, use of an AtomicInteger creates happens-before relationships between the various threads that access it. Consequently, changes to the number of accesses or order of accesses can alter the execution of the overall program. In such cases, you must either choose to accept the altered execution or carefully craft the implementation of your compliant technique to preserve the exact number of accesses and order of accesses to the AtomicInteger.

...

Consequently, itemsInInventory can wrap around to Integer.MIN_VALUE when itemInInventory the nextItem() method is invoked at the instant when itemsInInventory == Integer.MAX_VALUE.

Compliant Solution (AtomicInteger)

...

class InventoryManager {
  private final AtomicInteger itemsInInventory =
      new AtomicInteger(100);

  public final void nextItem() {
    while (true) {
      int old = itemsInInventory.get();
      if (old == Integer.MAX_VALUE) {
        throw new ArithmeticException("Integer overflow");
      }
      int next = old + 1; // Increment
      if (itemsInInventory.compareAndSet(old, next)) {
        break;
      }
    } // end while
  } // end nextItem()
}

The two arguments to the {{compareAndSet()}} method are the expected value of the variable when the method is invoked and the intended new value. The variable's value is updated if, and only if,when the current value and the expected value are equal. (See \[[API 2006|AA. Bibliography#API 06]\] class [{{AtomicInteger}}|http://download.oracle.com/javase/6/docs/api/java/util/concurrent/atomic/AtomicInteger.html].) Refer to rule "[VNA02-J. Ensure that compound operations on shared variables are atomic]" Bibliography#API 06]\]. Refer to rule VNA02-J for more details.

Exceptions

NUM00-EX0: Depending on circumstances, integer overflow could be benign. For example, many algorithms for computing hash codes use modular arithmetic, intentionally allowing overflow to occur. Such benign uses must be carefully documented.

NUM00-EX1: Prevention of integer overflow is not necessary unnecessary for numeric fields that undergo bitwise operations and not arithmetic operations. For more information, see See rule NUM01-J . Avoid performing bitwise and arithmetic operations on the same datafor more information.

Risk Assessment

Failure to perform appropriate range checking can lead to integer overflows, which can cause unexpected program control flow or unanticipated program behavior.

...

Automated detection of integer operations that can potentially overflow is straightforward. Automatic determination of which potential overflows are true errors and which are intended by the programmer is infeasible. Heuristic warnings could might be helpful.

Related Guidelines

Bibliography

...