path: root/lib/stdlib/doc/src/random.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2013</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 Dacker</responsible>
    <docno>1</docno>
    <approved>Bjarne D&auml;cker</approved>
    <checked></checked>
    <date>96-09-09</date>
    <rev>A</rev>
    <file>random.sgml</file>
  </header>
  <module>random</module>
  <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
      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>
    <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
      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: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>
  </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>
      <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="3"/>
      <fsummary>Seeds 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>
        <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
          <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>
      </desc>
    </func>
    <func>
      <name name="seed0" arity="0"/>
      <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>
      <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>
      <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>
      </desc>
    </func>
    <func>
      <name name="uniform_s" arity="1"/>
      <fsummary>Return a random float</fsummary>
      <desc>
        <p>Given a state, <c>uniform_s/1</c>returns 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>
      <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
          <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 <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
      produce a flawed series of only zeros.</p>
  </section>
</erlref>