docs/reference/glib/tmpl/random_numbers.sgml

<!-- ##### SECTION Title ##### -->
Random Numbers

<!-- ##### SECTION Short_Description ##### -->
pseudo-random number generator.

<!-- ##### SECTION Long_Description ##### -->
<para>
The following functions allow you to use a portable, fast and good
pseudo-random number generator (PRNG). It uses the Mersenne Twister
PRNG, which was originally developed by Makoto Matsumoto and Takuji
Nishimura. Further information can be found at <ulink
url="http://www.math.keio.ac.jp/~matumoto/emt.html"
>www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
</para>

<para>
If you just need a random number, you simply call the 
<function>g_random_*</function> functions, which will create a globally 
used #GRand and use the according <function>g_rand_*</function> functions 
internally. Whenever you need a stream of reproducible random numbers, you 
better create a #GRand yourself and use the <function>g_rand_*</function> 
functions directly, which will also be slightly faster. Initializing a #GRand 
with a certain seed will produce exactly the same series of random numbers 
on all platforms. This can thus be used as a seed for e.g. games.
</para>

<para>
The <function>g_rand*_range</function> functions will return high quality
equally distributed random numbers, whereas for example the
<literal>(g_random_int()&percnt;max)</literal> approach often doesn't
yield equally distributed numbers.
</para>

<para>
GLib changed the seeding algorithm for the pseudo-random number
generator Mersenne Twister, as used by <structname>GRand</structname>
and <structname>GRandom</structname>. This was necessary, because some
seeds would yield very bad pseudo-random streams.  Also the
pseudo-random integers generated by
<function>g_rand*_int_range()</function> will have a
slightly better equal distribution with the new version of GLib.
</para>

<para>
The original seeding and generation algorithms, as found in GLib 2.0.x,
can be used instead of the new ones by setting the environment variable
<envar>G_RANDOM_VERSION</envar> to the value of '2.0'. Use the
GLib-2.0 algorithms only if you have sequences of numbers generated
with Glib-2.0 that you need to reproduce exactly.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GRand ##### -->
<para>
The #GRand struct is an opaque data structure. It should only be
accessed through the <function>g_rand_*</function> functions.
</para>


<!-- ##### FUNCTION g_rand_new_with_seed ##### -->


@seed: 
@Returns: 


<!-- ##### FUNCTION g_rand_new_with_seed_array ##### -->
<para>

</para>

@seed: 
@seed_length: 
@Returns: 


<!-- ##### FUNCTION g_rand_new ##### -->


@Returns: 


<!-- ##### FUNCTION g_rand_copy ##### -->
<para>

</para>

@rand_: 
@Returns: 


<!-- ##### FUNCTION g_rand_free ##### -->


@rand_: 


<!-- ##### FUNCTION g_rand_set_seed ##### -->


@rand_: 
@seed: 


<!-- ##### FUNCTION g_rand_set_seed_array ##### -->
<para>

</para>

@rand_: 
@seed: 
@seed_length: 


<!-- ##### MACRO g_rand_boolean ##### -->
<para>
Returns a random #gboolean from @rand_. This corresponds to a unbiased
coin toss.
</para>

@rand_: a #GRand.
@Returns: a random #gboolean.


<!-- ##### FUNCTION g_rand_int ##### -->


@rand_: 
@Returns: 


<!-- ##### FUNCTION g_rand_int_range ##### -->


@rand_: 
@begin: 
@end: 
@Returns: 


<!-- ##### FUNCTION g_rand_double ##### -->


@rand_: 
@Returns: 


<!-- ##### FUNCTION g_rand_double_range ##### -->


@rand_: 
@begin: 
@end: 
@Returns: 


<!-- ##### FUNCTION g_random_set_seed ##### -->


@seed: 


<!-- ##### MACRO g_random_boolean ##### -->
<para>
Returns a random #gboolean. This corresponds to a unbiased coin toss.
</para>

@Returns: a random #gboolean.


<!-- ##### FUNCTION g_random_int ##### -->


@Returns: 


<!-- ##### FUNCTION g_random_int_range ##### -->


@begin: 
@end: 
@Returns: 


<!-- ##### FUNCTION g_random_double ##### -->


@Returns: 


<!-- ##### FUNCTION g_random_double_range ##### -->


@begin: 
@end: 
@Returns: