NAME

       random - Pseudo-random number generation.

DESCRIPTION

       This  module provides a 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  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
       is  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.

   Note:
       This  random  number  generator is not cryptographically strong. If a strong cryptographic
       random number generator is needed, use one of functions in the crypto module, for example,
       crypto:strong_rand_bytes/1.

   Note:
       The improved rand module is to 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(SValue) -> undefined | ran()

              Types:

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

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

       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.

              The following is an easy way of obtaining a unique value to seed with:

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

              For  details,  see  erlang:phash2/1,  erlang:node/0,  erlang:monotonic_time/0,  and
              erlang:unique_integer/0.

       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

              Returns,  for  a  specified  integer N >= 1, 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()

              Returns, for a specified state, 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()

              Returns,  for  a  specified  integer N >= 1 and a state, 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 Erlang/OTP R15. Upgrading to R15  breaks  applications  that
       expect  a  specific  output for a specified seed. The output is still deterministic number
       series, but different compared to releases older than R15. Seed {0,0,0} does, for example,
       no longer produce a flawed series of only zeros.