Add random::shuffle and random::pick (#1361)

Add the two functions `shuffle` and `pick` to the `random` module in the
stdlib according the issue #1307

---------

Co-authored-by: Philipp Schuster <philipp.schuster@uni-tuebingen.de>

Author: DennisKleinhans

examples/stdlib/random/pick.check

@@ -0,0 +1,11 @@
+5
+5
+6
+5
+3
+0
+5
+9
+2
+1
+0

examples/stdlib/random/pick.effekt

@@ -0,0 +1,12 @@
+import random
+import array
+
+def main() = {
+  val arr = array::build(10) { i => i }
+  val singleton = array::build(1) { i => i }
+  val empty = array(0, 0)
+
+  with minstd(1337)
+  10.repeat{ println(pick(arr)) }
+  println(pick(singleton))
+}

examples/stdlib/random/shuffle.check

@@ -0,0 +1,16 @@
+Array(5, 7, 4, 9, 1, 0, 2, 8, 6, 3)
+
+Array(5, 7, 4, 9, 1, 0, 2, 8, 6, 3)
+
+Array(8, -5, -3, 7, -4, -8, -7, -2, -6, 2, 3, 6, -10, 0, 4, -9, -1, 5, 1, 9)
+
+Array(D, B, C, A)
+Array(B, D, C, A)
+Array(D, C, B, A)
+Array(C, D, B, A)
+Array(D, A, B, C)
+Array(C, B, A, D)
+Array(B, D, C, A)
+Array(C, B, D, A)
+Array(D, A, C, B)
+Array(B, D, C, A)

examples/stdlib/random/shuffle.effekt

@@ -0,0 +1,34 @@
+import random
+import array
+import list
+
+def main() = {
+  val left = array::build(10) { i => i }
+  val right = array::build(10) { i => i }
+
+  with minstd(1337)
+  shuffle(left)
+  println(left)
+
+  println("")
+
+  with minstd(1337)
+  shuffle(right)
+  println(right)
+
+  println("")
+
+  val shuffled = array::build(20) { i => i - 10 }
+  with minstd(42);
+  shuffle(shuffled)
+  println(shuffled)
+
+  println("")
+
+  with minstd(1337)
+  val abcd = array::fromList(["A", "B", "C", "D"])
+  10.repeat {
+    shuffle(abcd)
+    println(abcd)
+  }
+}

libraries/common/random.effekt

@@ -1,6 +1,9 @@
 module random
 
 import stream
+import array
+import option
+import exception
 import io/filesystem
 import io/error
 
@@ -38,7 +41,7 @@ def minstd(seed: Int): Unit / emit[Byte] = {
     if (result < 0) result + m else result
   }
 
-  while (true) {
+  forever {
     state = nextInt()
     val b = state.mod(256).toByte
     do emit(b)
@@ -88,14 +91,14 @@ def devurandom { randomnessReader: () => Unit / random }: Unit / Exception[IOErr
 
 def randomByte(): Byte / random = do random()
 def randomBytes(): Unit / {emit[Byte], random} =
-  while (true) do emit(do random())
+  forever { do emit(do random()) }
 
 def randomBool(): Bool / random = {
   val b = do random()
   b.toInt.mod(2) == 1
 }
 def randomBools(): Unit / {emit[Bool], random} =
-  while (true) do emit(randomBool())
+  forever { do emit(randomBool()) }
 
 def randomInt32(): Int / random = {
   var result = 0
@@ -107,7 +110,7 @@ def randomInt32(): Int / random = {
   result.mod(1.bitwiseShl(31)).abs * if (signBit) 1 else -1
 }
 def randomInt32s(): Unit / {emit[Int], random} =
-  while (true) do emit(randomInt32())
+  forever { do emit(randomInt32()) }
 
 /// `max` is _inclusive_!
 def randomInt(min: Int, max: Int): Int / random = {
@@ -126,17 +129,36 @@ def randomInt(min: Int, max: Int): Int / random = {
     min + (abs(result).mod(range))
   }
 }
+
 /// `max` is _inclusive_!
 def randomInts(min: Int, max: Int): Unit / {emit[Int], random} =
-  while (true) do emit(randomInt(min, max))
+  forever { do emit(randomInt(min, max)) }
 
 
 /// Random double between 0.0 and 1.0
 def randomDouble(): Double / random =
   (randomInt32().toDouble / 1.bitwiseShl(31).toDouble).abs
   // This is not perfect, but it will do for now.
 def randomDoubles(): Unit / {emit[Double], random} =
-  while (true) do emit(randomDouble())
+  forever { do emit(randomDouble()) }
+
+/// Shuffle an array in-place using the Fisher-Yates algorithm.
+def shuffle[A](arr: Array[A]): Unit / random = {
+  val n = arr.size
+  each(0, n - 1) { i =>
+    arr.swap(i, randomInt(i, n - 1))
+  }
+}
+
+/// Pick a random element from an array.
+///
+/// Panics when called on an empty array.
+def pick[A](arr: Array[A]): A / random =
+  if (arr.size == 0) {
+    panic("Pick from an empty array")
+  } else {
+    arr.get(randomInt(0, arr.size - 1))
+  }
 
 
 namespace examples {