diff --git a/libraries/stdlib/src/kotlin/collections/MutableCollections.kt b/libraries/stdlib/src/kotlin/collections/MutableCollections.kt index 8dfb1ede9aa..c0e86f2c5f7 100644 --- a/libraries/stdlib/src/kotlin/collections/MutableCollections.kt +++ b/libraries/stdlib/src/kotlin/collections/MutableCollections.kt @@ -283,3 +283,46 @@ public fun > MutableList.sort(): Unit { public fun MutableList.sortWith(comparator: Comparator): Unit { if (size > 1) java.util.Collections.sort(this, comparator) } + +/** + * Fills the list with the provided [value]. + * + * Each element in the list gets replaced with the [value]. + */ +@kotlin.jvm.JvmVersion +@kotlin.internal.InlineOnly +public inline fun MutableList.fill(value: T) { + java.util.Collections.fill(this, value) +} + + +/** + * Randomly shuffles elements in this mutable list. + */ +@kotlin.jvm.JvmVersion +@kotlin.internal.InlineOnly +public inline fun MutableList.shuffle() { + java.util.Collections.shuffle(this) +} + +/** + * Randomly shuffles elements in this mutable list using the specified [random] instance as the source of randomness. + */ +@kotlin.jvm.JvmVersion +@kotlin.internal.InlineOnly +public inline fun MutableList.shuffle(random: java.util.Random) { + java.util.Collections.shuffle(this, random) +} + +/** + * Returns a new list with the elements of this list randomly shuffled. + */ +@kotlin.jvm.JvmVersion +public fun Iterable.shuffled(): List = toMutableList().apply { shuffle() } + +/** + * Returns a new list with the elements of this list randomly shuffled + * using the specified [random] instance as the source of randomness. + */ +@kotlin.jvm.JvmVersion +public fun Iterable.shuffled(random: java.util.Random): List = toMutableList().apply { shuffle(random) } diff --git a/libraries/stdlib/test/collections/MutableCollectionsTest.kt b/libraries/stdlib/test/collections/MutableCollectionsTest.kt index b7575b28999..add66797065 100644 --- a/libraries/stdlib/test/collections/MutableCollectionsTest.kt +++ b/libraries/stdlib/test/collections/MutableCollectionsTest.kt @@ -95,4 +95,39 @@ class MutableCollectionTest { } } + @JvmVersion + @Test fun listFill() { + val list = MutableList(3) { it } + list.fill(42) + assertEquals(listOf(42, 42, 42), list) + } + + @JvmVersion + @Test fun shuffled() { + val list = MutableList(100) { it } + val shuffled = list.shuffled() + + assertNotEquals(list, shuffled) + assertEquals(list.toSet(), shuffled.toSet()) + assertEquals(list.size, shuffled.distinct().size) + } + + @JvmVersion + @Test fun shuffledRnd() { + val rnd1 = java.util.Random(42L) + val rnd2 = java.util.Random(42L) + + val list = MutableList(100) { it } + val shuffled1 = list.shuffled(rnd1) + val shuffled2 = list.shuffled(rnd2) + + + assertNotEquals(list, shuffled1) + assertEquals(list.toSet(), shuffled1.toSet()) + assertEquals(list.size, shuffled1.distinct().size) + + assertEquals(shuffled1, shuffled2) + } + + } diff --git a/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt b/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt index 10ffa4ac78c..dae068e2f7d 100644 --- a/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt +++ b/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt @@ -1697,6 +1697,8 @@ public final class kotlin/collections/CollectionsKt { public static final fun retainAll (Ljava/util/List;Lkotlin/jvm/functions/Function1;)Z public static final fun reverse (Ljava/util/List;)V public static final fun reversed (Ljava/lang/Iterable;)Ljava/util/List; + public static final fun shuffled (Ljava/lang/Iterable;)Ljava/util/List; + public static final fun shuffled (Ljava/lang/Iterable;Ljava/util/Random;)Ljava/util/List; public static final fun single (Ljava/lang/Iterable;)Ljava/lang/Object; public static final fun single (Ljava/lang/Iterable;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object; public static final fun single (Ljava/util/List;)Ljava/lang/Object; diff --git a/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib.txt b/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib.txt index 7201a853b59..343765ac261 100644 --- a/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib.txt +++ b/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib.txt @@ -1556,6 +1556,8 @@ public final class kotlin/collections/CollectionsKt { public static final fun retainAll (Ljava/util/List;Lkotlin/jvm/functions/Function1;)Z public static final fun reverse (Ljava/util/List;)V public static final fun reversed (Ljava/lang/Iterable;)Ljava/util/List; + public static final fun shuffled (Ljava/lang/Iterable;)Ljava/util/List; + public static final fun shuffled (Ljava/lang/Iterable;Ljava/util/Random;)Ljava/util/List; public static final fun single (Ljava/lang/Iterable;)Ljava/lang/Object; public static final fun single (Ljava/lang/Iterable;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object; public static final fun single (Ljava/util/List;)Ljava/lang/Object;