From: Sebastian Wilhelmi Date: Fri, 13 Oct 2000 13:52:47 +0000 (+0000) Subject: Added inline documentation. X-Git-Tag: GLIB_1_3_2~80 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=eb27cad0f0495e9e74f06650eb40448f196e2b7b;p=platform%2Fupstream%2Fglib.git Added inline documentation. 2000-10-13 Sebastian Wilhelmi * 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. --- diff --git a/ChangeLog b/ChangeLog index 5e82e1e..89f2f73 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,7 @@ 2000-10-13 Sebastian Wilhelmi + * 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. diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 5e82e1e..89f2f73 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,5 +1,7 @@ 2000-10-13 Sebastian Wilhelmi + * 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. diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 5e82e1e..89f2f73 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,5 +1,7 @@ 2000-10-13 Sebastian Wilhelmi + * 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. diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 5e82e1e..89f2f73 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,5 +1,7 @@ 2000-10-13 Sebastian Wilhelmi + * 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. diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 5e82e1e..89f2f73 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,5 +1,7 @@ 2000-10-13 Sebastian Wilhelmi + * 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. diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 5e82e1e..89f2f73 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,5 +1,7 @@ 2000-10-13 Sebastian Wilhelmi + * 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. diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 5e82e1e..89f2f73 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,5 +1,7 @@ 2000-10-13 Sebastian Wilhelmi + * 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. diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 5e82e1e..89f2f73 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,5 +1,7 @@ 2000-10-13 Sebastian Wilhelmi + * 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. diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 782ac6d..4f4e277 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,10 @@ +2000-10-13 Sebastian Wilhelmi + + * glib/glib-sections.txt: Added misc items. + + * glib/tmpl/random_numbers.sgml: Documentation for the random + number generator. + 2000-10-09 Raja R Harinath * gobject/Makefile.am (DOC_SOURCE_DIR): Don't set to diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index 06a630e..763ad51 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -256,6 +256,10 @@ G_STMT_START G_STMT_END +G_BEGIN_DECLS +G_END_DECLS + + 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 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 +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 @@ -576,6 +589,9 @@ g_realloc g_free +g_alloca + + g_memmove g_memdup diff --git a/docs/reference/glib/tmpl/random_numbers.sgml b/docs/reference/glib/tmpl/random_numbers.sgml index 037992c..6b9c8fc 100644 --- a/docs/reference/glib/tmpl/random_numbers.sgml +++ b/docs/reference/glib/tmpl/random_numbers.sgml @@ -2,139 +2,60 @@ Random Numbers - +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 www.math.keio.ac.jp/~matumoto/emt.html. - - +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. - - +The g_rand*_range functions will return high quality equally +distributed random numbers, whereas for example the +(g_random_int()%%max) approach often doesn't +yield equally distributed numbers. - - - +A random binary decision is best implemented by using +if(g_random_int()&(1<<@a)), 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. -@seed: -@Returns: - - - + - +The #GRand struct is an opaque data structure. It should only be +accessed through the g_rand_* functions. -@Returns: - - + + - - - - -@rand: - - - - - - -@rand: -@seed: - - - - - - -@rand: -@Returns: - - - - - - -@rand: -@min: -@max: -@Returns: - - - - - - -@rand: -@Returns: - - - - - - -@rand: -@min: -@max: -@Returns: - - - - - - -@seed: - - - - - - -@Returns: - - - - - - -@min: -@max: -@Returns: - - - - - - -@Returns: - - - - - - -@min: -@max: -@Returns: - - diff --git a/glib/grand.c b/glib/grand.c index 95c95a8..b62257e 100644 --- a/glib/grand.c +++ b/glib/grand.c @@ -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) { diff --git a/grand.c b/grand.c index 95c95a8..b62257e 100644 --- a/grand.c +++ b/grand.c @@ -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) {