basis/random/random-docs.factor

   1 USING: help.markup help.syntax math kernel sequences ;
   2 IN: random
   3
   4 HELP: seed-random
   5 { $values { "tuple" "a random number generator" } { "seed" "an integer between 0 and 2^32-1" } }
   6 { $description "Seed the random number generator." }
   7 { $notes "Not supported on all random number generators." } ;
   8
   9 HELP: random-32*
  10 { $values { "tuple" "a random number generator" } { "r" "an integer between 0 and 2^32-1" } }
  11 { $description "Generates a random 32-bit unsigned integer." } ;
  12
  13 HELP: random-bytes*
  14 { $values { "n" "an integer" } { "tuple" "a random number generator" } { "byte-array" "a sequence of random bytes" } }
  15 { $description "Generates a byte-array of random bytes." } ;
  16
  17 HELP: random
  18 { $values { "seq" sequence } { "elt" "a random element" } }
  19 { $description "Outputs a random element of the input sequence. Outputs " { $link f } " if the sequence is empty." }
  20 { $notes "Since integers are sequences, passing an integer " { $snippet "n" } " outputs an integer in the interval " { $snippet "[0,n)" } "." }
  21 { $examples
  22     { $unchecked-example "USING: random prettyprint ;"
  23         "10 random ."
  24         "3" }
  25     { $unchecked-example "USING: random prettyprint ;"
  26         "SYMBOL: heads"
  27         "SYMBOL: tails"
  28         "{ heads tails } random ."
  29         "heads" }
  30 } ;
  31
  32 HELP: random-bytes
  33 { $values { "n" "an integer" } { "byte-array" "a random integer" } }
  34 { $description "Outputs an integer with n bytes worth of bits." }
  35 { $examples
  36     { $unchecked-example "USING: prettyprint random ;"
  37                "5 random-bytes ."
  38                "B{ 135 50 185 119 240 }"
  39     }
  40 } ;
  41
  42 HELP: random-bits
  43 { $values { "n" "an integer" } { "r" "a random integer" } }
  44 { $description "Outputs an random integer n bits in length." } ;
  45
  46 HELP: with-random
  47 { $values { "tuple" "a random generator" } { "quot" "a quotation" } }
  48 { $description "Calls the quotation with the random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
  49
  50 HELP: with-secure-random
  51 { $values { "quot" "a quotation" } }
  52 { $description "Calls the quotation with the secure random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
  53
  54 HELP: with-system-random
  55 { $values { "quot" "a quotation" } }
  56 { $description "Calls the quotation with the system's random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
  57
  58 { with-random with-secure-random with-system-random } related-words
  59
  60 HELP: randomize
  61 { $values
  62      { "seq" sequence }
  63      { "seq" sequence }
  64 }
  65 { $description "Randomizes a sequence in-place with the Fisher-Yates algorithm and returns the sequence." } ;
  66
  67 HELP: delete-random
  68 { $values
  69      { "seq" sequence }
  70      { "elt" object } }
  71 { $description "Deletes a random number from a sequence using " { $link delete-nth } " and returns the deleted object." } ;
  72
  73 ARTICLE: "random-protocol" "Random protocol"
  74 "A random number generator must implement one of these two words:"
  75 { $subsection random-32* }
  76 { $subsection random-bytes* }
  77 "Optional, to seed a random number generator:"
  78 { $subsection seed-random } ;
  79
  80 ARTICLE: "random" "Generating random integers"
  81 "The " { $vocab-link "random" } " vocabulary contains a protocol for generating random or pseudorandom numbers."
  82 $nl
  83 "The “Mersenne Twister” pseudorandom number generator algorithm is the default generator stored in " { $link random-generator } "."
  84 $nl
  85 "Generate a random object:"
  86 { $subsection random }
  87 "Combinators to change the random number generator:"
  88 { $subsection with-random }
  89 { $subsection with-system-random }
  90 { $subsection with-secure-random }
  91 "Implementation:"
  92 { $subsection "random-protocol" }
  93 "Randomizing a sequence:"
  94 { $subsection randomize }
  95 "Deleting a random element from a sequence:"
  96 { $subsection delete-random } ;
  97
  98 ABOUT: "random"