Improve Array contentEquals and contentDeepEquals doc #KT-66896
diff --git a/kotlin-native/runtime/src/main/kotlin/generated/_ArraysNative.kt b/kotlin-native/runtime/src/main/kotlin/generated/_ArraysNative.kt index 328296d..c39f2b4 100644 --- a/kotlin-native/runtime/src/main/kotlin/generated/_ArraysNative.kt +++ b/kotlin-native/runtime/src/main/kotlin/generated/_ArraysNative.kt
@@ -230,14 +230,19 @@ } /** - * Returns `true` if the two specified arrays are *deeply* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *deeply* equal to one another. * - * If two corresponding elements are nested arrays, they are also compared deeply. - * If any of arrays contains itself on any nesting level the behavior is undefined. + * Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + * That is, if two corresponding elements are nested arrays, they are also compared deeply. + * Elements of other types are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. * - * The elements of other types are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * If any of the arrays contain themselves at any nesting level, the behavior is undefined. + * + * @param other the array to compare deeply with this array. + * @return `true` if the two arrays are deeply equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.contentDeepEquals */ @SinceKotlin("1.1") @kotlin.internal.LowPriorityInOverloadResolution @@ -246,16 +251,21 @@ } /** - * Returns `true` if the two specified arrays are *deeply* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *deeply* equal to one another. * - * The specified arrays are also considered deeply equal if both are `null`. + * Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + * That is, if two corresponding elements are nested arrays, they are also compared deeply. + * Elements of other types are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. * - * If two corresponding elements are nested arrays, they are also compared deeply. - * If any of arrays contains itself on any nesting level the behavior is undefined. + * The arrays are also considered deeply equal if both are `null`. * - * The elements of other types are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * If any of the arrays contain themselves at any nesting level, the behavior is undefined. + * + * @param other the array to compare deeply with this array. + * @return `true` if the two arrays are deeply equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.contentDeepEquals */ @SinceKotlin("1.4") public actual infix fun <T> Array<out T>?.contentDeepEquals(other: Array<out T>?): Boolean { @@ -315,11 +325,18 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * If the arrays contain nested arrays, use [contentDeepEquals] to recursively compare their elements. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.arrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -329,11 +346,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -343,11 +363,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -357,11 +380,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -371,11 +397,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -385,11 +414,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -399,11 +433,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -413,11 +452,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.booleanArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -427,11 +469,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.charArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -441,11 +486,20 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * If the arrays contain nested arrays, use [contentDeepEquals] to recursively compare their elements. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.arrayContentEquals */ @SinceKotlin("1.4") public actual infix fun <T> Array<out T>?.contentEquals(other: Array<out T>?): Boolean { @@ -459,11 +513,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun ByteArray?.contentEquals(other: ByteArray?): Boolean { @@ -477,11 +536,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun ShortArray?.contentEquals(other: ShortArray?): Boolean { @@ -495,11 +559,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun IntArray?.contentEquals(other: IntArray?): Boolean { @@ -513,11 +582,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun LongArray?.contentEquals(other: LongArray?): Boolean { @@ -531,11 +605,18 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun FloatArray?.contentEquals(other: FloatArray?): Boolean { @@ -549,11 +630,18 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun DoubleArray?.contentEquals(other: DoubleArray?): Boolean { @@ -567,11 +655,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.booleanArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun BooleanArray?.contentEquals(other: BooleanArray?): Boolean { @@ -585,11 +678,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.charArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun CharArray?.contentEquals(other: CharArray?): Boolean {
diff --git a/kotlin-native/runtime/src/main/kotlin/generated/_UArraysNative.kt b/kotlin-native/runtime/src/main/kotlin/generated/_UArraysNative.kt index 1a8f3bf..1ad70da 100644 --- a/kotlin-native/runtime/src/main/kotlin/generated/_UArraysNative.kt +++ b/kotlin-native/runtime/src/main/kotlin/generated/_UArraysNative.kt
@@ -126,8 +126,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.3") @@ -138,8 +144,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.3") @@ -150,8 +162,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.3") @@ -162,8 +180,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.3")
diff --git a/libraries/kotlin.test/common/src/main/kotlin/kotlin/test/Assertions.kt b/libraries/kotlin.test/common/src/main/kotlin/kotlin/test/Assertions.kt index eb9304a..f11b0f8 100644 --- a/libraries/kotlin.test/common/src/main/kotlin/kotlin/test/Assertions.kt +++ b/libraries/kotlin.test/common/src/main/kotlin/kotlin/test/Assertions.kt
@@ -354,11 +354,14 @@ } /** - * Asserts that the [expected] iterable is *structurally* equal to the [actual] iterable, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] iterable is *structurally* equal to the [actual] iterable, with an optional [message]. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two iterables are considered structurally equal if they have the same size, + * and elements at corresponding positions, following the iteration order, are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The iterables are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun <@OnlyInputTypes T> assertContentEquals(expected: Iterable<T>?, actual: Iterable<T>?, message: String? = null) { @@ -374,11 +377,14 @@ assertContentEquals(expected, actual?.asIterable(), message) /** - * Asserts that the [expected] sequence is *structurally* equal to the [actual] sequence, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] sequence is *structurally* equal to the [actual] sequence, with an optional [message]. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two sequences are considered structurally equal if they have the same size, + * and elements at corresponding positions, following the iteration order, are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The sequences are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun <@OnlyInputTypes T> assertContentEquals(expected: Sequence<T>?, actual: Sequence<T>?, message: String? = null) { @@ -386,11 +392,13 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun <@OnlyInputTypes T> assertContentEquals(expected: Array<T>?, actual: Array<T>?, message: String? = null) { @@ -398,8 +406,11 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun assertContentEquals(expected: ByteArray?, actual: ByteArray?, message: String? = null) { @@ -407,8 +418,11 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun assertContentEquals(expected: ShortArray?, actual: ShortArray?, message: String? = null) { @@ -416,8 +430,11 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun assertContentEquals(expected: IntArray?, actual: IntArray?, message: String? = null) { @@ -425,8 +442,11 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun assertContentEquals(expected: LongArray?, actual: LongArray?, message: String? = null) { @@ -434,11 +454,13 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun assertContentEquals(expected: FloatArray?, actual: FloatArray?, message: String? = null) { @@ -446,11 +468,13 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun assertContentEquals(expected: DoubleArray?, actual: DoubleArray?, message: String? = null) { @@ -458,8 +482,11 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun assertContentEquals(expected: BooleanArray?, actual: BooleanArray?, message: String? = null) { @@ -467,8 +494,11 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") public fun assertContentEquals(expected: CharArray?, actual: CharArray?, message: String? = null) { @@ -476,8 +506,11 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") @OptIn(ExperimentalUnsignedTypes::class) @@ -486,8 +519,11 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") @OptIn(ExperimentalUnsignedTypes::class) @@ -496,8 +532,11 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") @OptIn(ExperimentalUnsignedTypes::class) @@ -506,8 +545,11 @@ } /** - * Asserts that the [expected] array is *structurally* equal to the [actual] array, - * i.e. contains the same number of the same elements in the same order, with an optional [message]. + * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message]. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered equal if both are `null`. */ @SinceKotlin("1.5") @OptIn(ExperimentalUnsignedTypes::class)
diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt index bbe6746..fdd5d5e 100644 --- a/libraries/stdlib/common/src/generated/_Arrays.kt +++ b/libraries/stdlib/common/src/generated/_Arrays.kt
@@ -6785,30 +6785,40 @@ public expect fun CharArray.asList(): List<Char> /** - * Returns `true` if the two specified arrays are *deeply* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *deeply* equal to one another. * - * If two corresponding elements are nested arrays, they are also compared deeply. - * If any of arrays contains itself on any nesting level the behavior is undefined. + * Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + * That is, if two corresponding elements are nested arrays, they are also compared deeply. + * Elements of other types are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. * - * The elements of other types are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * If any of the arrays contain themselves at any nesting level, the behavior is undefined. + * + * @param other the array to compare deeply with this array. + * @return `true` if the two arrays are deeply equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.contentDeepEquals */ @SinceKotlin("1.1") @kotlin.internal.LowPriorityInOverloadResolution public expect infix fun <T> Array<out T>.contentDeepEquals(other: Array<out T>): Boolean /** - * Returns `true` if the two specified arrays are *deeply* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *deeply* equal to one another. * - * The specified arrays are also considered deeply equal if both are `null`. + * Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + * That is, if two corresponding elements are nested arrays, they are also compared deeply. + * Elements of other types are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. * - * If two corresponding elements are nested arrays, they are also compared deeply. - * If any of arrays contains itself on any nesting level the behavior is undefined. + * The arrays are also considered deeply equal if both are `null`. * - * The elements of other types are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * If any of the arrays contain themselves at any nesting level, the behavior is undefined. + * + * @param other the array to compare deeply with this array. + * @return `true` if the two arrays are deeply equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.contentDeepEquals */ @SinceKotlin("1.4") public expect infix fun <T> Array<out T>?.contentDeepEquals(other: Array<out T>?): Boolean @@ -6858,91 +6868,144 @@ public expect fun <T> Array<out T>?.contentDeepToString(): String /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * If the arrays contain nested arrays, use [contentDeepEquals] to recursively compare their elements. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.arrayContentEquals */ @SinceKotlin("1.4") public expect infix fun <T> Array<out T>?.contentEquals(other: Array<out T>?): Boolean /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public expect infix fun ByteArray?.contentEquals(other: ByteArray?): Boolean /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public expect infix fun ShortArray?.contentEquals(other: ShortArray?): Boolean /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public expect infix fun IntArray?.contentEquals(other: IntArray?): Boolean /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public expect infix fun LongArray?.contentEquals(other: LongArray?): Boolean /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @SinceKotlin("1.4") public expect infix fun FloatArray?.contentEquals(other: FloatArray?): Boolean /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @SinceKotlin("1.4") public expect infix fun DoubleArray?.contentEquals(other: DoubleArray?): Boolean /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.booleanArrayContentEquals */ @SinceKotlin("1.4") public expect infix fun BooleanArray?.contentEquals(other: BooleanArray?): Boolean /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.charArrayContentEquals */ @SinceKotlin("1.4") public expect infix fun CharArray?.contentEquals(other: CharArray?): Boolean
diff --git a/libraries/stdlib/common/src/generated/_UArrays.kt b/libraries/stdlib/common/src/generated/_UArrays.kt index 7e34856..2366db8 100644 --- a/libraries/stdlib/common/src/generated/_UArrays.kt +++ b/libraries/stdlib/common/src/generated/_UArrays.kt
@@ -3308,8 +3308,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -3318,8 +3326,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -3328,8 +3344,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -3338,8 +3362,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes
diff --git a/libraries/stdlib/js/src/generated/_ArraysJs.kt b/libraries/stdlib/js/src/generated/_ArraysJs.kt index ede57e9..800c268 100644 --- a/libraries/stdlib/js/src/generated/_ArraysJs.kt +++ b/libraries/stdlib/js/src/generated/_ArraysJs.kt
@@ -186,14 +186,19 @@ } /** - * Returns `true` if the two specified arrays are *deeply* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *deeply* equal to one another. * - * If two corresponding elements are nested arrays, they are also compared deeply. - * If any of arrays contains itself on any nesting level the behavior is undefined. + * Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + * That is, if two corresponding elements are nested arrays, they are also compared deeply. + * Elements of other types are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. * - * The elements of other types are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * If any of the arrays contain themselves at any nesting level, the behavior is undefined. + * + * @param other the array to compare deeply with this array. + * @return `true` if the two arrays are deeply equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.contentDeepEquals */ @SinceKotlin("1.1") @kotlin.internal.LowPriorityInOverloadResolution @@ -202,16 +207,21 @@ } /** - * Returns `true` if the two specified arrays are *deeply* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *deeply* equal to one another. * - * The specified arrays are also considered deeply equal if both are `null`. + * Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + * That is, if two corresponding elements are nested arrays, they are also compared deeply. + * Elements of other types are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. * - * If two corresponding elements are nested arrays, they are also compared deeply. - * If any of arrays contains itself on any nesting level the behavior is undefined. + * The arrays are also considered deeply equal if both are `null`. * - * The elements of other types are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * If any of the arrays contain themselves at any nesting level, the behavior is undefined. + * + * @param other the array to compare deeply with this array. + * @return `true` if the two arrays are deeply equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.contentDeepEquals */ @SinceKotlin("1.4") public actual infix fun <T> Array<out T>?.contentDeepEquals(other: Array<out T>?): Boolean { @@ -271,11 +281,20 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * If the arrays contain nested arrays, use [contentDeepEquals] to recursively compare their elements. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.arrayContentEquals */ @SinceKotlin("1.4") public actual infix fun <T> Array<out T>?.contentEquals(other: Array<out T>?): Boolean { @@ -283,11 +302,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun ByteArray?.contentEquals(other: ByteArray?): Boolean { @@ -295,11 +319,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun ShortArray?.contentEquals(other: ShortArray?): Boolean { @@ -307,11 +336,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun IntArray?.contentEquals(other: IntArray?): Boolean { @@ -319,11 +353,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun LongArray?.contentEquals(other: LongArray?): Boolean { @@ -331,11 +370,18 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun FloatArray?.contentEquals(other: FloatArray?): Boolean { @@ -343,11 +389,18 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun DoubleArray?.contentEquals(other: DoubleArray?): Boolean { @@ -355,11 +408,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.booleanArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun BooleanArray?.contentEquals(other: BooleanArray?): Boolean { @@ -367,11 +425,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.charArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun CharArray?.contentEquals(other: CharArray?): Boolean {
diff --git a/libraries/stdlib/js/src/kotlin/collections/AbstractMutableList.kt b/libraries/stdlib/js/src/kotlin/collections/AbstractMutableList.kt index 1def982..282fc51 100644 --- a/libraries/stdlib/js/src/kotlin/collections/AbstractMutableList.kt +++ b/libraries/stdlib/js/src/kotlin/collections/AbstractMutableList.kt
@@ -100,9 +100,14 @@ } /** - * Compares this list with another list instance with the ordered structural equality. + * Checks if the two specified lists are *structurally* equal to one another. * - * @return true, if [other] instance is a [List] of the same size, which contains the same elements in the same order. + * Two lists are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * @param other the list to compare with this list. + * @return `true` if [other] is a [List] that is structurally equal to this list, `false` otherwise. */ override fun equals(other: Any?): Boolean { if (other === this) return true
diff --git a/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt b/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt index f917f1c..ae7fcf4 100644 --- a/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt +++ b/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt
@@ -445,14 +445,19 @@ } /** - * Returns `true` if the two specified arrays are *deeply* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *deeply* equal to one another. * - * If two corresponding elements are nested arrays, they are also compared deeply. - * If any of arrays contains itself on any nesting level the behavior is undefined. + * Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + * That is, if two corresponding elements are nested arrays, they are also compared deeply. + * Elements of other types are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. * - * The elements of other types are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * If any of the arrays contain themselves at any nesting level, the behavior is undefined. + * + * @param other the array to compare deeply with this array. + * @return `true` if the two arrays are deeply equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.contentDeepEquals */ @SinceKotlin("1.1") @kotlin.internal.LowPriorityInOverloadResolution @@ -463,16 +468,21 @@ } /** - * Returns `true` if the two specified arrays are *deeply* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *deeply* equal to one another. * - * The specified arrays are also considered deeply equal if both are `null`. + * Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + * That is, if two corresponding elements are nested arrays, they are also compared deeply. + * Elements of other types are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. * - * If two corresponding elements are nested arrays, they are also compared deeply. - * If any of arrays contains itself on any nesting level the behavior is undefined. + * The arrays are also considered deeply equal if both are `null`. * - * The elements of other types are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * If any of the arrays contain themselves at any nesting level, the behavior is undefined. + * + * @param other the array to compare deeply with this array. + * @return `true` if the two arrays are deeply equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.contentDeepEquals */ @SinceKotlin("1.4") @JvmName("contentDeepEqualsNullable") @@ -551,11 +561,20 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * If the arrays contain nested arrays, use [contentDeepEquals] to recursively compare their elements. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.arrayContentEquals */ @SinceKotlin("1.4") @kotlin.internal.InlineOnly @@ -564,11 +583,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") @kotlin.internal.InlineOnly @@ -577,11 +601,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") @kotlin.internal.InlineOnly @@ -590,11 +619,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") @kotlin.internal.InlineOnly @@ -603,11 +637,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") @kotlin.internal.InlineOnly @@ -616,11 +655,18 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @SinceKotlin("1.4") @kotlin.internal.InlineOnly @@ -629,11 +675,18 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @SinceKotlin("1.4") @kotlin.internal.InlineOnly @@ -642,11 +695,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.booleanArrayContentEquals */ @SinceKotlin("1.4") @kotlin.internal.InlineOnly @@ -655,11 +713,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.charArrayContentEquals */ @SinceKotlin("1.4") @kotlin.internal.InlineOnly
diff --git a/libraries/stdlib/native-wasm/src/kotlin/collections/AbstractMutableList.kt b/libraries/stdlib/native-wasm/src/kotlin/collections/AbstractMutableList.kt index 78905c3..261a8f4 100644 --- a/libraries/stdlib/native-wasm/src/kotlin/collections/AbstractMutableList.kt +++ b/libraries/stdlib/native-wasm/src/kotlin/collections/AbstractMutableList.kt
@@ -89,6 +89,16 @@ } } + /** + * Checks if the two specified lists are *structurally* equal to one another. + * + * Two lists are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * @param other the list to compare with this list. + * @return `true` if [other] is a [List] that is structurally equal to this list, `false` otherwise. + */ override fun equals(other: Any?): Boolean { if (other === this) return true if (other !is List<*>) return false
diff --git a/libraries/stdlib/samples/test/samples/collections/arrays.kt b/libraries/stdlib/samples/test/samples/collections/arrays.kt index 1d949be..558de6e 100644 --- a/libraries/stdlib/samples/test/samples/collections/arrays.kt +++ b/libraries/stdlib/samples/test/samples/collections/arrays.kt
@@ -175,6 +175,97 @@ assertPrints(matrix.contentDeepToString(), "[[3, 7, 9], [0, 1, 0], [2, 4, 8]]") } + + @Sample + fun arrayContentEquals() { + val array = arrayOf("apples", "oranges", "lime") + + // the same size and equal elements + assertPrints(array.contentEquals(arrayOf("apples", "oranges", "lime")), "true") + + // different size + assertPrints(array.contentEquals(arrayOf("apples", "oranges")), "false") + + // the elements at index 1 are not equal + assertPrints(array.contentEquals(arrayOf("apples", "lime", "oranges")), "false") + } + + @Sample + fun charArrayContentEquals() { + val array = charArrayOf('a', 'b', 'c') + + // the same size and equal elements + assertPrints(array.contentEquals(charArrayOf('a', 'b', 'c')), "true") + + // different size + assertPrints(array.contentEquals(charArrayOf('a', 'b')), "false") + + // the elements at index 1 are not equal + assertPrints(array.contentEquals(charArrayOf('a', 'c', 'b')), "false") + } + + @Sample + fun booleanArrayContentEquals() { + val array = booleanArrayOf(true, false, true) + + // the same size and equal elements + assertPrints(array.contentEquals(booleanArrayOf(true, false, true)), "true") + + // different size + assertPrints(array.contentEquals(booleanArrayOf(true, false)), "false") + + // the elements at index 1 are not equal + assertPrints(array.contentEquals(booleanArrayOf(true, true, false)), "false") + } + + @Sample + fun intArrayContentEquals() { + val array = intArrayOf(1, 2, 3) + + // the same size and equal elements + assertPrints(array.contentEquals(intArrayOf(1, 2, 3)), "true") + + // different size + assertPrints(array.contentEquals(intArrayOf(1, 2)), "false") + + // the elements at index 1 are not equal + assertPrints(array.contentEquals(intArrayOf(1, 3, 2)), "false") + } + + @Sample + fun doubleArrayContentEquals() { + val array = doubleArrayOf(1.0, Double.NaN, 0.0) + + // the same size and equal elements, NaN is equal to NaN + assertPrints(array.contentEquals(doubleArrayOf(1.0, Double.NaN, 0.0)), "true") + + // different size + assertPrints(array.contentEquals(doubleArrayOf(1.0, Double.NaN)), "false") + + // the elements at index 2 are not equal, 0.0 is not equal to -0.0 + assertPrints(array.contentEquals(doubleArrayOf(1.0, Double.NaN, -0.0)), "false") + + // the elements at index 1 are not equal + assertPrints(array.contentEquals(doubleArrayOf(1.0, 0.0, Double.NaN)), "false") + } + + @Sample + fun contentDeepEquals() { + val identityMatrix = arrayOf( + intArrayOf(1, 0), + intArrayOf(0, 1) + ) + val reflectionMatrix = arrayOf( + intArrayOf(1, 0), + intArrayOf(0, -1) + ) + + // the elements at index [1][1] are not equal + assertPrints(identityMatrix.contentDeepEquals(reflectionMatrix), "false") + + reflectionMatrix[1][1] = 1 + assertPrints(identityMatrix.contentDeepEquals(reflectionMatrix), "true") + } } class CopyOfOperations {
diff --git a/libraries/stdlib/src/kotlin/collections/AbstractList.kt b/libraries/stdlib/src/kotlin/collections/AbstractList.kt index f534178..eb25adf 100644 --- a/libraries/stdlib/src/kotlin/collections/AbstractList.kt +++ b/libraries/stdlib/src/kotlin/collections/AbstractList.kt
@@ -52,9 +52,14 @@ } /** - * Compares this list with other list instance with the ordered structural equality. + * Checks if the two specified lists are *structurally* equal to one another. * - * @return true, if [other] instance is a [List] of the same size, which contains the same elements in the same order. + * Two lists are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * @param other the list to compare with this list. + * @return `true` if [other] is a [List] that is structurally equal to this list, `false` otherwise. */ override fun equals(other: Any?): Boolean { if (other === this) return true
diff --git a/libraries/stdlib/wasm/src/generated/_ArraysWasm.kt b/libraries/stdlib/wasm/src/generated/_ArraysWasm.kt index 8a114b2..526a921 100644 --- a/libraries/stdlib/wasm/src/generated/_ArraysWasm.kt +++ b/libraries/stdlib/wasm/src/generated/_ArraysWasm.kt
@@ -230,14 +230,19 @@ } /** - * Returns `true` if the two specified arrays are *deeply* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *deeply* equal to one another. * - * If two corresponding elements are nested arrays, they are also compared deeply. - * If any of arrays contains itself on any nesting level the behavior is undefined. + * Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + * That is, if two corresponding elements are nested arrays, they are also compared deeply. + * Elements of other types are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. * - * The elements of other types are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * If any of the arrays contain themselves at any nesting level, the behavior is undefined. + * + * @param other the array to compare deeply with this array. + * @return `true` if the two arrays are deeply equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.contentDeepEquals */ @SinceKotlin("1.1") @kotlin.internal.LowPriorityInOverloadResolution @@ -246,16 +251,21 @@ } /** - * Returns `true` if the two specified arrays are *deeply* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *deeply* equal to one another. * - * The specified arrays are also considered deeply equal if both are `null`. + * Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + * That is, if two corresponding elements are nested arrays, they are also compared deeply. + * Elements of other types are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. * - * If two corresponding elements are nested arrays, they are also compared deeply. - * If any of arrays contains itself on any nesting level the behavior is undefined. + * The arrays are also considered deeply equal if both are `null`. * - * The elements of other types are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * If any of the arrays contain themselves at any nesting level, the behavior is undefined. + * + * @param other the array to compare deeply with this array. + * @return `true` if the two arrays are deeply equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.contentDeepEquals */ @SinceKotlin("1.4") public actual infix fun <T> Array<out T>?.contentDeepEquals(other: Array<out T>?): Boolean { @@ -315,11 +325,18 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * If the arrays contain nested arrays, use [contentDeepEquals] to recursively compare their elements. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.arrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -329,11 +346,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -343,11 +363,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -357,11 +380,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -371,11 +397,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -385,11 +414,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -399,11 +433,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -413,11 +452,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.booleanArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -427,11 +469,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.charArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.1") @@ -441,11 +486,20 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * If the arrays contain nested arrays, use [contentDeepEquals] to recursively compare their elements. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.arrayContentEquals */ @SinceKotlin("1.4") public actual infix fun <T> Array<out T>?.contentEquals(other: Array<out T>?): Boolean { @@ -459,11 +513,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun ByteArray?.contentEquals(other: ByteArray?): Boolean { @@ -477,11 +536,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun ShortArray?.contentEquals(other: ShortArray?): Boolean { @@ -495,11 +559,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun IntArray?.contentEquals(other: IntArray?): Boolean { @@ -513,11 +582,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun LongArray?.contentEquals(other: LongArray?): Boolean { @@ -531,11 +605,18 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun FloatArray?.contentEquals(other: FloatArray?): Boolean { @@ -549,11 +630,18 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * Elements are compared for equality using the [equals][Any.equals] function. + * This means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.doubleArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun DoubleArray?.contentEquals(other: DoubleArray?): Boolean { @@ -567,11 +655,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.booleanArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun BooleanArray?.contentEquals(other: BooleanArray?): Boolean { @@ -585,11 +678,16 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. * - * The elements are compared for equality with the [equals][Any.equals] function. - * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * The arrays are also considered structurally equal if both are `null`. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.charArrayContentEquals */ @SinceKotlin("1.4") public actual infix fun CharArray?.contentEquals(other: CharArray?): Boolean {
diff --git a/libraries/stdlib/wasm/src/generated/_UArraysWasm.kt b/libraries/stdlib/wasm/src/generated/_UArraysWasm.kt index 1a8f3bf..1ad70da 100644 --- a/libraries/stdlib/wasm/src/generated/_UArraysWasm.kt +++ b/libraries/stdlib/wasm/src/generated/_UArraysWasm.kt
@@ -126,8 +126,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.3") @@ -138,8 +144,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.3") @@ -150,8 +162,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.3") @@ -162,8 +180,14 @@ } /** - * Returns `true` if the two specified arrays are *structurally* equal to one another, - * i.e. contain the same number of the same elements in the same order. + * Checks if the two specified arrays are *structurally* equal to one another. + * + * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + * + * @param other the array to compare with this array. + * @return `true` if the two arrays are structurally equal, `false` otherwise. + * + * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals */ @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.") @SinceKotlin("1.3")
diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt index 3c0f8c3..4e70c79 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt
@@ -87,6 +87,53 @@ annotation("""@DeprecatedSinceKotlin(hiddenSince = "1.4")""") } + private fun MemberBuilder.contentEqualsDoc(nullabilityNote: String = "") { + doc { + """ + Checks if the two specified arrays are *structurally* equal to one another. + + Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal. + """ + } + + val isArrayOfObjects = f == ArraysOfObjects + val isArrayOfFloatingPoint = primitive?.isFloatingPoint() == true + + if (isArrayOfObjects || isArrayOfFloatingPoint) { + val prefix = if (isArrayOfObjects) "For floating point numbers, this" else "This" + doc { + doc + """Elements are compared for equality using the [equals][Any.equals] function. + $prefix means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + """ + } + } + doc { + doc + nullabilityNote + } + if (isArrayOfObjects) { + doc { + doc + """ + If the arrays contain nested arrays, use [contentDeepEquals] to recursively compare their elements. + """ + } + } + doc { + doc + """ + @param other the array to compare with this array. + @return `true` if the two arrays are structurally equal, `false` otherwise. + """ + } + + val sampleMethod = when { + isArrayOfObjects -> "arrayContentEquals" + isArrayOfFloatingPoint -> "doubleArrayContentEquals" + primitive == PrimitiveType.Char -> "charArrayContentEquals" + primitive == PrimitiveType.Boolean -> "booleanArrayContentEquals" + else -> "intArrayContentEquals" + } + sample("samples.collections.Arrays.ContentOperations.$sampleMethod") + } + val f_contentEquals = fn("contentEquals(other: SELF)") { platforms(Platform.Native) include(ArraysOfObjects, ArraysOfPrimitives, ArraysOfUnsigned) @@ -94,23 +141,9 @@ since("1.1") deprecatedNonNullArrayFunction() infix(true) - doc { - """ - Returns `true` if the two specified arrays are *structurally* equal to one another, - i.e. contain the same number of the same elements in the same order. - """ - } returns("Boolean") + contentEqualsDoc() body { "return this.contentEquals(other)" } - if (f == ArraysOfUnsigned) { - return@builder - } - doc { - doc + """ - The elements are compared for equality with the [equals][Any.equals] function. - For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. - """ - } } val f_contentEquals_nullable = fn("contentEquals(other: SELF?)") { @@ -118,25 +151,17 @@ } builder { since("1.4") infix(true) - doc { - """ - Returns `true` if the two specified arrays are *structurally* equal to one another, - i.e. contain the same number of the same elements in the same order. - """ - } receiver("SELF?") returns("Boolean") + contentEqualsDoc( + nullabilityNote = """ + The arrays are also considered structurally equal if both are `null`. + """ + ) if (family == ArraysOfUnsigned) { body { "return this?.storage.contentEquals(other?.storage)" } return@builder } - - doc { - doc + """ - The elements are compared for equality with the [equals][Any.equals] function. - For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. - """ - } on(Platform.JVM) { inlineOnly() body { "return java.util.Arrays.equals(this, other)" } @@ -164,25 +189,39 @@ } } + private fun MemberBuilder.contentDeepEqualsDoc(nullabilityNote: String = "") { + doc { + """ + Checks if the two specified arrays are *deeply* equal to one another. + + Two arrays are considered deeply equal if they have the same size, and elements at corresponding indices are deeply equal. + That is, if two corresponding elements are nested arrays, they are also compared deeply. + Elements of other types are compared for equality using the [equals][Any.equals] function. + For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`. + """ + } + doc { + doc + nullabilityNote + } + doc { + doc + """ + If any of the arrays contain themselves at any nesting level, the behavior is undefined. + + @param other the array to compare deeply with this array. + @return `true` if the two arrays are deeply equal, `false` otherwise. + """ + } + sample("samples.collections.Arrays.ContentOperations.contentDeepEquals") + } + val f_contentDeepEquals = fn("contentDeepEquals(other: SELF)") { include(ArraysOfObjects) } builder { since("1.1") annotation("@kotlin.internal.LowPriorityInOverloadResolution") infix(true) - doc { - """ - Returns `true` if the two specified arrays are *deeply* equal to one another, - i.e. contain the same number of the same elements in the same order. - - If two corresponding elements are nested arrays, they are also compared deeply. - If any of arrays contains itself on any nesting level the behavior is undefined. - - The elements of other types are compared for equality with the [equals][Any.equals] function. - For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. - """ - } returns("Boolean") + contentDeepEqualsDoc() body { "return this.contentDeepEquals(other)" } on(Platform.JVM) { inlineOnly() @@ -195,22 +234,13 @@ } builder { since("1.4") infix(true) - doc { - """ - Returns `true` if the two specified arrays are *deeply* equal to one another, - i.e. contain the same number of the same elements in the same order. - - The specified arrays are also considered deeply equal if both are `null`. - - If two corresponding elements are nested arrays, they are also compared deeply. - If any of arrays contains itself on any nesting level the behavior is undefined. - - The elements of other types are compared for equality with the [equals][Any.equals] function. - For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`. - """ - } receiver("SELF?") returns("Boolean") + contentDeepEqualsDoc( + nullabilityNote = """ + The arrays are also considered deeply equal if both are `null`. + """ + ) on(Platform.JVM) { inlineOnly() annotation("""@JvmName("contentDeepEqualsNullable")""")