| <!-- ##### 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()%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> |
| |
| <!-- ##### 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: |
| |
| |