Random Numbers

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);
#define     g_rand_boolean                  (rand_)
guint32     g_rand_int                      (GRand *rand_);
gint32      g_rand_int_range                (GRand *rand_,
                                             gint32 begin,
                                             gint32 end);
gdouble     g_rand_double                   (GRand *rand_);
gdouble     g_rand_double_range             (GRand *rand_,
                                             gdouble begin,
                                             gdouble end);
void        g_random_set_seed               (guint32 seed);
#define     g_random_boolean                ()
guint32     g_random_int                    (void);
gint32      g_random_int_range              (gint32 begin,
                                             gint32 end);
gdouble     g_random_double                 (void);
gdouble     g_random_double_range           (gdouble begin,
                                             gdouble end);

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_* functions 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.

GLib changed the seeding algorithm for the pseudo-random number generator Mersenne Twister, as used by GRand and GRandom. This was necessary, because some seeds would yield very bad pseudo-random streams. The original seeding algorithm, as found in GLib 2.0.x, can be used instead of the new one by setting the environment variable G_RANDOM_VERSION to the value of '2.0'. Use the GLib-2.0 algorithm only if you have sequences of numbers generated with Glib-2.0 that you need to reproduce exactly.

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_boolean()

#define     g_rand_boolean(rand_)

Returns a random gboolean from rand_. This corresponds to a unbiased coin toss.

rand_ :a GRand.
Returns :a random gboolean.

g_rand_int ()

guint32     g_rand_int                      (GRand *rand_);

Returns the next random guint32 from rand_ equally 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 begin,
                                             gint32 end);

Returns the next random gint32 from rand_ equally distributed over the range [begin..end-1].

rand_ : a GRand.
begin : lower closed bound of the interval.
end : upper open bound of the interval.
Returns : A random number.

g_rand_double ()

gdouble     g_rand_double                   (GRand *rand_);

Returns the next random gdouble from rand_ equally 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 begin,
                                             gdouble end);

Returns the next random gdouble from rand_ equally distributed over the range [begin..end).

rand_ : a GRand.
begin : lower closed bound of the interval.
end : 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 the g_random_* functions, to seed.

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

g_random_boolean()

#define     g_random_boolean()

Returns a random gboolean. This corresponds to a unbiased coin toss.

Returns :a random gboolean.

g_random_int ()

guint32     g_random_int                    (void);

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

Returns : A random number.

g_random_int_range ()

gint32      g_random_int_range              (gint32 begin,
                                             gint32 end);

Returns a random gint32 equally distributed over the range [begin..end-1].

begin : lower closed bound of the interval.
end : upper open bound of the interval.
Returns : A random number.

g_random_double ()

gdouble     g_random_double                 (void);

Returns a random gdouble equally distributed over the range [0..1).

Returns : A random number.

g_random_double_range ()

gdouble     g_random_double_range           (gdouble begin,
                                             gdouble end);

Returns a random gdouble equally distributed over the range [begin..end).

begin : lower closed bound of the interval.
end : upper open bound of the interval.
Returns : A random number.