PageRenderTime 20ms CodeModel.GetById 11ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/glib/library/utilities/glib_random_numbers.e

http://github.com/tybor/Liberty
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