Specify •MakeRand and •rand

1 files changed, 28 insertions, 0 deletions

diff --git a/docs/spec/system.html b/docs/spec/system.html
index 76d36a2f..477f32b4 100644
--- a/docs/spec/system.html
+++ b/docs/spec/system.html
@@ -446,3 +446,31 @@
 <p>The <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a> is 1970-01-01 00:00:00 UTC. <code><span class='Function'>•UnixTime</span></code> is intended for absolute time measurement and should be implemented with the method that gives the most accurate result at any given time. <code><span class='Function'>•MonoTime</span></code> is intended for relative measurement and should use the method that gives the most precise time differences over the course of the program. Its return value must never decrease between calls.</p>
 <p><code><span class='Modifier'>•_timed</span></code> returns the total time taken divided by the number of function calls (<code><span class='Value'>𝕨</span></code> if provided and 1 otherwise), including the overhead required for the outer loop that counts iterations (which will typically be negligible in comparison to the BQN code).</p>
 <p>More accurately the modifier <code><span class='Modifier2'>•_maxTime_</span></code> <em>may</em> fail if execution of <code><span class='Function'>𝔽</span></code> takes over <code><span class='Value'>𝕨</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span></code> seconds, and should fail as quickly as it is practically able to. The most likely way to implement this modifier is to interrupt execution at the given time. If <code><span class='Function'>𝔽</span></code> completes before the interrupt there is no need to measure the amount of time it actually took.</p>
+<h2 id="random-generation"><a class="header" href="#random-generation">Random generation</a></h2>
+<p><code><span class='Function'>•MakeRand</span></code> initializes a deterministic pseudorandom number generator with seed value <code><span class='Value'>𝕩</span></code>. <code><span class='Value'>•rand</span></code>, if it exists, is a globally accessible generator initialized at first use. A random generator has the following member functions:</p>
+<table>
+<thead>
+<tr>
+<th>Name</th>
+<th>Summary</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code><span class='Function'>Range</span></code></td>
+<td>An array of shape <code><span class='Value'>𝕨</span><span class='Function'>⊣</span><span class='Bracket'>⟨⟩</span></code> selected from <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code></td>
+</tr>
+<tr>
+<td><code><span class='Function'>Deal</span></code></td>
+<td>A simple random sample of <code><span class='Value'>𝕨</span><span class='Function'>⊣</span><span class='Value'>𝕩</span></code> elements of <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code></td>
+</tr>
+<tr>
+<td><code><span class='Function'>Subset</span></code></td>
+<td>A sorted SRS of <code><span class='Value'>𝕨</span></code> elements of <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code></td>
+</tr>
+</tbody>
+</table>
+<p>For each of these functions, <code><span class='Value'>𝕩</span></code> is a natural number. For <code><span class='Function'>Range</span></code>, <code><span class='Value'>𝕨</span></code> must be a valid shape if given, and for <code><span class='Function'>Deal</span></code> and <code><span class='Function'>Subset</span></code> it's a natural number less than or equal to <code><span class='Value'>𝕩</span></code>. All selections are made uniformly at random, that is, each possible result is equally likely. A simple random sample (SRS) of <code><span class='Value'>k</span></code> elements from list <code><span class='Value'>s</span></code> is a list of <code><span class='Value'>k</span></code> distinct elements of <code><span class='Value'>s</span></code> in any order. Both the choice of elements and their ordering must be uniformly random. <a href="../implementation/primitive/random.html#simple-random-sample">Recommended algorithms</a> for SRS selection are variants of a partial Knuth shuffle.</p>
+<p>When <code><span class='Value'>𝕨</span></code> isn't given, <code><span class='Function'>Deal</span></code>'s result contains all elements of <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code>, making it a random shuffle of those values, or random permutation. In <code><span class='Function'>Subset</span></code>, setting <code><span class='Value'>𝕨</span></code> to <code><span class='Value'>𝕩</span></code> would instead always result in the list <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code>; because this is not useful, <code><span class='Value'>𝕨</span></code> must be provided.</p>
+<p>In <code><span class='Function'>Range</span></code>, <code><span class='Value'>𝕩</span></code> may be <code><span class='Number'>0</span></code>. In this case the result consists of floating-point numbers in the unit interval from 0 to 1. The numbers should have an overall uniform distribution, but their precision and whether the endpoints 0 and 1 are possible may depend on the implementation.</p>
+<p>Ranges up to <code><span class='Number'>2</span><span class='Function'>⋆</span><span class='Number'>32</span></code> must be supported (that is, a maximum integer result of <code><span class='Paren'>(</span><span class='Number'>2</span><span class='Function'>⋆</span><span class='Number'>32</span><span class='Paren'>)</span><span class='Function'>-</span><span class='Number'>1</span></code>) if the number system accommodates it. In implementations based on double-precision floats it's preferable but not required to support ranges up to <code><span class='Number'>2</span><span class='Function'>⋆</span><span class='Number'>53</span></code>.</p>