1random(3)                  Erlang Module Definition                  random(3)
2
3
4

NAME

6       random - Pseudo-random number generation.
7

DESCRIPTION

9       This  module  provides a random number generator. The method is attrib‐
10       uted to B.A. Wichmann and I.D.  Hill  in  'An  efficient  and  portable
11       pseudo-random  number generator', Journal of Applied Statistics. AS183.
12       1982. Also Byte March 1987.
13
14       The algorithm is a modification of the version attributed to Richard A.
15       O'Keefe in the standard Prolog library.
16
17       Every  time  a random number is requested, a state is used to calculate
18       it, and a new state is produced. The state can either be implicit (kept
19       in the process dictionary) or be an explicit argument and return value.
20       In this implementation, the state (the type ran()) consists of a  tuple
21       of three integers.
22
23   Note:
24       This  random  number  generator  is  not cryptographically strong. If a
25       strong cryptographic random number generator  is  needed,  use  one  of
26       functions      in      the      crypto     module,     for     example,
27       crypto:strong_rand_bytes/1.
28
29
30   Note:
31       The improved rand module is to be used instead of this module.
32
33

DATA TYPES

35       ran() = {integer(), integer(), integer()}
36
37              The state.
38

EXPORTS

40       seed() -> ran()
41
42              Seeds random number generation with default  (fixed)  values  in
43              the process dictionary and returns the old state.
44
45       seed(SValue) -> undefined | ran()
46
47              Types:
48
49                 SValue = {A1, A2, A3} | integer()
50                 A1 = A2 = A3 = integer()
51
52              seed({A1, A2, A3}) is equivalent to seed(A1, A2, A3).
53
54       seed(A1, A2, A3) -> undefined | ran()
55
56              Types:
57
58                 A1 = A2 = A3 = integer()
59
60              Seeds  random  number  generation  with  integer  values  in the
61              process dictionary and returns the old state.
62
63              The following is an easy way of obtaining a unique value to seed
64              with:
65
66              random:seed(erlang:phash2([node()]),
67                          erlang:monotonic_time(),
68                          erlang:unique_integer())
69
70              For  details,  see  erlang:phash2/1, erlang:node/0, erlang:mono‐
71              tonic_time/0, and erlang:unique_integer/0.
72
73       seed0() -> ran()
74
75              Returns the default state.
76
77       uniform() -> float()
78
79              Returns a random float uniformly  distributed  between  0.0  and
80              1.0, updating the state in the process dictionary.
81
82       uniform(N) -> integer() >= 1
83
84              Types:
85
86                 N = integer() >= 1
87
88              Returns,  for  a specified integer N >= 1, a random integer uni‐
89              formly distributed between 1 and N, updating the  state  in  the
90              process dictionary.
91
92       uniform_s(State0) -> {float(), State1}
93
94              Types:
95
96                 State0 = State1 = ran()
97
98              Returns,  for  a  specified state, a random float uniformly dis‐
99              tributed between 0.0 and 1.0, and a new state.
100
101       uniform_s(N, State0) -> {integer(), State1}
102
103              Types:
104
105                 N = integer() >= 1
106                 State0 = State1 = ran()
107
108              Returns, for a specified integer N >= 1 and a  state,  a  random
109              integer uniformly distributed between 1 and N, and a new state.
110

NOTE

112       Some  of  the functions use the process dictionary variable random_seed
113       to remember the current seed.
114
115       If a process calls uniform/0 or uniform/1 without setting a seed first,
116       seed/0 is called automatically.
117
118       The  implementation  changed in Erlang/OTP R15. Upgrading to R15 breaks
119       applications that expect a specific output for a  specified  seed.  The
120       output  is still deterministic number series, but different compared to
121       releases older than R15. Seed {0,0,0} does, for example, no longer pro‐
122       duce a flawed series of only zeros.
123
124
125
126Ericsson AB                       stdlib 4.2                         random(3)