basis/random/random-docs.factor

   1 USING: help.markup help.syntax math kernel sequences arrays ;
   2 IN: random
   3
   4 HELP: seed-random
   5 { $values
   6     { "obj" "a random number generator" }
   7     { "seed" "a seed specific to the random number generator" }
   8 }
   9 { $description "Seed the random number generator. Repeatedly seeding the random number generator should provide the same sequence of random numbers." }
  10 { $notes "Not supported on all random number generators." } ;
  11
  12 HELP: random-32*
  13 { $values { "obj" "a random number generator" } { "r" "an integer between 0 and 2^32-1" } }
  14 { $description "Generates a random 32-bit unsigned integer." } ;
  15
  16 HELP: random-bytes*
  17 { $values { "n" "an integer" } { "obj" "a random number generator" } { "byte-array" "a sequence of random bytes" } }
  18 { $description "Generates a byte-array of random bytes." } ;
  19
  20 HELP: random
  21 { $values { "obj" object } { "elt" "a random element" } }
  22 { $description "Outputs a random element of the input object, or outputs " { $link f } " if the object contains no elements." }
  23 { $examples
  24     { $unchecked-example "USING: random prettyprint ;"
  25         "10 random ."
  26         "3" }
  27     { $unchecked-example "USING: random prettyprint ;"
  28         "SYMBOL: heads"
  29         "SYMBOL: tails"
  30         "{ heads tails } random ."
  31         "heads" }
  32 } ;
  33
  34 HELP: random-32
  35 { $values { "n" "a 32-bit random integer" } }
  36 { $description "Outputs 32 random bits. This word is more efficient than calling " { $link random } " because no scaling is done on the output." } ;
  37
  38 HELP: random-bytes
  39 { $values { "n" "an integer" } { "byte-array" "a random integer" } }
  40 { $description "Outputs an integer with n bytes worth of bits." }
  41 { $examples
  42     { $unchecked-example "USING: prettyprint random ;"
  43                "5 random-bytes ."
  44                "B{ 135 50 185 119 240 }"
  45     }
  46 } ;
  47
  48 HELP: random-integers
  49 { $values { "length" integer } { "n" integer } { "sequence" array } }
  50 { $description "Outputs an array with " { $snippet "length" } " random integers from [0,n)." }
  51 { $examples
  52     { $unchecked-example "USING: prettyprint random ;"
  53                "10 100 random-integers ."
  54                "{ 32 62 71 89 54 12 57 57 10 19 }"
  55     }
  56 } ;
  57
  58 HELP: random-unit
  59 { $values { "n" float } }
  60 { $description "Outputs a random uniform float from [0,1]." } ;
  61
  62 HELP: random-units
  63 { $values { "length" integer } { "sequence" array } }
  64 { $description "Outputs an array with " { $snippet "length" } " random uniform floats from [0,1]." }
  65 { $examples
  66     { $unchecked-example "USING: prettyprint random ;"
  67                "7 random-units ."
  68                "{
  69     0.1881956429982787
  70     0.9063571897519639
  71     0.9550470241550406
  72     0.6289397941552234
  73     0.9441213853903183
  74     0.7673290082934152
  75     0.573743749061385
  76 }"
  77     }
  78 } ;
  79
  80 HELP: random-bits
  81 { $values { "numbits" integer } { "r" "a random integer" } }
  82 { $description "Outputs an random integer n bits in length." } ;
  83
  84 HELP: random-bits*
  85 { $values { "numbits" integer } { "r" "a random integer" } }
  86 { $description "Returns an integer exactly " { $snippet "numbits" } " in length, with the topmost bit set to one." } ;
  87
  88 HELP: with-random
  89 { $values { "obj" "a random number generator" } { "quot" "a quotation" } }
  90 { $description "Calls the quotation with the random number generator in a dynamic variable.  All random numbers will be generated using this random number generator." } ;
  91
  92 HELP: with-secure-random
  93 { $values { "quot" "a quotation" } }
  94 { $description "Calls the quotation with the secure random number generator in a dynamic variable.  All random numbers will be generated using this random number generator." } ;
  95
  96 HELP: with-system-random
  97 { $values { "quot" "a quotation" } }
  98 { $description "Calls the quotation with the system's random number generator in a dynamic variable.  All random numbers will be generated using this random number generator." } ;
  99
 100 { with-random with-secure-random with-system-random } related-words
 101
 102 HELP: randomize
 103 { $values
 104      { "seq" sequence }
 105      { "randomized" sequence }
 106 }
 107 { $description "Randomizes a sequence in-place with the Fisher-Yates algorithm and returns the sequence." } ;
 108
 109 HELP: sample
 110 { $values
 111     { "seq" sequence } { "n" integer }
 112     { "seq'" sequence }
 113 }
 114 { $description "Takes " { $snippet "n" } " samples at random without replacement from a sequence. Throws an error if " { $snippet "n" } " is longer than the sequence." }
 115 { $examples
 116     { $unchecked-example "USING: random prettyprint ;"
 117     "{ 1 2 3 } 2 sample ."
 118     "{ 3 2 }"
 119     }
 120 } ;
 121
 122 HELP: delete-random
 123 { $values
 124      { "seq" sequence }
 125      { "elt" object } }
 126 { $description "Deletes a random number from a sequence using " { $link remove-nth! } " and returns the deleted object." } ;
 127
 128 ARTICLE: "random-protocol" "Random protocol"
 129 "A random number generator must implement one of these two words:"
 130 { $subsections
 131     random-32*
 132     random-bytes*
 133 }
 134 "Optional, to seed a random number generator:"
 135 { $subsections seed-random } ;
 136
 137 ARTICLE: "random" "Generating random integers"
 138 "The " { $vocab-link "random" } " vocabulary contains a protocol for generating random or pseudorandom numbers."
 139 $nl
 140 "The “Mersenne Twister” pseudorandom number generator algorithm is the default generator stored in " { $link random-generator } "."
 141 $nl
 142 "Generate a random object:"
 143 { $subsections random }
 144 "Efficient 32-bit random numbers:"
 145 { $subsections random-32 }
 146 "Combinators to change the random number generator:"
 147 { $subsections
 148     with-random
 149     with-system-random
 150     with-secure-random
 151 }
 152 "Implementation:"
 153 { $subsections "random-protocol" }
 154 "Randomizing a sequence:"
 155 { $subsections randomize }
 156 "Sampling a sequences:"
 157 { $subsections sample }
 158 "Deleting a random element from a sequence:"
 159 { $subsections delete-random }
 160 "Sequences of random numbers:"
 161 { $subsections random-bytes random-integers random-units }
 162 "Random numbers with " { $snippet "n" } " bits:"
 163 { $subsections
 164     random-bits
 165     random-bits*
 166 } ;
 167
 168 ABOUT: "random"