Random Numbers

Name

Random Numbers -- pseudo random number generator.

Synopsis


#include <glib.h>


struct      GRand;
GRand*      g_rand_new_with_seed            (guint32 seed);
GRand*      g_rand_new                      (void);
void        g_rand_free                     (GRand *rand);
void        g_rand_set_seed                 (GRand *rand,
                                             guint32 seed);
guint32     g_rand_int                      (GRand *rand);
gint32      g_rand_int_range                (GRand *rand,
                                             gint32 min,
                                             gint32 max);
gdouble     g_rand_double                   (GRand *rand);
gdouble     g_rand_double_range             (GRand *rand,
                                             gdouble min,
                                             gdouble max);
void        g_random_set_seed               (guint32 seed);
guint32     g_random_int                    (void);
gint32      g_random_int_range              (gint32 min,
                                             gint32 max);
gdouble     g_random_double                 (void);
gdouble     g_random_double_range           (gdouble min,
                                             gdouble max);

Description

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 www.math.keio.ac.jp/~matumoto/emt.html.

If you just need a random number, you simply call the g_random_* functions, which will create a globally used GRand and use the according g_rand_* function internally. Whenever you need a stream of reproducible random numbers, you better create a GRand yourself and use the g_rand_* 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.

The g_rand*_range functions will return high quality equally distributed random numbers, whereas for example the (g_random_int()%max) approach often doesn't yield equally distributed numbers.

A random binary decision is best implemented by using if(g_random_int()&(1<<a)), where a can be every integer constant from 0 to 31. The Mersenne Twister PRNG is said to produce highly random lower bits too, but it is common not to rely on that, so choosing a to be from 4 to 31 might be wise.

Details

struct GRand

struct GRand;

The GRand struct is an opaque data structure. It should only be accessed through the g_rand_* functions.


g_rand_new_with_seed ()

GRand*      g_rand_new_with_seed            (guint32 seed);

Creates a new random number generator initialized with seed.

seed : a value to initialize the random number generator.
Returns : the new GRand.


g_rand_new ()

GRand*      g_rand_new                      (void);

Creates a new random number generator initialized with a seed taken either from /dev/urandom (if existing) or from the current time (as a fallback).

Returns : the new GRand.


g_rand_free ()

void        g_rand_free                     (GRand *rand);

Frees the memory allocated for the GRand.

rand : a GRand.


g_rand_set_seed ()

void        g_rand_set_seed                 (GRand *rand,
                                             guint32 seed);

Sets the seed for the random number generator GRand to seed.

rand : a GRand.
seed : a value to reinitialize the random number generator.


g_rand_int ()

guint32     g_rand_int                      (GRand *rand);

Return the next random guint32 from rand equaly distributed over the range [0..2^32-1].

rand : a GRand.
Returns : A random number.


g_rand_int_range ()

gint32      g_rand_int_range                (GRand *rand,
                                             gint32 min,
                                             gint32 max);

Return the next random gint32 from rand equaly distributed over the range [min..max-1].

rand : a GRand.
min : lower closed bound of the interval.
max : upper open bound of the interval.
Returns : A random number.


g_rand_double ()

gdouble     g_rand_double                   (GRand *rand);

Return the next random gdouble from rand equaly distributed over the range [0..1).

rand : a GRand.
Returns : A random number.


g_rand_double_range ()

gdouble     g_rand_double_range             (GRand *rand,
                                             gdouble min,
                                             gdouble max);

Return the next random gdouble from rand equaly distributed over the range [min..max).

rand : a GRand.
min : lower closed bound of the interval.
max : upper open bound of the interval.
Returns : A random number.


g_random_set_seed ()

void        g_random_set_seed               (guint32 seed);

Sets the seed for the global random number generator, which is used by te g_random_* functions, to seed.

seed : a value to reinitialize the global random number generator.


g_random_int ()

guint32     g_random_int                    (void);

Return a random guint32 equaly distributed over the range [0..2^32-1].

Returns : A random number.


g_random_int_range ()

gint32      g_random_int_range              (gint32 min,
                                             gint32 max);

Return a random gint32 equaly distributed over the range [min..max-1].

min : lower closed bound of the interval.
max : upper open bound of the interval.
Returns : A random number.


g_random_double ()

gdouble     g_random_double                 (void);

Return a random gdouble equaly distributed over the range [0..1).

Returns : A random number.


g_random_double_range ()

gdouble     g_random_double_range           (gdouble min,
                                             gdouble max);

Return a random gdouble equaly distributed over the range [min..max).

min : lower closed bound of the interval.
max : upper open bound of the interval.
Returns : A random number.