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


-- | random number library
--   
--   This package provides a random number library.
@package random
@version 1.0.0.3


-- | 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.
--   
--   Minimal complete definition: <a>next</a> and <a>split</a>.
class RandomGen g
next :: RandomGen g => g -> (Int, g)
split :: RandomGen g => g -> (g, g)
genRange :: RandomGen g => g -> (Int, Int)

-- | 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
randomR :: (Random a, RandomGen g) => (a, a) -> g -> (a, g)
random :: (Random a, RandomGen g) => g -> (a, g)
randomRs :: (Random a, RandomGen g) => (a, a) -> g -> [a]
randoms :: (Random a, RandomGen g) => g -> [a]
randomRIO :: Random a => (a, a) -> IO a
randomIO :: Random a => IO a
instance Random Float
instance Random Double
instance Random Integer
instance Random Bool
instance Random Char
instance Random Int
instance Read StdGen
instance Show StdGen
instance RandomGen StdGen