basis/random/random-docs.factor

   1 USING: help.markup help.syntax math ;
   2 IN: random
   3
   4 ARTICLE: "random-numbers" "Generating random integers"
   5 "The " { $vocab-link "random" } " vocabulary implements the ``Mersenne Twister'' pseudo-random number generator algorithm."
   6 { $subsection random } ;
   7
   8 ABOUT: "random-numbers"
   9
  10 HELP: seed-random
  11 { $values { "tuple" "a random number generator" } { "seed" "an integer between 0 and 2^32-1" } }
  12 { $description "Seed the random number generator." }
  13 { $notes "Not supported on all random number generators." } ;
  14
  15 HELP: random-32*
  16 { $values { "tuple" "a random number generator" } { "r" "an integer between 0 and 2^32-1" } }
  17 { $description "Generates a random 32-bit unsigned integer." } ;
  18
  19 HELP: random-bytes*
  20 { $values { "n" "an integer" } { "tuple" "a random number generator" } { "byte-array" "a sequence of random bytes" } }
  21 { $description "Generates a byte-array of random bytes." } ;
  22
  23 HELP: random
  24 { $values { "seq" "a sequence" } { "elt" "a random element" } }
  25 { $description "Outputs a random element of the sequence. If the sequence is empty, always outputs " { $link f } "." }
  26 { $notes "Since integers are sequences, passing an integer " { $snippet "n" } " yields a random integer in the interval " { $snippet "[0,n)" } "." } ;
  27
  28 HELP: random-bytes
  29 { $values { "n" "an integer" } { "byte-array" "a random integer" } }
  30 { $description "Outputs an integer with n bytes worth of bits." } ;
  31
  32 HELP: random-bits
  33 { $values { "n" "an integer" } { "r" "a random integer" } }
  34 { $description "Outputs an random integer n bits in length." } ;
  35
  36 HELP: with-random
  37 { $values { "tuple" "a random generator" } { "quot" "a quotation" } }
  38 { $description "Calls the quotation with the random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
  39
  40 HELP: with-secure-random
  41 { $values { "quot" "a quotation" } }
  42 { $description "Calls the quotation with the secure random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
  43
  44 { with-random with-secure-random } related-words