mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-26 15:36:14 +01:00
GRand: move docs from tmpl to inline comments
This commit is contained in:
Ryan Lortie
parent
3de141b8d5
commit
d51b6c471a
1
docs/reference/glib/tmpl/.gitignore
vendored
1
docs/reference/glib/tmpl/.gitignore
vendored
@ -4,3 +4,4 @@ gurifuncs.sgml
|
||||
gvarianttype.sgml
|
||||
hash_tables.sgml
|
||||
option.sgml
|
||||
random_numbers.sgml
|
||||
|
||||
@ -1,206 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
Random Numbers
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
pseudo-random number generator
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
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 <ulink
|
||||
url="http://www.math.keio.ac.jp/~matumoto/emt.html"
|
||||
>www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you just need a random number, you simply call the
|
||||
<function>g_random_*</function> functions, which will create a globally
|
||||
used #GRand and use the according <function>g_rand_*</function> functions
|
||||
internally. Whenever you need a stream of reproducible random numbers, you
|
||||
better create a #GRand yourself and use the <function>g_rand_*</function>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <function>g_rand*_range</function> functions will return high quality
|
||||
equally distributed random numbers, whereas for example the
|
||||
<literal>(g_random_int()%max)</literal> approach often doesn't
|
||||
yield equally distributed numbers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
GLib changed the seeding algorithm for the pseudo-random number
|
||||
generator Mersenne Twister, as used by <structname>GRand</structname>
|
||||
and <structname>GRandom</structname>. This was necessary, because some
|
||||
seeds would yield very bad pseudo-random streams. Also the
|
||||
pseudo-random integers generated by
|
||||
<function>g_rand*_int_range()</function> will have a
|
||||
slightly better equal distribution with the new version of GLib.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The original seeding and generation algorithms, as found in GLib 2.0.x,
|
||||
can be used instead of the new ones by setting the environment variable
|
||||
<envar>G_RANDOM_VERSION</envar> to the value of '2.0'. Use the
|
||||
GLib-2.0 algorithms only if you have sequences of numbers generated
|
||||
with Glib-2.0 that you need to reproduce exactly.
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### STRUCT GRand ##### -->
|
||||
<para>
|
||||
The #GRand struct is an opaque data structure. It should only be
|
||||
accessed through the <function>g_rand_*</function> functions.
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_new_with_seed ##### -->
|
||||
|
||||
|
||||
@seed:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_new_with_seed_array ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@seed:
|
||||
@seed_length:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_new ##### -->
|
||||
|
||||
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_copy ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@rand_:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_free ##### -->
|
||||
|
||||
|
||||
@rand_:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_set_seed ##### -->
|
||||
|
||||
|
||||
@rand_:
|
||||
@seed:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_set_seed_array ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@rand_:
|
||||
@seed:
|
||||
@seed_length:
|
||||
|
||||
|
||||
<!-- ##### MACRO g_rand_boolean ##### -->
|
||||
<para>
|
||||
Returns a random #gboolean from @rand_. This corresponds to a unbiased
|
||||
coin toss.
|
||||
</para>
|
||||
|
||||
@rand_: a #GRand.
|
||||
@Returns: a random #gboolean.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_int ##### -->
|
||||
|
||||
|
||||
@rand_:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_int_range ##### -->
|
||||
|
||||
|
||||
@rand_:
|
||||
@begin:
|
||||
@end:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_double ##### -->
|
||||
|
||||
|
||||
@rand_:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_rand_double_range ##### -->
|
||||
|
||||
|
||||
@rand_:
|
||||
@begin:
|
||||
@end:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_random_set_seed ##### -->
|
||||
|
||||
|
||||
@seed:
|
||||
|
||||
|
||||
<!-- ##### MACRO g_random_boolean ##### -->
|
||||
<para>
|
||||
Returns a random #gboolean. This corresponds to a unbiased coin toss.
|
||||
</para>
|
||||
|
||||
@Returns: a random #gboolean.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_random_int ##### -->
|
||||
|
||||
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_random_int_range ##### -->
|
||||
|
||||
|
||||
@begin:
|
||||
@end:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_random_double ##### -->
|
||||
|
||||
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_random_double_range ##### -->
|
||||
|
||||
|
||||
@begin:
|
||||
@end:
|
||||
@Returns:
|
||||
|
||||
|
||||
64
glib/grand.c
64
glib/grand.c
@ -55,6 +55,56 @@
|
||||
#include <process.h> /* For getpid() */
|
||||
#endif
|
||||
|
||||
/**
|
||||
* SECTION: random_numbers
|
||||
* @title: Random Numbers
|
||||
* @short_description: pseudo-random number generator
|
||||
*
|
||||
* 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
|
||||
* <ulink url="http://www.math.keio.ac.jp/~matumoto/emt.html">
|
||||
* www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
|
||||
*
|
||||
* If you just need a random number, you simply call the
|
||||
* <function>g_random_*</function> functions, which will create a
|
||||
* globally used #GRand and use the according
|
||||
* <function>g_rand_*</function> functions internally. Whenever you
|
||||
* need a stream of reproducible random numbers, you better create a
|
||||
* #GRand yourself and use the <function>g_rand_*</function> 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 <function>g_rand*_range</function> functions will return high
|
||||
* quality equally distributed random numbers, whereas for example the
|
||||
* <literal>(g_random_int()%max)</literal> approach often
|
||||
* doesn't yield equally distributed numbers.
|
||||
*
|
||||
* GLib changed the seeding algorithm for the pseudo-random number
|
||||
* generator Mersenne Twister, as used by
|
||||
* <structname>GRand</structname> and <structname>GRandom</structname>.
|
||||
* This was necessary, because some seeds would yield very bad
|
||||
* pseudo-random streams. Also the pseudo-random integers generated by
|
||||
* <function>g_rand*_int_range()</function> will have a slightly better
|
||||
* equal distribution with the new version of GLib.
|
||||
*
|
||||
* The original seeding and generation algorithms, as found in GLib
|
||||
* 2.0.x, can be used instead of the new ones by setting the
|
||||
* environment variable <envar>G_RANDOM_VERSION</envar> to the value of
|
||||
* '2.0'. Use the GLib-2.0 algorithms only if you have sequences of
|
||||
* numbers generated with Glib-2.0 that you need to reproduce exactly.
|
||||
**/
|
||||
|
||||
/**
|
||||
* GRand:
|
||||
*
|
||||
* The #GRand struct is an opaque data structure. It should only be
|
||||
* accessed through the <function>g_rand_*</function> functions.
|
||||
**/
|
||||
|
||||
G_LOCK_DEFINE_STATIC (global_random);
|
||||
static GRand* global_random = NULL;
|
||||
|
||||
@ -357,6 +407,14 @@ g_rand_set_seed_array (GRand* rand, const guint32 *seed, guint seed_length)
|
||||
rand->mt[0] = 0x80000000UL; /* MSB is 1; assuring non-zero initial array */
|
||||
}
|
||||
|
||||
/**
|
||||
* g_rand_boolean:
|
||||
* @rand_: a #GRand.
|
||||
* @Returns: a random #gboolean.
|
||||
*
|
||||
* Returns a random #gboolean from @rand_. This corresponds to a
|
||||
* unbiased coin toss.
|
||||
**/
|
||||
/**
|
||||
* g_rand_int:
|
||||
* @rand_: a #GRand.
|
||||
@ -527,6 +585,12 @@ g_rand_double_range (GRand* rand, gdouble begin, gdouble end)
|
||||
return g_rand_double (rand) * (end - begin) + begin;
|
||||
}
|
||||
|
||||
/**
|
||||
* g_random_boolean:
|
||||
* @Returns: a random #gboolean.
|
||||
*
|
||||
* Returns a random #gboolean. This corresponds to a unbiased coin toss.
|
||||
**/
|
||||
/**
|
||||
* g_random_int:
|
||||
*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user