Skip to content

update: clarify null-handling behavior of==operator #4808

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 13, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions docs/topics/operator-overloading.md
Original file line number Diff line number Diff line change
Expand Up @@ -176,15 +176,16 @@ For the assignment operations, for example `a += b`, the compiler performs the f
| `a != b` | `!(a?.equals(b) ?: (b === null))` |

These operators only work with the function [`equals(other: Any?): Boolean`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/equals.html),
which can be overridden to provide custom equality check implementation. Any other function with the same name (like `equals(other: Foo)`) will not be called.
which you can override to provide a custom equality check implementation.
Any other function with the same name (like `equals(other: Foo)`) is ignored.

> `===` and `!==` (identity checks) are not overloadable, so no conventions exist for them.
Kotlin calls `.equals()` when neither operand compares directly to `null` in the `==` expression and the comparison isn't between two floating-point types.
Otherwise, Kotlin uses `===` for direct `null` comparisons and compares non-null floating-point values by numeric value.

> `===` and `!==` (identity checks) aren't overloadable, so no conventions exist for them.
>
{style="note"}

The `==` operation is special: it is translated to a complex expression that screens for `null`'s.
`null == null` is always true, and `x == null` for a non-null `x` is always false and won't invoke `x.equals()`.

### Comparison operators

| Expression | Translated to |
Expand Down