diff options
Diffstat (limited to 'lib/stdlib/doc/src/random.xml')
| -rw-r--r-- | lib/stdlib/doc/src/random.xml | 134 |
1 files changed, 82 insertions, 52 deletions
diff --git a/lib/stdlib/doc/src/random.xml b/lib/stdlib/doc/src/random.xml index dea4e43c95..8d090d20b3 100644 --- a/lib/stdlib/doc/src/random.xml +++ b/lib/stdlib/doc/src/random.xml @@ -24,116 +24,140 @@ <title>random</title> <prepared>Joe Armstrong</prepared> - <responsible>Bjarne Dacker</responsible> + <responsible>Bjarne Däcker</responsible> <docno>1</docno> <approved>Bjarne Dä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> |