-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | random number library
--   
--   This package provides a basic random number generation library,
--   including the ability to split random number generators.
@package random
@version 1.1


-- | This library deals with the common task of pseudo-random number
--   generation. The library makes it possible to generate repeatable
--   results, by starting with a specified initial random number generator,
--   or to get different results on each run by using the
--   system-initialised generator or by supplying a seed from some other
--   source.
--   
--   The library is split into two layers:
--   
--   <ul>
--   <li>A core <i>random number generator</i> provides a supply of bits.
--   The class <a>RandomGen</a> provides a common interface to such
--   generators. The library provides one instance of <a>RandomGen</a>, the
--   abstract data type <a>StdGen</a>. Programmers may, of course, supply
--   their own instances of <a>RandomGen</a>.</li>
--   <li>The class <a>Random</a> provides a way to extract values of a
--   particular type from a random number generator. For example, the
--   <a>Float</a> instance of <a>Random</a> allows one to generate random
--   values of type <a>Float</a>.</li>
--   </ul>
--   
--   This implementation uses the Portable Combined Generator of L'Ecuyer
--   [<a>System.Random\#LEcuyer</a>] for 32-bit computers, transliterated
--   by Lennart Augustsson. It has a period of roughly 2.30584e18.
module System.Random

-- | The class <a>RandomGen</a> provides a common interface to random
--   number generators.
class RandomGen g where genRange _ = (minBound, maxBound)

-- | The <a>next</a> operation returns an <a>Int</a> that is uniformly
--   distributed in the range returned by <a>genRange</a> (including both
--   end points), and a new generator.
next :: RandomGen g => g -> (Int, g)

-- | The <a>genRange</a> operation yields the range of values returned by
--   the generator.
--   
--   It is required that:
--   
--   <ul>
--   <li>If <tt>(a,b) = <a>genRange</a> g</tt>, then <tt>a &lt;
--   b</tt>.</li>
--   <li><a>genRange</a> always returns a pair of defined <a>Int</a>s.</li>
--   </ul>
--   
--   The second condition ensures that <a>genRange</a> cannot examine its
--   argument, and hence the value it returns can be determined only by the
--   instance of <a>RandomGen</a>. That in turn allows an implementation to
--   make a single call to <a>genRange</a> to establish a generator's
--   range, without being concerned that the generator returned by (say)
--   <a>next</a> might have a different range to the generator passed to
--   <a>next</a>.
--   
--   The default definition spans the full range of <a>Int</a>.
genRange :: RandomGen g => g -> (Int, Int)

-- | The <a>split</a> operation allows one to obtain two distinct random
--   number generators. This is very useful in functional programs (for
--   example, when passing a random number generator down to recursive
--   calls), but very little work has been done on statistically robust
--   implementations of <a>split</a> ([<a>System.Random\#Burton</a>,
--   <a>System.Random\#Hellekalek</a>] are the only examples we know of).
split :: RandomGen g => g -> (g, g)

-- | The <a>StdGen</a> instance of <a>RandomGen</a> has a <a>genRange</a>
--   of at least 30 bits.
--   
--   The result of repeatedly using <a>next</a> should be at least as
--   statistically robust as the <i>Minimal Standard Random Number
--   Generator</i> described by [<a>System.Random\#Park</a>,
--   <a>System.Random\#Carta</a>]. Until more is known about
--   implementations of <a>split</a>, all we require is that <a>split</a>
--   deliver generators that are (a) not identical and (b) independently
--   robust in the sense just given.
--   
--   The <a>Show</a> and <a>Read</a> instances of <a>StdGen</a> provide a
--   primitive way to save the state of a random number generator. It is
--   required that <tt><a>read</a> (<a>show</a> g) == g</tt>.
--   
--   In addition, <a>reads</a> may be used to map an arbitrary string (not
--   necessarily one produced by <a>show</a>) onto a value of type
--   <a>StdGen</a>. In general, the <a>Read</a> instance of <a>StdGen</a>
--   has the following properties:
--   
--   <ul>
--   <li>It guarantees to succeed on any string.</li>
--   <li>It guarantees to consume only a finite portion of the string.</li>
--   <li>Different argument strings are likely to result in different
--   results.</li>
--   </ul>
data StdGen

-- | The function <a>mkStdGen</a> provides an alternative way of producing
--   an initial generator, by mapping an <a>Int</a> into a generator.
--   Again, distinct arguments should be likely to produce distinct
--   generators.
mkStdGen :: Int -> StdGen

-- | Uses the supplied function to get a value from the current global
--   random generator, and updates the global generator with the new
--   generator returned by the function. For example, <tt>rollDice</tt>
--   gets a random integer between 1 and 6:
--   
--   <pre>
--   rollDice :: IO Int
--   rollDice = getStdRandom (randomR (1,6))
--   </pre>
getStdRandom :: (StdGen -> (a, StdGen)) -> IO a

-- | Gets the global random number generator.
getStdGen :: IO StdGen

-- | Sets the global random number generator.
setStdGen :: StdGen -> IO ()

-- | Applies <a>split</a> to the current global random generator, updates
--   it with one of the results, and returns the other.
newStdGen :: IO StdGen

-- | With a source of random number supply in hand, the <a>Random</a> class
--   allows the programmer to extract random values of a variety of types.
--   
--   Minimal complete definition: <a>randomR</a> and <a>random</a>.
class Random a where randomRs ival g = build (\ cons _nil -> buildRandoms cons (randomR ival) g) randoms g = build (\ cons _nil -> buildRandoms cons random g) randomRIO range = getStdRandom (randomR range) randomIO = getStdRandom random

-- | Takes a range <i>(lo,hi)</i> and a random number generator <i>g</i>,
--   and returns a random value uniformly distributed in the closed
--   interval <i>[lo,hi]</i>, together with a new generator. It is
--   unspecified what happens if <i>lo&gt;hi</i>. For continuous types
--   there is no requirement that the values <i>lo</i> and <i>hi</i> are
--   ever produced, but they may be, depending on the implementation and
--   the interval.
randomR :: (Random a, RandomGen g) => (a, a) -> g -> (a, g)

-- | The same as <a>randomR</a>, but using a default range determined by
--   the type:
--   
--   <ul>
--   <li>For bounded types (instances of <a>Bounded</a>, such as
--   <a>Char</a>), the range is normally the whole type.</li>
--   <li>For fractional types, the range is normally the semi-closed
--   interval <tt>[0,1)</tt>.</li>
--   <li>For <a>Integer</a>, the range is (arbitrarily) the range of
--   <a>Int</a>.</li>
--   </ul>
random :: (Random a, RandomGen g) => g -> (a, g)

-- | Plural variant of <a>randomR</a>, producing an infinite list of random
--   values instead of returning a new generator.
randomRs :: (Random a, RandomGen g) => (a, a) -> g -> [a]

-- | Plural variant of <a>random</a>, producing an infinite list of random
--   values instead of returning a new generator.
randoms :: (Random a, RandomGen g) => g -> [a]

-- | A variant of <a>randomR</a> that uses the global random number
--   generator (see <a>System.Random#globalrng</a>).
randomRIO :: Random a => (a, a) -> IO a

-- | A variant of <a>random</a> that uses the global random number
--   generator (see <a>System.Random#globalrng</a>).
randomIO :: Random a => IO a
instance System.Random.RandomGen System.Random.StdGen
instance GHC.Show.Show System.Random.StdGen
instance GHC.Read.Read System.Random.StdGen
instance System.Random.Random GHC.Integer.Type.Integer
instance System.Random.Random GHC.Types.Int
instance System.Random.Random GHC.Int.Int8
instance System.Random.Random GHC.Int.Int16
instance System.Random.Random GHC.Int.Int32
instance System.Random.Random GHC.Int.Int64
instance System.Random.Random GHC.Types.Word
instance System.Random.Random GHC.Word.Word8
instance System.Random.Random GHC.Word.Word16
instance System.Random.Random GHC.Word.Word32
instance System.Random.Random GHC.Word.Word64
instance System.Random.Random Foreign.C.Types.CChar
instance System.Random.Random Foreign.C.Types.CSChar
instance System.Random.Random Foreign.C.Types.CUChar
instance System.Random.Random Foreign.C.Types.CShort
instance System.Random.Random Foreign.C.Types.CUShort
instance System.Random.Random Foreign.C.Types.CInt
instance System.Random.Random Foreign.C.Types.CUInt
instance System.Random.Random Foreign.C.Types.CLong
instance System.Random.Random Foreign.C.Types.CULong
instance System.Random.Random Foreign.C.Types.CPtrdiff
instance System.Random.Random Foreign.C.Types.CSize
instance System.Random.Random Foreign.C.Types.CWchar
instance System.Random.Random Foreign.C.Types.CSigAtomic
instance System.Random.Random Foreign.C.Types.CLLong
instance System.Random.Random Foreign.C.Types.CULLong
instance System.Random.Random Foreign.C.Types.CIntPtr
instance System.Random.Random Foreign.C.Types.CUIntPtr
instance System.Random.Random Foreign.C.Types.CIntMax
instance System.Random.Random Foreign.C.Types.CUIntMax
instance System.Random.Random GHC.Types.Char
instance System.Random.Random GHC.Types.Bool
instance System.Random.Random GHC.Types.Double
instance System.Random.Random GHC.Types.Float
instance System.Random.Random Foreign.C.Types.CFloat
instance System.Random.Random Foreign.C.Types.CDouble
