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


-- | Pseudo-random number generation
--   
--   This package provides basic pseudo-random number generation, including
--   the ability to split random number generators.
--   
--   <h2><a>System.Random</a>: pure pseudo-random number interface</h2>
--   
--   In pure code, use <a>System.Random.uniform</a> and
--   <a>System.Random.uniformR</a> from <a>System.Random</a> to generate
--   pseudo-random numbers with a pure pseudo-random number generator like
--   <a>System.Random.StdGen</a>.
--   
--   As an example, here is how you can simulate rolls of a six-sided die
--   using <a>System.Random.uniformR</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let roll = uniformR (1, 6)        :: RandomGen g =&gt; g -&gt; (Word, g)
--   
--   &gt;&gt;&gt; let rolls = unfoldr (Just . roll) :: RandomGen g =&gt; g -&gt; [Word]
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 42
--   
--   &gt;&gt;&gt; take 10 (rolls pureGen)           :: [Word]
--   [1,1,3,2,4,5,3,4,6,2]
--   </pre>
--   
--   See <a>System.Random</a> for more details.
--   
--   <h2><a>System.Random.Stateful</a>: monadic pseudo-random number
--   interface</h2>
--   
--   In monadic code, use <a>System.Random.Stateful.uniformM</a> and
--   <a>System.Random.Stateful.uniformRM</a> from
--   <a>System.Random.Stateful</a> to generate pseudo-random numbers with a
--   monadic pseudo-random number generator, or using a monadic adapter.
--   
--   As an example, here is how you can simulate rolls of a six-sided die
--   using <a>System.Random.Stateful.uniformRM</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let rollM = uniformRM (1, 6)                 :: StatefulGen g m =&gt; g -&gt; m Word
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 42
--   
--   &gt;&gt;&gt; runStateGen_ pureGen (replicateM 10 . rollM) :: [Word]
--   [1,1,3,2,4,5,3,4,6,2]
--   </pre>
--   
--   The monadic adapter <a>System.Random.Stateful.runGenState_</a> is used
--   here to lift the pure pseudo-random number generator <tt>pureGen</tt>
--   into the <a>System.Random.Stateful.StatefulGen</a> context.
--   
--   The monadic interface can also be used with existing monadic
--   pseudo-random number generators. In this example, we use the one
--   provided in the <a>mwc-random</a> package:
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.MWC as MWC
--   
--   &gt;&gt;&gt; let rollM = uniformRM (1, 6)       :: StatefulGen g m =&gt; g -&gt; m Word
--   
--   &gt;&gt;&gt; monadicGen &lt;- MWC.create
--   
--   &gt;&gt;&gt; replicateM 10 (rollM monadicGen) :: IO [Word]
--   [2,3,6,6,4,4,3,1,5,4]
--   </pre>
--   
--   See <a>System.Random.Stateful</a> for more details.
@package random
@version 1.2.0


-- | This library deals with the common task of pseudo-random number
--   generation.
module System.Random

-- | <a>RandomGen</a> is an interface to pure pseudo-random number
--   generators.
--   
--   <a>StdGen</a> is the standard <a>RandomGen</a> instance provided by
--   this library.
class RandomGen g

-- | Returns an <a>Int</a> that is uniformly distributed over the range
--   returned by <a>genRange</a> (including both end points), and a new
--   generator. Using <a>next</a> is inefficient as all operations go via
--   <a>Integer</a>. See <a>here</a> for more details. It is thus
--   deprecated.

-- | <i>Deprecated: No longer used</i>
next :: RandomGen g => g -> (Int, g)

-- | Returns a <a>Word8</a> that is uniformly distributed over the entire
--   <a>Word8</a> range.
genWord8 :: RandomGen g => g -> (Word8, g)

-- | Returns a <a>Word16</a> that is uniformly distributed over the entire
--   <a>Word16</a> range.
genWord16 :: RandomGen g => g -> (Word16, g)

-- | Returns a <a>Word32</a> that is uniformly distributed over the entire
--   <a>Word32</a> range.
genWord32 :: RandomGen g => g -> (Word32, g)

-- | Returns a <a>Word64</a> that is uniformly distributed over the entire
--   <a>Word64</a> range.
genWord64 :: RandomGen g => g -> (Word64, g)

-- | <tt>genWord32R upperBound g</tt> returns a <a>Word32</a> that is
--   uniformly distributed over the range <tt>[0, upperBound]</tt>.
genWord32R :: RandomGen g => Word32 -> g -> (Word32, g)

-- | <tt>genWord64R upperBound g</tt> returns a <a>Word64</a> that is
--   uniformly distributed over the range <tt>[0, upperBound]</tt>.
genWord64R :: RandomGen g => Word64 -> g -> (Word64, g)

-- | <tt>genShortByteString n g</tt> returns a <a>ShortByteString</a> of
--   length <tt>n</tt> filled with pseudo-random bytes.
genShortByteString :: RandomGen g => Int -> g -> (ShortByteString, g)

-- | Yields the range of values returned by <a>next</a>.
--   
--   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> must not examine its argument so the value it
--   returns is determined only by the instance of <a>RandomGen</a>.</li>
--   </ul>
--   
--   The default definition spans the full range of <a>Int</a>.

-- | <i>Deprecated: No longer used</i>
genRange :: RandomGen g => g -> (Int, Int)

-- | Returns two distinct pseudo-random number generators.
--   
--   Implementations should take care to ensure that the resulting
--   generators are not correlated. Some pseudo-random number generators
--   are not splittable. In that case, the <a>split</a> implementation
--   should fail with a descriptive <a>error</a> message.
split :: RandomGen g => g -> (g, g)

-- | Generates a value uniformly distributed over all possible values of
--   that type.
--   
--   This is a pure version of <a>uniformM</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; uniform pureGen :: (Bool, StdGen)
--   (True,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--   </pre>
uniform :: (RandomGen g, Uniform a) => g -> (a, g)

-- | Generates a value uniformly distributed over the provided range, which
--   is interpreted as inclusive in the lower and upper bound.
--   
--   <ul>
--   <li><tt>uniformR (1 :: Int, 4 :: Int)</tt> generates values uniformly
--   from the set &lt;math&gt;</li>
--   <li><tt>uniformR (1 :: Float, 4 :: Float)</tt> generates values
--   uniformly from the set &lt;math&gt;</li>
--   </ul>
--   
--   The following law should hold to make the function always defined:
--   
--   <pre>
--   uniformR (a, b) = uniformR (b, a)
--   </pre>
--   
--   This is a pure version of <a>uniformRM</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; uniformR (1 :: Int, 4 :: Int) pureGen
--   (4,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--   </pre>
uniformR :: (RandomGen g, UniformRange a) => (a, a) -> g -> (a, g)

-- | Generates a <a>ByteString</a> of the specified size using a pure
--   pseudo-random number generator. See <tt>uniformByteString</tt> for the
--   monadic version.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random
--   
--   &gt;&gt;&gt; import Data.ByteString
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; unpack . fst . genByteString 10 $ pureGen
--   [51,123,251,37,49,167,90,109,1,4]
--   </pre>
genByteString :: RandomGen g => Int -> g -> (ByteString, g)

-- | The class of types for which uniformly distributed values can be
--   generated.
--   
--   <a>Random</a> exists primarily for backwards compatibility with
--   version 1.1 of this library. In new code, use the better specified
--   <a>Uniform</a> and <a>UniformRange</a> instead.
class Random a

-- | Takes a range <i>(lo,hi)</i> and a pseudo-random number generator
--   <i>g</i>, and returns a pseudo-random value uniformly distributed over
--   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)

-- | Takes a range <i>(lo,hi)</i> and a pseudo-random number generator
--   <i>g</i>, and returns a pseudo-random value uniformly distributed over
--   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, UniformRange a) => (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)

-- | 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, Uniform a) => g -> (a, g)

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

-- | The class of types for which a uniformly distributed value can be
--   drawn from all possible values of the type.
class Uniform a

-- | The class of types for which a uniformly distributed value can be
--   drawn from a range.
class UniformRange a

-- | The standard pseudo-random number generator.
data StdGen

-- | Constructs a <a>StdGen</a> deterministically.
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 pseudo-random integer between 1 and 6:
--   
--   <pre>
--   rollDice :: IO Int
--   rollDice = getStdRandom (randomR (1,6))
--   </pre>
getStdRandom :: MonadIO m => (StdGen -> (a, StdGen)) -> m a

-- | Gets the global pseudo-random number generator.
getStdGen :: MonadIO m => m StdGen

-- | Sets the global pseudo-random number generator.
setStdGen :: MonadIO m => StdGen -> m ()

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

-- | A variant of <a>random</a> that uses the global pseudo-random number
--   generator.
randomIO :: (Random a, MonadIO m) => m a

-- | A variant of <a>randomR</a> that uses the global pseudo-random number
--   generator.
randomRIO :: (Random a, MonadIO m) => (a, a) -> m a
instance System.Random.Random GHC.Integer.Type.Integer
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.Int
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 Foreign.C.Types.CFloat
instance System.Random.Random Foreign.C.Types.CDouble
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


-- | This library deals with the common task of pseudo-random number
--   generation.
module System.Random.Stateful

-- | <a>StatefulGen</a> is an interface to monadic pseudo-random number
--   generators.
class Monad m => StatefulGen g m

-- | <tt>uniformWord32R upperBound g</tt> generates a <a>Word32</a> that is
--   uniformly distributed over the range <tt>[0, upperBound]</tt>.
uniformWord32R :: StatefulGen g m => Word32 -> g -> m Word32

-- | <tt>uniformWord64R upperBound g</tt> generates a <a>Word64</a> that is
--   uniformly distributed over the range <tt>[0, upperBound]</tt>.
uniformWord64R :: StatefulGen g m => Word64 -> g -> m Word64

-- | Generates a <a>Word8</a> that is uniformly distributed over the entire
--   <a>Word8</a> range.
--   
--   The default implementation extracts a <a>Word8</a> from
--   <a>uniformWord32</a>.
uniformWord8 :: StatefulGen g m => g -> m Word8

-- | Generates a <a>Word16</a> that is uniformly distributed over the
--   entire <a>Word16</a> range.
--   
--   The default implementation extracts a <a>Word16</a> from
--   <a>uniformWord32</a>.
uniformWord16 :: StatefulGen g m => g -> m Word16

-- | Generates a <a>Word32</a> that is uniformly distributed over the
--   entire <a>Word32</a> range.
--   
--   The default implementation extracts a <a>Word32</a> from
--   <a>uniformWord64</a>.
uniformWord32 :: StatefulGen g m => g -> m Word32

-- | Generates a <a>Word64</a> that is uniformly distributed over the
--   entire <a>Word64</a> range.
--   
--   The default implementation combines two <a>Word32</a> from
--   <a>uniformWord32</a> into one <a>Word64</a>.
uniformWord64 :: StatefulGen g m => g -> m Word64

-- | <tt>uniformShortByteString n g</tt> generates a <a>ShortByteString</a>
--   of length <tt>n</tt> filled with pseudo-random bytes.
uniformShortByteString :: StatefulGen g m => Int -> g -> m ShortByteString

-- | <tt>uniformShortByteString n g</tt> generates a <a>ShortByteString</a>
--   of length <tt>n</tt> filled with pseudo-random bytes.
uniformShortByteString :: (StatefulGen g m, MonadIO m) => Int -> g -> m ShortByteString

-- | This class is designed for stateful pseudo-random number generators
--   that can be saved as and restored from an immutable data type.
class StatefulGen (MutableGen f m) m => FrozenGen f m where {
    
    -- | Represents the state of the pseudo-random number generator for use
    --   with <a>thawGen</a> and <a>freezeGen</a>.
    type family MutableGen f m = (g :: Type) | g -> f;
}

-- | Saves the state of the pseudo-random number generator as a frozen
--   seed.
freezeGen :: FrozenGen f m => MutableGen f m -> m f

-- | Restores the pseudo-random number generator from its frozen seed.
thawGen :: FrozenGen f m => f -> m (MutableGen f m)

-- | Interface to operations on <a>RandomGen</a> wrappers like
--   <a>IOGenM</a> and <a>StateGenM</a>.
class (RandomGen r, StatefulGen g m) => RandomGenM g r m | g -> r
applyRandomGenM :: RandomGenM g r m => (r -> (a, r)) -> g -> m a

-- | Runs a mutable pseudo-random number generator from its <tt>Frozen</tt>
--   state.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Int (Int8)
--   
--   &gt;&gt;&gt; withMutableGen (IOGen (mkStdGen 217)) (uniformListM 5) :: IO ([Int8], IOGen StdGen)
--   ([-74,37,-50,-2,3],IOGen {unIOGen = StdGen {unStdGen = SMGen 4273268533320920145 15251669095119325999}})
--   </pre>
withMutableGen :: FrozenGen f m => f -> (MutableGen f m -> m a) -> m (a, f)

-- | Same as <a>withMutableGen</a>, but only returns the generated value.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; withMutableGen_ (IOGen pureGen) (uniformRM (1 :: Int, 6 :: Int))
--   4
--   </pre>
withMutableGen_ :: FrozenGen f m => f -> (MutableGen f m -> m a) -> m a

-- | Generates a pseudo-random value using monadic interface and
--   <a>Random</a> instance.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; g &lt;- newIOGenM pureGen
--   
--   &gt;&gt;&gt; randomM g :: IO Double
--   0.5728354935654512
--   </pre>
randomM :: (RandomGenM g r m, Random a) => g -> m a

-- | Generates a pseudo-random value using monadic interface and
--   <a>Random</a> instance.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; g &lt;- newIOGenM pureGen
--   
--   &gt;&gt;&gt; randomRM (1, 100) g :: IO Int
--   52
--   </pre>
randomRM :: (RandomGenM g r m, Random a) => (a, a) -> g -> m a

-- | Splits a pseudo-random number generator into two. Overwrites the
--   mutable wrapper with one of the resulting generators and returns the
--   other.
splitGenM :: RandomGenM g r m => g -> m r

-- | Wrapper for pure state gen, which acts as an immutable seed for the
--   corresponding stateful generator <a>StateGenM</a>
newtype StateGen g
StateGen :: g -> StateGen g
[unStateGen] :: StateGen g -> g

-- | Opaque data type that carries the type of a pure pseudo-random number
--   generator.
data StateGenM g
StateGenM :: StateGenM g

-- | Runs a monadic generating action in the <a>State</a> monad using a
--   pure pseudo-random number generator.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; runStateGen pureGen randomM :: (Int, StdGen)
--   (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--   </pre>
runStateGen :: RandomGen g => g -> (StateGenM g -> State g a) -> (a, g)

-- | Runs a monadic generating action in the <a>State</a> monad using a
--   pure pseudo-random number generator. Returns only the resulting
--   pseudo-random value.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; runStateGen_ pureGen  randomM :: Int
--   7879794327570578227
--   </pre>
runStateGen_ :: RandomGen g => g -> (StateGenM g -> State g a) -> a

-- | Runs a monadic generating action in the <a>StateT</a> monad using a
--   pure pseudo-random number generator.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; runStateGenT pureGen randomM :: IO (Int, StdGen)
--   (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--   </pre>
runStateGenT :: RandomGen g => g -> (StateGenM g -> StateT g m a) -> m (a, g)

-- | Runs a monadic generating action in the <a>StateT</a> monad using a
--   pure pseudo-random number generator. Returns only the resulting
--   pseudo-random value.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; runStateGenT_ pureGen randomM :: IO Int
--   7879794327570578227
--   </pre>
runStateGenT_ :: (RandomGen g, Functor f) => g -> (StateGenM g -> StateT g f a) -> f a

-- | Runs a monadic generating action in the <a>ST</a> monad using a pure
--   pseudo-random number generator.
runStateGenST :: RandomGen g => g -> (forall s. StateGenM g -> StateT g (ST s) a) -> (a, g)

-- | Frozen version of mutable <a>AtomicGenM</a> generator
newtype AtomicGen g
AtomicGen :: g -> AtomicGen g
[unAtomicGen] :: AtomicGen g -> g

-- | Wraps an <a>IORef</a> that holds a pure pseudo-random number
--   generator. All operations are performed atomically.
--   
--   <ul>
--   <li><a>AtomicGenM</a> is safe in the presence of exceptions and
--   concurrency.</li>
--   <li><a>AtomicGenM</a> is the slowest of the monadic adapters due to
--   the overhead of its atomic operations.</li>
--   </ul>
newtype AtomicGenM g
AtomicGenM :: IORef g -> AtomicGenM g
[unAtomicGenM] :: AtomicGenM g -> IORef g

-- | Creates a new <a>AtomicGenM</a>.
newAtomicGenM :: MonadIO m => g -> m (AtomicGenM g)

-- | Atomically applies a pure operation to the wrapped pseudo-random
--   number generator.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; g &lt;- newAtomicGenM pureGen
--   
--   &gt;&gt;&gt; applyAtomicGen random g :: IO Int
--   7879794327570578227
--   </pre>
applyAtomicGen :: MonadIO m => (g -> (a, g)) -> AtomicGenM g -> m a

-- | Frozen version of mutable <a>IOGenM</a> generator
newtype IOGen g
IOGen :: g -> IOGen g
[unIOGen] :: IOGen g -> g

-- | Wraps an <a>IORef</a> that holds a pure pseudo-random number
--   generator.
--   
--   <ul>
--   <li><a>IOGenM</a> is safe in the presence of exceptions, but not
--   concurrency.</li>
--   <li><a>IOGenM</a> is slower than <a>StateGenM</a> due to the extra
--   pointer indirection.</li>
--   <li><a>IOGenM</a> is faster than <a>AtomicGenM</a> since the
--   <a>IORef</a> operations used by <a>IOGenM</a> are not atomic.</li>
--   </ul>
--   
--   An example use case is writing pseudo-random bytes into a file:
--   
--   <pre>
--   &gt;&gt;&gt; import UnliftIO.Temporary (withSystemTempFile)
--   
--   &gt;&gt;&gt; import Data.ByteString (hPutStr)
--   
--   &gt;&gt;&gt; let ioGen g = withSystemTempFile "foo.bin" $ \_ h -&gt; uniformRM (0, 100) g &gt;&gt;= flip uniformByteStringM g &gt;&gt;= hPutStr h
--   </pre>
--   
--   and then run it:
--   
--   <pre>
--   &gt;&gt;&gt; newIOGenM (mkStdGen 1729) &gt;&gt;= ioGen
--   </pre>
newtype IOGenM g
IOGenM :: IORef g -> IOGenM g
[unIOGenM] :: IOGenM g -> IORef g

-- | Creates a new <a>IOGenM</a>.
newIOGenM :: MonadIO m => g -> m (IOGenM g)

-- | Applies a pure operation to the wrapped pseudo-random number
--   generator.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; g &lt;- newIOGenM pureGen
--   
--   &gt;&gt;&gt; applyIOGen random g :: IO Int
--   7879794327570578227
--   </pre>
applyIOGen :: MonadIO m => (g -> (a, g)) -> IOGenM g -> m a

-- | Frozen version of mutable <a>STGenM</a> generator
newtype STGen g
STGen :: g -> STGen g
[unSTGen] :: STGen g -> g

-- | Wraps an <a>STRef</a> that holds a pure pseudo-random number
--   generator.
--   
--   <ul>
--   <li><a>STGenM</a> is safe in the presence of exceptions, but not
--   concurrency.</li>
--   <li><a>STGenM</a> is slower than <a>StateGenM</a> due to the extra
--   pointer indirection.</li>
--   </ul>
newtype STGenM g s
STGenM :: STRef s g -> STGenM g s
[unSTGenM] :: STGenM g s -> STRef s g

-- | Creates a new <a>STGenM</a>.
newSTGenM :: g -> ST s (STGenM g s)

-- | Applies a pure operation to the wrapped pseudo-random number
--   generator.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; (runSTGen pureGen (\g -&gt; applySTGen random g)) :: (Int, StdGen)
--   (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--   </pre>
applySTGen :: (g -> (a, g)) -> STGenM g s -> ST s a

-- | Runs a monadic generating action in the <a>ST</a> monad using a pure
--   pseudo-random number generator.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; (runSTGen pureGen (\g -&gt; applySTGen random g)) :: (Int, StdGen)
--   (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--   </pre>
runSTGen :: RandomGen g => g -> (forall s. STGenM g s -> ST s a) -> (a, g)

-- | Runs a monadic generating action in the <a>ST</a> monad using a pure
--   pseudo-random number generator. Returns only the resulting
--   pseudo-random value.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; (runSTGen_ pureGen (\g -&gt; applySTGen random g)) :: Int
--   7879794327570578227
--   </pre>
runSTGen_ :: RandomGen g => g -> (forall s. STGenM g s -> ST s a) -> a

-- | The class of types for which a uniformly distributed value can be
--   drawn from all possible values of the type.
class Uniform a

-- | Generates a value uniformly distributed over all possible values of
--   that type.
uniformM :: (Uniform a, StatefulGen g m) => g -> m a

-- | Generates a list of pseudo-random values.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; g &lt;- newIOGenM pureGen
--   
--   &gt;&gt;&gt; uniformListM 10 g :: IO [Bool]
--   [True,True,True,True,False,True,True,False,False,False]
--   </pre>
uniformListM :: (StatefulGen g m, Uniform a) => Int -> g -> m [a]

-- | The class of types for which a uniformly distributed value can be
--   drawn from a range.
class UniformRange a

-- | Generates a value uniformly distributed over the provided range, which
--   is interpreted as inclusive in the lower and upper bound.
--   
--   <ul>
--   <li><tt>uniformRM (1 :: Int, 4 :: Int)</tt> generates values uniformly
--   from the set &lt;math&gt;</li>
--   <li><tt>uniformRM (1 :: Float, 4 :: Float)</tt> generates values
--   uniformly from the set &lt;math&gt;</li>
--   </ul>
--   
--   The following law should hold to make the function always defined:
--   
--   <pre>
--   uniformRM (a, b) = uniformRM (b, a)
--   </pre>
uniformRM :: (UniformRange a, StatefulGen g m) => (a, a) -> g -> m a

-- | Efficiently generates a sequence of pseudo-random bytes in a platform
--   independent manner.
genShortByteStringIO :: MonadIO m => Int -> m Word64 -> m ShortByteString

-- | Same as <a>genShortByteStringIO</a>, but runs in <a>ST</a>.
genShortByteStringST :: Int -> ST s Word64 -> ST s ShortByteString

-- | Generates a pseudo-random <a>ByteString</a> of the specified size.
uniformByteStringM :: StatefulGen g m => Int -> g -> m ByteString

-- | Generates uniformly distributed <a>Double</a> in the range
--   &lt;math&gt;. Numbers are generated by generating uniform
--   <a>Word64</a> and dividing it by &lt;math&gt;. It's used to implement
--   <tt>UniformR</tt> instance for <a>Double</a>.
uniformDouble01M :: StatefulGen g m => g -> m Double

-- | Generates uniformly distributed <a>Double</a> in the range
--   &lt;math&gt;. Number is generated as &lt;math&gt;. Constant is 1/2 of
--   smallest nonzero value which could be generated by
--   <a>uniformDouble01M</a>.
uniformDoublePositive01M :: StatefulGen g m => g -> m Double

-- | Generates uniformly distributed <a>Float</a> in the range
--   &lt;math&gt;. Numbers are generated by generating uniform
--   <a>Word32</a> and dividing it by &lt;math&gt;. It's used to implement
--   <tt>UniformR</tt> instance for <a>Float</a>
uniformFloat01M :: StatefulGen g m => g -> m Float

-- | Generates uniformly distributed <a>Float</a> in the range
--   &lt;math&gt;. Number is generated as &lt;math&gt;. Constant is 1/2 of
--   smallest nonzero value which could be generated by
--   <a>uniformFloat01M</a>.
uniformFloatPositive01M :: StatefulGen g m => g -> m Float
instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (System.Random.Stateful.AtomicGen g)
instance Foreign.Storable.Storable g => Foreign.Storable.Storable (System.Random.Stateful.AtomicGen g)
instance System.Random.Internal.RandomGen g => System.Random.Internal.RandomGen (System.Random.Stateful.AtomicGen g)
instance GHC.Show.Show g => GHC.Show.Show (System.Random.Stateful.AtomicGen g)
instance GHC.Classes.Ord g => GHC.Classes.Ord (System.Random.Stateful.AtomicGen g)
instance GHC.Classes.Eq g => GHC.Classes.Eq (System.Random.Stateful.AtomicGen g)
instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (System.Random.Stateful.IOGen g)
instance Foreign.Storable.Storable g => Foreign.Storable.Storable (System.Random.Stateful.IOGen g)
instance System.Random.Internal.RandomGen g => System.Random.Internal.RandomGen (System.Random.Stateful.IOGen g)
instance GHC.Show.Show g => GHC.Show.Show (System.Random.Stateful.IOGen g)
instance GHC.Classes.Ord g => GHC.Classes.Ord (System.Random.Stateful.IOGen g)
instance GHC.Classes.Eq g => GHC.Classes.Eq (System.Random.Stateful.IOGen g)
instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (System.Random.Stateful.STGen g)
instance Foreign.Storable.Storable g => Foreign.Storable.Storable (System.Random.Stateful.STGen g)
instance System.Random.Internal.RandomGen g => System.Random.Internal.RandomGen (System.Random.Stateful.STGen g)
instance GHC.Show.Show g => GHC.Show.Show (System.Random.Stateful.STGen g)
instance GHC.Classes.Ord g => GHC.Classes.Ord (System.Random.Stateful.STGen g)
instance GHC.Classes.Eq g => GHC.Classes.Eq (System.Random.Stateful.STGen g)
instance System.Random.Internal.RandomGen g => System.Random.Internal.FrozenGen (System.Random.Stateful.STGen g) (GHC.ST.ST s)
instance System.Random.Internal.RandomGen r => System.Random.Stateful.RandomGenM (System.Random.Stateful.STGenM r s) r (GHC.ST.ST s)
instance System.Random.Internal.RandomGen g => System.Random.Internal.StatefulGen (System.Random.Stateful.STGenM g s) (GHC.ST.ST s)
instance (System.Random.Internal.RandomGen g, Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.FrozenGen (System.Random.Stateful.IOGen g) m
instance (System.Random.Internal.RandomGen r, Control.Monad.IO.Class.MonadIO m) => System.Random.Stateful.RandomGenM (System.Random.Stateful.IOGenM r) r m
instance (System.Random.Internal.RandomGen g, Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.StatefulGen (System.Random.Stateful.IOGenM g) m
instance (System.Random.Internal.RandomGen g, Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.FrozenGen (System.Random.Stateful.AtomicGen g) m
instance (System.Random.Internal.RandomGen r, Control.Monad.IO.Class.MonadIO m) => System.Random.Stateful.RandomGenM (System.Random.Stateful.AtomicGenM r) r m
instance (System.Random.Internal.RandomGen g, Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.StatefulGen (System.Random.Stateful.AtomicGenM g) m
instance (System.Random.Internal.RandomGen r, Control.Monad.State.Class.MonadState r m) => System.Random.Stateful.RandomGenM (System.Random.Internal.StateGenM r) r m
