• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!-- ##### SECTION Title ##### -->
2Random Numbers
3
4<!-- ##### SECTION Short_Description ##### -->
5pseudo-random number generator
6
7<!-- ##### SECTION Long_Description ##### -->
8<para>
9The following functions allow you to use a portable, fast and good
10pseudo-random number generator (PRNG). It uses the Mersenne Twister
11PRNG, which was originally developed by Makoto Matsumoto and Takuji
12Nishimura. Further information can be found at <ulink
13url="http://www.math.keio.ac.jp/~matumoto/emt.html"
14>www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
15</para>
16
17<para>
18If you just need a random number, you simply call the
19<function>g_random_*</function> functions, which will create a globally
20used #GRand and use the according <function>g_rand_*</function> functions
21internally. Whenever you need a stream of reproducible random numbers, you
22better create a #GRand yourself and use the <function>g_rand_*</function>
23functions directly, which will also be slightly faster. Initializing a #GRand
24with a certain seed will produce exactly the same series of random numbers
25on all platforms. This can thus be used as a seed for e.g. games.
26</para>
27
28<para>
29The <function>g_rand*_range</function> functions will return high quality
30equally distributed random numbers, whereas for example the
31<literal>(g_random_int()&percnt;max)</literal> approach often doesn't
32yield equally distributed numbers.
33</para>
34
35<para>
36GLib changed the seeding algorithm for the pseudo-random number
37generator Mersenne Twister, as used by <structname>GRand</structname>
38and <structname>GRandom</structname>. This was necessary, because some
39seeds would yield very bad pseudo-random streams.  Also the
40pseudo-random integers generated by
41<function>g_rand*_int_range()</function> will have a
42slightly better equal distribution with the new version of GLib.
43</para>
44
45<para>
46The original seeding and generation algorithms, as found in GLib 2.0.x,
47can be used instead of the new ones by setting the environment variable
48<envar>G_RANDOM_VERSION</envar> to the value of '2.0'. Use the
49GLib-2.0 algorithms only if you have sequences of numbers generated
50with Glib-2.0 that you need to reproduce exactly.
51</para>
52
53<!-- ##### SECTION See_Also ##### -->
54<para>
55
56</para>
57
58<!-- ##### SECTION Stability_Level ##### -->
59
60
61<!-- ##### STRUCT GRand ##### -->
62<para>
63The #GRand struct is an opaque data structure. It should only be
64accessed through the <function>g_rand_*</function> functions.
65</para>
66
67
68<!-- ##### FUNCTION g_rand_new_with_seed ##### -->
69
70
71@seed:
72@Returns:
73
74
75<!-- ##### FUNCTION g_rand_new_with_seed_array ##### -->
76<para>
77
78</para>
79
80@seed:
81@seed_length:
82@Returns:
83
84
85<!-- ##### FUNCTION g_rand_new ##### -->
86
87
88@Returns:
89
90
91<!-- ##### FUNCTION g_rand_copy ##### -->
92<para>
93
94</para>
95
96@rand_:
97@Returns:
98
99
100<!-- ##### FUNCTION g_rand_free ##### -->
101
102
103@rand_:
104
105
106<!-- ##### FUNCTION g_rand_set_seed ##### -->
107
108
109@rand_:
110@seed:
111
112
113<!-- ##### FUNCTION g_rand_set_seed_array ##### -->
114<para>
115
116</para>
117
118@rand_:
119@seed:
120@seed_length:
121
122
123<!-- ##### MACRO g_rand_boolean ##### -->
124<para>
125Returns a random #gboolean from @rand_. This corresponds to a unbiased
126coin toss.
127</para>
128
129@rand_: a #GRand.
130@Returns: a random #gboolean.
131
132
133<!-- ##### FUNCTION g_rand_int ##### -->
134
135
136@rand_:
137@Returns:
138
139
140<!-- ##### FUNCTION g_rand_int_range ##### -->
141
142
143@rand_:
144@begin:
145@end:
146@Returns:
147
148
149<!-- ##### FUNCTION g_rand_double ##### -->
150
151
152@rand_:
153@Returns:
154
155
156<!-- ##### FUNCTION g_rand_double_range ##### -->
157
158
159@rand_:
160@begin:
161@end:
162@Returns:
163
164
165<!-- ##### FUNCTION g_random_set_seed ##### -->
166
167
168@seed:
169
170
171<!-- ##### MACRO g_random_boolean ##### -->
172<para>
173Returns a random #gboolean. This corresponds to a unbiased coin toss.
174</para>
175
176@Returns: a random #gboolean.
177
178
179<!-- ##### FUNCTION g_random_int ##### -->
180
181
182@Returns:
183
184
185<!-- ##### FUNCTION g_random_int_range ##### -->
186
187
188@begin:
189@end:
190@Returns:
191
192
193<!-- ##### FUNCTION g_random_double ##### -->
194
195
196@Returns:
197
198
199<!-- ##### FUNCTION g_random_double_range ##### -->
200
201
202@begin:
203@end:
204@Returns:
205
206
207