NAME

       random - Pseudo random number generation

DESCRIPTION

       Random  number  generator.  The method is attributed to B.A. Wichmann and I.D.Hill, in 'An
       efficient and portable pseudo-random number generator',  Journal  of  Applied  Statistics.
       AS183. 1982. Also Byte March 1987.

       The  current algorithm is a modification of the version attributed to Richard A O'Keefe in
       the standard Prolog library.

       Every time a random number is requested, a state is used to calculate it, and a new  state
       produced.  The  state  can  either  be  implicit (kept in the process dictionary) or be an
       explicit argument and return value. In this implementation, the  state  (the  type  ran())
       consists of a tuple of three integers.

       It should be noted that this random number generator is not cryptographically strong. If a
       strong    cryptographic    random    number    generator    is    needed    for    example
       crypto:strong_rand_bytes/1 could be used instead.

   Note:
       The new and improved rand module should be used instead of this module.

DATA TYPES

       ran() = {integer(), integer(), integer()}

              The state.

EXPORTS

       seed() -> ran()

              Seeds  random  number  generation  with  default  (fixed)  values  in  the  process
              dictionary, and returns the old state.

       seed(A1, A2, A3) -> undefined | ran()

              Types:

                 A1 = A2 = A3 = integer()

              Seeds random number generation with integer values in the process  dictionary,  and
              returns the old state.

              One easy way of obtaining a unique value to seed with is to:

              random:seed(erlang:phash2([node()]),
                          erlang:monotonic_time(),
                          erlang:unique_integer())

              See        erlang:phash2/1,        node/0,        erlang:monotonic_time/0,      and
              erlang:unique_integer/0) for details.

       seed(SValue) -> undefined | ran()

              Types:

                 SValue = {A1, A2, A3} | integer()
                 A1 = A2 = A3 = integer()

              seed({A1, A2, A3}) is equivalent to seed(A1, A2, A3).

       seed0() -> ran()

              Returns the default state.

       uniform() -> float()

              Returns a random float uniformly distributed between  0.0  and  1.0,  updating  the
              state in the process dictionary.

       uniform(N) -> integer() >= 1

              Types:

                 N = integer() >= 1

              Given  an  integer N >= 1, uniform/1 returns a random integer uniformly distributed
              between 1 and N, updating the state in the process dictionary.

       uniform_s(State0) -> {float(), State1}

              Types:

                 State0 = State1 = ran()

              Given a state, uniform_s/1returns a random float uniformly distributed between  0.0
              and 1.0, and a new state.

       uniform_s(N, State0) -> {integer(), State1}

              Types:

                 N = integer() >= 1
                 State0 = State1 = ran()

              Given an integer N >= 1 and a state, uniform_s/2 returns a random integer uniformly
              distributed between 1 and N, and a new state.

NOTE

       Some of the functions use the process dictionary  variable  random_seed  to  remember  the
       current seed.

       If  a  process calls uniform/0 or uniform/1 without setting a seed first, seed/0 is called
       automatically.

       The implementation changed in R15. Upgrading to R15 will break applications that expect  a
       specific  output  for  a  given seed. The output is still deterministic number series, but
       different compared to releases older than R15. The seed  {0,0,0}  will,  for  example,  no
       longer produce a flawed series of only zeros.