aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/random.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/random.xml')
-rw-r--r--lib/stdlib/doc/src/random.xml136
1 files changed, 83 insertions, 53 deletions
diff --git a/lib/stdlib/doc/src/random.xml b/lib/stdlib/doc/src/random.xml
index fc4f796863..8d090d20b3 100644
--- a/lib/stdlib/doc/src/random.xml
+++ b/lib/stdlib/doc/src/random.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2013</year>
+ <year>1996</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -24,116 +24,140 @@
<title>random</title>
<prepared>Joe Armstrong</prepared>
- <responsible>Bjarne Dacker</responsible>
+ <responsible>Bjarne D&auml;cker</responsible>
<docno>1</docno>
<approved>Bjarne D&auml;cker</approved>
<checked></checked>
- <date>96-09-09</date>
+ <date>1996-09-09</date>
<rev>A</rev>
- <file>random.sgml</file>
+ <file>random.xml</file>
</header>
<module>random</module>
- <modulesummary>Pseudo random number generation</modulesummary>
+ <modulesummary>Pseudo-random number generation.</modulesummary>
<description>
- <p>Random number generator. The method is attributed to
- B.A. Wichmann and I.D.Hill, in 'An efficient and portable
+ <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 current algorithm is a modification of the version attributed
- to Richard A O'Keefe in the standard Prolog library.</p>
+ 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 produced. The state can either be implicit (kept
+ 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>
- <p>It should be noted that this random number generator is not cryptographically
- strong. If a strong cryptographic random number generator is needed for
- example <c>crypto:strong_rand_bytes/1</c> could be used instead.</p>
- <note><p>The new and improved <seealso
- marker="stdlib:rand">rand</seealso> module should be used
- instead of this module.</p></note>
+
+ <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
+ <seealso marker="crypto:crypto"><c>crypto</c></seealso>
+ module, for example, <seealso marker="crypto:crypto">
+ <c>crypto:strong_rand_bytes/1</c></seealso>.</p>
+ </note>
+
+ <note>
+ <p>The improved <seealso marker="rand"><c>rand</c></seealso>
+ 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"/>
- <fsummary>Seeds random number generation with default values</fsummary>
+ <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>
+ in the process dictionary and returns the old state.</p>
</desc>
</func>
+
+ <func>
+ <name name="seed" arity="1"/>
+ <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"/>
- <fsummary>Seeds random number generator</fsummary>
+ <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>One easy way of obtaining a unique value to seed with is to:</p>
+ 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>See <seealso marker="erts:erlang#phash2/1">
- erlang:phash2/1</seealso>, <seealso marker="erts:erlang#node/0">
- node/0</seealso>, <seealso marker="erts:erlang#monotonic_time/0">
- erlang:monotonic_time/0</seealso>, and
+ <p>For details, see
+ <seealso marker="erts:erlang#phash2/1">
+ <c>erlang:phash2/1</c></seealso>,
+ <seealso marker="erts:erlang#node/0">
+ <c>erlang:node/0</c></seealso>,
+ <seealso marker="erts:erlang#monotonic_time/0">
+ <c>erlang:monotonic_time/0</c></seealso>, and
<seealso marker="erts:erlang#unique_integer/0">
- erlang:unique_integer/0</seealso>) for details.</p>
- </desc>
- </func>
- <func>
- <name name="seed" arity="1"/>
- <fsummary>Seeds 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>
+ <c>erlang:unique_integer/0</c></seealso>.</p>
</desc>
</func>
+
<func>
<name name="seed0" arity="0"/>
- <fsummary>Return default state for random number generation</fsummary>
+ <fsummary>Return default state for random number generation.</fsummary>
<desc>
<p>Returns the default state.</p>
</desc>
</func>
+
<func>
<name name="uniform" arity="0"/>
- <fsummary>Return a random float</fsummary>
+ <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"/>
- <fsummary>Return a random integer</fsummary>
+ <fsummary>Return a random integer.</fsummary>
<desc>
- <p>Given an integer <c><anno>N</anno> >= 1</c>, <c>uniform/1</c> returns a
- random integer uniformly distributed between <c>1</c> and
- <c><anno>N</anno></c>, updating the state in the process dictionary.</p>
+ <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"/>
- <fsummary>Return a random float</fsummary>
+ <fsummary>Return a random float.</fsummary>
<desc>
- <p>Given a state, <c>uniform_s/1</c>returns a random float uniformly
+ <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"/>
- <fsummary>Return a random integer</fsummary>
+ <fsummary>Return a random integer.</fsummary>
<desc>
- <p>Given an integer <c><anno>N</anno> >= 1</c> and a state, <c>uniform_s/2</c>
- returns a random integer uniformly distributed between <c>1</c> and
+ <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>
@@ -143,12 +167,18 @@ random:seed(erlang:phash2([node()]),
<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 <c>uniform/0</c> or <c>uniform/1</c> without
- setting a seed first, <c>seed/0</c> is called automatically.</p>
- <p>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 <c>{0,0,0}</c> will, for example, no longer
+
+ <p>If a process calls
+ <seealso marker="#uniform/0"><c>uniform/0</c></seealso> or
+ <seealso marker="#uniform/1"><c>uniform/1</c></seealso>
+ without setting a seed first,
+ <seealso marker="#seed/0"><c>seed/0</c></seealso>
+ 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>