basis/random/random-docs.factor

   1 USING: help.markup help.syntax math kernel sequences ;
   2 IN: random
   3
   4 HELP: seed-random
   5 { $values
   6     { "tuple" "a random number generator" }
   7     { "seed" "a seed specific to the random number generator" }
   8     { "tuple'" "a 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 { "tuple" "a random number generator" } { "r" "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" "an integer" } { "tuple" "a random number generator" } { "byte-array" "a sequence of random bytes" } }
  19 { $description "Generates a byte-array of random bytes." } ;
  20
  21 HELP: random
  22 { $values { "seq" sequence } { "elt" "a random element" } }
  23 { $description "Outputs a random element of the input sequence. Outputs " { $link f } " if the sequence is empty." }
  24 { $notes "Since integers are sequences, passing an integer " { $snippet "n" } " outputs an integer in the interval " { $snippet "[0,n)" } "." }
  25 { $examples
  26     { $unchecked-example "USING: random prettyprint ;"
  27         "10 random ."
  28         "3" }
  29     { $unchecked-example "USING: random prettyprint ;"
  30         "SYMBOL: heads"
  31         "SYMBOL: tails"
  32         "{ heads tails } random ."
  33         "heads" }
  34 } ;
  35
  36 HELP: random-32
  37 { $values { "n" "a 32-bit random integer" } }
  38 { $description "Outputs 32 random bits. This word is more efficient than calling " { $link random } " because no scaling is done on the output." } ;
  39
  40 HELP: random-bytes
  41 { $values { "n" "an integer" } { "byte-array" "a random integer" } }
  42 { $description "Outputs an integer with n bytes worth of bits." }
  43 { $examples
  44     { $unchecked-example "USING: prettyprint random ;"
  45                "5 random-bytes ."
  46                "B{ 135 50 185 119 240 }"
  47     }
  48 } ;
  49
  50 HELP: random-bits
  51 { $values { "numbits" integer } { "r" "a random integer" } }
  52 { $description "Outputs an random integer n bits in length." } ;
  53
  54 HELP: random-bits*
  55 { $values
  56     { "numbits" integer }
  57     { "n" integer }
  58 }
  59 { $description "Returns an integer exactly " { $snippet "numbits" } " in length, with the topmost bit set to one." } ;
  60
  61
  62 HELP: with-random
  63 { $values { "tuple" "a random generator" } { "quot" "a quotation" } }
  64 { $description "Calls the quotation with the random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
  65
  66 HELP: with-secure-random
  67 { $values { "quot" "a quotation" } }
  68 { $description "Calls the quotation with the secure random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
  69
  70 HELP: with-system-random
  71 { $values { "quot" "a quotation" } }
  72 { $description "Calls the quotation with the system's random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
  73
  74 { with-random with-secure-random with-system-random } related-words
  75
  76 HELP: randomize
  77 { $values
  78      { "seq" sequence }
  79      { "seq" sequence }
  80 }
  81 { $description "Randomizes a sequence in-place with the Fisher-Yates algorithm and returns the sequence." } ;
  82
  83 HELP: sample
  84 { $values
  85     { "seq" sequence } { "n" integer }
  86     { "seq'" sequence }
  87 }
  88 { $description "Takes " { $snippet "n" } " samples at random without replacement from a sequence. Throws an error if " { $snippet "n" } " is longer than the sequence." }
  89 { $examples
  90     { $unchecked-example "USING: random prettyprint ; { 1 2 3 } 2 sample ."
  91         "{ 3 2 }"
  92     }
  93 } ;
  94
  95 HELP: delete-random
  96 { $values
  97      { "seq" sequence }
  98      { "elt" object } }
  99 { $description "Deletes a random number from a sequence using " { $link remove-nth! } " and returns the deleted object." } ;
 100
 101 ARTICLE: "random-protocol" "Random protocol"
 102 "A random number generator must implement one of these two words:"
 103 { $subsections
 104     random-32*
 105     random-bytes*
 106 }
 107 "Optional, to seed a random number generator:"
 108 { $subsections seed-random } ;
 109
 110 ARTICLE: "random" "Generating random integers"
 111 "The " { $vocab-link "random" } " vocabulary contains a protocol for generating random or pseudorandom numbers."
 112 $nl
 113 "The “Mersenne Twister” pseudorandom number generator algorithm is the default generator stored in " { $link random-generator } "."
 114 $nl
 115 "Generate a random object:"
 116 { $subsections random }
 117 "Efficient 32-bit random numbers:"
 118 { $subsections random-32 }
 119 "Combinators to change the random number generator:"
 120 { $subsections
 121     with-random
 122     with-system-random
 123     with-secure-random
 124 }
 125 "Implementation:"
 126 { $subsections "random-protocol" }
 127 "Randomizing a sequence:"
 128 { $subsections randomize }
 129 "Sampling a sequences:"
 130 { $subsections sample }
 131 "Deleting a random element from a sequence:"
 132 { $subsections delete-random }
 133 "Random numbers with " { $snippet "n" } " bits:"
 134 { $subsections
 135     random-bits
 136     random-bits*
 137 } ;
 138
 139 ABOUT: "random"