1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 pseudo-random number generator
7 <!-- ##### SECTION Long_Description ##### -->
9 The following functions allow you to use a portable, fast and good
10 pseudo-random number generator (PRNG). It uses the Mersenne Twister
11 PRNG, which was originally developed by Makoto Matsumoto and Takuji
12 Nishimura. Further information can be found at <ulink
13 url="http://www.math.keio.ac.jp/~matumoto/emt.html"
14 >www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
18 If you just need a random number, you simply call the
19 <function>g_random_*</function> functions, which will create a globally
20 used #GRand and use the according <function>g_rand_*</function> functions
21 internally. Whenever you need a stream of reproducible random numbers, you
22 better create a #GRand yourself and use the <function>g_rand_*</function>
23 functions directly, which will also be slightly faster. Initializing a #GRand
24 with a certain seed will produce exactly the same series of random numbers
25 on all platforms. This can thus be used as a seed for e.g. games.
29 The <function>g_rand*_range</function> functions will return high quality
30 equally distributed random numbers, whereas for example the
31 <literal>(g_random_int()%max)</literal> approach often doesn't
32 yield equally distributed numbers.
36 GLib changed the seeding algorithm for the pseudo-random number
37 generator Mersenne Twister, as used by <structname>GRand</structname>
38 and <structname>GRandom</structname>. This was necessary, because some
39 seeds would yield very bad pseudo-random streams. Also the
40 pseudo-random integers generated by
41 <function>g_rand*_int_range()</function> will have a
42 slightly better equal distribution with the new version of GLib.
46 The original seeding and generation algorithms, as found in GLib 2.0.x,
47 can 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
49 GLib-2.0 algorithms only if you have sequences of numbers generated
50 with Glib-2.0 that you need to reproduce exactly.
53 <!-- ##### SECTION See_Also ##### -->
58 <!-- ##### SECTION Stability_Level ##### -->
61 <!-- ##### STRUCT GRand ##### -->
63 The #GRand struct is an opaque data structure. It should only be
64 accessed through the <function>g_rand_*</function> functions.
68 <!-- ##### FUNCTION g_rand_new_with_seed ##### -->
75 <!-- ##### FUNCTION g_rand_new_with_seed_array ##### -->
85 <!-- ##### FUNCTION g_rand_new ##### -->
91 <!-- ##### FUNCTION g_rand_copy ##### -->
100 <!-- ##### FUNCTION g_rand_free ##### -->
106 <!-- ##### FUNCTION g_rand_set_seed ##### -->
113 <!-- ##### FUNCTION g_rand_set_seed_array ##### -->
123 <!-- ##### MACRO g_rand_boolean ##### -->
125 Returns a random #gboolean from @rand_. This corresponds to a unbiased
130 @Returns: a random #gboolean.
133 <!-- ##### FUNCTION g_rand_int ##### -->
140 <!-- ##### FUNCTION g_rand_int_range ##### -->
149 <!-- ##### FUNCTION g_rand_double ##### -->
156 <!-- ##### FUNCTION g_rand_double_range ##### -->
165 <!-- ##### FUNCTION g_random_set_seed ##### -->
171 <!-- ##### MACRO g_random_boolean ##### -->
173 Returns a random #gboolean. This corresponds to a unbiased coin toss.
176 @Returns: a random #gboolean.
179 <!-- ##### FUNCTION g_random_int ##### -->
185 <!-- ##### FUNCTION g_random_int_range ##### -->
193 <!-- ##### FUNCTION g_random_double ##### -->
199 <!-- ##### FUNCTION g_random_double_range ##### -->