]> gitweb.factorcode.org Git - factor.git/blob - basis/random/random-docs.factor
Merge branch 'browser' of git://github.com/klazuka/factor
[factor.git] / 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-bytes
37 { $values { "n" "an integer" } { "byte-array" "a random integer" } }
38 { $description "Outputs an integer with n bytes worth of bits." }
39 { $examples 
40     { $unchecked-example "USING: prettyprint random ;"
41                "5 random-bytes ."
42                "B{ 135 50 185 119 240 }"
43     }
44 } ;
45
46 HELP: random-bits
47 { $values { "numbits" integer } { "r" "a random integer" } }
48 { $description "Outputs an random integer n bits in length." } ;
49
50 HELP: random-bits*
51 { $values
52     { "numbits" integer }
53     { "n" integer }
54 }
55 { $description "Returns an integer exactly " { $snippet "numbits" } " in length, with the topmost bit set to one." } ;
56
57
58 HELP: with-random
59 { $values { "tuple" "a random generator" } { "quot" "a quotation" } }
60 { $description "Calls the quotation with the random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
61
62 HELP: with-secure-random
63 { $values { "quot" "a quotation" } }
64 { $description "Calls the quotation with the secure random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
65
66 HELP: with-system-random
67 { $values { "quot" "a quotation" } }
68 { $description "Calls the quotation with the system's random generator in a dynamic variable.  All random numbers will be generated using this random generator." } ;
69
70 { with-random with-secure-random with-system-random } related-words
71
72 HELP: randomize
73 { $values
74      { "seq" sequence }
75      { "seq" sequence }
76 }
77 { $description "Randomizes a sequence in-place with the Fisher-Yates algorithm and returns the sequence." } ;
78
79 HELP: sample
80 { $values
81     { "seq" sequence } { "n" integer }
82     { "seq'" sequence }
83 }
84 { $description "Takes " { $snippet "n" } " samples at random without replacement from a sequence. Throws an error if " { $snippet "n" } " is longer than the sequence." }
85 { $examples
86     { $unchecked-example "USING: random prettyprint ; { 1 2 3 } 2 sample ."
87         "{ 3 2 }"
88     }
89 } ;
90
91 HELP: delete-random
92 { $values
93      { "seq" sequence }
94      { "elt" object } }
95 { $description "Deletes a random number from a sequence using " { $link delete-nth } " and returns the deleted object." } ;
96
97 ARTICLE: "random-protocol" "Random protocol"
98 "A random number generator must implement one of these two words:"
99 { $subsection random-32 }
100 { $subsection random-bytes* }
101 "Optional, to seed a random number generator:"
102 { $subsection seed-random } ;
103
104 ARTICLE: "random" "Generating random integers"
105 "The " { $vocab-link "random" } " vocabulary contains a protocol for generating random or pseudorandom numbers."
106 $nl
107 "The “Mersenne Twister” pseudorandom number generator algorithm is the default generator stored in " { $link random-generator } "."
108 $nl
109 "Generate a random object:"
110 { $subsection random }
111 "Combinators to change the random number generator:"
112 { $subsection with-random }
113 { $subsection with-system-random }
114 { $subsection with-secure-random }
115 "Implementation:"
116 { $subsection "random-protocol" }
117 "Randomizing a sequence:"
118 { $subsection randomize }
119 "Sampling a sequences:"
120 { $subsection sample }
121 "Deleting a random element from a sequence:"
122 { $subsection delete-random }
123 "Random numbers with " { $snippet "n" } " bits:"
124 { $subsection random-bits }
125 { $subsection random-bits* } ;
126
127 ABOUT: "random"