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 <funcion>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()%%max)</literal> approach often doesn't
  32 yield equally distributed numbers.
  33 </para>
  34
  35 <!-- ##### SECTION See_Also ##### -->
  36 <para>
  37
  38 </para>
  39
  40 <!-- ##### STRUCT GRand ##### -->
  41 <para>
  42 The #GRand struct is an opaque data structure. It should only be
  43 accessed through the <function>g_rand_*</function> functions.
  44 </para>
  45
  46
  47 <!-- ##### FUNCTION g_rand_new_with_seed ##### -->
  48
  49
  50 @seed:
  51 @Returns:
  52
  53
  54 <!-- ##### FUNCTION g_rand_new ##### -->
  55
  56
  57 @Returns:
  58
  59
  60 <!-- ##### FUNCTION g_rand_free ##### -->
  61
  62
  63 @rand:
  64
  65
  66 <!-- ##### FUNCTION g_rand_set_seed ##### -->
  67
  68
  69 @rand:
  70 @seed:
  71
  72
  73 <!-- ##### MACRO g_rand_boolean ##### -->
  74 <para>
  75 Returns a random #gboolean from @rand. This corresponds to a unbiased
  76 coin toss.
  77 </para>
  78
  79 @rand: a #GRand.
  80 @Returns: a random #gboolean.
  81
  82
  83 <!-- ##### FUNCTION g_rand_int ##### -->
  84
  85
  86 @rand:
  87 @Returns:
  88
  89
  90 <!-- ##### FUNCTION g_rand_int_range ##### -->
  91
  92
  93 @rand:
  94 @begin:
  95 @end:
  96 @Returns:
  97
  98
  99 <!-- ##### FUNCTION g_rand_double ##### -->
 100
 101
 102 @rand:
 103 @Returns:
 104
 105
 106 <!-- ##### FUNCTION g_rand_double_range ##### -->
 107
 108
 109 @rand:
 110 @begin:
 111 @end:
 112 @Returns:
 113
 114
 115 <!-- ##### FUNCTION g_random_set_seed ##### -->
 116
 117
 118 @seed:
 119
 120
 121 <!-- ##### MACRO g_random_boolean ##### -->
 122 <para>
 123 Returns a random #gboolean. This corresponds to a unbiased coin toss.
 124 </para>
 125
 126 @Returns: a random #gboolean.
 127
 128
 129 <!-- ##### FUNCTION g_random_int ##### -->
 130
 131
 132 @Returns:
 133
 134
 135 <!-- ##### FUNCTION g_random_int_range ##### -->
 136
 137
 138 @begin:
 139 @end:
 140 @Returns:
 141
 142
 143 <!-- ##### FUNCTION g_random_double ##### -->
 144
 145
 146 @Returns:
 147
 148
 149 <!-- ##### FUNCTION g_random_double_range ##### -->
 150
 151
 152 @begin:
 153 @end:
 154 @Returns:
 155
 156