/src/wrappers/glib/library/utilities/glib_random_numbers.e
Specman e | 306 lines | 2 code | 109 blank | 195 comment | 0 complexity | dd520fbe6721c6adfdaa75826a272f8c MD5 | raw file
1deferred class GLIB_RANDOM_NUMBERS 2-- Random Numbers 3 4-- Random Numbers -- pseudo-random number generator. 5 6-- Synopsis 7 8 9-- #include <glib.h> 10 11 12-- GRand; 13-- GRand* g_rand_new_with_seed (guint32 seed); 14-- GRand* g_rand_new_with_seed_array (const guint32 *seed, 15-- guint seed_length); 16-- GRand* g_rand_new (void); 17-- GRand* g_rand_copy (GRand *rand_); 18-- void g_rand_free (GRand *rand_); 19-- void g_rand_set_seed (GRand *rand_, 20-- guint32 seed); 21-- void g_rand_set_seed_array (GRand *rand_, 22-- const guint32 *seed, 23-- guint seed_length); 24-- #define g_rand_boolean (rand_) 25-- guint32 g_rand_int (GRand *rand_); 26-- gint32 g_rand_int_range (GRand *rand_, 27-- gint32 begin, 28-- gint32 end); 29-- gdouble g_rand_double (GRand *rand_); 30-- gdouble g_rand_double_range (GRand *rand_, 31-- gdouble begin, 32-- gdouble end); 33-- void g_random_set_seed (guint32 seed); 34-- #define g_random_boolean () 35-- guint32 g_random_int (void); 36-- gint32 g_random_int_range (gint32 begin, 37-- gint32 end); 38-- gdouble g_random_double (void); 39-- gdouble g_random_double_range (gdouble begin, 40-- gdouble end); 41 42-- Description 43 44-- The following functions allow you to use a portable, fast and good pseudo-random 45-- number generator (PRNG). It uses the Mersenne Twister PRNG, which was originally 46-- developed by Makoto Matsumoto and Takuji Nishimura. Further information can be 47-- found at www.math.keio.ac.jp/~matumoto/emt.html. 48 49-- If you just need a random number, you simply call the g_random_* functions, which 50-- will create a globally used GRand and use the according g_rand_* functions 51-- internally. Whenever you need a stream of reproducible random numbers, you better 52-- create a GRand yourself and use the g_rand_* functions directly, which will also 53-- be slightly faster. Initializing a GRand with a certain seed will produce exactly 54-- the same series of random numbers on all platforms. This can thus be used as a 55-- seed for e.g. games. 56 57-- The g_rand*_range functions will return high quality equally distributed random 58-- numbers, whereas for example the (g_random_int()%max) approach often doesn't 59-- yield equally distributed numbers. 60 61-- GLib changed the seeding algorithm for the pseudo-random number generator 62-- Mersenne Twister, as used by GRand and GRandom. This was necessary, because some 63-- seeds would yield very bad pseudo-random streams. Also the pseudo-random integers 64-- generated by g_rand*_int_range() will have a slightly better equal distribution 65-- with the new version of GLib. 66 67-- The original seeding and generation algorithms, as found in GLib 2.0.x, can be 68-- used instead of the new ones by setting the environment variable G_RANDOM_VERSION 69-- to the value of '2.0'. Use the GLib-2.0 algorithms only if you have sequences of 70-- numbers generated with Glib-2.0 that you need to reproduce exactly. 71 72-- Details 73 74-- GRand 75 76-- typedef struct _GRand GRand; 77 78-- The GRand struct is an opaque data structure. It should only be accessed through 79-- the g_rand_* functions. 80 81-- --------------------------------------------------------------------------------- 82 83-- g_rand_new_with_seed () 84 85-- GRand* g_rand_new_with_seed (guint32 seed); 86 87-- Creates a new random number generator initialized with seed. 88 89-- seed : a value to initialize the random number generator. 90-- Returns : the new GRand. 91 92-- --------------------------------------------------------------------------------- 93 94-- g_rand_new_with_seed_array () 95 96-- GRand* g_rand_new_with_seed_array (const guint32 *seed, 97-- guint seed_length); 98 99-- Creates a new random number generator initialized with seed. 100 101-- seed : an array of seeds to initialize the random number generator. 102-- seed_length : an array of seeds to initialize the random number generator. 103-- Returns : the new GRand. 104 105-- Since 2.4 106 107-- --------------------------------------------------------------------------------- 108 109-- g_rand_new () 110 111-- GRand* g_rand_new (void); 112 113-- Creates a new random number generator initialized with a seed taken either from 114-- /dev/urandom (if existing) or from the current time (as a fallback). 115 116-- Returns : the new GRand. 117 118-- --------------------------------------------------------------------------------- 119 120-- g_rand_copy () 121 122-- GRand* g_rand_copy (GRand *rand_); 123 124-- Copies a GRand into a new one with the same exact state as before. This way you 125-- can take a snapshot of the random number generator for replaying later. 126 127-- rand_ : a GRand. 128-- Returns : the new GRand. 129 130-- Since 2.4 131 132-- --------------------------------------------------------------------------------- 133 134-- g_rand_free () 135 136-- void g_rand_free (GRand *rand_); 137 138-- Frees the memory allocated for the GRand. 139 140-- rand_ : a GRand. 141 142-- --------------------------------------------------------------------------------- 143 144-- g_rand_set_seed () 145 146-- void g_rand_set_seed (GRand *rand_, 147-- guint32 seed); 148 149-- Sets the seed for the random number generator GRand to seed. 150 151-- rand_ : a GRand. 152-- seed : a value to reinitialize the random number generator. 153 154-- --------------------------------------------------------------------------------- 155 156-- g_rand_set_seed_array () 157 158-- void g_rand_set_seed_array (GRand *rand_, 159-- const guint32 *seed, 160-- guint seed_length); 161 162-- Initializes the random number generator by an array of longs. Array can be of 163-- arbitrary size, though only the first 624 values are taken. This function is 164-- useful if you have many low entropy seeds, or if you require more then 32bits of 165-- actual entropy for your application. 166 167-- rand_ : a GRand. 168-- seed : array to initialize with 169-- seed_length : length of array 170 171-- Since 2.4 172 173-- --------------------------------------------------------------------------------- 174 175-- g_rand_boolean() 176 177-- #define g_rand_boolean(rand_) 178 179-- Returns a random gboolean from rand_. This corresponds to a unbiased coin toss. 180 181-- rand_ : a GRand. 182-- Returns : a random gboolean. 183 184-- --------------------------------------------------------------------------------- 185 186-- g_rand_int () 187 188-- guint32 g_rand_int (GRand *rand_); 189 190-- Returns the next random guint32 from rand_ equally distributed over the range 191-- [0..2^32-1]. 192 193-- rand_ : a GRand. 194-- Returns : A random number. 195 196-- --------------------------------------------------------------------------------- 197 198-- g_rand_int_range () 199 200-- gint32 g_rand_int_range (GRand *rand_, 201-- gint32 begin, 202-- gint32 end); 203 204-- Returns the next random gint32 from rand_ equally distributed over the range 205-- [begin..end-1]. 206 207-- rand_ : a GRand. 208-- begin : lower closed bound of the interval. 209-- end : upper open bound of the interval. 210-- Returns : A random number. 211 212-- --------------------------------------------------------------------------------- 213 214-- g_rand_double () 215 216-- gdouble g_rand_double (GRand *rand_); 217 218-- Returns the next random gdouble from rand_ equally distributed over the range 219-- [0..1). 220 221-- rand_ : a GRand. 222-- Returns : A random number. 223 224-- --------------------------------------------------------------------------------- 225 226-- g_rand_double_range () 227 228-- gdouble g_rand_double_range (GRand *rand_, 229-- gdouble begin, 230-- gdouble end); 231 232-- Returns the next random gdouble from rand_ equally distributed over the range 233-- [begin..end). 234 235-- rand_ : a GRand. 236-- begin : lower closed bound of the interval. 237-- end : upper open bound of the interval. 238-- Returns : A random number. 239 240-- --------------------------------------------------------------------------------- 241 242-- g_random_set_seed () 243 244-- void g_random_set_seed (guint32 seed); 245 246-- Sets the seed for the global random number generator, which is used by the 247-- g_random_* functions, to seed. 248 249-- seed : a value to reinitialize the global random number generator. 250 251-- --------------------------------------------------------------------------------- 252 253-- g_random_boolean() 254 255-- #define g_random_boolean() 256 257-- Returns a random gboolean. This corresponds to a unbiased coin toss. 258 259-- Returns : a random gboolean. 260 261-- --------------------------------------------------------------------------------- 262 263-- g_random_int () 264 265-- guint32 g_random_int (void); 266 267-- Return a random guint32 equally distributed over the range [0..2^32-1]. 268 269-- Returns : A random number. 270 271-- --------------------------------------------------------------------------------- 272 273-- g_random_int_range () 274 275-- gint32 g_random_int_range (gint32 begin, 276-- gint32 end); 277 278-- Returns a random gint32 equally distributed over the range [begin..end-1]. 279 280-- begin : lower closed bound of the interval. 281-- end : upper open bound of the interval. 282-- Returns : A random number. 283 284-- --------------------------------------------------------------------------------- 285 286-- g_random_double () 287 288-- gdouble g_random_double (void); 289 290-- Returns a random gdouble equally distributed over the range [0..1). 291 292-- Returns : A random number. 293 294-- --------------------------------------------------------------------------------- 295 296-- g_random_double_range () 297 298-- gdouble g_random_double_range (gdouble begin, 299-- gdouble end); 300 301-- Returns a random gdouble equally distributed over the range [begin..end). 302 303-- begin : lower closed bound of the interval. 304-- end : upper open bound of the interval. 305-- Returns : A random number. 306end -- class GLIB_RANDOM_NUMBERS