diff --git a/libraries/stdlib/src/generated/_Arrays.kt b/libraries/stdlib/src/generated/_Arrays.kt index 3a04ab0b27f..f382f366f61 100644 --- a/libraries/stdlib/src/generated/_Arrays.kt +++ b/libraries/stdlib/src/generated/_Arrays.kt @@ -5486,6 +5486,7 @@ public fun Array.toShortArray(): ShortArray { * Returns a [Map] containing key-value pairs provided by [transform] function * applied to elements of the given array. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun Array.associate(transform: (T) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5497,6 +5498,7 @@ public inline fun Array.associate(transform: (T) -> Pair) * Returns a [Map] containing key-value pairs provided by [transform] function * applied to elements of the given array. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun ByteArray.associate(transform: (Byte) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5508,6 +5510,7 @@ public inline fun ByteArray.associate(transform: (Byte) -> Pair): M * Returns a [Map] containing key-value pairs provided by [transform] function * applied to elements of the given array. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun ShortArray.associate(transform: (Short) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5519,6 +5522,7 @@ public inline fun ShortArray.associate(transform: (Short) -> Pair): * Returns a [Map] containing key-value pairs provided by [transform] function * applied to elements of the given array. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun IntArray.associate(transform: (Int) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5530,6 +5534,7 @@ public inline fun IntArray.associate(transform: (Int) -> Pair): Map * Returns a [Map] containing key-value pairs provided by [transform] function * applied to elements of the given array. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun LongArray.associate(transform: (Long) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5541,6 +5546,7 @@ public inline fun LongArray.associate(transform: (Long) -> Pair): M * Returns a [Map] containing key-value pairs provided by [transform] function * applied to elements of the given array. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun FloatArray.associate(transform: (Float) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5552,6 +5558,7 @@ public inline fun FloatArray.associate(transform: (Float) -> Pair): * Returns a [Map] containing key-value pairs provided by [transform] function * applied to elements of the given array. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun DoubleArray.associate(transform: (Double) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5563,6 +5570,7 @@ public inline fun DoubleArray.associate(transform: (Double) -> Pair * Returns a [Map] containing key-value pairs provided by [transform] function * applied to elements of the given array. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun BooleanArray.associate(transform: (Boolean) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5574,6 +5582,7 @@ public inline fun BooleanArray.associate(transform: (Boolean) -> Pair CharArray.associate(transform: (Char) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5585,6 +5594,7 @@ public inline fun CharArray.associate(transform: (Char) -> Pair): M * Returns a [Map] containing the elements from the given array indexed by the key * returned from [keySelector] function applied to each element. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun Array.associateBy(keySelector: (T) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5596,6 +5606,7 @@ public inline fun Array.associateBy(keySelector: (T) -> K): Map ByteArray.associateBy(keySelector: (Byte) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5607,6 +5618,7 @@ public inline fun ByteArray.associateBy(keySelector: (Byte) -> K): Map ShortArray.associateBy(keySelector: (Short) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5618,6 +5630,7 @@ public inline fun ShortArray.associateBy(keySelector: (Short) -> K): Map IntArray.associateBy(keySelector: (Int) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5629,6 +5642,7 @@ public inline fun IntArray.associateBy(keySelector: (Int) -> K): Map * Returns a [Map] containing the elements from the given array indexed by the key * returned from [keySelector] function applied to each element. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun LongArray.associateBy(keySelector: (Long) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5640,6 +5654,7 @@ public inline fun LongArray.associateBy(keySelector: (Long) -> K): Map FloatArray.associateBy(keySelector: (Float) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5651,6 +5666,7 @@ public inline fun FloatArray.associateBy(keySelector: (Float) -> K): Map DoubleArray.associateBy(keySelector: (Double) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5662,6 +5678,7 @@ public inline fun DoubleArray.associateBy(keySelector: (Double) -> K): Map BooleanArray.associateBy(keySelector: (Boolean) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5673,6 +5690,7 @@ public inline fun BooleanArray.associateBy(keySelector: (Boolean) -> K): Map * Returns a [Map] containing the elements from the given array indexed by the key * returned from [keySelector] function applied to each element. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun CharArray.associateBy(keySelector: (Char) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5683,6 +5701,7 @@ public inline fun CharArray.associateBy(keySelector: (Char) -> K): Map Array.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5693,6 +5712,7 @@ public inline fun Array.associateBy(keySelector: (T) -> K, valu /** * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun ByteArray.associateBy(keySelector: (Byte) -> K, valueTransform: (Byte) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5703,6 +5723,7 @@ public inline fun ByteArray.associateBy(keySelector: (Byte) -> K, valueTr /** * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun ShortArray.associateBy(keySelector: (Short) -> K, valueTransform: (Short) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5713,6 +5734,7 @@ public inline fun ShortArray.associateBy(keySelector: (Short) -> K, value /** * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun IntArray.associateBy(keySelector: (Int) -> K, valueTransform: (Int) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5723,6 +5745,7 @@ public inline fun IntArray.associateBy(keySelector: (Int) -> K, valueTran /** * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun LongArray.associateBy(keySelector: (Long) -> K, valueTransform: (Long) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5733,6 +5756,7 @@ public inline fun LongArray.associateBy(keySelector: (Long) -> K, valueTr /** * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun FloatArray.associateBy(keySelector: (Float) -> K, valueTransform: (Float) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5743,6 +5767,7 @@ public inline fun FloatArray.associateBy(keySelector: (Float) -> K, value /** * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun DoubleArray.associateBy(keySelector: (Double) -> K, valueTransform: (Double) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5753,6 +5778,7 @@ public inline fun DoubleArray.associateBy(keySelector: (Double) -> K, val /** * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun BooleanArray.associateBy(keySelector: (Boolean) -> K, valueTransform: (Boolean) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -5763,6 +5789,7 @@ public inline fun BooleanArray.associateBy(keySelector: (Boolean) -> K, v /** * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original array. */ public inline fun CharArray.associateBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -6445,6 +6472,7 @@ public fun CharArray.toMutableList(): MutableList { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original array. */ public fun Array.toSet(): Set { return when (size) { @@ -6456,6 +6484,7 @@ public fun Array.toSet(): Set { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original array. */ public fun ByteArray.toSet(): Set { return when (size) { @@ -6467,6 +6496,7 @@ public fun ByteArray.toSet(): Set { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original array. */ public fun ShortArray.toSet(): Set { return when (size) { @@ -6478,6 +6508,7 @@ public fun ShortArray.toSet(): Set { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original array. */ public fun IntArray.toSet(): Set { return when (size) { @@ -6489,6 +6520,7 @@ public fun IntArray.toSet(): Set { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original array. */ public fun LongArray.toSet(): Set { return when (size) { @@ -6500,6 +6532,7 @@ public fun LongArray.toSet(): Set { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original array. */ public fun FloatArray.toSet(): Set { return when (size) { @@ -6511,6 +6544,7 @@ public fun FloatArray.toSet(): Set { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original array. */ public fun DoubleArray.toSet(): Set { return when (size) { @@ -6522,6 +6556,7 @@ public fun DoubleArray.toSet(): Set { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original array. */ public fun BooleanArray.toSet(): Set { return when (size) { @@ -6533,6 +6568,7 @@ public fun BooleanArray.toSet(): Set { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original array. */ public fun CharArray.toSet(): Set { return when (size) { @@ -6788,6 +6824,7 @@ public inline fun > CharArray.flatMapTo(destinati /** * Groups elements of the original array by the key returned by the given [keySelector] function * applied to each element and returns a map where each group key is associated with a list of corresponding elements. + * The returned map preserves the entry iteration order of the keys produced from the original array. * @sample test.collections.CollectionTest.groupBy */ public inline fun Array.groupBy(keySelector: (T) -> K): Map> { @@ -6797,6 +6834,7 @@ public inline fun Array.groupBy(keySelector: (T) -> K): Map ByteArray.groupBy(keySelector: (Byte) -> K): Map> { @@ -6806,6 +6844,7 @@ public inline fun ByteArray.groupBy(keySelector: (Byte) -> K): Map ShortArray.groupBy(keySelector: (Short) -> K): Map> { @@ -6815,6 +6854,7 @@ public inline fun ShortArray.groupBy(keySelector: (Short) -> K): Map IntArray.groupBy(keySelector: (Int) -> K): Map> { @@ -6824,6 +6864,7 @@ public inline fun IntArray.groupBy(keySelector: (Int) -> K): Map LongArray.groupBy(keySelector: (Long) -> K): Map> { @@ -6833,6 +6874,7 @@ public inline fun LongArray.groupBy(keySelector: (Long) -> K): Map FloatArray.groupBy(keySelector: (Float) -> K): Map> { @@ -6842,6 +6884,7 @@ public inline fun FloatArray.groupBy(keySelector: (Float) -> K): Map DoubleArray.groupBy(keySelector: (Double) -> K): Map> { @@ -6851,6 +6894,7 @@ public inline fun DoubleArray.groupBy(keySelector: (Double) -> K): Map BooleanArray.groupBy(keySelector: (Boolean) -> K): Map> { @@ -6860,6 +6904,7 @@ public inline fun BooleanArray.groupBy(keySelector: (Boolean) -> K): Map CharArray.groupBy(keySelector: (Char) -> K): Map> { @@ -6870,6 +6915,7 @@ public inline fun CharArray.groupBy(keySelector: (Char) -> K): Map Array.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map> { @@ -6880,6 +6926,7 @@ public inline fun Array.groupBy(keySelector: (T) -> K, valueTra * Groups values returned by the [valueTransform] function applied to each element of the original array * by the key returned by the given [keySelector] function applied to the element * and returns a map where each group key is associated with a list of corresponding values. + * The returned map preserves the entry iteration order of the keys produced from the original array. * @sample test.collections.CollectionTest.groupByKeysAndValues */ public inline fun ByteArray.groupBy(keySelector: (Byte) -> K, valueTransform: (Byte) -> V): Map> { @@ -6890,6 +6937,7 @@ public inline fun ByteArray.groupBy(keySelector: (Byte) -> K, valueTransf * Groups values returned by the [valueTransform] function applied to each element of the original array * by the key returned by the given [keySelector] function applied to the element * and returns a map where each group key is associated with a list of corresponding values. + * The returned map preserves the entry iteration order of the keys produced from the original array. * @sample test.collections.CollectionTest.groupByKeysAndValues */ public inline fun ShortArray.groupBy(keySelector: (Short) -> K, valueTransform: (Short) -> V): Map> { @@ -6900,6 +6948,7 @@ public inline fun ShortArray.groupBy(keySelector: (Short) -> K, valueTran * Groups values returned by the [valueTransform] function applied to each element of the original array * by the key returned by the given [keySelector] function applied to the element * and returns a map where each group key is associated with a list of corresponding values. + * The returned map preserves the entry iteration order of the keys produced from the original array. * @sample test.collections.CollectionTest.groupByKeysAndValues */ public inline fun IntArray.groupBy(keySelector: (Int) -> K, valueTransform: (Int) -> V): Map> { @@ -6910,6 +6959,7 @@ public inline fun IntArray.groupBy(keySelector: (Int) -> K, valueTransfor * Groups values returned by the [valueTransform] function applied to each element of the original array * by the key returned by the given [keySelector] function applied to the element * and returns a map where each group key is associated with a list of corresponding values. + * The returned map preserves the entry iteration order of the keys produced from the original array. * @sample test.collections.CollectionTest.groupByKeysAndValues */ public inline fun LongArray.groupBy(keySelector: (Long) -> K, valueTransform: (Long) -> V): Map> { @@ -6920,6 +6970,7 @@ public inline fun LongArray.groupBy(keySelector: (Long) -> K, valueTransf * Groups values returned by the [valueTransform] function applied to each element of the original array * by the key returned by the given [keySelector] function applied to the element * and returns a map where each group key is associated with a list of corresponding values. + * The returned map preserves the entry iteration order of the keys produced from the original array. * @sample test.collections.CollectionTest.groupByKeysAndValues */ public inline fun FloatArray.groupBy(keySelector: (Float) -> K, valueTransform: (Float) -> V): Map> { @@ -6930,6 +6981,7 @@ public inline fun FloatArray.groupBy(keySelector: (Float) -> K, valueTran * Groups values returned by the [valueTransform] function applied to each element of the original array * by the key returned by the given [keySelector] function applied to the element * and returns a map where each group key is associated with a list of corresponding values. + * The returned map preserves the entry iteration order of the keys produced from the original array. * @sample test.collections.CollectionTest.groupByKeysAndValues */ public inline fun DoubleArray.groupBy(keySelector: (Double) -> K, valueTransform: (Double) -> V): Map> { @@ -6940,6 +6992,7 @@ public inline fun DoubleArray.groupBy(keySelector: (Double) -> K, valueTr * Groups values returned by the [valueTransform] function applied to each element of the original array * by the key returned by the given [keySelector] function applied to the element * and returns a map where each group key is associated with a list of corresponding values. + * The returned map preserves the entry iteration order of the keys produced from the original array. * @sample test.collections.CollectionTest.groupByKeysAndValues */ public inline fun BooleanArray.groupBy(keySelector: (Boolean) -> K, valueTransform: (Boolean) -> V): Map> { @@ -6950,6 +7003,7 @@ public inline fun BooleanArray.groupBy(keySelector: (Boolean) -> K, value * Groups values returned by the [valueTransform] function applied to each element of the original array * by the key returned by the given [keySelector] function applied to the element * and returns a map where each group key is associated with a list of corresponding values. + * The returned map preserves the entry iteration order of the keys produced from the original array. * @sample test.collections.CollectionTest.groupByKeysAndValues */ public inline fun CharArray.groupBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map> { @@ -7923,6 +7977,7 @@ public inline fun CharArray.distinctBy(selector: (Char) -> K): List { /** * Returns a set containing all elements that are contained by both this set and the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun Array.intersect(other: Iterable): Set { val set = this.toMutableSet() @@ -7932,6 +7987,7 @@ public infix fun Array.intersect(other: Iterable): Set { /** * Returns a set containing all elements that are contained by both this set and the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun ByteArray.intersect(other: Iterable): Set { val set = this.toMutableSet() @@ -7941,6 +7997,7 @@ public infix fun ByteArray.intersect(other: Iterable): Set { /** * Returns a set containing all elements that are contained by both this set and the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun ShortArray.intersect(other: Iterable): Set { val set = this.toMutableSet() @@ -7950,6 +8007,7 @@ public infix fun ShortArray.intersect(other: Iterable): Set { /** * Returns a set containing all elements that are contained by both this set and the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun IntArray.intersect(other: Iterable): Set { val set = this.toMutableSet() @@ -7959,6 +8017,7 @@ public infix fun IntArray.intersect(other: Iterable): Set { /** * Returns a set containing all elements that are contained by both this set and the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun LongArray.intersect(other: Iterable): Set { val set = this.toMutableSet() @@ -7968,6 +8027,7 @@ public infix fun LongArray.intersect(other: Iterable): Set { /** * Returns a set containing all elements that are contained by both this set and the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun FloatArray.intersect(other: Iterable): Set { val set = this.toMutableSet() @@ -7977,6 +8037,7 @@ public infix fun FloatArray.intersect(other: Iterable): Set { /** * Returns a set containing all elements that are contained by both this set and the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun DoubleArray.intersect(other: Iterable): Set { val set = this.toMutableSet() @@ -7986,6 +8047,7 @@ public infix fun DoubleArray.intersect(other: Iterable): Set { /** * Returns a set containing all elements that are contained by both this set and the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun BooleanArray.intersect(other: Iterable): Set { val set = this.toMutableSet() @@ -7995,6 +8057,7 @@ public infix fun BooleanArray.intersect(other: Iterable): Set /** * Returns a set containing all elements that are contained by both this set and the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun CharArray.intersect(other: Iterable): Set { val set = this.toMutableSet() @@ -8003,7 +8066,8 @@ public infix fun CharArray.intersect(other: Iterable): Set { } /** - * Returns a set containing all elements that are contained by this set and not contained by the specified collection. + * Returns a set containing all elements that are contained by this array and not contained by the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun Array.subtract(other: Iterable): Set { val set = this.toMutableSet() @@ -8012,7 +8076,8 @@ public infix fun Array.subtract(other: Iterable): Set { } /** - * Returns a set containing all elements that are contained by this set and not contained by the specified collection. + * Returns a set containing all elements that are contained by this array and not contained by the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun ByteArray.subtract(other: Iterable): Set { val set = this.toMutableSet() @@ -8021,7 +8086,8 @@ public infix fun ByteArray.subtract(other: Iterable): Set { } /** - * Returns a set containing all elements that are contained by this set and not contained by the specified collection. + * Returns a set containing all elements that are contained by this array and not contained by the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun ShortArray.subtract(other: Iterable): Set { val set = this.toMutableSet() @@ -8030,7 +8096,8 @@ public infix fun ShortArray.subtract(other: Iterable): Set { } /** - * Returns a set containing all elements that are contained by this set and not contained by the specified collection. + * Returns a set containing all elements that are contained by this array and not contained by the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun IntArray.subtract(other: Iterable): Set { val set = this.toMutableSet() @@ -8039,7 +8106,8 @@ public infix fun IntArray.subtract(other: Iterable): Set { } /** - * Returns a set containing all elements that are contained by this set and not contained by the specified collection. + * Returns a set containing all elements that are contained by this array and not contained by the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun LongArray.subtract(other: Iterable): Set { val set = this.toMutableSet() @@ -8048,7 +8116,8 @@ public infix fun LongArray.subtract(other: Iterable): Set { } /** - * Returns a set containing all elements that are contained by this set and not contained by the specified collection. + * Returns a set containing all elements that are contained by this array and not contained by the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun FloatArray.subtract(other: Iterable): Set { val set = this.toMutableSet() @@ -8057,7 +8126,8 @@ public infix fun FloatArray.subtract(other: Iterable): Set { } /** - * Returns a set containing all elements that are contained by this set and not contained by the specified collection. + * Returns a set containing all elements that are contained by this array and not contained by the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun DoubleArray.subtract(other: Iterable): Set { val set = this.toMutableSet() @@ -8066,7 +8136,8 @@ public infix fun DoubleArray.subtract(other: Iterable): Set { } /** - * Returns a set containing all elements that are contained by this set and not contained by the specified collection. + * Returns a set containing all elements that are contained by this array and not contained by the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun BooleanArray.subtract(other: Iterable): Set { val set = this.toMutableSet() @@ -8075,7 +8146,8 @@ public infix fun BooleanArray.subtract(other: Iterable): Set { } /** - * Returns a set containing all elements that are contained by this set and not contained by the specified collection. + * Returns a set containing all elements that are contained by this array and not contained by the specified collection. + * The returned set preserves the element iteration order of the original array. */ public infix fun CharArray.subtract(other: Iterable): Set { val set = this.toMutableSet() @@ -8085,6 +8157,7 @@ public infix fun CharArray.subtract(other: Iterable): Set { /** * Returns a mutable set containing all distinct elements from the given array. + * The returned set preserves the element iteration order of the original array. */ public fun Array.toMutableSet(): MutableSet { val set = LinkedHashSet(mapCapacity(size)) @@ -8094,6 +8167,7 @@ public fun Array.toMutableSet(): MutableSet { /** * Returns a mutable set containing all distinct elements from the given array. + * The returned set preserves the element iteration order of the original array. */ public fun ByteArray.toMutableSet(): MutableSet { val set = LinkedHashSet(mapCapacity(size)) @@ -8103,6 +8177,7 @@ public fun ByteArray.toMutableSet(): MutableSet { /** * Returns a mutable set containing all distinct elements from the given array. + * The returned set preserves the element iteration order of the original array. */ public fun ShortArray.toMutableSet(): MutableSet { val set = LinkedHashSet(mapCapacity(size)) @@ -8112,6 +8187,7 @@ public fun ShortArray.toMutableSet(): MutableSet { /** * Returns a mutable set containing all distinct elements from the given array. + * The returned set preserves the element iteration order of the original array. */ public fun IntArray.toMutableSet(): MutableSet { val set = LinkedHashSet(mapCapacity(size)) @@ -8121,6 +8197,7 @@ public fun IntArray.toMutableSet(): MutableSet { /** * Returns a mutable set containing all distinct elements from the given array. + * The returned set preserves the element iteration order of the original array. */ public fun LongArray.toMutableSet(): MutableSet { val set = LinkedHashSet(mapCapacity(size)) @@ -8130,6 +8207,7 @@ public fun LongArray.toMutableSet(): MutableSet { /** * Returns a mutable set containing all distinct elements from the given array. + * The returned set preserves the element iteration order of the original array. */ public fun FloatArray.toMutableSet(): MutableSet { val set = LinkedHashSet(mapCapacity(size)) @@ -8139,6 +8217,7 @@ public fun FloatArray.toMutableSet(): MutableSet { /** * Returns a mutable set containing all distinct elements from the given array. + * The returned set preserves the element iteration order of the original array. */ public fun DoubleArray.toMutableSet(): MutableSet { val set = LinkedHashSet(mapCapacity(size)) @@ -8148,6 +8227,7 @@ public fun DoubleArray.toMutableSet(): MutableSet { /** * Returns a mutable set containing all distinct elements from the given array. + * The returned set preserves the element iteration order of the original array. */ public fun BooleanArray.toMutableSet(): MutableSet { val set = LinkedHashSet(mapCapacity(size)) @@ -8157,6 +8237,7 @@ public fun BooleanArray.toMutableSet(): MutableSet { /** * Returns a mutable set containing all distinct elements from the given array. + * The returned set preserves the element iteration order of the original array. */ public fun CharArray.toMutableSet(): MutableSet { val set = LinkedHashSet(mapCapacity(size)) @@ -8166,6 +8247,9 @@ public fun CharArray.toMutableSet(): MutableSet { /** * Returns a set containing all distinct elements from both collections. + * The returned set preserves the element iteration order of the original array. + * Those elements of the [other] collection that are unique are iterated in the end + * in the order of the [other] collection. */ public infix fun Array.union(other: Iterable): Set { val set = this.toMutableSet() @@ -8175,6 +8259,9 @@ public infix fun Array.union(other: Iterable): Set { /** * Returns a set containing all distinct elements from both collections. + * The returned set preserves the element iteration order of the original array. + * Those elements of the [other] collection that are unique are iterated in the end + * in the order of the [other] collection. */ public infix fun ByteArray.union(other: Iterable): Set { val set = this.toMutableSet() @@ -8184,6 +8271,9 @@ public infix fun ByteArray.union(other: Iterable): Set { /** * Returns a set containing all distinct elements from both collections. + * The returned set preserves the element iteration order of the original array. + * Those elements of the [other] collection that are unique are iterated in the end + * in the order of the [other] collection. */ public infix fun ShortArray.union(other: Iterable): Set { val set = this.toMutableSet() @@ -8193,6 +8283,9 @@ public infix fun ShortArray.union(other: Iterable): Set { /** * Returns a set containing all distinct elements from both collections. + * The returned set preserves the element iteration order of the original array. + * Those elements of the [other] collection that are unique are iterated in the end + * in the order of the [other] collection. */ public infix fun IntArray.union(other: Iterable): Set { val set = this.toMutableSet() @@ -8202,6 +8295,9 @@ public infix fun IntArray.union(other: Iterable): Set { /** * Returns a set containing all distinct elements from both collections. + * The returned set preserves the element iteration order of the original array. + * Those elements of the [other] collection that are unique are iterated in the end + * in the order of the [other] collection. */ public infix fun LongArray.union(other: Iterable): Set { val set = this.toMutableSet() @@ -8211,6 +8307,9 @@ public infix fun LongArray.union(other: Iterable): Set { /** * Returns a set containing all distinct elements from both collections. + * The returned set preserves the element iteration order of the original array. + * Those elements of the [other] collection that are unique are iterated in the end + * in the order of the [other] collection. */ public infix fun FloatArray.union(other: Iterable): Set { val set = this.toMutableSet() @@ -8220,6 +8319,9 @@ public infix fun FloatArray.union(other: Iterable): Set { /** * Returns a set containing all distinct elements from both collections. + * The returned set preserves the element iteration order of the original array. + * Those elements of the [other] collection that are unique are iterated in the end + * in the order of the [other] collection. */ public infix fun DoubleArray.union(other: Iterable): Set { val set = this.toMutableSet() @@ -8229,6 +8331,9 @@ public infix fun DoubleArray.union(other: Iterable): Set { /** * Returns a set containing all distinct elements from both collections. + * The returned set preserves the element iteration order of the original array. + * Those elements of the [other] collection that are unique are iterated in the end + * in the order of the [other] collection. */ public infix fun BooleanArray.union(other: Iterable): Set { val set = this.toMutableSet() @@ -8238,6 +8343,9 @@ public infix fun BooleanArray.union(other: Iterable): Set { /** * Returns a set containing all distinct elements from both collections. + * The returned set preserves the element iteration order of the original array. + * Those elements of the [other] collection that are unique are iterated in the end + * in the order of the [other] collection. */ public infix fun CharArray.union(other: Iterable): Set { val set = this.toMutableSet() diff --git a/libraries/stdlib/src/generated/_Collections.kt b/libraries/stdlib/src/generated/_Collections.kt index 50e9bcbbd10..af28a4f44c3 100644 --- a/libraries/stdlib/src/generated/_Collections.kt +++ b/libraries/stdlib/src/generated/_Collections.kt @@ -958,6 +958,7 @@ public fun Collection.toShortArray(): ShortArray { * Returns a [Map] containing key-value pairs provided by [transform] function * applied to elements of the given collection. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original collection. */ public inline fun Iterable.associate(transform: (T) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -969,6 +970,7 @@ public inline fun Iterable.associate(transform: (T) -> Pair): * Returns a [Map] containing the elements from the given collection indexed by the key * returned from [keySelector] function applied to each element. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original collection. */ public inline fun Iterable.associateBy(keySelector: (T) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -979,6 +981,7 @@ public inline fun Iterable.associateBy(keySelector: (T) -> K): Map Iterable.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -1073,6 +1076,7 @@ public fun Collection.toMutableList(): MutableList { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original collection. */ public fun Iterable.toSet(): Set { if (this is Collection) { @@ -1123,6 +1127,7 @@ public inline fun > Iterable.flatMapTo(dest /** * Groups elements of the original collection by the key returned by the given [keySelector] function * applied to each element and returns a map where each group key is associated with a list of corresponding elements. + * The returned map preserves the entry iteration order of the keys produced from the original collection. * @sample test.collections.CollectionTest.groupBy */ public inline fun Iterable.groupBy(keySelector: (T) -> K): Map> { @@ -1133,6 +1138,7 @@ public inline fun Iterable.groupBy(keySelector: (T) -> K): Map Iterable.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map> { @@ -1284,6 +1290,7 @@ public inline fun Iterable.distinctBy(selector: (T) -> K): List { /** * Returns a set containing all elements that are contained by both this set and the specified collection. + * The returned set preserves the element iteration order of the original collection. */ public infix fun Iterable.intersect(other: Iterable): Set { val set = this.toMutableSet() @@ -1292,7 +1299,8 @@ public infix fun Iterable.intersect(other: Iterable): Set { } /** - * Returns a set containing all elements that are contained by this set and not contained by the specified collection. + * Returns a set containing all elements that are contained by this collection and not contained by the specified collection. + * The returned set preserves the element iteration order of the original collection. */ public infix fun Iterable.subtract(other: Iterable): Set { val set = this.toMutableSet() @@ -1302,6 +1310,7 @@ public infix fun Iterable.subtract(other: Iterable): Set { /** * Returns a mutable set containing all distinct elements from the given collection. + * The returned set preserves the element iteration order of the original collection. */ public fun Iterable.toMutableSet(): MutableSet { return when (this) { @@ -1312,6 +1321,9 @@ public fun Iterable.toMutableSet(): MutableSet { /** * Returns a set containing all distinct elements from both collections. + * The returned set preserves the element iteration order of the original collection. + * Those elements of the [other] collection that are unique are iterated in the end + * in the order of the [other] collection. */ public infix fun Iterable.union(other: Iterable): Set { val set = this.toMutableSet() diff --git a/libraries/stdlib/src/generated/_Sequences.kt b/libraries/stdlib/src/generated/_Sequences.kt index b11d7f0c3ae..e965417a029 100644 --- a/libraries/stdlib/src/generated/_Sequences.kt +++ b/libraries/stdlib/src/generated/_Sequences.kt @@ -457,6 +457,7 @@ public fun Sequence.sortedWith(comparator: Comparator): Sequence * Returns a [Map] containing key-value pairs provided by [transform] function * applied to elements of the given sequence. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original sequence. */ public inline fun Sequence.associate(transform: (T) -> Pair): Map { return associateTo(LinkedHashMap(), transform) @@ -466,6 +467,7 @@ public inline fun Sequence.associate(transform: (T) -> Pair): * Returns a [Map] containing the elements from the given sequence indexed by the key * returned from [keySelector] function applied to each element. * If any two elements would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original sequence. */ public inline fun Sequence.associateBy(keySelector: (T) -> K): Map { return associateByTo(LinkedHashMap(), keySelector) @@ -474,6 +476,7 @@ public inline fun Sequence.associateBy(keySelector: (T) -> K): Map Sequence.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map { return associateByTo(LinkedHashMap(), keySelector, valueTransform) @@ -550,6 +553,7 @@ public fun Sequence.toMutableList(): MutableList { /** * Returns a [Set] of all elements. + * The returned set preserves the element iteration order of the original sequence. */ public fun Sequence.toSet(): Set { return toCollection(LinkedHashSet()).optimizeReadOnlySet() @@ -593,6 +597,7 @@ public inline fun > Sequence.flatMapTo(dest /** * Groups elements of the original sequence by the key returned by the given [keySelector] function * applied to each element and returns a map where each group key is associated with a list of corresponding elements. + * The returned map preserves the entry iteration order of the keys produced from the original sequence. * @sample test.collections.CollectionTest.groupBy */ public inline fun Sequence.groupBy(keySelector: (T) -> K): Map> { @@ -603,6 +608,7 @@ public inline fun Sequence.groupBy(keySelector: (T) -> K): Map Sequence.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map> { @@ -745,6 +751,7 @@ public fun Sequence.distinctBy(selector: (T) -> K): Sequence { /** * Returns a mutable set containing all distinct elements from the given sequence. + * The returned set preserves the element iteration order of the original sequence. */ public fun Sequence.toMutableSet(): MutableSet { val set = LinkedHashSet() diff --git a/libraries/stdlib/src/generated/_Sets.kt b/libraries/stdlib/src/generated/_Sets.kt index 49d158a48dd..6bc045cc83e 100644 --- a/libraries/stdlib/src/generated/_Sets.kt +++ b/libraries/stdlib/src/generated/_Sets.kt @@ -15,6 +15,7 @@ import java.util.Collections // TODO: it's temporary while we have java.util.Col /** * Returns a set containing all elements of the original set except the given [element]. + * The returned set preserves the element iteration order of the original set. */ public operator fun Set.minus(element: T): Set { val result = LinkedHashSet(mapCapacity(size)) @@ -24,6 +25,7 @@ public operator fun Set.minus(element: T): Set { /** * Returns a set containing all elements of the original set except the elements contained in the given [elements] array. + * The returned set preserves the element iteration order of the original set. */ public operator fun Set.minus(elements: Array): Set { val result = LinkedHashSet(this) @@ -33,6 +35,7 @@ public operator fun Set.minus(elements: Array): Set { /** * Returns a set containing all elements of the original set except the elements contained in the given [elements] collection. + * The returned set preserves the element iteration order of the original set. */ public operator fun Set.minus(elements: Iterable): Set { val other = elements.convertToSetForSetOperationWith(this) @@ -47,6 +50,7 @@ public operator fun Set.minus(elements: Iterable): Set { /** * Returns a set containing all elements of the original set except the elements contained in the given [elements] sequence. + * The returned set preserves the element iteration order of the original set. */ public operator fun Set.minus(elements: Sequence): Set { val result = LinkedHashSet(this) @@ -56,6 +60,7 @@ public operator fun Set.minus(elements: Sequence): Set { /** * Returns a set containing all elements of the original set except the given [element]. + * The returned set preserves the element iteration order of the original set. */ @kotlin.internal.InlineOnly public inline fun Set.minusElement(element: T): Set { @@ -63,7 +68,8 @@ public inline fun Set.minusElement(element: T): Set { } /** - * Returns a set containing all elements of the original set and then the given [element]. + * Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set. + * The returned set preserves the element iteration order of the original set. */ public operator fun Set.plus(element: T): Set { val result = LinkedHashSet(mapCapacity(size + 1)) @@ -73,7 +79,9 @@ public operator fun Set.plus(element: T): Set { } /** - * Returns a set containing all elements both of the original set and the given [elements] array. + * Returns a set containing all elements of the original set and the given [elements] array, + * which aren't already in this set. + * The returned set preserves the element iteration order of the original set. */ public operator fun Set.plus(elements: Array): Set { val result = LinkedHashSet(mapCapacity(this.size + elements.size)) @@ -83,7 +91,9 @@ public operator fun Set.plus(elements: Array): Set { } /** - * Returns a set containing all elements both of the original set and the given [elements] collection. + * Returns a set containing all elements of the original set and the given [elements] collection, + * which aren't already in this set. + * The returned set preserves the element iteration order of the original set. */ public operator fun Set.plus(elements: Iterable): Set { val result = LinkedHashSet(mapCapacity(elements.collectionSizeOrNull()?.let { this.size + it } ?: this.size * 2)) @@ -93,7 +103,9 @@ public operator fun Set.plus(elements: Iterable): Set { } /** - * Returns a set containing all elements both of the original set and the given [elements] sequence. + * Returns a set containing all elements of the original set and the given [elements] sequence, + * which aren't already in this set. + * The returned set preserves the element iteration order of the original set. */ public operator fun Set.plus(elements: Sequence): Set { val result = LinkedHashSet(mapCapacity(this.size * 2)) @@ -103,7 +115,8 @@ public operator fun Set.plus(elements: Sequence): Set { } /** - * Returns a set containing all elements of the original set and then the given [element]. + * Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set. + * The returned set preserves the element iteration order of the original set. */ @kotlin.internal.InlineOnly public inline fun Set.plusElement(element: T): Set { diff --git a/libraries/stdlib/src/generated/_Strings.kt b/libraries/stdlib/src/generated/_Strings.kt index f93d0560d46..a473e5ebe2a 100644 --- a/libraries/stdlib/src/generated/_Strings.kt +++ b/libraries/stdlib/src/generated/_Strings.kt @@ -503,6 +503,7 @@ public inline fun String.reversed(): String { * Returns a [Map] containing key-value pairs provided by [transform] function * applied to characters of the given char sequence. * If any of two pairs would have the same key the last one gets added to the map. + * The returned map preserves the entry iteration order of the original char sequence. */ public inline fun CharSequence.associate(transform: (Char) -> Pair): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -514,6 +515,7 @@ public inline fun CharSequence.associate(transform: (Char) -> Pair) * Returns a [Map] containing the characters from the given char sequence indexed by the key * returned from [keySelector] function applied to each character. * If any two characters would have the same key returned by [keySelector] the last one gets added to the map. + * The returned map preserves the entry iteration order of the original char sequence. */ public inline fun CharSequence.associateBy(keySelector: (Char) -> K): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -524,6 +526,7 @@ public inline fun CharSequence.associateBy(keySelector: (Char) -> K): Map CharSequence.associateBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map { @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -606,6 +609,7 @@ public fun CharSequence.toMutableList(): MutableList { /** * Returns a [Set] of all characters. + * The returned set preserves the element iteration order of the original char sequence. */ public fun CharSequence.toSet(): Set { return when (length) { @@ -644,6 +648,7 @@ public inline fun > CharSequence.flatMapTo(destin /** * Groups characters of the original char sequence by the key returned by the given [keySelector] function * applied to each character and returns a map where each group key is associated with a list of corresponding characters. + * The returned map preserves the entry iteration order of the keys produced from the original char sequence. * @sample test.collections.CollectionTest.groupBy */ public inline fun CharSequence.groupBy(keySelector: (Char) -> K): Map> { @@ -654,6 +659,7 @@ public inline fun CharSequence.groupBy(keySelector: (Char) -> K): Map CharSequence.groupBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map> { diff --git a/libraries/stdlib/src/kotlin/collections/Maps.kt b/libraries/stdlib/src/kotlin/collections/Maps.kt index 95113f22101..5c1c56f5845 100644 --- a/libraries/stdlib/src/kotlin/collections/Maps.kt +++ b/libraries/stdlib/src/kotlin/collections/Maps.kt @@ -32,6 +32,7 @@ public fun emptyMap(): Map = @Suppress("CAST_NEVER_SUCCEEDS") (Empt * where the first value is the key and the second is the value. If multiple pairs have * the same key, the resulting map will contain the value from the last of those pairs. * + * Entries of the map are iterated in the order they were specified. * The returned map is serializable (JVM). */ public fun mapOf(vararg pairs: Pair): Map = if (pairs.size > 0) linkedMapOf(*pairs) else emptyMap() @@ -49,8 +50,9 @@ public fun mapOf(pair: Pair): Map = Collections.singletonMap( /** * Returns a new [MutableMap] with the specified contents, given as a list of pairs - * where the first component is the key and the second is the value. - * This map preserves insertion order so iterating through the map's entries will be in the same order. + * where the first component is the key and the second is the value. If multiple pairs have + * the same key, the resulting map will contain the value from the last of those pairs. + * Entries of the map are iterated in the order they were specified. */ public fun mutableMapOf(vararg pairs: Pair): MutableMap = LinkedHashMap(mapCapacity(pairs.size)).apply { putAll(pairs) } @@ -67,8 +69,9 @@ public fun hashMapOf(vararg pairs: Pair): HashMap /** * Returns a new [LinkedHashMap] with the specified contents, given as a list of pairs - * where the first component is the key and the second is the value. - * This map preserves insertion order so iterating through the map's entries will be in the same order. + * where the first component is the key and the second is the value. If multiple pairs have + * the same key, the resulting map will contain the value from the last of those pairs. + * Entries of the map are iterated in the order they were specified. * * @sample test.collections.MapTest.createLinkedMap */ @@ -232,16 +235,19 @@ public inline operator fun Map.iterator(): Iterator public inline operator fun MutableMap.iterator(): MutableIterator> = entries.iterator() /** - * Populates the given `destination` [Map] with entries having the keys of this map and the values obtained - * by applying the `transform` function to each entry in this [Map]. + * Populates the given [destination] map with entries having the keys of this map and the values obtained + * by applying the [transform] function to each entry in this [Map]. */ public inline fun > Map.mapValuesTo(destination: C, transform: (Map.Entry) -> R): C { return entries.associateByTo(destination, { it.key }, transform) } /** - * Populates the given `destination` [Map] with entries having the keys obtained - * by applying the `transform` function to each entry in this [Map] and the values of this map. + * Populates the given [destination] map with entries having the keys obtained + * by applying the [transform] function to each entry in this [Map] and the values of this map. + * + * In case if any two entries are mapped to the equal keys, the value of the latter one will overwrite + * the value associated with the former one. */ public inline fun > Map.mapKeysTo(destination: C, transform: (Map.Entry) -> R): C { return entries.associateByTo(destination, transform, { it.value }) @@ -275,9 +281,11 @@ public fun MutableMap.putAll(pairs: Sequence>): Uni } /** - * Returns a new map with entries having the keys of this map and the values obtained by applying the `transform` + * Returns a new map with entries having the keys of this map and the values obtained by applying the [transform] * function to each entry in this [Map]. * + * The returned map preserves the entry iteration order of the original map. + * * @sample test.collections.MapTest.mapValues */ @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -286,9 +294,14 @@ public inline fun Map.mapValues(transform: (Map.Entry) -> } /** - * Returns a new Map with entries having the keys obtained by applying the `transform` function to each entry in this + * Returns a new Map with entries having the keys obtained by applying the [transform] function to each entry in this * [Map] and the values of this map. * + * In case if any two entries are mapped to the equal keys, the value of the latter one will overwrite + * the value associated with the former one. + * + * The returned map preserves the entry iteration order of the original map. + * * @sample test.collections.MapTest.mapKeys */ @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE") @@ -298,6 +311,8 @@ public inline fun Map.mapKeys(transform: (Map.Entry) -> R) /** * Returns a map containing all key-value pairs with keys matching the given [predicate]. + * + * The returned map preserves the entry iteration order of the original map. */ public inline fun Map.filterKeys(predicate: (K) -> Boolean): Map { val result = LinkedHashMap() @@ -311,6 +326,8 @@ public inline fun Map.filterKeys(predicate: (K) -> Boolean): Map Map.filterValues(predicate: (V) -> Boolean): Map { val result = LinkedHashMap() @@ -339,6 +356,8 @@ public inline fun > Map.filterTo(destinat /** * Returns a new map containing all key-value pairs matching the given [predicate]. + * + * The returned map preserves the entry iteration order of the original map. */ public inline fun Map.filter(predicate: (Map.Entry) -> Boolean): Map { return filterTo(LinkedHashMap(), predicate) @@ -360,6 +379,8 @@ public inline fun > Map.filterNotTo(desti /** * Returns a new map containing all key-value pairs not matching the given [predicate]. + * + * The returned map preserves the entry iteration order of the original map. */ public inline fun Map.filterNot(predicate: (Map.Entry) -> Boolean): Map { return filterNotTo(LinkedHashMap(), predicate) @@ -367,6 +388,8 @@ public inline fun Map.filterNot(predicate: (Map.Entry) -> Boo /** * Returns a new map containing all key-value pairs from the given collection of pairs. + * + * The returned map preserves the entry iteration order of the original collection. */ public fun Iterable>.toMap(): Map { if (this is Collection) { @@ -387,6 +410,8 @@ public fun > Iterable>.toMap(destina /** * Returns a new map containing all key-value pairs from the given array of pairs. + * + * The returned map preserves the entry iteration order of the original array. */ public fun Array>.toMap(): Map = when(size) { 0 -> emptyMap() @@ -402,43 +427,58 @@ public fun > Array>.toMap(destin /** * Returns a new map containing all key-value pairs from the given sequence of pairs. + * + * The returned map preserves the entry iteration order of the original sequence. */ - public fun Sequence>.toMap(): Map = toMap(LinkedHashMap()).optimizeReadOnlyMap() /** * Populates and returns the [destination] mutable map with key-value pairs from the given sequence of pairs. */ - public fun > Sequence>.toMap(destination: M): M = destination.apply { putAll(this@toMap) } /** * Creates a new read-only map by replacing or adding an entry to this map from a given key-value [pair]. + * + * The returned map preserves the entry iteration order of the original map. + * The [pair] is iterated in the end if it has a unique key. */ public operator fun Map.plus(pair: Pair): Map = if (this.isEmpty()) mapOf(pair) else LinkedHashMap(this).apply { put(pair.first, pair.second) } /** * Creates a new read-only map by replacing or adding entries to this map from a given collection of key-value [pairs]. + * + * The returned map preserves the entry iteration order of the original map. + * Those [pairs] with unique keys are iterated in the end in the order of [pairs] collection. */ public operator fun Map.plus(pairs: Iterable>): Map = if (this.isEmpty()) pairs.toMap() else LinkedHashMap(this).apply { putAll(pairs) } /** * Creates a new read-only map by replacing or adding entries to this map from a given array of key-value [pairs]. + * + * The returned map preserves the entry iteration order of the original map. + * Those [pairs] with unique keys are iterated in the end in the order of [pairs] array. */ public operator fun Map.plus(pairs: Array>): Map = if (this.isEmpty()) pairs.toMap() else LinkedHashMap(this).apply { putAll(pairs) } /** * Creates a new read-only map by replacing or adding entries to this map from a given sequence of key-value [pairs]. + * + * The returned map preserves the entry iteration order of the original map. + * Those [pairs] with unique keys are iterated in the end in the order of [pairs] sequence. */ public operator fun Map.plus(pairs: Sequence>): Map = LinkedHashMap(this).apply { putAll(pairs) }.optimizeReadOnlyMap() /** * Creates a new read-only map by replacing or adding entries to this map from another [map]. + * + * The returned map preserves the entry iteration order of the original map. + * Those entries of another [map] that are missing in this map are iterated in the end in the order of that [map]. */ public operator fun Map.plus(map: Map): Map = LinkedHashMap(this).apply { putAll(map) } diff --git a/libraries/stdlib/src/kotlin/collections/Sets.kt b/libraries/stdlib/src/kotlin/collections/Sets.kt index a8f6d62e224..013c9f76b4b 100644 --- a/libraries/stdlib/src/kotlin/collections/Sets.kt +++ b/libraries/stdlib/src/kotlin/collections/Sets.kt @@ -25,20 +25,30 @@ internal object EmptySet : Set, Serializable { /** Returns an empty read-only set. The returned set is serializable (JVM). */ public fun emptySet(): Set = EmptySet -/** Returns a new read-only ordered set with the given elements. The returned set is serializable (JVM). */ +/** + * Returns a new read-only set with the given elements. + * Elements of the set are iterated in the order they were specified. + * The returned set is serializable (JVM). + */ public fun setOf(vararg elements: T): Set = if (elements.size > 0) elements.toSet() else emptySet() /** Returns an empty read-only set. The returned set is serializable (JVM). */ @kotlin.internal.InlineOnly public inline fun setOf(): Set = emptySet() -/** Returns a new [MutableSet] with the given elements. */ +/** + * Returns a new [MutableSet] with the given elements. + * Elements of the set are iterated in the order they were specified. + */ public fun mutableSetOf(vararg elements: T): MutableSet = elements.toCollection(LinkedHashSet(mapCapacity(elements.size))) /** Returns a new [HashSet] with the given elements. */ public fun hashSetOf(vararg elements: T): HashSet = elements.toCollection(HashSet(mapCapacity(elements.size))) -/** Returns a new [LinkedHashSet] with the given elements. */ +/** + * Returns a new [LinkedHashSet] with the given elements. + * Elements of the set are iterated in the order they were specified. + */ public fun linkedSetOf(vararg elements: T): LinkedHashSet = elements.toCollection(LinkedHashSet(mapCapacity(elements.size))) /** Returns this Set if it's not `null` and the empty set otherwise. */ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt index 161837130e8..f4616d96dfc 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt @@ -10,7 +10,12 @@ fun generators(): List { only(Iterables, Collections, Sets, Sequences) doc { "Returns a list containing all elements of the original collection and then the given [element]." } - doc(Sets) { "Returns a set containing all elements of the original set and then the given [element]." } + doc(Sets) { + """ + Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set. + The returned set preserves the element iteration order of the original set. + """ + } doc(Sequences) { "Returns a sequence containing all elements of the original sequence and then the given [element]." } returns("List") @@ -45,7 +50,12 @@ fun generators(): List { // TODO: use build scope function when available // TODO: use immutable sets when available returns("SELF", Sets, Sequences) - doc(Sets) { "Returns a set containing all elements of the original set and then the given [element]." } + doc(Sets) { + """ + Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set. + The returned set preserves the element iteration order of the original set. + """ + } body(Sets) { """ val result = LinkedHashSet(mapCapacity(size + 1)) @@ -95,7 +105,13 @@ fun generators(): List { } // TODO: use immutable set builder when available - doc(Sets) { "Returns a set containing all elements both of the original set and the given [elements] collection." } + doc(Sets) { + """ + Returns a set containing all elements of the original set and the given [elements] collection, + which aren't already in this set. + The returned set preserves the element iteration order of the original set. + """ + } body(Sets) { """ val result = LinkedHashSet(mapCapacity(elements.collectionSizeOrNull()?.let { this.size + it } ?: this.size * 2)) @@ -144,7 +160,13 @@ fun generators(): List { return result """ } - doc(Sets) { "Returns a set containing all elements both of the original set and the given [elements] array." } + doc(Sets) { + """ + Returns a set containing all elements of the original set and the given [elements] array, + which aren't already in this set. + The returned set preserves the element iteration order of the original set. + """ + } body(Sets) { """ val result = LinkedHashSet(mapCapacity(this.size + elements.size)) @@ -194,7 +216,13 @@ fun generators(): List { } // TODO: use immutable set builder when available - doc(Sets) { "Returns a set containing all elements both of the original set and the given [elements] sequence." } + doc(Sets) { + """ + Returns a set containing all elements of the original set and the given [elements] sequence, + which aren't already in this set. + The returned set preserves the element iteration order of the original set. + """ + } body(Sets) { """ val result = LinkedHashSet(mapCapacity(this.size * 2)) @@ -224,7 +252,12 @@ fun generators(): List { only(Iterables, Sets, Sequences) doc { "Returns a list containing all elements of the original collection without the first occurrence of the given [element]." } - doc(Sets) { "Returns a set containing all elements of the original set except the given [element]." } + doc(Sets) { + """ + Returns a set containing all elements of the original set except the given [element]. + The returned set preserves the element iteration order of the original set. + """ + } doc(Sequences) { "Returns a sequence containing all elements of the original sequence without the first occurrence of the given [element]." } returns("List") @@ -247,7 +280,12 @@ fun generators(): List { } returns("SELF", Sets, Sequences) - doc(Sets) { "Returns a set containing all elements of the original set except the given [element]." } + doc(Sets) { + """ + Returns a set containing all elements of the original set except the given [element]. + The returned set preserves the element iteration order of the original set. + """ + } body(Sets) { """ val result = LinkedHashSet(mapCapacity(size)) @@ -288,7 +326,12 @@ fun generators(): List { """ } - doc(Sets) { "Returns a set containing all elements of the original set except the elements contained in the given [elements] collection." } + doc(Sets) { + """ + Returns a set containing all elements of the original set except the elements contained in the given [elements] collection. + The returned set preserves the element iteration order of the original set. + """ + } body(Sets) { """ val other = elements.convertToSetForSetOperationWith(this) @@ -340,7 +383,12 @@ fun generators(): List { return this.filterNot { it in other } """ } - doc(Sets) { "Returns a set containing all elements of the original set except the elements contained in the given [elements] array." } + doc(Sets) { + """ + Returns a set containing all elements of the original set except the elements contained in the given [elements] array. + The returned set preserves the element iteration order of the original set. + """ + } body(Sets) { """ val result = LinkedHashSet(this) @@ -386,7 +434,12 @@ fun generators(): List { return this.filterNot { it in other } """ } - doc(Sets) { "Returns a set containing all elements of the original set except the elements contained in the given [elements] sequence." } + doc(Sets) { + """ + Returns a set containing all elements of the original set except the elements contained in the given [elements] sequence. + The returned set preserves the element iteration order of the original set. + """ + } body(Sets) { """ val result = LinkedHashSet(this) diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt index 7977992e8e2..900acb4ff77 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt @@ -294,6 +294,7 @@ fun mapping(): List { """ Groups ${f.element.pluralize()} of the original ${f.collection} by the key returned by the given [keySelector] function applied to each ${f.element} and returns a map where each group key is associated with a list of corresponding ${f.element.pluralize()}. + The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}. @sample test.collections.CollectionTest.groupBy """ } @@ -339,6 +340,7 @@ fun mapping(): List { Groups values returned by the [valueTransform] function applied to each ${f.element} of the original ${f.collection} by the key returned by the given [keySelector] function applied to the ${f.element} and returns a map where each group key is associated with a list of corresponding values. + The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}. @sample test.collections.CollectionTest.groupByKeysAndValues """ } diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt index 5e129ac2ce1..ebbf49c5410 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt @@ -7,7 +7,12 @@ fun sets(): List { templates add f("toMutableSet()") { exclude(Strings) - doc { f -> "Returns a mutable set containing all distinct ${f.element.pluralize()} from the given ${f.collection}." } + doc { f -> + """ + Returns a mutable set containing all distinct ${f.element.pluralize()} from the given ${f.collection}. + The returned set preserves the element iteration order of the original ${f.collection}. + """ + } returns("MutableSet") body { """ @@ -24,7 +29,6 @@ fun sets(): List { return set """ } - doc(Sequences) { "Returns a mutable set containing all distinct elements from the given sequence." } body(Sequences) { """ val set = LinkedHashSet() @@ -90,7 +94,14 @@ fun sets(): List { templates add f("union(other: Iterable)") { infix(true) exclude(Strings, Sequences) - doc { "Returns a set containing all distinct elements from both collections." } + doc { f -> + """ + Returns a set containing all distinct elements from both collections. + The returned set preserves the element iteration order of the original ${f.collection}. + Those elements of the [other] collection that are unique are iterated in the end + in the order of the [other] collection. + """ + } returns("Set") body { """ @@ -104,7 +115,12 @@ fun sets(): List { templates add f("intersect(other: Iterable)") { infix(true) exclude(Strings, Sequences) - doc { "Returns a set containing all elements that are contained by both this set and the specified collection." } + doc { f -> + """ + Returns a set containing all elements that are contained by both this set and the specified collection. + The returned set preserves the element iteration order of the original ${f.collection}. + """ + } returns("Set") body { """ @@ -118,7 +134,12 @@ fun sets(): List { templates add f("subtract(other: Iterable)") { infix(true) exclude(Strings, Sequences) - doc { "Returns a set containing all elements that are contained by this set and not contained by the specified collection." } + doc { f -> + """ + Returns a set containing all elements that are contained by this ${f.collection} and not contained by the specified collection. + The returned set preserves the element iteration order of the original ${f.collection}. + """ + } returns("Set") body { """ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt index 8c0002e00b3..f7eb5fbf879 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt @@ -21,7 +21,12 @@ fun snapshots(): List { } templates add f("toSet()") { - doc { f -> "Returns a [Set] of all ${f.element.pluralize()}." } + doc { f -> + """ + Returns a [Set] of all ${f.element.pluralize()}. + The returned set preserves the element iteration order of the original ${f.collection}. + """ + } returns("Set") body(Iterables) { """ @@ -168,6 +173,7 @@ fun snapshots(): List { Returns a [Map] containing key-value pairs provided by [transform] function applied to ${f.element.pluralize()} of the given ${f.collection}. If any of two pairs would have the same key the last one gets added to the map. + The returned map preserves the entry iteration order of the original ${f.collection}. """ } body { @@ -231,6 +237,7 @@ fun snapshots(): List { Returns a [Map] containing the ${f.element.pluralize()} from the given ${f.collection} indexed by the key returned from [keySelector] function applied to each ${f.element}. If any two ${f.element.pluralize()} would have the same key returned by [keySelector] the last one gets added to the map. + The returned map preserves the entry iteration order of the original ${f.collection}. """ } returns("Map") @@ -301,6 +308,7 @@ fun snapshots(): List { """ Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to ${f.element.pluralize()} of the given ${f.collection}. If any two ${f.element.pluralize()} would have the same key returned by [keySelector] the last one gets added to the map. + The returned map preserves the entry iteration order of the original ${f.collection}. """ } returns("Map")