feat: add sample(list) and sample(list, count) methods to Random class with two sampling algorithms

test/random/sample_count_all.wren

@@ -0,0 +1,19 @@
+import "random" for Random
+
+var random = Random.new(12345)
+
+// Should choose all elements with roughly equal probability.
+var list = ["a", "b", "c"]
+var histogram = {}
+for (i in 1..5000) {
+  var sample = random.sample(list, 3)
+  var string = sample.toString
+  if (!histogram.containsKey(string)) histogram[string] = 0
+  histogram[string] = histogram[string] + 1
+}
+
+System.print(histogram.count) // expect: 6
+for (key in histogram.keys) {
+  var error = (histogram[key] / (5000 / 6) - 1).abs
+  if (error > 0.1) System.print("!!! %(error)")
+}

test/random/sample_count_multiple.wren

@@ -0,0 +1,19 @@
+import "random" for Random
+
+var random = Random.new(12345)
+
+// Should choose all elements with roughly equal probability.
+var list = ["a", "b", "c", "d"]
+var histogram = {}
+for (i in 1..5000) {
+  var sample = random.sample(list, 3)
+  var string = sample.toString
+  if (!histogram.containsKey(string)) histogram[string] = 0
+  histogram[string] = histogram[string] + 1
+}
+
+System.print(histogram.count) // expect: 24
+for (key in histogram.keys) {
+  var error = (histogram[key] / (5000 / 24) - 1).abs
+  if (error > 0.2) System.print("!!! %(error)")
+}

test/random/sample_count_one.wren

@@ -0,0 +1,23 @@
+import "random" for Random
+
+var random = Random.new(12345)
+
+// Single element list.
+System.print(random.sample(["single"], 1)) // expect: [single]
+
+// Should choose all elements with roughly equal probability.
+var list = ["a", "b", "c", "d", "e"]
+var histogram = {}
+for (i in 1..5000) {
+  var sample = random.sample(list, 1)
+
+  var string = sample.toString
+  if (!histogram.containsKey(string)) histogram[string] = 0
+  histogram[string] = histogram[string] + 1
+}
+
+System.print(histogram.count) // expect: 5
+for (key in histogram.keys) {
+  var error = (histogram[key] / (5000 / list.count) - 1).abs
+  if (error > 0.1) System.print("!!! %(error)")
+}

test/random/sample_count_too_many.wren

@@ -0,0 +1,5 @@
+import "random" for Random
+
+var random = Random.new(12345)
+
+random.sample([1, 2, 3], 4) // expect runtime error: Not enough elements to sample.

test/random/sample_count_zero.wren

@@ -0,0 +1,6 @@
+import "random" for Random
+
+var random = Random.new(12345)
+
+System.print(random.sample([], 0)) // expect: []
+System.print(random.sample([1, 2, 3], 0)) // expect: []

test/random/sample_one.wren

@@ -0,0 +1,20 @@
+import "random" for Random
+
+var random = Random.new(12345)
+
+// Single element list.
+System.print(random.sample(["single"])) // expect: single
+
+// Should choose all elements with roughly equal probability.
+var list = ["a", "b", "c", "d", "e"]
+var histogram = {"a": 0, "b": 0, "c": 0, "d": 0, "e": 0}
+for (i in 1..1000) {
+  var sample = random.sample(list)
+  histogram[sample] = histogram[sample] + 1
+}
+
+System.print(histogram.count) // expect: 5
+for (key in histogram.keys) {
+  var error = (histogram[key] / (1000 / list.count) - 1).abs
+  if (error > 0.2) System.print("!!! %(error)")
+}

test/random/sample_one_empty.wren

@@ -0,0 +1,5 @@
+import "random" for Random
+
+var random = Random.new(12345)
+
+random.sample([]) // expect runtime error: Not enough elements to sample.

test/random/shuffle.wren

@@ -12,12 +12,21 @@ list = [1]
 random.shuffle(list)
 System.print(list) // expect: [1]
 
-// Given enough tries, should generate all permutations.
-var hits = {}
-for (i in 1..200) {
+// Given enough tries, should generate all permutations with roughly equal
+// probability.
+var histogram = {}
+for (i in 1..5000) {
   var list = [1, 2, 3, 4]
   random.shuffle(list)
-  hits[list.toString] = true
+
+  var string = list.toString
+  if (!histogram.containsKey(string)) histogram[string] = 0
+  histogram[string] = histogram[string] + 1
+}
+
+System.print(histogram.count) // expect: 24
+for (key in histogram.keys) {
+  var error = (histogram[key] / (5000 / 24) - 1).abs
+  if (error > 0.2) System.print("!!! %(error)")
 }
 
-System.print(hits.count) // expect: 24