% =============================================================================
% The CGAL Reference Manual
% Section: Random Numbers Generator
% -----------------------------------------------------------------------------
% file  : Kernel/spec/Random.tex
% author: Sven Schönherr (sven@inf.fu-berlin.de)
% -----------------------------------------------------------------------------
% $Revision$
% $Date$
% =============================================================================

\begin{ccClass}{CGAL_Random}
\ccSection{Random Numbers Generator}

% -----------------------------------------------------------------------------
\ccDefinition

An instance of type \ccClassName\ is a random numbers generator. It
allows to generate uniformly distributed random \ccc{bool}s,
\ccc{int}s and \ccc{double}s. It can be used as the random number
generating function object in the STL algorithm \ccc{random_shuffle}.

Instances of \ccClassName\ can be seen as input streams. Different
streams are \emph{independent} of each other, i.e.\ the sequence of
numbers from one stream does \emph{not} depend upon how many numbers
were extracted from the other streams.

It can be very useful, e.g.\ for debugging, to reproduce a sequence of
random numbers.  This can be done by either initialising
deterministically or using the seed functions as described below.

\ccInclude{CGAL/Random.h}

% -----------------------------------------------------------------------------
\ccHeading{Global Variables}

\ccVariable{ CGAL_Random CGAL_random;}{
          This global variable is used as the
          default random numbers generator.}

% -----------------------------------------------------------------------------
\ccTypes

\ccUnchecked
\ccNestedType{Seed}{Seed type.}

% -----------------------------------------------------------------------------
\ccCreation
\ccCreationVariable{random}

\ccConstructor{ CGAL_Random( );}{
        introduces a variable \ccVar\ of type \ccClassTemplateName.}

\ccConstructor{ CGAL_Random( Seed seed);}{
        introduces a variable \ccVar\ of type \ccClassTemplateName\
        and initializes it's internal seed with \ccc{seed}.}

\ccConstructor{ CGAL_Random( long init);}{
        introduces a variable \ccVar\ of type \ccClassTemplateName\
        and initializes it's internal seed using \ccc{init}. Equal
        values for \ccc{init} result in equal sequences of random
        numbers.}

% -----------------------------------------------------------------------------
\ccOperations

\ccMemberFunction{ bool get_bool( );}{
        returns a random \ccc{bool}.}

\ccMemberFunction{ int get_int( int lower, int upper);}{
        returns a random \ccc{int} from the interval
        $[\mbox{\ccc{lower},\ccc{upper}})$.}

\ccMemberFunction{ double get_double( double lower = 0.0,
                                      double upper = 1.0);}{
        returns a random \ccc{double} from the interval
        $[\mbox{\ccc{lower},\ccc{upper}})$.}

\ccMemberFunction{ int operator() ( int upper);}{
        returns \ccVar\ccc{.get_int( 0, upper)}.}

% -----------------------------------------------------------------------------
\ccHeading{Seed Functions}

\ccMemberFunction{ void save_seed( Seed& seed) const;}{
        saves the current internal seed in \ccc{seed}.}

\ccMemberFunction{ void restore_seed( Seed const& seed);}{
        restores the internal seed from \ccc{seed}.}

% -----------------------------------------------------------------------------
\ccHeading{Equality Test}

\ccMemberFunction{ bool  operator == ( CGAL_Random const& random2) const;}{
        returns \ccc{true}, iff \ccVar\ and \ccc{random2} have equal
        internal seeds.}

% -----------------------------------------------------------------------------
\ccImplementation

We use the C library function \ccc{erand48} to generate the random
numbers, i.e.\ the sequence of numbers depends on the implementation
of \ccc{erand48} on your specific platform.

\end{ccClass}

% ===== EOF ===================================================================