Added inline documentation.

2000-10-13  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>

	* grand.c: Added inline documentation.

	* docs/refernce/glib/glib-sections.txt: Added misc items.

	* docs/refernce/glib/tmpl/random_numbers.sgml: Documentation for
        the random number generator.
This commit is contained in:
Sebastian Wilhelmi 2000-10-13 13:52:47 +00:00 committed by Sebastian Wilhelmi
parent 24b4bfbea1
commit eb27cad0f0
13 changed files with 292 additions and 110 deletions

View File

@ -1,5 +1,7 @@
2000-10-13 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
* grand.c: Added inline documentation.
* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
g_node_insert_after and g_find_program_in_path resp., which
mysteriously disappeared during the glib.h dissection.

View File

@ -1,5 +1,7 @@
2000-10-13 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
* grand.c: Added inline documentation.
* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
g_node_insert_after and g_find_program_in_path resp., which
mysteriously disappeared during the glib.h dissection.

View File

@ -1,5 +1,7 @@
2000-10-13 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
* grand.c: Added inline documentation.
* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
g_node_insert_after and g_find_program_in_path resp., which
mysteriously disappeared during the glib.h dissection.

View File

@ -1,5 +1,7 @@
2000-10-13 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
* grand.c: Added inline documentation.
* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
g_node_insert_after and g_find_program_in_path resp., which
mysteriously disappeared during the glib.h dissection.

View File

@ -1,5 +1,7 @@
2000-10-13 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
* grand.c: Added inline documentation.
* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
g_node_insert_after and g_find_program_in_path resp., which
mysteriously disappeared during the glib.h dissection.

View File

@ -1,5 +1,7 @@
2000-10-13 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
* grand.c: Added inline documentation.
* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
g_node_insert_after and g_find_program_in_path resp., which
mysteriously disappeared during the glib.h dissection.

View File

@ -1,5 +1,7 @@
2000-10-13 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
* grand.c: Added inline documentation.
* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
g_node_insert_after and g_find_program_in_path resp., which
mysteriously disappeared during the glib.h dissection.

View File

@ -1,5 +1,7 @@
2000-10-13 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
* grand.c: Added inline documentation.
* gtypes.h, gnode.h, gutils.h: Readded GFreeFunc,
g_node_insert_after and g_find_program_in_path resp., which
mysteriously disappeared during the glib.h dissection.

View File

@ -1,3 +1,10 @@
2000-10-13 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
* glib/glib-sections.txt: Added misc items.
* glib/tmpl/random_numbers.sgml: Documentation for the random
number generator.
2000-10-09 Raja R Harinath <harinath@cs.umn.edu>
* gobject/Makefile.am (DOC_SOURCE_DIR): Don't set to

View File

@ -255,6 +255,10 @@ G_INLINE_FUNC
G_STMT_START
G_STMT_END
<SUBSECTION>
G_BEGIN_DECLS
G_END_DECLS
<SUBSECTION>
G_N_ELEMENTS
@ -269,6 +273,7 @@ G_GNUC_EXTENSION
G_GNUC_CONST
G_GNUC_NORETURN
G_GNUC_UNUSED
G_GNUC_PURE
G_GNUC_PRINTF
G_GNUC_SCANF
G_GNUC_FORMAT
@ -359,6 +364,8 @@ g_source_remove_by_user_data
<SUBSECTION Private>
GLIB_HAVE_SYS_POLL_H
GLIB_HAVE_ALLOCA_H
alloca
GLIB_SYSDEF_POLLERR
GLIB_SYSDEF_POLLHUP
GLIB_SYSDEF_POLLIN
@ -466,9 +473,15 @@ g_static_private_set
g_static_private_set_for_thread
<SUBSECTION Private>
G_THREAD_ECF
G_THREAD_CF
G_THREAD_UF
g_static_mutex_get_mutex_impl
g_mutex_lock_with_debug_name
g_mutex_trylock_with_debug_name
g_mutex_unlock_with_debug_name
G_MUTEX_DEBUG_MAGIC
g_thread_init_with_errorcheck_mutexes
G_LOCK_NAME
glib_dummy_decl
GSystemThread
@ -575,6 +588,9 @@ g_realloc
<SUBSECTION>
g_free
<SUBSECTION>
g_alloca
<SUBSECTION>
g_memmove
g_memdup

View File

@ -2,139 +2,60 @@
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>
<!-- ##### SECTION See_Also ##### -->
<para>
If you just need a random number, you simply call the g_random_*
functions, which will create a globally used #GRand and use the
according g_rand_* function internally. Whenever you need a stream of
reproducible random numbers, you better create a #GRand yourself and
use the g_rand_* 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 g_rand*_range 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>
A random binary decision is best implemented by using
<literal>if(g_random_int()&amp;(1<<@a))</literal>, where @a can be every
integer constant from 0 to 31. The Mersenne Twister PRNG is said to
produce highly random lower bits too, but it is common not to rely on
that, so choosing @a to be from 4 to 31 might be wise.
</para>
<!-- ##### STRUCT GRand ##### -->
<para>
The #GRand struct is an opaque data structure. It should only be
accessed through the g_rand_* functions.
</para>
<!-- ##### FUNCTION g_rand_new_with_seed ##### -->
<para>
</para>
@seed:
@Returns:
<!-- ##### FUNCTION g_rand_new ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION g_rand_free ##### -->
<para>
</para>
@rand:
<!-- ##### FUNCTION g_rand_set_seed ##### -->
<para>
</para>
@rand:
@seed:
<!-- ##### FUNCTION g_rand_int ##### -->
<para>
</para>
@rand:
@Returns:
<!-- ##### FUNCTION g_rand_int_range ##### -->
<para>
</para>
@rand:
@min:
@max:
@Returns:
<!-- ##### FUNCTION g_rand_double ##### -->
<para>
</para>
@rand:
@Returns:
<!-- ##### FUNCTION g_rand_double_range ##### -->
<para>
</para>
@rand:
@min:
@max:
@Returns:
<!-- ##### FUNCTION g_random_set_seed ##### -->
<para>
</para>
@seed:
<!-- ##### FUNCTION g_random_int ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION g_random_int_range ##### -->
<para>
</para>
@min:
@max:
@Returns:
<!-- ##### FUNCTION g_random_double ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION g_random_double_range ##### -->
<para>
</para>
@min:
@max:
@Returns:

View File

@ -64,6 +64,14 @@ struct _GRand
guint mti;
};
/**
* g_rand_new_with_seed:
* @seed: a value to initialize the random number generator.
*
* Creates a new random number generator initialized with @seed.
*
* Return value: the new #GRand.
**/
GRand*
g_rand_new_with_seed (guint32 seed)
{
@ -72,6 +80,15 @@ g_rand_new_with_seed (guint32 seed)
return rand;
}
/**
* g_rand_new:
*
* Creates a new random number generator initialized with a seed taken
* either from /dev/urandom (if existing) or from the current time (as
* a fallback).
*
* Return value: the new #GRand.
**/
GRand*
g_rand_new (void)
{
@ -100,6 +117,12 @@ g_rand_new (void)
return g_rand_new_with_seed (seed);
}
/**
* g_rand_free:
* @rand: a #GRand.
*
* Frees the memory allocated for the #GRand.
**/
void
g_rand_free (GRand* rand)
{
@ -108,6 +131,13 @@ g_rand_free (GRand* rand)
g_free (rand);
}
/**
* g_rand_set_seed:
* @rand: a #GRand.
* @seed: a value to reinitialize the random number generator.
*
* Sets the seed for the random number generator #GRand to @seed.
**/
void
g_rand_set_seed (GRand* rand, guint32 seed)
{
@ -126,6 +156,15 @@ g_rand_set_seed (GRand* rand, guint32 seed)
rand->mt[rand->mti] = (69069 * rand->mt[rand->mti-1]) & 0xffffffff;
}
/**
* g_rand_int:
* @rand: a #GRand.
*
* Return the next random #guint32 from @rand equaly distributed over
* the range [0..2^32-1].
*
* Return value: A random number.
**/
guint32
g_rand_int (GRand* rand)
{
@ -161,6 +200,17 @@ g_rand_int (GRand* rand)
return y;
}
/**
* g_rand_int_range:
* @rand: a #GRand.
* @min: lower closed bound of the interval.
* @max: upper open bound of the interval.
*
* Return the next random #gint32 from @rand equaly distributed over
* the range [@min..@max-1].
*
* Return value: A random number.
**/
gint32
g_rand_int_range (GRand* rand, gint32 min, gint32 max)
{
@ -215,18 +265,46 @@ g_rand_int_range (GRand* rand, gint32 min, gint32 max)
/* transform [0..2^32-1] -> [0..1) */
#define G_RAND_DOUBLE_TRANSFORM 2.3283064365386963e-10
/**
* g_rand_double:
* @rand: a #GRand.
*
* Return the next random #gdouble from @rand equaly distributed over
* the range [0..1).
*
* Return value: A random number.
**/
gdouble
g_rand_double (GRand* rand)
{
return g_rand_int (rand) * G_RAND_DOUBLE_TRANSFORM;
}
/**
* g_rand_double_range:
* @rand: a #GRand.
* @min: lower closed bound of the interval.
* @max: upper open bound of the interval.
*
* Return the next random #gdouble from @rand equaly distributed over
* the range [@min..@max).
*
* Return value: A random number.
**/
gdouble
g_rand_double_range (GRand* rand, gdouble min, gdouble max)
{
return g_rand_int (rand) * ((max - min) * G_RAND_DOUBLE_TRANSFORM) + min;
}
/**
* g_random_int:
*
* Return a random #guint32 equaly distributed over the range
* [0..2^32-1].
*
* Return value: A random number.
**/
guint32
g_random_int (void)
{
@ -240,6 +318,16 @@ g_random_int (void)
return result;
}
/**
* g_random_int_range:
* @min: lower closed bound of the interval.
* @max: upper open bound of the interval.
*
* Return a random #gint32 equaly distributed over the range
* [@min..@max-1].
*
* Return value: A random number.
**/
gint32
g_random_int_range (gint32 min, gint32 max)
{
@ -253,6 +341,13 @@ g_random_int_range (gint32 min, gint32 max)
return result;
}
/**
* g_random_double:
*
* Return a random #gdouble equaly distributed over the range [0..1).
*
* Return value: A random number.
**/
gdouble
g_random_double (void)
{
@ -266,6 +361,15 @@ g_random_double (void)
return result;
}
/**
* g_random_double_range:
* @min: lower closed bound of the interval.
* @max: upper open bound of the interval.
*
* Return a random #gdouble equaly distributed over the range [@min..@max).
*
* Return value: A random number.
**/
gdouble
g_random_double_range (gdouble min, gdouble max)
{
@ -279,6 +383,13 @@ g_random_double_range (gdouble min, gdouble max)
return result;
}
/**
* g_random_set_seed:
* @seed: a value to reinitialize the global random number generator.
*
* Sets the seed for the global random number generator, which is used
* by te g_random_* functions, to @seed.
**/
void
g_random_set_seed (guint32 seed)
{

111
grand.c
View File

@ -64,6 +64,14 @@ struct _GRand
guint mti;
};
/**
* g_rand_new_with_seed:
* @seed: a value to initialize the random number generator.
*
* Creates a new random number generator initialized with @seed.
*
* Return value: the new #GRand.
**/
GRand*
g_rand_new_with_seed (guint32 seed)
{
@ -72,6 +80,15 @@ g_rand_new_with_seed (guint32 seed)
return rand;
}
/**
* g_rand_new:
*
* Creates a new random number generator initialized with a seed taken
* either from /dev/urandom (if existing) or from the current time (as
* a fallback).
*
* Return value: the new #GRand.
**/
GRand*
g_rand_new (void)
{
@ -100,6 +117,12 @@ g_rand_new (void)
return g_rand_new_with_seed (seed);
}
/**
* g_rand_free:
* @rand: a #GRand.
*
* Frees the memory allocated for the #GRand.
**/
void
g_rand_free (GRand* rand)
{
@ -108,6 +131,13 @@ g_rand_free (GRand* rand)
g_free (rand);
}
/**
* g_rand_set_seed:
* @rand: a #GRand.
* @seed: a value to reinitialize the random number generator.
*
* Sets the seed for the random number generator #GRand to @seed.
**/
void
g_rand_set_seed (GRand* rand, guint32 seed)
{
@ -126,6 +156,15 @@ g_rand_set_seed (GRand* rand, guint32 seed)
rand->mt[rand->mti] = (69069 * rand->mt[rand->mti-1]) & 0xffffffff;
}
/**
* g_rand_int:
* @rand: a #GRand.
*
* Return the next random #guint32 from @rand equaly distributed over
* the range [0..2^32-1].
*
* Return value: A random number.
**/
guint32
g_rand_int (GRand* rand)
{
@ -161,6 +200,17 @@ g_rand_int (GRand* rand)
return y;
}
/**
* g_rand_int_range:
* @rand: a #GRand.
* @min: lower closed bound of the interval.
* @max: upper open bound of the interval.
*
* Return the next random #gint32 from @rand equaly distributed over
* the range [@min..@max-1].
*
* Return value: A random number.
**/
gint32
g_rand_int_range (GRand* rand, gint32 min, gint32 max)
{
@ -215,18 +265,46 @@ g_rand_int_range (GRand* rand, gint32 min, gint32 max)
/* transform [0..2^32-1] -> [0..1) */
#define G_RAND_DOUBLE_TRANSFORM 2.3283064365386963e-10
/**
* g_rand_double:
* @rand: a #GRand.
*
* Return the next random #gdouble from @rand equaly distributed over
* the range [0..1).
*
* Return value: A random number.
**/
gdouble
g_rand_double (GRand* rand)
{
return g_rand_int (rand) * G_RAND_DOUBLE_TRANSFORM;
}
/**
* g_rand_double_range:
* @rand: a #GRand.
* @min: lower closed bound of the interval.
* @max: upper open bound of the interval.
*
* Return the next random #gdouble from @rand equaly distributed over
* the range [@min..@max).
*
* Return value: A random number.
**/
gdouble
g_rand_double_range (GRand* rand, gdouble min, gdouble max)
{
return g_rand_int (rand) * ((max - min) * G_RAND_DOUBLE_TRANSFORM) + min;
}
/**
* g_random_int:
*
* Return a random #guint32 equaly distributed over the range
* [0..2^32-1].
*
* Return value: A random number.
**/
guint32
g_random_int (void)
{
@ -240,6 +318,16 @@ g_random_int (void)
return result;
}
/**
* g_random_int_range:
* @min: lower closed bound of the interval.
* @max: upper open bound of the interval.
*
* Return a random #gint32 equaly distributed over the range
* [@min..@max-1].
*
* Return value: A random number.
**/
gint32
g_random_int_range (gint32 min, gint32 max)
{
@ -253,6 +341,13 @@ g_random_int_range (gint32 min, gint32 max)
return result;
}
/**
* g_random_double:
*
* Return a random #gdouble equaly distributed over the range [0..1).
*
* Return value: A random number.
**/
gdouble
g_random_double (void)
{
@ -266,6 +361,15 @@ g_random_double (void)
return result;
}
/**
* g_random_double_range:
* @min: lower closed bound of the interval.
* @max: upper open bound of the interval.
*
* Return a random #gdouble equaly distributed over the range [@min..@max).
*
* Return value: A random number.
**/
gdouble
g_random_double_range (gdouble min, gdouble max)
{
@ -279,6 +383,13 @@ g_random_double_range (gdouble min, gdouble max)
return result;
}
/**
* g_random_set_seed:
* @seed: a value to reinitialize the global random number generator.
*
* Sets the seed for the global random number generator, which is used
* by te g_random_* functions, to @seed.
**/
void
g_random_set_seed (guint32 seed)
{