From e50962f5a1787222dbde0789e01a03c08c796b3a Mon Sep 17 00:00:00 2001 From: Daniel Csorba Date: Wed, 16 Apr 2025 11:48:11 +0200 Subject: [PATCH 1/4] update: clarify null-handling behavior of==operator --- docs/topics/operator-overloading.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/topics/operator-overloading.md b/docs/topics/operator-overloading.md index 23a09117a23..6a46863187e 100644 --- a/docs/topics/operator-overloading.md +++ b/docs/topics/operator-overloading.md @@ -182,8 +182,12 @@ which can be overridden to provide custom equality check implementation. Any oth > {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()`. +The `==` operation translates `a == b` to `a?.equals(b) ?: (b === null)`, which safely handles comparisons involving `null` values. +The behavior of the comparison depends on the nullability of the values being compared: + +* If `a` is `null`, the comparison returns `true` only if `b` is also `null`, and no function is called. +* If `a` is a nullable type and isn't `null` at runtime, the compiler calls `a.equals(b)`, even if `b` is `null`. +* If `a` is a non-nullable type and `b` is known to be `null`, the compiler replaces the comparison with `false` at compile time and skips the function call. ### Comparison operators From 8beefa731e230d36c0af3173d44a9c5f9bbe0683 Mon Sep 17 00:00:00 2001 From: Daniel Csorba Date: Thu, 7 Aug 2025 14:27:12 +0200 Subject: [PATCH 2/4] update: implementing comments from Nikita --- docs/topics/operator-overloading.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/topics/operator-overloading.md b/docs/topics/operator-overloading.md index 6a46863187e..ece2605a095 100644 --- a/docs/topics/operator-overloading.md +++ b/docs/topics/operator-overloading.md @@ -176,18 +176,15 @@ 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. +> `===` and `!==` (identity checks) aren't overloadable, so no conventions exist for them. > {style="note"} -The `==` operation translates `a == b` to `a?.equals(b) ?: (b === null)`, which safely handles comparisons involving `null` values. -The behavior of the comparison depends on the nullability of the values being compared: - -* If `a` is `null`, the comparison returns `true` only if `b` is also `null`, and no function is called. -* If `a` is a nullable type and isn't `null` at runtime, the compiler calls `a.equals(b)`, even if `b` is `null`. -* If `a` is a non-nullable type and `b` is known to be `null`, the compiler replaces the comparison with `false` at compile time and skips the function call. +Kotlin calls `.equals()` when neither operand is the `null` literal and the comparison isn’t between two floating-point types. +Otherwise, `===` is used for `null` literal checks, and non-null floating-point values are compared by numeric value. ### Comparison operators From 1750bc161762ac2ed1080bfab8989277fb782633 Mon Sep 17 00:00:00 2001 From: Daniel Csorba Date: Mon, 11 Aug 2025 15:27:28 +0200 Subject: [PATCH 3/4] update: implementing TWr review comments --- docs/topics/operator-overloading.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/topics/operator-overloading.md b/docs/topics/operator-overloading.md index ece2605a095..18ce0cf10e4 100644 --- a/docs/topics/operator-overloading.md +++ b/docs/topics/operator-overloading.md @@ -179,13 +179,13 @@ These operators only work with the function [`equals(other: Any?): Boolean`](htt which you can override to provide a custom equality check implementation. Any other function with the same name (like `equals(other: Foo)`) is ignored. +Kotlin calls `.equals()` when neither operand is the `null` literal and the comparison isn't between two floating-point types. +Otherwise, Kotlin uses `===` for `null` literal checks and compares non-null floating-point values by numeric value. + > `===` and `!==` (identity checks) aren't overloadable, so no conventions exist for them. > {style="note"} -Kotlin calls `.equals()` when neither operand is the `null` literal and the comparison isn’t between two floating-point types. -Otherwise, `===` is used for `null` literal checks, and non-null floating-point values are compared by numeric value. - ### Comparison operators | Expression | Translated to | From b0c8e037cdb4527ccabb0c84cf532d5d6e8315d5 Mon Sep 17 00:00:00 2001 From: Daniel Csorba Date: Wed, 13 Aug 2025 10:53:48 +0200 Subject: [PATCH 4/4] Implementing comments from Sarah --- docs/topics/operator-overloading.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/topics/operator-overloading.md b/docs/topics/operator-overloading.md index 18ce0cf10e4..a129fd46650 100644 --- a/docs/topics/operator-overloading.md +++ b/docs/topics/operator-overloading.md @@ -179,8 +179,8 @@ These operators only work with the function [`equals(other: Any?): Boolean`](htt which you can override to provide a custom equality check implementation. Any other function with the same name (like `equals(other: Foo)`) is ignored. -Kotlin calls `.equals()` when neither operand is the `null` literal and the comparison isn't between two floating-point types. -Otherwise, Kotlin uses `===` for `null` literal checks and compares non-null floating-point values by numeric value. +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. >