docs/reference/glib/tmpl/random_numbers.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Random Numbers
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 pseudo-random number generator.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The following functions allow you to use a portable, fast and good
  10 pseudo-random number generator (PRNG). It uses the Mersenne Twister
  11 PRNG, which was originally developed by Makoto Matsumoto and Takuji
  12 Nishimura. Further information can be found at <ulink
  13 url="http://www.math.keio.ac.jp/~matumoto/emt.html"
  14 >www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
  15 </para>
  16
  17 <para>
  18 If you just need a random number, you simply call the
  19 <function>g_random_*</function> functions, which will create a globally
  20 used #GRand and use the according <function>g_rand_*</function> functions
  21 internally. Whenever you need a stream of reproducible random numbers, you
  22 better create a #GRand yourself and use the <function>g_rand_*</function>
  23 functions directly, which will also be slightly faster. Initializing a #GRand
  24 with a certain seed will produce exactly the same series of random numbers
  25 on all platforms. This can thus be used as a seed for e.g. games.
  26 </para>
  27
  28 <para>
  29 The <function>g_rand*_range</function> functions will return high quality
  30 equally distributed random numbers, whereas for example the
  31 <literal>(g_random_int()&percnt;max)</literal> approach often doesn't
  32 yield equally distributed numbers.
  33 </para>
  34
  35 <para>
  36 GLib changed the seeding algorithm for the pseudo-random number
  37 generator Mersenne Twister, as used by <structname>GRand</structname>
  38 and <structname>GRandom</structname>. This was necessary, because some
  39 seeds would yield very bad pseudo-random streams.  Also the
  40 pseudo-random integers generated by
  41 <function>g_rand*_int_range()</function> will have a
  42 slightly better equal distribution with the new version of GLib.
  43 </para>
  44
  45 <para>
  46 The original seeding and generation algorithms, as found in GLib 2.0.x,
  47 can be used instead of the new ones by setting the environment variable
  48 <envar>G_RANDOM_VERSION</envar> to the value of '2.0'. Use the
  49 GLib-2.0 algorithms only if you have sequences of numbers generated
  50 with Glib-2.0 that you need to reproduce exactly.
  51 </para>
  52
  53 <!-- ##### SECTION See_Also ##### -->
  54 <para>
  55
  56 </para>
  57
  58 <!-- ##### SECTION Stability_Level ##### -->
  59
  60
  61 <!-- ##### STRUCT GRand ##### -->
  62 <para>
  63 The #GRand struct is an opaque data structure. It should only be
  64 accessed through the <function>g_rand_*</function> functions.
  65 </para>
  66
  67
  68 <!-- ##### FUNCTION g_rand_new_with_seed ##### -->
  69
  70
  71 @seed:
  72 @Returns:
  73
  74
  75 <!-- ##### FUNCTION g_rand_new_with_seed_array ##### -->
  76 <para>
  77
  78 </para>
  79
  80 @seed:
  81 @seed_length:
  82 @Returns:
  83
  84
  85 <!-- ##### FUNCTION g_rand_new ##### -->
  86
  87
  88 @Returns:
  89
  90
  91 <!-- ##### FUNCTION g_rand_copy ##### -->
  92 <para>
  93
  94 </para>
  95
  96 @rand_:
  97 @Returns:
  98
  99
 100 <!-- ##### FUNCTION g_rand_free ##### -->
 101
 102
 103 @rand_:
 104
 105
 106 <!-- ##### FUNCTION g_rand_set_seed ##### -->
 107
 108
 109 @rand_:
 110 @seed:
 111
 112
 113 <!-- ##### FUNCTION g_rand_set_seed_array ##### -->
 114 <para>
 115
 116 </para>
 117
 118 @rand_:
 119 @seed:
 120 @seed_length:
 121
 122
 123 <!-- ##### MACRO g_rand_boolean ##### -->
 124 <para>
 125 Returns a random #gboolean from @rand_. This corresponds to a unbiased
 126 coin toss.
 127 </para>
 128
 129 @rand_: a #GRand.
 130 @Returns: a random #gboolean.
 131
 132
 133 <!-- ##### FUNCTION g_rand_int ##### -->
 134
 135
 136 @rand_:
 137 @Returns:
 138
 139
 140 <!-- ##### FUNCTION g_rand_int_range ##### -->
 141
 142
 143 @rand_:
 144 @begin:
 145 @end:
 146 @Returns:
 147
 148
 149 <!-- ##### FUNCTION g_rand_double ##### -->
 150
 151
 152 @rand_:
 153 @Returns:
 154
 155
 156 <!-- ##### FUNCTION g_rand_double_range ##### -->
 157
 158
 159 @rand_:
 160 @begin:
 161 @end:
 162 @Returns:
 163
 164
 165 <!-- ##### FUNCTION g_random_set_seed ##### -->
 166
 167
 168 @seed:
 169
 170
 171 <!-- ##### MACRO g_random_boolean ##### -->
 172 <para>
 173 Returns a random #gboolean. This corresponds to a unbiased coin toss.
 174 </para>
 175
 176 @Returns: a random #gboolean.
 177
 178
 179 <!-- ##### FUNCTION g_random_int ##### -->
 180
 181
 182 @Returns:
 183
 184
 185 <!-- ##### FUNCTION g_random_int_range ##### -->
 186
 187
 188 @begin:
 189 @end:
 190 @Returns:
 191
 192
 193 <!-- ##### FUNCTION g_random_double ##### -->
 194
 195
 196 @Returns:
 197
 198
 199 <!-- ##### FUNCTION g_random_double_range ##### -->
 200
 201
 202 @begin:
 203 @end:
 204 @Returns:
 205
 206