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.
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.
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.
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.
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.
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.
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.
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.
+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
G_STMT_END
<SUBSECTION>
+G_BEGIN_DECLS
+G_END_DECLS
+
+<SUBSECTION>
G_N_ELEMENTS
<SUBSECTION>
G_GNUC_CONST
G_GNUC_NORETURN
G_GNUC_UNUSED
+G_GNUC_PURE
G_GNUC_PRINTF
G_GNUC_SCANF
G_GNUC_FORMAT
<SUBSECTION Private>
GLIB_HAVE_SYS_POLL_H
+GLIB_HAVE_ALLOCA_H
+alloca
GLIB_SYSDEF_POLLERR
GLIB_SYSDEF_POLLHUP
GLIB_SYSDEF_POLLIN
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
g_free
<SUBSECTION>
+g_alloca
+
+<SUBSECTION>
g_memmove
g_memdup
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>
-<!-- ##### STRUCT GRand ##### -->
<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>
-
-<!-- ##### FUNCTION g_rand_new_with_seed ##### -->
<para>
-
+A random binary decision is best implemented by using
+<literal>if(g_random_int()&(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>
-@seed:
-@Returns:
-
-
-<!-- ##### FUNCTION g_rand_new ##### -->
+<!-- ##### STRUCT GRand ##### -->
<para>
-
+The #GRand struct is an opaque data structure. It should only be
+accessed through the g_rand_* functions.
</para>
-@Returns:
-
-
+<!-- ##### FUNCTION g_rand_new_with_seed ##### -->
+<!-- ##### FUNCTION g_rand_new ##### -->
<!-- ##### 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:
-
-
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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
/* 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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
/* 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)
{
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)
{
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)
{
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)
{
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)
{
projects / platform / upstream / glib.git / commitdiff