Page History

...

Autoboxing automatically wraps a value of a primitive type with the corresponding wrapper object. The Java Language Specification (JLS), §5.1.7, "Boxing Conversion" [JLS 20052015], explains which primitive values are memoized during autoboxing:

If the value p being boxed is true, false, a byte, a char in the range \u0000 to \u007f, or an int or short number between -128 and 127, then let r1 and r2 be the results of any two boxing conversions of p. It is always the case that r1 == r2.

Use of the == and != operators for comparing the values of fully memoized boxed primitive types is permitted.

...

Note that Java Virtual Machine (JVM) implementations are allowed, but not required, to memoize additional values [JLS 20052015]:

Less memory-limited implementations could, for example, cache all characters and shorts, as well as integers and longs in the range of −32K to +32K. (§5.1.7)

Code that depends on implementation-defined behavior is nonportable. It is permissible to depend on implementation-specific ranges of memoized values provided that all targeted implementations support these greater ranges.

...

This noncompliant code example attempts to count the number of indices in arrays list1 and list2 that have equivalent values. Recall that class Integer is required to memoize only those integer values in the range −128 to 127; it might return a nonunique object for any value outside that range. Consequently, when comparing autoboxed integer values outside that range, the == operator might return false and the example could deceptively output 0.

public class Wrapper {
  public static void main(String[] args) {
    // Create an array list of integers, where each element 
    // is greater than 127
    ArrayList<Integer> list1 = new ArrayList<Integer>();
    for (int i = 0; i < 10; i++) {
      list1.add(i + 1000);
    }

    // Create another array list of integers, where each element
    // has the same value as the first list
    ArrayList<Integer> list2 = new ArrayList<Integer>();
    for (int i = 0; i < 10; i++) {
      list2.add(i + 1000);
    }

    // Count matching values
    int counter = 0;
    for (int i = 0; i < 10; i++) {
      if (list1.get(i) == list2.get(i)) {  // usesUses '=='
        counter++;
      }
    }

    // Print the counter: 0 in this example
    System.out.println(counter);
  }

}

...

public class Wrapper {
  public static void main(String[] args) {
    // Create an array list of integers
    ArrayList<Integer> list1 = new ArrayList<Integer>();

    for (int i = 0; i < 10; i++) {
      list1.add(i + 1000);
    }

    // Create another array list of integers, where each element
    // has the same value as the first one
    ArrayList<Integer> list2 = new ArrayList<Integer>();
    for (int i = 0; i < 10; i++) {
      list2.add(i + 1000);
    }
 
    // Count matching values
    int counter = 0;
    for (int i = 0; i < 10; i++) {
      if (list1.get(i).equals(list2.get(i))) {  // usesUses 'equals()'
        counter++;
      }
    }
 
    // Print the counter: 10 in this example
    System.out.println(counter);
  }
}

...

Boolean.TRUE, Boolean.FALSE, or the values of autoboxed true and false literals false literals, may be compared using the reference equality operators because the Java language guarantees that the Boolean type is fully memoized. Consequently, these objects are guaranteed to be singletons.

...

Using the equivalence operators to compare values of boxed primitives can lead to erroneous comparisons.

Automated Detection

Detection of all uses of the reference equality operators on boxed primitive objects is straightforward. Determining the correctness of such uses is infeasible in the general case.

Related Guidelines

Bibliography

[Bloch 2009]	Puzzle 4, "Searching for the One"
[JLS

2005

2015]	§5.1.7, "Boxing Conversion"
[Pugh 2009]	Using == to Compare Objects Rather than .equals
[Seacord 2015]	Image Modified EXP03-J. Do not use the equality operators when comparing values of boxed primitives LiveLesson

...

...

Image Modified Image Modified Image Modified