New function: random-sample.

Implements reservoir sampling.

* rand.c (radom_float_impl): New static function, made out of
random_float. Returns double, giving us access to the unboxed
result
(random_float): Now a wrapper around random_float_impl: boxes
the result of random_float.
(elrd, flrd, random_sample): New static functions.
(rand_init): Register random-sample intrinsic.

* txr.1: Documented.

* stdlib/doc-syms.tl: Updated.

1 files changed, 31 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index 81ee2846..47b89655 100644
--- a/txr.1
+++ b/txr.1
@@ -64759,6 +64759,37 @@ for a description of
 .code buf
 objects.
 
+.coNP Function @ random-sample
+.synb
+.mets (random-sample < size < seq <> [ random-state ])
+.syne
+.desc
+The
+.code random-sample
+function returns a vector of
+.meta size
+randomly selected elements from the sequence
+.metn seq ,
+using reservoir sampling.
+
+If the number of elements in
+.meta seq
+is equal to or smaller than
+.metn size ,
+then the function returns a vector of all the elements of
+.meta seq
+in their original order.
+
+In other cases, the selected elements are not required to appear
+in their original order.
+
+No element of sequence
+.meta seq
+is selected more than once; duplicate values can appear
+in the output only if
+.meta seq
+itself contains duplicates.
+
 .SS* Time
 .coNP Functions @, time @ time-usec and @ time-nsec
 .synb