15.21

Equality Operators

EXPRESSIONS

It is a compile-time error if the ReferenceType mentioned after the instanceof operator does not denote a reference type that is reifiable (§4.7).

At run-time, the result of the instanceof operator is true if the value of the RelationalExpression is not null and the reference could be cast (§15.16) to the ReferenceType without raising a ClassCastException. Otherwise the result is false.

If a cast of the RelationalExpression to the ReferenceType would be rejected as a compile-time error, then the instanceof relational expression likewise produces a compile-time error. In such a situation, the result of the instanceof expression could never be true.

Example 15.20.2-1. The instanceof Operator

class Point {	int x, y; }
class Element {	int atomicNumber; }
class Test {
public static void main(String[] args) {
Point	p = new Point();
Element	e = new Element();
if (e instanceof Point) { // compile-time error
System.out.println("I get your point!");
p =	(Point)e; // compile-time error
}
}
}

This program results in two compile-time errors. The cast (Point)e is incorrect because no instance of Element or any of its possible subclasses (none are shown here) could possibly be an instance of any subclass of Point. The instanceof expression is incorrect for exactly the same reason. If, on the other hand, the class Point were a subclass of Element (an admittedly strange notion in this example):

class Point extends Element { int x, y; }

then the cast would be possible, though it would require a run-time check, and the instanceof expression would then be sensible and valid. The cast (Point)e would never raise an exception because it would not be executed if the value of e could not correctly be cast to type Point.

15.21 Equality Operators

The operators == (equal to) and != (not equal to) are called the equality operators.

514

EXPRESSIONS

Numerical Equality Operators == and != 15.21.1

EqualityExpression:

RelationalExpression

EqualityExpression == RelationalExpression

EqualityExpression != RelationalExpression

The equality operators are syntactically left-associative (they group left-to-right).

However, this fact is essentially never useful. For example, a==b==c parses as (a==b)==c. The result type of a==b is always boolean, and c must therefore be of type boolean or a compile-time error occurs. Thus, a==b==c does not test to see whether a, b, and c are all equal.

The equality operators are commutative if the operand expressions have no side effects.

The equality operators are analogous to the relational operators except for their lower precedence. Thus, a<b==c<d is true whenever a<b and c<d have the same truth value.

The equality operators may be used to compare two operands that are convertible (§5.1.8) to numeric type, or two operands of type boolean or Boolean, or two operands that are each of either reference type or the null type. All other cases result in a compile-time error.

The type of an equality expression is always boolean.

In all cases, a!=b produces the same result as !(a==b).

15.21.1 Numerical Equality Operators == and !=

If the operands of an equality operator are both of numeric type, or one is of numeric type and the other is convertible (§5.1.8) to numeric type, binary numeric promotion is performed on the operands (§5.6.2).

Note that binary numeric promotion performs value set conversion (§5.1.13) and may perform unboxing conversion (§5.1.8).

If the promoted type of the operands is int or long, then an integer equality test is performed.

If the promoted type is float or double, then a floating-point equality test is performed.

Comparison is carried out accurately on floating-point values, no matter what value sets their representing values were drawn from.

515

15.21.2 Boolean Equality Operators == and !=

EXPRESSIONS

Floating-point equality testing is performed in accordance with the rules of the IEEE 754 standard:

•If either operand is NaN, then the result of == is false but the result of != is true. Indeed, the test x!=x is true if and only if the value of x is NaN.

The methods Float.isNaN and Double.isNaN may also be used to test whether a value is NaN.

• Positive zero and negative zero are considered equal.

For example, -0.0==0.0 is true.

•Otherwise, two distinct floating-point values are considered unequal by the equality operators.

In particular, there is one value representing positive infinity and one value representing negative infinity; each compares equal only to itself, and each compares unequal to all other values.

Subject to these considerations for floating-point numbers, the following rules then hold for integer operands or for floating-point operands other than NaN:

•The value produced by the == operator is true if the value of the left-hand operand is equal to the value of the right-hand operand; otherwise, the result is

false.

•The value produced by the != operator is true if the value of the left-hand operand is not equal to the value of the right-hand operand; otherwise, the result is false.

15.21.2 Boolean Equality Operators == and !=

If the operands of an equality operator are both of type boolean, or if one operand is of type boolean and the other is of type Boolean, then the operation is boolean equality.

The boolean equality operators are associative.

If one of the operands is of type Boolean, it is subjected to unboxing conversion (§5.1.8).

The result of == is true if the operands (after any required unboxing conversion) are both true or both false; otherwise, the result is false.

The result of != is false if the operands are both true or both false; otherwise, the result is true.

516