random_numbers.xml [plain text]
<refentry id="glib-Random-Numbers">
<refmeta>
<refentrytitle>Random Numbers</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Random Numbers</refname><refpurpose>pseudo-random number generator.</refpurpose>
</refnamediv>
<refsynopsisdiv><title>Synopsis</title>
<synopsis>
#include <glib.h>
struct <link linkend="GRand">GRand</link>;
<link linkend="GRand">GRand</link>* <link linkend="g-rand-new-with-seed">g_rand_new_with_seed</link> (<link linkend="guint32">guint32</link> seed);
<link linkend="GRand">GRand</link>* <link linkend="g-rand-new-with-seed-array">g_rand_new_with_seed_array</link> (const <link linkend="guint32">guint32</link> *seed,
<link linkend="guint">guint</link> seed_length);
<link linkend="GRand">GRand</link>* <link linkend="g-rand-new">g_rand_new</link> (void);
<link linkend="GRand">GRand</link>* <link linkend="g-rand-copy">g_rand_copy</link> (<link linkend="GRand">GRand</link> *rand_);
<link linkend="void">void</link> <link linkend="g-rand-free">g_rand_free</link> (<link linkend="GRand">GRand</link> *rand_);
<link linkend="void">void</link> <link linkend="g-rand-set-seed">g_rand_set_seed</link> (<link linkend="GRand">GRand</link> *rand_,
<link linkend="guint32">guint32</link> seed);
<link linkend="void">void</link> <link linkend="g-rand-set-seed-array">g_rand_set_seed_array</link> (<link linkend="GRand">GRand</link> *rand_,
const <link linkend="guint32">guint32</link> *seed,
<link linkend="guint">guint</link> seed_length);
#define <link linkend="g-rand-boolean">g_rand_boolean</link> (rand_)
<link linkend="guint32">guint32</link> <link linkend="g-rand-int">g_rand_int</link> (<link linkend="GRand">GRand</link> *rand_);
<link linkend="gint32">gint32</link> <link linkend="g-rand-int-range">g_rand_int_range</link> (<link linkend="GRand">GRand</link> *rand_,
<link linkend="gint32">gint32</link> begin,
<link linkend="gint32">gint32</link> end);
<link linkend="gdouble">gdouble</link> <link linkend="g-rand-double">g_rand_double</link> (<link linkend="GRand">GRand</link> *rand_);
<link linkend="gdouble">gdouble</link> <link linkend="g-rand-double-range">g_rand_double_range</link> (<link linkend="GRand">GRand</link> *rand_,
<link linkend="gdouble">gdouble</link> begin,
<link linkend="gdouble">gdouble</link> end);
<link linkend="void">void</link> <link linkend="g-random-set-seed">g_random_set_seed</link> (<link linkend="guint32">guint32</link> seed);
#define <link linkend="g-random-boolean">g_random_boolean</link> ()
<link linkend="guint32">guint32</link> <link linkend="g-random-int">g_random_int</link> (void);
<link linkend="gint32">gint32</link> <link linkend="g-random-int-range">g_random_int_range</link> (<link linkend="gint32">gint32</link> begin,
<link linkend="gint32">gint32</link> end);
<link linkend="gdouble">gdouble</link> <link linkend="g-random-double">g_random_double</link> (void);
<link linkend="gdouble">gdouble</link> <link linkend="g-random-double-range">g_random_double_range</link> (<link linkend="gdouble">gdouble</link> begin,
<link linkend="gdouble">gdouble</link> end);
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<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 <link linkend="GRand"><type>GRand</type></link> and use the according <function>g_rand_*</function> functions
internally. Whenever you need a stream of reproducible random numbers, you
better create a <link linkend="GRand"><type>GRand</type></link> yourself and use the <function>g_rand_*</function>
functions directly, which will also be slightly faster. Initializing a <link linkend="GRand"><type>GRand</type></link>
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>(<link linkend="g-random-int"><function>g_random_int()</function></link>%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*<link linkend="int-range"><function>_int_range()</function></link></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>
</refsect1>
<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GRand"/>struct GRand</title>
<indexterm><primary>GRand</primary></indexterm><programlisting>struct GRand;</programlisting>
<para>
The <link linkend="GRand"><type>GRand</type></link> struct is an opaque data structure. It should only be
accessed through the <function>g_rand_*</function> functions.
</para></refsect2>
<refsect2>
<title><anchor id="g-rand-new-with-seed"/>g_rand_new_with_seed ()</title>
<indexterm><primary>g_rand_new_with_seed</primary></indexterm><programlisting><link linkend="GRand">GRand</link>* g_rand_new_with_seed (<link linkend="guint32">guint32</link> seed);</programlisting>
<para>
Creates a new random number generator initialized with <parameter>seed</parameter>.</para>
<variablelist role="params">
<varlistentry><term><parameter>seed</parameter> :</term>
<listitem><simpara> a value to initialize the random number generator.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the new <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-rand-new-with-seed-array"/>g_rand_new_with_seed_array ()</title>
<indexterm role="2.4"><primary>g_rand_new_with_seed_array</primary></indexterm><programlisting><link linkend="GRand">GRand</link>* g_rand_new_with_seed_array (const <link linkend="guint32">guint32</link> *seed,
<link linkend="guint">guint</link> seed_length);</programlisting>
<para>
Creates a new random number generator initialized with <parameter>seed</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>seed</parameter> :</term>
<listitem><simpara> an array of seeds to initialize the random number generator.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>seed_length</parameter> :</term>
<listitem><simpara> an array of seeds to initialize the random number generator.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the new <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-rand-new"/>g_rand_new ()</title>
<indexterm><primary>g_rand_new</primary></indexterm><programlisting><link linkend="GRand">GRand</link>* g_rand_new (void);</programlisting>
<para>
Creates a new random number generator initialized with a seed taken
either from <filename>/dev/urandom</filename> (if existing) or from
the current time (as a fallback).</para>
<variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the new <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-rand-copy"/>g_rand_copy ()</title>
<indexterm role="2.4"><primary>g_rand_copy</primary></indexterm><programlisting><link linkend="GRand">GRand</link>* g_rand_copy (<link linkend="GRand">GRand</link> *rand_);</programlisting>
<para>
Copies a <link linkend="GRand"><type>GRand</type></link> 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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>rand_</parameter> :</term>
<listitem><simpara> a <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the new <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-rand-free"/>g_rand_free ()</title>
<indexterm><primary>g_rand_free</primary></indexterm><programlisting><link linkend="void">void</link> g_rand_free (<link linkend="GRand">GRand</link> *rand_);</programlisting>
<para>
Frees the memory allocated for the <link linkend="GRand"><type>GRand</type></link>.</para>
<variablelist role="params">
<varlistentry><term><parameter>rand_</parameter> :</term>
<listitem><simpara> a <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-rand-set-seed"/>g_rand_set_seed ()</title>
<indexterm><primary>g_rand_set_seed</primary></indexterm><programlisting><link linkend="void">void</link> g_rand_set_seed (<link linkend="GRand">GRand</link> *rand_,
<link linkend="guint32">guint32</link> seed);</programlisting>
<para>
Sets the seed for the random number generator <link linkend="GRand"><type>GRand</type></link> to <parameter>seed</parameter>.</para>
<variablelist role="params">
<varlistentry><term><parameter>rand_</parameter> :</term>
<listitem><simpara> a <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>seed</parameter> :</term>
<listitem><simpara> a value to reinitialize the random number generator.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-rand-set-seed-array"/>g_rand_set_seed_array ()</title>
<indexterm role="2.4"><primary>g_rand_set_seed_array</primary></indexterm><programlisting><link linkend="void">void</link> g_rand_set_seed_array (<link linkend="GRand">GRand</link> *rand_,
const <link linkend="guint32">guint32</link> *seed,
<link linkend="guint">guint</link> seed_length);</programlisting>
<para>
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
32bits of actual entropy for your application.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>rand_</parameter> :</term>
<listitem><simpara> a <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>seed</parameter> :</term>
<listitem><simpara> array to initialize with
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>seed_length</parameter> :</term>
<listitem><simpara> length of array
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-rand-boolean"/>g_rand_boolean()</title>
<indexterm><primary>g_rand_boolean</primary></indexterm><programlisting>#define g_rand_boolean(rand_)</programlisting>
<para>
Returns a random <link linkend="gboolean"><type>gboolean</type></link> from <parameter>rand_</parameter>. This corresponds to a unbiased
coin toss.
</para><variablelist role="params">
<varlistentry><term><parameter>rand_</parameter> :</term>
<listitem><simpara>a <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a random <link linkend="gboolean"><type>gboolean</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-rand-int"/>g_rand_int ()</title>
<indexterm><primary>g_rand_int</primary></indexterm><programlisting><link linkend="guint32">guint32</link> g_rand_int (<link linkend="GRand">GRand</link> *rand_);</programlisting>
<para>
Returns the next random <link linkend="guint32"><type>guint32</type></link> from <parameter>rand_</parameter> equally distributed over
the range [0..2^32-1].</para>
<variablelist role="params">
<varlistentry><term><parameter>rand_</parameter> :</term>
<listitem><simpara> a <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A random number.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-rand-int-range"/>g_rand_int_range ()</title>
<indexterm><primary>g_rand_int_range</primary></indexterm><programlisting><link linkend="gint32">gint32</link> g_rand_int_range (<link linkend="GRand">GRand</link> *rand_,
<link linkend="gint32">gint32</link> begin,
<link linkend="gint32">gint32</link> end);</programlisting>
<para>
Returns the next random <link linkend="gint32"><type>gint32</type></link> from <parameter>rand_</parameter> equally distributed over
the range [<parameter>begin</parameter>..<parameter>end</parameter>-1].</para>
<variablelist role="params">
<varlistentry><term><parameter>rand_</parameter> :</term>
<listitem><simpara> a <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>begin</parameter> :</term>
<listitem><simpara> lower closed bound of the interval.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>end</parameter> :</term>
<listitem><simpara> upper open bound of the interval.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A random number.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-rand-double"/>g_rand_double ()</title>
<indexterm><primary>g_rand_double</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link> g_rand_double (<link linkend="GRand">GRand</link> *rand_);</programlisting>
<para>
Returns the next random <link linkend="gdouble"><type>gdouble</type></link> from <parameter>rand_</parameter> equally distributed over
the range [0..1).</para>
<variablelist role="params">
<varlistentry><term><parameter>rand_</parameter> :</term>
<listitem><simpara> a <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A random number.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-rand-double-range"/>g_rand_double_range ()</title>
<indexterm><primary>g_rand_double_range</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link> g_rand_double_range (<link linkend="GRand">GRand</link> *rand_,
<link linkend="gdouble">gdouble</link> begin,
<link linkend="gdouble">gdouble</link> end);</programlisting>
<para>
Returns the next random <link linkend="gdouble"><type>gdouble</type></link> from <parameter>rand_</parameter> equally distributed over
the range [<parameter>begin</parameter>..<parameter>end</parameter>).</para>
<variablelist role="params">
<varlistentry><term><parameter>rand_</parameter> :</term>
<listitem><simpara> a <link linkend="GRand"><type>GRand</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>begin</parameter> :</term>
<listitem><simpara> lower closed bound of the interval.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>end</parameter> :</term>
<listitem><simpara> upper open bound of the interval.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A random number.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-random-set-seed"/>g_random_set_seed ()</title>
<indexterm><primary>g_random_set_seed</primary></indexterm><programlisting><link linkend="void">void</link> g_random_set_seed (<link linkend="guint32">guint32</link> seed);</programlisting>
<para>
Sets the seed for the global random number generator, which is used
by the <function>g_random_*</function> functions, to <parameter>seed</parameter>.</para>
<variablelist role="params">
<varlistentry><term><parameter>seed</parameter> :</term>
<listitem><simpara> a value to reinitialize the global random number generator.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-random-boolean"/>g_random_boolean()</title>
<indexterm><primary>g_random_boolean</primary></indexterm><programlisting>#define g_random_boolean()</programlisting>
<para>
Returns a random <link linkend="gboolean"><type>gboolean</type></link>. This corresponds to a unbiased coin toss.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a random <link linkend="gboolean"><type>gboolean</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-random-int"/>g_random_int ()</title>
<indexterm><primary>g_random_int</primary></indexterm><programlisting><link linkend="guint32">guint32</link> g_random_int (void);</programlisting>
<para>
Return a random <link linkend="guint32"><type>guint32</type></link> equally distributed over the range
[0..2^32-1].</para>
<variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A random number.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-random-int-range"/>g_random_int_range ()</title>
<indexterm><primary>g_random_int_range</primary></indexterm><programlisting><link linkend="gint32">gint32</link> g_random_int_range (<link linkend="gint32">gint32</link> begin,
<link linkend="gint32">gint32</link> end);</programlisting>
<para>
Returns a random <link linkend="gint32"><type>gint32</type></link> equally distributed over the range
[<parameter>begin</parameter>..<parameter>end</parameter>-1].</para>
<variablelist role="params">
<varlistentry><term><parameter>begin</parameter> :</term>
<listitem><simpara> lower closed bound of the interval.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>end</parameter> :</term>
<listitem><simpara> upper open bound of the interval.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A random number.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-random-double"/>g_random_double ()</title>
<indexterm><primary>g_random_double</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link> g_random_double (void);</programlisting>
<para>
Returns a random <link linkend="gdouble"><type>gdouble</type></link> equally distributed over the range [0..1).</para>
<variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A random number.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-random-double-range"/>g_random_double_range ()</title>
<indexterm><primary>g_random_double_range</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link> g_random_double_range (<link linkend="gdouble">gdouble</link> begin,
<link linkend="gdouble">gdouble</link> end);</programlisting>
<para>
Returns a random <link linkend="gdouble"><type>gdouble</type></link> equally distributed over the range [<parameter>begin</parameter>..<parameter>end</parameter>).</para>
<variablelist role="params">
<varlistentry><term><parameter>begin</parameter> :</term>
<listitem><simpara> lower closed bound of the interval.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>end</parameter> :</term>
<listitem><simpara> upper open bound of the interval.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A random number.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>