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:rand_bytes/1 could be used instead.

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 way of obtaining a seed is to use the BIF now/0:

                        ...
                        {A1,A2,A3} = now(),
                        random:seed(A1, A2, A3),
                        ...

       seed(X1 :: {A1, A2, A3}) -> undefined | ran()

              Types:

                 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.

Ericsson AB                                       stdlib 1.19.4                                     random(3erl)