From 71d842674faf2cd0a2d85808d64132e9aa206fd2 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 1 Feb 2014 20:50:57 -0500 Subject: [PATCH] grand: formatting cleanups --- glib/grand.c | 222 ++++++++++++++++++++++++++++----------------------- 1 file changed, 120 insertions(+), 102 deletions(-) diff --git a/glib/grand.c b/glib/grand.c index 018c620f0..1ca48578d 100644 --- a/glib/grand.c +++ b/glib/grand.c @@ -84,12 +84,13 @@ * * 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_* functions 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. + * according g_rand_* functions 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 @@ -97,23 +98,24 @@ * doesn't yield equally distributed numbers. * * GLib changed the seeding algorithm for the pseudo-random number - * generator Mersenne Twister, as used by #GRand and #GRandom. - * This was necessary, because some seeds would yield very bad - * pseudo-random streams. Also the pseudo-random integers generated - * by g_rand*_int_range() will have a slightly better equal - * distribution with the new version of GLib. + * generator Mersenne Twister, as used by #GRand. This was necessary, + * because some seeds would yield very bad pseudo-random streams. + * Also the pseudo-random integers generated by g_rand*_int_range() + * 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 G_RANDOM_VERSION 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. - **/ + * 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 G_RANDOM_VERSION 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 + * The GRand struct is an opaque data structure. It should only be * accessed through the g_rand_* functions. **/ @@ -168,11 +170,11 @@ struct _GRand /** * g_rand_new_with_seed: - * @seed: a value to initialize the random number generator. + * @seed: a value to initialize the random number generator * * Creates a new random number generator initialized with @seed. * - * Return value: the new #GRand. + * Return value: the new #GRand **/ GRand* g_rand_new_with_seed (guint32 seed) @@ -184,17 +186,19 @@ g_rand_new_with_seed (guint32 seed) /** * g_rand_new_with_seed_array: - * @seed: an array of seeds to initialize the random number generator. - * @seed_length: an array of seeds to initialize the random number generator. + * @seed: an array of seeds to initialize the random number generator + * @seed_length: an array of seeds to initialize the random number + * generator * * Creates a new random number generator initialized with @seed. * - * Return value: the new #GRand. + * Return value: the new #GRand * * Since: 2.4 - **/ + */ GRand* -g_rand_new_with_seed_array (const guint32 *seed, guint seed_length) +g_rand_new_with_seed_array (const guint32 *seed, + guint seed_length) { GRand *rand = g_new0 (GRand, 1); g_rand_set_seed_array (rand, seed, seed_length); @@ -206,11 +210,12 @@ g_rand_new_with_seed_array (const guint32 *seed, guint seed_length) * * 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). On Windows, the seed is taken from - * rand_s(). + * the current time (as a fallback). + * + * On Windows, the seed is taken from rand_s(). * - * Return value: the new #GRand. - **/ + * Return value: the new #GRand + */ GRand* g_rand_new (void) { @@ -270,12 +275,12 @@ g_rand_new (void) /** * g_rand_free: - * @rand_: a #GRand. + * @rand_: a #GRand * * Frees the memory allocated for the #GRand. - **/ + */ void -g_rand_free (GRand* rand) +g_rand_free (GRand *rand) { g_return_if_fail (rand != NULL); @@ -284,18 +289,18 @@ g_rand_free (GRand* rand) /** * g_rand_copy: - * @rand_: a #GRand. + * @rand_: a #GRand * * Copies a #GRand into a new one with the same exact state as before. * This way you can take a snapshot of the random number generator for * replaying later. * - * Return value: the new #GRand. + * Return value: the new #GRand * * Since: 2.4 - **/ -GRand * -g_rand_copy (GRand* rand) + */ +GRand* +g_rand_copy (GRand *rand) { GRand* new_rand; @@ -309,13 +314,14 @@ g_rand_copy (GRand* rand) /** * g_rand_set_seed: - * @rand_: a #GRand. - * @seed: a value to reinitialize the random number generator. + * @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) +g_rand_set_seed (GRand *rand, + guint32 seed) { g_return_if_fail (rand != NULL); @@ -352,20 +358,22 @@ g_rand_set_seed (GRand* rand, guint32 seed) /** * g_rand_set_seed_array: - * @rand_: a #GRand. + * @rand_: a #GRand * @seed: array to initialize with * @seed_length: length of array * * Initializes the random number generator by an array of longs. - * Array can be of arbitrary size, though only the - * first 624 values are taken. This function is useful - * if you have many low entropy seeds, or if you require more then - * 32 bits of actual entropy for your application. + * Array can be of arbitrary size, though only the first 624 values + * are taken. This function is useful if you have many low entropy + * seeds, or if you require more then 32 bits of actual entropy for + * your application. * * Since: 2.4 - **/ + */ void -g_rand_set_seed_array (GRand* rand, const guint32 *seed, guint seed_length) +g_rand_set_seed_array (GRand *rand, + const guint32 *seed, + guint seed_length) { int i, j, k; @@ -410,24 +418,24 @@ g_rand_set_seed_array (GRand* rand, const guint32 *seed, guint seed_length) /** * g_rand_boolean: - * @rand_: a #GRand. + * @rand_: a #GRand * - * Returns a random #gboolean from @rand_. This corresponds to a - * unbiased coin toss. + * Returns a random #gboolean from @rand_. + * This corresponds to a unbiased coin toss. * - * Returns: a random #gboolean. - **/ + * Returns: a random #gboolean + */ /** * g_rand_int: - * @rand_: a #GRand. + * @rand_: a #GRand * * Returns the next random #guint32 from @rand_ equally distributed over * the range [0..2^32-1]. * - * Return value: A random number. - **/ + * Return value: a random number + */ guint32 -g_rand_int (GRand* rand) +g_rand_int (GRand *rand) { guint32 y; static const guint32 mag01[2]={0x0, MATRIX_A}; @@ -438,11 +446,11 @@ g_rand_int (GRand* rand) if (rand->mti >= N) { /* generate N words at one time */ int kk; - for (kk=0;kkmt[kk]&UPPER_MASK)|(rand->mt[kk+1]&LOWER_MASK); rand->mt[kk] = rand->mt[kk+M] ^ (y >> 1) ^ mag01[y & 0x1]; } - for (;kkmt[kk]&UPPER_MASK)|(rand->mt[kk+1]&LOWER_MASK); rand->mt[kk] = rand->mt[kk+(M-N)] ^ (y >> 1) ^ mag01[y & 0x1]; } @@ -466,17 +474,19 @@ g_rand_int (GRand* rand) /** * g_rand_int_range: - * @rand_: a #GRand. - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @rand_: a #GRand + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * * Returns the next random #gint32 from @rand_ equally distributed over * the range [@begin..@end-1]. * - * Return value: A random number. - **/ + * Return value: a random number + */ gint32 -g_rand_int_range (GRand* rand, gint32 begin, gint32 end) +g_rand_int_range (GRand *rand, + gint32 begin, + gint32 end) { guint32 dist = end - begin; guint32 random; @@ -491,9 +501,9 @@ g_rand_int_range (GRand* rand, gint32 begin, gint32 end) { /* This method, which only calls g_rand_int once is only good * for (end - begin) <= 2^16, because we only have 32 bits set - * from the one call to g_rand_int (). */ - - /* we are using (trans + trans * trans), because g_rand_int only + * from the one call to g_rand_int (). + * + * We are using (trans + trans * trans), because g_rand_int only * covers [0..2^32-1] and thus g_rand_int * trans only covers * [0..1-2^-32], but the biggest double < 1 is 1-2^-52. */ @@ -506,9 +516,10 @@ g_rand_int_range (GRand* rand, gint32 begin, gint32 end) } else { - /* Now we use g_rand_double_range (), which will set 52 bits for - us, so that it is safe to round and still get a decent - distribution */ + /* Now we use g_rand_double_range (), which will set 52 bits + * for us, so that it is safe to round and still get a decent + * distribution + */ random = (gint32) g_rand_double_range (rand, 0, dist); } break; @@ -518,7 +529,8 @@ g_rand_int_range (GRand* rand, gint32 begin, gint32 end) else { /* maxvalue is set to the predecessor of the greatest - * multiple of dist less or equal 2^32. */ + * multiple of dist less or equal 2^32. + */ guint32 maxvalue; if (dist <= 0x80000000u) /* 2^31 */ { @@ -547,15 +559,15 @@ g_rand_int_range (GRand* rand, gint32 begin, gint32 end) /** * g_rand_double: - * @rand_: a #GRand. + * @rand_: a #GRand * * Returns the next random #gdouble from @rand_ equally distributed over * the range [0..1). * - * Return value: A random number. - **/ + * Return value: a random number + */ gdouble -g_rand_double (GRand* rand) +g_rand_double (GRand *rand) { /* We set all 52 bits after the point for this, not only the first 32. Thats why we need two calls to g_rand_int */ @@ -572,17 +584,19 @@ g_rand_double (GRand* rand) /** * g_rand_double_range: - * @rand_: a #GRand. - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @rand_: a #GRand + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * * Returns the next random #gdouble from @rand_ equally distributed over * the range [@begin..@end). * - * Return value: A random number. - **/ + * Return value: a random number + */ gdouble -g_rand_double_range (GRand* rand, gdouble begin, gdouble end) +g_rand_double_range (GRand *rand, + gdouble begin, + gdouble end) { gdouble r; @@ -606,18 +620,19 @@ get_global_random (void) /** * g_random_boolean: * - * Returns a random #gboolean. This corresponds to a unbiased coin toss. + * Returns a random #gboolean. + * This corresponds to a unbiased coin toss. * - * Returns: a random #gboolean. - **/ + * Returns: a random #gboolean + */ /** * g_random_int: * * Return a random #guint32 equally distributed over the range * [0..2^32-1]. * - * Return value: A random number. - **/ + * Return value: a random number + */ guint32 g_random_int (void) { @@ -630,16 +645,17 @@ g_random_int (void) /** * g_random_int_range: - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * * Returns a random #gint32 equally distributed over the range * [@begin..@end-1]. * - * Return value: A random number. - **/ + * Return value: a random number + */ gint32 -g_random_int_range (gint32 begin, gint32 end) +g_random_int_range (gint32 begin, + gint32 end) { gint32 result; G_LOCK (global_random); @@ -653,8 +669,8 @@ g_random_int_range (gint32 begin, gint32 end) * * Returns a random #gdouble equally distributed over the range [0..1). * - * Return value: A random number. - **/ + * Return value: a random number + */ gdouble g_random_double (void) { @@ -667,15 +683,17 @@ g_random_double (void) /** * g_random_double_range: - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * - * Returns a random #gdouble equally distributed over the range [@begin..@end). + * Returns a random #gdouble equally distributed over the range + * [@begin..@end). * - * Return value: A random number. - **/ + * Return value: a random number + */ gdouble -g_random_double_range (gdouble begin, gdouble end) +g_random_double_range (gdouble begin, + gdouble end) { double result; G_LOCK (global_random); @@ -686,11 +704,11 @@ g_random_double_range (gdouble begin, gdouble end) /** * g_random_set_seed: - * @seed: a value to reinitialize the global random number generator. + * @seed: a value to reinitialize the global random number generator * * Sets the seed for the global random number generator, which is used * by the g_random_* functions, to @seed. - **/ + */ void g_random_set_seed (guint32 seed) {