basis/random/random-docs.factor

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