Provide java.util.Collections#shuffle as extensions for collections in JS

Fixes: #KT-2460

Author: Pap Lőrinc

js/js.libraries/src/core/collections.kt

@@ -91,6 +91,27 @@ public fun <T> MutableList<T>.fill(value: T): Unit {
     }
 }
 
+/**
+ * Randomly shuffles elements in this list.
+ *
+ * See: https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm
+ */
+@SinceKotlin("1.2")
+public fun <T> MutableList<T>.shuffle(): Unit {
+    (lastIndex downTo 1).forEach { i ->
+        rand(i + 1).let { j ->
+            swap(i, j)
+        }
+    }
+}
+private fun rand(upperBound: Int) = Math.floor(Math.random() * upperBound)
+
+/**
+ * Returns a new list with the elements of this list randomly shuffled.
+ */
+@SinceKotlin("1.2")
+public fun <T> Iterable<T>.shuffled(): List<T> = toMutableList().apply { shuffle() }
+
 /**
  * Sorts elements in the list in-place according to their natural sort order.
  */

libraries/stdlib/common/src/kotlin/CollectionsH.kt

@@ -150,6 +150,9 @@ header inline fun <reified T> Array<out T>?.orEmpty(): Array<out T>
 header inline fun <reified T> Collection<T>.toTypedArray(): Array<T>
 
 @SinceKotlin("1.2") header fun <T> MutableList<T>.fill(value: T): Unit
+@SinceKotlin("1.2") header fun <T> MutableList<T>.shuffle(): Unit
+@SinceKotlin("1.2") header fun <T> Iterable<T>.shuffled(): List<T>
+
 header fun <T : Comparable<T>> MutableList<T>.sort(): Unit
 header fun <T> MutableList<T>.sortWith(comparator: Comparator<in T>): Unit
 

libraries/stdlib/test/collections/MutableCollectionsTest.kt

@@ -101,7 +101,6 @@ class MutableCollectionTest {
         assertEquals(listOf(42, 42, 42), list)
     }
 
-    @JvmVersion
     @Test fun shuffled() {
         val list = MutableList(100) { it }
         val shuffled = list.shuffled()