From bc491b154bb3a74159c66279bb427befca2f3db7 Mon Sep 17 00:00:00 2001 From: Nguyen Van Nam Date: Mon, 30 Mar 2026 22:48:41 +0700 Subject: [PATCH] docs: undocumented identity-based comparison in `equalimmutablelists` `equalImmutableLists` is public and uses referential equality (`===`) per element rather than structural equality (`==`). Without documentation, callers may assume normal list equality and get false negatives for value-equal but distinct instances. This is a non-obvious contract and should be documented explicitly to prevent subtle logic bugs. Affected files: ListUtils.kt Signed-off-by: Nguyen Van Nam --- .../com/vitorpamplona/amethyst/commons/utils/ListUtils.kt | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/utils/ListUtils.kt b/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/utils/ListUtils.kt index d70e2417f..8c1412096 100644 --- a/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/utils/ListUtils.kt +++ b/commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/utils/ListUtils.kt @@ -22,6 +22,14 @@ package com.vitorpamplona.amethyst.commons.utils import kotlinx.collections.immutable.ImmutableList +/** + * Compares two [ImmutableList] instances by element identity (`===`), not value equality (`==`). + * + * Returns `true` only when both lists have the same size and each element at the same index + * is the exact same object reference. + * + * Useful for cheap change detection in UI/state pipelines where object identity is meaningful. + */ fun equalImmutableLists( list1: ImmutableList, list2: ImmutableList,