1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>1996</year><year>2020</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>random</title>
<prepared>Joe Armstrong</prepared>
<responsible>Bjarne Däcker</responsible>
<docno>1</docno>
<approved>Bjarne Däcker</approved>
<checked></checked>
<date>1996-09-09</date>
<rev>A</rev>
<file>random.xml</file>
</header>
<module since="">random</module>
<modulesummary>Pseudo-random number generation.</modulesummary>
<description>
<p>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.</p>
<p>The algorithm is a modification of the version attributed
to Richard A. O'Keefe in the standard Prolog library.</p>
<p>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 <c>ran()</c>) consists of a
tuple of three integers.</p>
<note>
<p>This random number generator is not cryptographically
strong. If a strong cryptographic random number generator is
needed, use one of functions in the
<seeerl marker="crypto:crypto"><c>crypto</c></seeerl>
module, for example, <seeerl marker="crypto:crypto">
<c>crypto:strong_rand_bytes/1</c></seeerl>.</p>
</note>
<note>
<p>The improved <seeerl marker="rand"><c>rand</c></seeerl>
module is to be used instead of this module.</p>
</note>
</description>
<datatypes>
<datatype>
<name name="ran"/>
<desc><p>The state.</p></desc>
</datatype>
</datatypes>
<funcs>
<func>
<name name="seed" arity="0" since=""/>
<fsummary>Seed random number generation with default values.</fsummary>
<desc>
<p>Seeds random number generation with default (fixed) values
in the process dictionary and returns the old state.</p>
</desc>
</func>
<func>
<name name="seed" arity="1" since=""/>
<fsummary>Seed random number generator.</fsummary>
<desc>
<p><c>seed({<anno>A1</anno>, <anno>A2</anno>, <anno>A3</anno>})</c>
is equivalent to
<c>seed(<anno>A1</anno>, <anno>A2</anno>, <anno>A3</anno>)</c>.</p>
</desc>
</func>
<func>
<name name="seed" arity="3" since=""/>
<fsummary>Seed random number generator.</fsummary>
<desc>
<p>Seeds random number generation with integer values in the process
dictionary and returns the old state.</p>
<p>The following is an easy way of obtaining a unique value to seed
with:</p>
<code type="none">
random:seed(erlang:phash2([node()]),
erlang:monotonic_time(),
erlang:unique_integer())</code>
<p>For details, see
<seemfa marker="erts:erlang#phash2/1">
<c>erlang:phash2/1</c></seemfa>,
<seemfa marker="erts:erlang#node/0">
<c>erlang:node/0</c></seemfa>,
<seemfa marker="erts:erlang#monotonic_time/0">
<c>erlang:monotonic_time/0</c></seemfa>, and
<seemfa marker="erts:erlang#unique_integer/0">
<c>erlang:unique_integer/0</c></seemfa>.</p>
</desc>
</func>
<func>
<name name="seed0" arity="0" since=""/>
<fsummary>Return default state for random number generation.</fsummary>
<desc>
<p>Returns the default state.</p>
</desc>
</func>
<func>
<name name="uniform" arity="0" since=""/>
<fsummary>Return a random float.</fsummary>
<desc>
<p>Returns a random float uniformly distributed between <c>0.0</c>
and <c>1.0</c>, updating the state in the process dictionary.</p>
</desc>
</func>
<func>
<name name="uniform" arity="1" since=""/>
<fsummary>Return a random integer.</fsummary>
<desc>
<p>Returns, for a specified integer <c><anno>N</anno> >= 1</c>,
a random integer uniformly distributed between <c>1</c> and
<c><anno>N</anno></c>, updating the state in the process
dictionary.</p>
</desc>
</func>
<func>
<name name="uniform_s" arity="1" since=""/>
<fsummary>Return a random float.</fsummary>
<desc>
<p>Returns, for a specified state, a random float uniformly
distributed between <c>0.0</c> and <c>1.0</c>, and a new state.</p>
</desc>
</func>
<func>
<name name="uniform_s" arity="2" since=""/>
<fsummary>Return a random integer.</fsummary>
<desc>
<p>Returns, for a specified integer <c><anno>N</anno> >= 1</c> and a
state, a random integer uniformly distributed between <c>1</c> and
<c><anno>N</anno></c>, and a new state.</p>
</desc>
</func>
</funcs>
<section>
<title>Note</title>
<p>Some of the functions use the process dictionary variable
<c>random_seed</c> to remember the current seed.</p>
<p>If a process calls
<seemfa marker="#uniform/0"><c>uniform/0</c></seemfa> or
<seemfa marker="#uniform/1"><c>uniform/1</c></seemfa>
without setting a seed first,
<seemfa marker="#seed/0"><c>seed/0</c></seemfa>
is called automatically.</p>
<p>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 <c>{0,0,0}</c> does, for example, no longer
produce a flawed series of only zeros.</p>
</section>
</erlref>
|
