Introduce MutableList.fill and shuffle/shuffled extensions for JVM only

'shuffle' and 'fill' are inline only, but 'shuffled' is not.

#KT-8823 Fixed
#KT-9010 Fixed

libraries/stdlib/src/kotlin/collections/MutableCollections.kt

@@ -283,3 +283,46 @@ public fun <T : Comparable<T>> MutableList<T>.sort(): Unit {
 public fun <T> MutableList<T>.sortWith(comparator: Comparator<in T>): 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 <T> MutableList<T>.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 <T> MutableList<T>.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 <T> MutableList<T>.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 <T> Iterable<T>.shuffled(): List<T> = 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 <T> Iterable<T>.shuffled(random: java.util.Random): List<T> = toMutableList().apply { shuffle(random) }

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)
+    }
+
+
 }

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;

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;