Equality expressions

Equality expressions return a Boolean value (true or false) indicating the result of the comparison between the two expressions. Equality expressions consist of the following types:

  • Relational equality operator (==)
  • Object equality operator (===)
  • Inequality operator (!=)
  • Object inequality operator (!==)

Relational equality operator (==)

The == operator tests for relational equality. The operands can be of any compatible types. The result is always Boolean. For object types, the following rules apply in the following order:

  • If both objects implement the Comparable interface, the == operator calls the Comparable interface method compareTo. Gosu calls the compareTo method on the object to the left of the == operator.
  • Otherwise, the == operator calls the native Java method object.equals() to compare values. Gosu calls the equals method on the object to the left of the == operator.
Important: To determine whether two objects are the same in-memory object, instead use the === or !== operators.

In the Java language, the == operator evaluates to true if and only if both operands have exactly the same reference value, which refers to the same object in memory. This behavior works well for primitive types like integers. For reference types, you usually do not want to compare the object in memory. Instead, to compare value equality, Java code typically uses object.equals(), not the == operator. The object.equals() method includes the comparison of object reference values, but also compares property values.

If you use the == operator for comparison of reference types, Gosu calls object.equals(). In most cases, this behavior is what you want for reference types.

Syntax

a == b

Examples

Expression

Result

7 == 7

true

"3" == 3

true

3 == 5

false

Object equality operator (===)

You compare identity references, rather than the object values, to determine whether two objects reference the same in-memory object. You use the Gosu operator === (three equal signs) to compare object equality.

The operands can be of any compatible types. The result type is always Boolean.

Examples comparing == and ===

Expression

Output

Description

print("3" == "3")

true

The two String objects contain the same value.

print("3" == new String("3"))

true

The two String objects contain the same value.

print("3" == "4")

false

The two String objects contain different values.

print("3" === "4")

false

Gosu represents the two String literals as separate objects in memory (as well as separate values).

var x = 1 + 2

var s = x as String

print(s == "3")

true

These two variables reference the same value but different objects, so the double-equals operator returns true.

var x = 1 + 2

var s = x as String

print(s === "3")

false

These two variables reference the same value but different objects, so the triple-equals operator returns false.

print("3" === "3")

true

This example is harder to understand. By just looking at the code, it seems like these two String objects would be different objects. However, the Gosu compiler detects that the objects are the same String. Gosu optimizes the code to point to the same String object in memory for both usages of the String literal "3".

print("3" === new String("3"))

false

The two String objects both contain the value "3", but are not the same object.

Inequality operator (!=)

The != operator tests for relational inequality. The operands can be of any compatible types. The result type is always Boolean.

For object types, the following rules apply in the following order:

  • If both objects implement the Comparable interface, the != operator calls the Comparable interface method compareTo to compare values. Gosu calls the compareTo method on the object to the left of the == operator.
  • Otherwise, the != operator calls the native Java method object.equals() to compare values. Gosu calls the equals method on the object to the left of the == operator.
Important: To compare whether two objects are the same in-memory object, instead use the === or !== operators.

Syntax

a != b

Examples

Expression

Result

7 != 7

false

"3" != 3

false

3 != 5

true

Object inequality operator (!==)

The !== operator tests for object inequality. It returns the opposite value of the === operator, which tests for object equality not value equality.

The operands can be of any compatible types. The result type is always Boolean.

Syntax

a !== b

Examples comparing != and !==

Expression

Output

Description

print("3" != "4")

true

The two String objects contain different values.

print("3" !== "4")

true

Gosu represents the two String literals as separate objects in memory (as well as separate values).

var x = 1 + 2

var s = x as String

print(s != "3")

false

These two variables reference the same value but different objects. If you use the == operator, it returns true.

var x = 1 + 2

var s = x as String

print(s !== "3")

true

These two variables reference the same value but different objects. If you use the === operator, it returns false.

print("3" != "3")

false

The two String objects contain the same value. Compare to the examples in the following rows.

print("3" != new String("3"))

false

The two String objects contain the same value.

print("3" !== "3")

false

This example is harder to understand. By just looking at the code, it seems like these two String objects would be different objects. However, in this case, the Gosu compiler detects they are the same String at compile time. Gosu optimizes the code for both usages of a String literal to point to the same object in memory for both usages of the "3".

print("3" !== new String("3"))

true

The two String objects both contain the value "3", but are not the same object.