luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-26 15:36:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

GRand: move docs from tmpl to inline comments

Browse Source
This commit is contained in:
Ryan Lortie 2010-01-30 01:00:50 -05:00
parent 3de141b8d5
commit d51b6c471a
3 changed files with 65 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -4,3 +4,4 @@ gurifuncs.sgml
gvarianttype.sgml gvarianttype.sgml
hash_tables.sgml hash_tables.sgml
option.sgml option.sgml
random_numbers.sgml

206
docs/reference/glib/tmpl/random_numbers.sgml
View File

@ -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()&percnt;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
View File

@ -55,6 +55,56 @@
#include <process.h> /* For getpid() */ #include <process.h> /* For getpid() */
#endif #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()&percnt;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); G_LOCK_DEFINE_STATIC (global_random);
static GRand* global_random = NULL; 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 */ 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: * g_rand_int:
* @rand_: a #GRand. * @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; 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: * g_random_int:
* *