Choosing Between Identity and Structural Equality in Ceylon Classes

The Equality Decision in Ceylon

In Ceylon, the == operator does not compare object identity. It calls the equals() method inherited from ceylon.language::Object, whose default implementation compares identity. A separate operator, ===, always compares identity and cannot be overridden. This gives you an explicit decision to make for every class you write: keep the default identity-based equality, or override equals() and hash to get structural (field-based) equality.

The takeaway: override equals() and hash for immutable data carriers that will be compared by content or used as keys in sets and maps. Keep the default identity equality for entities whose identity is meaningful, such as services or stateful resources.

Comparison of the Two Options

Trade-offs

Consistency between equals and hash

If you override equals() without overriding hash, two instances that compare equal can still land in different hash buckets, and Set membership checks will behave incorrectly. The language documentation and the Object contract require that equal objects produce equal hashes. Always override the pair together, and derive the hash from the same fields used in the equality check.

Mutability risk

If equality depends on a mutable field and that field changes while the instance is a key in a hash-based collection, lookups will fail silently. Restrict custom equality to classes whose equality-relevant fields are immutable (declared without variable).

Type checking in equals

The parameter of equals() is Object?. A correct implementation narrows the type before comparing fields, typically with if (is MyClass that), and returns false for anything else, including null.

Concrete Implementation

The following sketch shows a class with structural equality and a check demonstrating both operators. Confirm exact syntax against your installed Ceylon compiler version; the language's tooling has not been actively developed for years, so treat this as a guide to the documented semantics rather than a tested listing.

class Point(shared Integer x, shared Integer y) {
    shared actual Boolean equals(Object that) {
        if (is Point that) {
            return x == that.x && y == that.y;
        }
        return false;
    }
    shared actual Integer hash {
        return 31 * x + y;
    }
}

shared void run() {
    value a = Point(1, 2);
    value b = Point(1, 2);
    print(a == b);   // structural: expected true
    print(a === b);  // identity: expected false
    print(a === a);  // identity: expected true
}

How to validate

1. Where to run: In a Ceylon module source file, compiled with the ceylon compile CLI and executed with ceylon run <module.name>, replacing <module.name> with your module's declared name. You need the Ceylon SDK on your PATH and write access to the module output directory.
2. Expected result: The three print statements produce true, false, true. If the first prints false, your equals() override is not being picked up—check the shared actual annotations and the parameter type.
3. Collection check: Add both a and b to a HashSet and confirm its size is 1. A size of 2 indicates hash and equals() are inconsistent.

Limitations and Caveats

Overriding equality interacts with inheritance: if a subclass adds fields, the parent's equals() may consider a subclass instance equal to a parent instance, breaking symmetry. A common conservative approach is to only override equality in classes not intended for extension, or to compare runtime types strictly.

Also note that Ceylon has no user-defined value-type construct: the value keyword is a local declaration modifier for type inference, not a type definition. Structural equality in Ceylon is achieved only by overriding equals() and hash on ordinary classes, exactly as shown above. Finally, given the project's slowed development, verify compiler behavior on your installed version before relying on any specific tooling behavior.