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.