Add sample(_) and sample(_,_) to Random.

src/optional/wren_opt_random.wren

@@ -47,6 +47,67 @@ foreign class Random {
   int(end) { (float() * end).floor }
   int(start, end) { (float() * (end - start)).floor + start }
 
+  sample(list) { sample(list, 1)[0] }
+  sample(list, count) {
+    if (count > list.count) Fiber.abort("Not enough elements to sample.")
+
+    // There at (at least) two simple algorithms for choosing a number of
+    // samples from a list without replacement -- where we don't pick the same
+    // element more than once.
+    //
+    // The first is faster when the number of samples is small relative to the
+    // size of the collection. In many cases, it avoids scanning the entire
+    // list. In the common case of just wanting one sample, it's a single
+    // random index lookup.
+    //
+    // However, its performance degrades badly as the sample size increases.
+    // Vitter's algorithm always scans the entire list, but it's also always
+    // O(n).
+    //
+    // The cutoff point between the two follows a quadratic curve on the same
+    // size. Based on some empirical testing, scaling that by 5 seems to fit
+    // pretty closely and chooses the fastest one for the given sample and
+    // collection size.
+    if (count * count * 5 < list.count) {
+      // Pick random elements and retry if you hit a previously chosen one.
+      var picked = {}
+      var result = []
+      for (i in 0...count) {
+        // Find an index that we haven't already selected.
+        var index
+        while (true) {
+          index = int(count)
+          if (!picked.containsKey(index)) break
+        }
+
+        picked[index] = true
+        result.add(list[index])
+      }
+
+      return result
+    } else {
+      // Jeffrey Vitter's Algorithm R.
+
+      // Fill the reservoir with the first elements in the list.
+      var result = list[0...count]
+
+      // We want to ensure the results are always in random order, so shuffle
+      // them. In cases where the sample size is the entire collection, this
+      // devolves to running Fisher-Yates on a copy of the list.
+      shuffle(result)
+
+      // Now walk the rest of the list. For each element, randomly consider
+      // replacing one of the reservoir elements with it. The probability here
+      // works out such that it does this uniformly.
+      for (i in count...list.count) {
+        var slot = int(0, i + 1)
+        if (slot < count) result[slot] = list[i]
+      }
+
+      return result
+    }
+  }
+
   shuffle(list) {
     if (list.isEmpty) return
 

src/optional/wren_opt_random.wren.inc

@@ -49,6 +49,67 @@ static const char* randomModuleSource =
 "  int(end) { (float() * end).floor }\n"
 "  int(start, end) { (float() * (end - start)).floor + start }\n"
 "\n"
+"  sample(list) { sample(list, 1)[0] }\n"
+"  sample(list, count) {\n"
+"    if (count > list.count) Fiber.abort(\"Not enough elements to sample.\")\n"
+"\n"
+"    // There at (at least) two simple algorithms for choosing a number of\n"
+"    // samples from a list without replacement -- where we don't pick the same\n"
+"    // element more than once.\n"
+"    //\n"
+"    // The first is faster when the number of samples is small relative to the\n"
+"    // size of the collection. In many cases, it avoids scanning the entire\n"
+"    // list. In the common case of just wanting one sample, it's a single\n"
+"    // random index lookup.\n"
+"    //\n"
+"    // However, its performance degrades badly as the sample size increases.\n"
+"    // Vitter's algorithm always scans the entire list, but it's also always\n"
+"    // O(n).\n"
+"    //\n"
+"    // The cutoff point between the two follows a quadratic curve on the same\n"
+"    // size. Based on some empirical testing, scaling that by 5 seems to fit\n"
+"    // pretty closely and chooses the fastest one for the given sample and\n"
+"    // collection size.\n"
+"    if (count * count * 5 < list.count) {\n"
+"      // Pick random elements and retry if you hit a previously chosen one.\n"
+"      var picked = {}\n"
+"      var result = []\n"
+"      for (i in 0...count) {\n"
+"        // Find an index that we haven't already selected.\n"
+"        var index\n"
+"        while (true) {\n"
+"          index = int(count)\n"
+"          if (!picked.containsKey(index)) break\n"
+"        }\n"
+"\n"
+"        picked[index] = true\n"
+"        result.add(list[index])\n"
+"      }\n"
+"\n"
+"      return result\n"
+"    } else {\n"
+"      // Jeffrey Vitter's Algorithm R.\n"
+"\n"
+"      // Fill the reservoir with the first elements in the list.\n"
+"      var result = list[0...count]\n"
+"\n"
+"      // We want to ensure the results are always in random order, so shuffle\n"
+"      // them. In cases where the sample size is the entire collection, this\n"
+"      // devolves to running Fisher-Yates on a copy of the list.\n"
+"      shuffle(result)\n"
+"\n"
+"      // Now walk the rest of the list. For each element, randomly consider\n"
+"      // replacing one of the reservoir elements with it. The probability here\n"
+"      // works out such that it does this uniformly.\n"
+"      for (i in count...list.count) {\n"
+"        var slot = int(0, i + 1)\n"
+"        if (slot < count) result[slot] = list[i]\n"
+"      }\n"
+"\n"
+"      return result\n"
+"    }\n"
+"  }\n"
+"\n"
 "  shuffle(list) {\n"
 "    if (list.isEmpty) return\n"
 "\n"