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


-- | 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.runStateGen_</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.3.1


-- | 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 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)

-- | Fill in the supplied <a>MutableByteArray</a> with uniformly generated
--   random bytes. This function is unsafe because it is not required to do
--   any bounds checking. For a safe variant use
--   <a>uniformFillMutableByteArrayM</a> instead.
--   
--   Default type class implementation uses
--   <a>defaultUnsafeUniformFillMutableByteArray</a>.
unsafeUniformFillMutableByteArray :: RandomGen g => MutableByteArray s -> Int -> Int -> g -> ST s g

-- | 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.

-- | <i>Deprecated: In favor of <a>splitGen</a></i>
split :: RandomGen g => g -> (g, g)
($dmsplit) :: (RandomGen g, SplitGen g) => g -> (g, g)

-- | Pseudo-random generators that can be split into two separate and
--   independent psuedo-random generators should provide an instance for
--   this type class.
--   
--   Historically this functionality was included in the <a>RandomGen</a>
--   type class in the <a>split</a> function, however, few pseudo-random
--   generators possess this property of splittability. This lead the old
--   <a>split</a> function being usually implemented in terms of
--   <a>error</a>.
class RandomGen g => SplitGen g

-- | Returns two distinct pseudo-random number generators.
--   
--   Implementations should take care to ensure that the resulting
--   generators are not correlated.
splitGen :: SplitGen 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>
--   
--   You can use type applications to disambiguate the type of the
--   generated numbers:
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XTypeApplications
--   
--   &gt;&gt;&gt; uniform @Bool pureGen
--   (True,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--   </pre>
uniform :: (Uniform a, RandomGen g) => 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>
--   
--   You can use type applications to disambiguate the type of the
--   generated numbers:
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XTypeApplications
--   
--   &gt;&gt;&gt; uniformR @Int (1, 4) pureGen
--   (4,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--   </pre>
uniformR :: (UniformRange a, RandomGen g) => (a, a) -> g -> (a, g)

-- | The class of types for which random values can be generated. Most
--   instances of <a>Random</a> will produce values that are uniformly
--   distributed on the full range, but for those types without a
--   well-defined "full range" some sensible default subrange will be
--   selected.
--   
--   <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>, but usually the values
--   will simply get swapped.
--   
--   <pre>
--   &gt;&gt;&gt; let gen = mkStdGen 26
--   
--   &gt;&gt;&gt; fst $ randomR ('a', 'z') gen
--   'z'
--   
--   &gt;&gt;&gt; fst $ randomR ('a', 'z') gen
--   'z'
--   </pre>
--   
--   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.
--   
--   There is no requirement to follow the <tt>Ord</tt> instance and the
--   concept of range can be defined on per type basis. For example product
--   types will treat their values independently:
--   
--   <pre>
--   &gt;&gt;&gt; fst $ randomR (('a', 5.0), ('z', 10.0)) $ mkStdGen 26
--   ('z',5.22694980853051)
--   </pre>
--   
--   In case when a lawful range is desired <a>uniformR</a> should be used
--   instead.
randomR :: (Random a, RandomGen g) => (a, a) -> g -> (a, g)
($dmrandomR) :: (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 floating point types, the range is normally the 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)
($dmrandom) :: (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

-- | A type class for data with a finite number of inhabitants. This type
--   class is used in the default implementation of <a>Uniform</a>.
--   
--   Users are not supposed to write instances of <a>Finite</a> manually.
--   There is a default implementation in terms of <a>Generic</a> instead.
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XDeriveGeneric -XDeriveAnyClass
--   
--   &gt;&gt;&gt; import GHC.Generics (Generic)
--   
--   &gt;&gt;&gt; data MyBool = MyTrue | MyFalse deriving (Generic, Finite)
--   
--   &gt;&gt;&gt; data Action = Code MyBool | Eat (Maybe Bool) | Sleep deriving (Generic, Finite)
--   </pre>
class Finite a

-- | Construct a <a>Seed</a> from a <a>ByteArray</a> of expected length.
--   Whenever <a>ByteArray</a> does not match the <a>SeedSize</a> specified
--   by the pseudo-random generator, this function will <a>fail</a>.
mkSeed :: (SeedGen g, MonadFail m) => ByteArray -> m (Seed g)

-- | Just like <a>mkSeed</a>, but uses <tt>ByteString</tt> as argument.
--   Results in a memcopy of the seed.
mkSeedFromByteString :: (SeedGen g, MonadFail m) => ByteString -> m (Seed g)

-- | Convert a <a>Seed</a> to a list of 64bit words.
nonEmptyFromSeed :: SeedGen g => Seed g -> NonEmpty Word64

-- | Construct a seed from a list of 64-bit words. At most <a>SeedSize</a>
--   many bytes will be used.
nonEmptyToSeed :: SeedGen g => NonEmpty Word64 -> Seed g

-- | This is a function that shows the name of the generator type, which is
--   useful for error reporting.
seedGenTypeName :: SeedGen g => String

-- | Get the expected size of the <a>Seed</a> in number bytes
seedSize :: SeedGen g => Int

-- | Just like <a>seedSize</a>, except it accepts a proxy as an argument.
seedSizeProxy :: forall proxy g. SeedGen g => proxy g -> Int

-- | Unwrap the <a>Seed</a> and get the underlying <a>ByteArray</a>
unSeed :: Seed g -> ByteArray

-- | Just like <a>unSeed</a>, but produced a <tt>ByteString</tt>. Results
--   in a memcopy of the seed.
unSeedToByteString :: Seed g -> ByteString

-- | Helper function that allows for operating directly on the <a>Seed</a>,
--   while supplying a function that uses the pseudo-random number
--   generator that is constructed from that <a>Seed</a>.
--   
--   <h4><b>Example</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; :set -XTypeApplications
--   
--   &gt;&gt;&gt; import System.Random
--   
--   &gt;&gt;&gt; withSeed (nonEmptyToSeed (pure 2024) :: Seed StdGen) (uniform @Int)
--   (1039666877624726199,Seed [0xe9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
--   </pre>
withSeed :: SeedGen g => Seed g -> (g -> (a, g)) -> (a, Seed g)

-- | Read the seed from a file and use it for constructing a pseudo-random
--   number generator. After supplied action has been applied to the
--   constructed generator, the resulting generator will be converted back
--   to a seed and written to the same file.
withSeedFile :: (SeedGen g, MonadIO m) => FilePath -> (Seed g -> m (a, Seed g)) -> m a

-- | Same as <a>withSeed</a>, except it is useful with monadic computation
--   and frozen generators.
--   
--   See <a>withSeedMutableGen</a> for a helper that also handles seeds for
--   mutable pseduo-random number generators.
withSeedM :: (SeedGen g, Functor f) => Seed g -> (g -> f (a, g)) -> f (a, Seed g)

-- | This is a binary form of pseudo-random number generator's state. It is
--   designed to be safe and easy to use for input/output operations like
--   restoring from file, transmitting over the network, etc.
--   
--   Constructor is not exported, becasue it is important for
--   implementation to enforce the invariant of the underlying byte array
--   being of the exact same length as the generator has specified in
--   <a>SeedSize</a>. Use <a>mkSeed</a> and <a>unSeed</a> to get access to
--   the raw bytes in a safe manner.
data Seed g

-- | Interface for converting a pure pseudo-random number generator to and
--   from non-empty sequence of bytes. Seeds are stored in Little-Endian
--   order regardless of the platform it is being used on, which provides
--   cross-platform compatibility, while providing optimal performance for
--   the most common platform type.
--   
--   Conversion to and from a <a>Seed</a> serves as a building block for
--   implementing serialization for any pure or frozen pseudo-random number
--   generator.
--   
--   It is not trivial to implement platform independence. For this reason
--   this type class has two alternative ways of creating an instance for
--   this class. The easiest way for constructing a platform indepent seed
--   is by converting the inner state of a generator to and from a list of
--   64 bit words using <a>toSeed64</a> and <a>fromSeed64</a> respectively.
--   In that case cross-platform support will be handled automaticaly.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XDataKinds -XTypeFamilies
--   
--   &gt;&gt;&gt; import Data.Word (Word8, Word32)
--   
--   &gt;&gt;&gt; import Data.Bits ((.|.), shiftR, shiftL)
--   
--   &gt;&gt;&gt; import Data.List.NonEmpty (NonEmpty ((:|)))
--   
--   &gt;&gt;&gt; data FiveByteGen = FiveByteGen Word8 Word32 deriving Show
--   
--   &gt;&gt;&gt; :{
--   instance SeedGen FiveByteGen where
--     type SeedSize FiveByteGen = 5
--     fromSeed64 (w64 :| _) =
--       FiveByteGen (fromIntegral (w64 `shiftR` 32)) (fromIntegral w64)
--     toSeed64 (FiveByteGen x1 x4) =
--       let w64 = (fromIntegral x1 `shiftL` 32) .|. fromIntegral x4
--        in (w64 :| [])
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; FiveByteGen 0x80 0x01020304
--   FiveByteGen 128 16909060
--   
--   &gt;&gt;&gt; fromSeed (toSeed (FiveByteGen 0x80 0x01020304))
--   FiveByteGen 128 16909060
--   
--   &gt;&gt;&gt; toSeed (FiveByteGen 0x80 0x01020304)
--   Seed [0x04, 0x03, 0x02, 0x01, 0x80]
--   
--   &gt;&gt;&gt; toSeed64 (FiveByteGen 0x80 0x01020304)
--   549772722948 :| []
--   </pre>
--   
--   However, when performance is of utmost importance or default handling
--   of cross platform independence is not sufficient, then an adventurous
--   developer can try implementing conversion into bytes directly with
--   <a>toSeed</a> and <a>fromSeed</a>.
--   
--   Properties that must hold:
--   
--   <pre>
--   &gt; fromSeed (toSeed gen) == gen
--   </pre>
--   
--   <pre>
--   &gt; fromSeed64 (toSeed64 gen) == gen
--   </pre>
--   
--   Note, that there is no requirement for every <a>Seed</a> to roundtrip,
--   eg. this proprty does not even hold for <a>StdGen</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let seed = nonEmptyToSeed (0xab :| [0xff00]) :: Seed StdGen
--   
--   &gt;&gt;&gt; seed == toSeed (fromSeed seed)
--   False
--   </pre>
class (KnownNat SeedSize g, 1 <= SeedSize g, Typeable g) => SeedGen g where {
    
    -- | Number of bytes that is required for storing the full state of a
    --   pseudo-random number generator. It should be big enough to satisfy the
    --   roundtrip property:
    --   
    --   <pre>
    --   &gt; fromSeed (toSeed gen) == gen
    --   </pre>
    type SeedSize g :: Nat;
}

-- | Convert from a binary representation to a pseudo-random number
--   generator
fromSeed :: SeedGen g => Seed g -> g

-- | Convert to a binary representation of a pseudo-random number generator
toSeed :: SeedGen g => g -> Seed g

-- | Construct pseudo-random number generator from a list of words.
--   Whenever list does not have enough bytes to satisfy the
--   <a>SeedSize</a> requirement, it will be padded with zeros. On the
--   other hand when it has more than necessary, extra bytes will be
--   dropped.
--   
--   For example if <a>SeedSize</a> is set to 2, then only the lower 16
--   bits of the first element in the list will be used.
fromSeed64 :: SeedGen g => NonEmpty Word64 -> g

-- | Convert pseudo-random number generator to a list of words
--   
--   In case when <a>SeedSize</a> is not a multiple of 8, then the upper
--   bits of the last word in the list will be set to zero.
toSeed64 :: SeedGen g => g -> NonEmpty Word64

-- | Number of bytes that is required for storing the full state of a
--   pseudo-random number generator. It should be big enough to satisfy the
--   roundtrip property:
--   
--   <pre>
--   &gt; fromSeed (toSeed gen) == gen
--   </pre>
type family SeedSize g :: Nat

-- | Produce an infinite list of pseudo-random values. Integrates nicely
--   with list fusion. Naturally, there is no way to recover the final
--   generator, therefore either use <a>split</a> before calling
--   <a>uniforms</a> or use <a>uniformList</a> instead.
--   
--   Similar to <a>randoms</a>, except it relies on <a>Uniform</a> type
--   class instead of <a>Random</a>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; let gen = mkStdGen 2023
--   
--   &gt;&gt;&gt; import Data.Word (Word16)
--   
--   &gt;&gt;&gt; take 5 $ uniforms gen :: [Word16]
--   [56342,15850,25292,14347,13919]
--   </pre>
uniforms :: (Uniform a, RandomGen g) => g -> [a]

-- | Produce an infinite list of pseudo-random values in a specified range.
--   Same as <a>uniforms</a>, integrates nicely with list fusion. There is
--   no way to recover the final generator, therefore either use
--   <a>split</a> before calling <a>uniformRs</a> or use
--   <a>uniformListR</a> instead.
--   
--   Similar to <a>randomRs</a>, except it relies on <a>UniformRange</a>
--   type class instead of <a>Random</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; let gen = mkStdGen 2023
--   
--   &gt;&gt;&gt; take 5 $ uniformRs (10, 100) gen :: [Int]
--   [32,86,21,57,39]
--   </pre>
uniformRs :: (UniformRange a, RandomGen g) => (a, a) -> g -> [a]

-- | Produce a list of the supplied length with elements generated
--   uniformly.
--   
--   See <a>uniformListM</a> for a stateful counterpart.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; let gen = mkStdGen 2023
--   
--   &gt;&gt;&gt; import Data.Word (Word16)
--   
--   &gt;&gt;&gt; uniformList 5 gen :: ([Word16], StdGen)
--   ([56342,15850,25292,14347,13919],StdGen {unStdGen = SMGen 6446154349414395371 1920468677557965761})
--   </pre>
uniformList :: (Uniform a, RandomGen g) => Int -> g -> ([a], g)

-- | Produce a list of the supplied length with elements generated
--   uniformly.
--   
--   See <a>uniformListM</a> for a stateful counterpart.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; let gen = mkStdGen 2023
--   
--   &gt;&gt;&gt; uniformListR 10 (20, 30) gen :: ([Int], StdGen)
--   ([26,30,27,24,30,25,27,21,27,27],StdGen {unStdGen = SMGen 12965503083958398648 1920468677557965761})
--   </pre>
uniformListR :: (UniformRange a, RandomGen g) => Int -> (a, a) -> g -> ([a], g)

-- | Shuffle elements of a list in a uniformly random order.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; uniformShuffleList "ELVIS" $ mkStdGen 252
--   ("LIVES",StdGen {unStdGen = SMGen 17676540583805057877 5302934877338729551})
--   </pre>
uniformShuffleList :: RandomGen g => [a] -> g -> ([a], g)

-- | Efficiently generates a sequence of pseudo-random bytes in a platform
--   independent manner.
uniformByteArray :: RandomGen g => Bool -> Int -> g -> (ByteArray, g)

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

-- | Same as <tt><a>uniformByteArray</a> <a>False</a></tt>, but for
--   <a>ShortByteString</a>.
--   
--   Returns a <a>ShortByteString</a> of length <tt>n</tt> filled with
--   pseudo-random bytes.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random
--   
--   &gt;&gt;&gt; import Data.ByteString.Short (unpack)
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; unpack . fst $ uniformShortByteString 10 pureGen
--   [51,123,251,37,49,167,90,109,1,4]
--   </pre>
uniformShortByteString :: RandomGen g => Int -> g -> (ShortByteString, g)

-- | Fill in a slice of a mutable byte array with randomly generated bytes.
--   This function does not fail, instead it clamps the offset and number
--   of bytes to generate into a valid range.
uniformFillMutableByteArray :: RandomGen g => MutableByteArray s -> Int -> Int -> g -> ST s g

-- | Generates a <a>ByteString</a> of the specified size using a pure
--   pseudo-random number generator. See <tt>uniformByteStringM</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; :seti -Wno-deprecations
--   
--   &gt;&gt;&gt; unpack . fst . genByteString 10 $ pureGen
--   [51,123,251,37,49,167,90,109,1,4]
--   </pre>

-- | <i>Deprecated: In favor of <a>uniformByteString</a></i>
genByteString :: RandomGen g => Int -> g -> (ByteString, g)

-- | Same as <tt><a>uniformByteArray</a> <a>False</a></tt>, but for
--   <a>ShortByteString</a>.
--   
--   <tt>genShortByteString n g</tt> returns a <a>ShortByteString</a> of
--   length <tt>n</tt> filled with pseudo-random bytes.
--   
--   <i>Note</i> - This function will be removed from the type class in the
--   next major release as it is no longer needed because of
--   <a>unsafeUniformFillMutableByteArray</a>.

-- | <i>Deprecated: In favor of <a>uniformShortByteString</a></i>
genShortByteString :: RandomGen g => Int -> g -> (ShortByteString, g)

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

-- | Constructs a <a>StdGen</a> deterministically from an <a>Int</a> seed.
--   See <a>mkStdGen64</a> for a <a>Word64</a> variant that is architecture
--   agnostic.
mkStdGen :: Int -> StdGen

-- | Constructs a <a>StdGen</a> deterministically from a <a>Word64</a>
--   seed.
--   
--   The difference between <a>mkStdGen</a> is that <a>mkStdGen64</a> will
--   work the same on 64-bit and 32-bit architectures, while the former can
--   only use 32-bit of information for initializing the psuedo-random
--   number generator on 32-bit operating systems
mkStdGen64 :: Word64 -> StdGen

-- | Initialize <a>StdGen</a> using system entropy (i.e.
--   <tt>/dev/urandom</tt>) when it is available, while falling back on
--   using system time as the seed.
initStdGen :: MonadIO m => m 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>
--   produces a pseudo-random integer between 1 and 6:
--   
--   <pre>
--   &gt;&gt;&gt; rollDice = getStdRandom (randomR (1, 6))
--   
--   &gt;&gt;&gt; replicateM 10 (rollDice :: IO Int)
--   [1,1,1,4,5,6,1,2,2,5]
--   </pre>
--   
--   This is an outdated function and it is recommended to switch to its
--   equivalent <a>applyAtomicGen</a> instead, possibly with the
--   <a>globalStdGen</a> if relying on the global state is acceptable.
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; rollDice = applyAtomicGen (uniformR (1, 6)) globalStdGen
--   
--   &gt;&gt;&gt; replicateM 10 (rollDice :: IO Int)
--   [2,1,1,5,4,3,6,6,3,2]
--   </pre>
getStdRandom :: MonadIO m => (StdGen -> (a, StdGen)) -> m a

-- | Gets the global pseudo-random number generator. Extracts the contents
--   of <a>globalStdGen</a>
getStdGen :: MonadIO m => m StdGen

-- | Sets the global pseudo-random number generator. Overwrites the
--   contents of <a>globalStdGen</a>
setStdGen :: MonadIO m => StdGen -> m ()

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

-- | A variant of <a>randomM</a> that uses the global pseudo-random number
--   generator <a>globalStdGen</a>.
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Int
--   
--   &gt;&gt;&gt; randomIO :: IO Int32
--   114794456
--   </pre>
--   
--   This function is equivalent to <tt><a>getStdRandom</a>
--   <a>random</a></tt> and is included in this interface for historical
--   reasons and backwards compatibility. It is recommended to use
--   <a>uniformM</a> instead, possibly with the <a>globalStdGen</a> if
--   relying on the global state is acceptable.
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; uniformM globalStdGen :: IO Int32
--   -1768545016
--   </pre>
randomIO :: (Random a, MonadIO m) => m a

-- | A variant of <a>randomRM</a> that uses the global pseudo-random number
--   generator <a>globalStdGen</a>
--   
--   <pre>
--   &gt;&gt;&gt; randomRIO (2020, 2100) :: IO Int
--   2028
--   </pre>
--   
--   Similar to <a>randomIO</a>, this function is equivalent to
--   <tt><a>getStdRandom</a> <a>randomR</a></tt> and is included in this
--   interface for historical reasons and backwards compatibility. It is
--   recommended to use <a>uniformRM</a> instead, possibly with the
--   <a>globalStdGen</a> if relying on the global state is acceptable.
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; uniformRM (2020, 2100) globalStdGen :: IO Int
--   2044
--   </pre>
randomRIO :: (Random a, MonadIO m) => (a, a) -> m a

-- | 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 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)
instance System.Random.Random GHC.Types.Bool
instance System.Random.Random GHC.Internal.Foreign.C.Types.CBool
instance System.Random.Random GHC.Internal.Foreign.C.Types.CChar
instance System.Random.Random GHC.Internal.Foreign.C.Types.CDouble
instance System.Random.Random GHC.Internal.Foreign.C.Types.CFloat
instance System.Random.Random GHC.Internal.Foreign.C.Types.CInt
instance System.Random.Random GHC.Internal.Foreign.C.Types.CIntMax
instance System.Random.Random GHC.Internal.Foreign.C.Types.CIntPtr
instance System.Random.Random GHC.Internal.Foreign.C.Types.CLLong
instance System.Random.Random GHC.Internal.Foreign.C.Types.CLong
instance System.Random.Random GHC.Internal.Foreign.C.Types.CPtrdiff
instance System.Random.Random GHC.Internal.Foreign.C.Types.CSChar
instance System.Random.Random GHC.Internal.Foreign.C.Types.CShort
instance System.Random.Random GHC.Internal.Foreign.C.Types.CSigAtomic
instance System.Random.Random GHC.Internal.Foreign.C.Types.CSize
instance System.Random.Random GHC.Internal.Foreign.C.Types.CUChar
instance System.Random.Random GHC.Internal.Foreign.C.Types.CUInt
instance System.Random.Random GHC.Internal.Foreign.C.Types.CUIntMax
instance System.Random.Random GHC.Internal.Foreign.C.Types.CUIntPtr
instance System.Random.Random GHC.Internal.Foreign.C.Types.CULLong
instance System.Random.Random GHC.Internal.Foreign.C.Types.CULong
instance System.Random.Random GHC.Internal.Foreign.C.Types.CUShort
instance System.Random.Random GHC.Internal.Foreign.C.Types.CWchar
instance System.Random.Random GHC.Types.Char
instance System.Random.Random GHC.Types.Double
instance System.Random.Random GHC.Types.Float
instance System.Random.Random GHC.Types.Int
instance System.Random.Random GHC.Internal.Int.Int16
instance System.Random.Random GHC.Internal.Int.Int32
instance System.Random.Random GHC.Internal.Int.Int64
instance System.Random.Random GHC.Internal.Int.Int8
instance System.Random.Random GHC.Num.Integer.Integer
instance (System.Random.Random a, System.Random.Random b) => System.Random.Random (a, b)
instance (System.Random.Random a, System.Random.Random b, System.Random.Random c) => System.Random.Random (a, b, c)
instance (System.Random.Random a, System.Random.Random b, System.Random.Random c, System.Random.Random d) => System.Random.Random (a, b, c, d)
instance (System.Random.Random a, System.Random.Random b, System.Random.Random c, System.Random.Random d, System.Random.Random e) => System.Random.Random (a, b, c, d, e)
instance (System.Random.Random a, System.Random.Random b, System.Random.Random c, System.Random.Random d, System.Random.Random e, System.Random.Random f) => System.Random.Random (a, b, c, d, e, f)
instance (System.Random.Random a, System.Random.Random b, System.Random.Random c, System.Random.Random d, System.Random.Random e, System.Random.Random f, System.Random.Random g) => System.Random.Random (a, b, c, d, e, f, g)
instance System.Random.Random GHC.Types.Word
instance System.Random.Random GHC.Internal.Word.Word16
instance System.Random.Random GHC.Internal.Word.Word32
instance System.Random.Random GHC.Internal.Word.Word64
instance System.Random.Random GHC.Internal.Word.Word8


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

-- | Generates a <a>ByteString</a> of the specified size using a pure
--   pseudo-random number generator. See <tt>uniformByteStringM</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; :seti -Wno-deprecations
--   
--   &gt;&gt;&gt; unpack . fst . genByteString 10 $ pureGen
--   [51,123,251,37,49,167,90,109,1,4]
--   </pre>

-- | <i>Deprecated: In favor of <a>uniformByteString</a></i>
genByteString :: RandomGen g => Int -> g -> (ByteString, g)

-- | Gets the global pseudo-random number generator. Extracts the contents
--   of <a>globalStdGen</a>
getStdGen :: MonadIO m => m 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>
--   produces a pseudo-random integer between 1 and 6:
--   
--   <pre>
--   &gt;&gt;&gt; rollDice = getStdRandom (randomR (1, 6))
--   
--   &gt;&gt;&gt; replicateM 10 (rollDice :: IO Int)
--   [1,1,1,4,5,6,1,2,2,5]
--   </pre>
--   
--   This is an outdated function and it is recommended to switch to its
--   equivalent <a>applyAtomicGen</a> instead, possibly with the
--   <a>globalStdGen</a> if relying on the global state is acceptable.
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; rollDice = applyAtomicGen (uniformR (1, 6)) globalStdGen
--   
--   &gt;&gt;&gt; replicateM 10 (rollDice :: IO Int)
--   [2,1,1,5,4,3,6,6,3,2]
--   </pre>
getStdRandom :: MonadIO m => (StdGen -> (a, StdGen)) -> m a

-- | Initialize <a>StdGen</a> using system entropy (i.e.
--   <tt>/dev/urandom</tt>) when it is available, while falling back on
--   using system time as the seed.
initStdGen :: MonadIO m => m StdGen

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

-- | A variant of <a>randomM</a> that uses the global pseudo-random number
--   generator <a>globalStdGen</a>.
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Int
--   
--   &gt;&gt;&gt; randomIO :: IO Int32
--   114794456
--   </pre>
--   
--   This function is equivalent to <tt><a>getStdRandom</a>
--   <a>random</a></tt> and is included in this interface for historical
--   reasons and backwards compatibility. It is recommended to use
--   <a>uniformM</a> instead, possibly with the <a>globalStdGen</a> if
--   relying on the global state is acceptable.
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; uniformM globalStdGen :: IO Int32
--   -1768545016
--   </pre>
randomIO :: (Random a, MonadIO m) => m a

-- | A variant of <a>randomRM</a> that uses the global pseudo-random number
--   generator <a>globalStdGen</a>
--   
--   <pre>
--   &gt;&gt;&gt; randomRIO (2020, 2100) :: IO Int
--   2028
--   </pre>
--   
--   Similar to <a>randomIO</a>, this function is equivalent to
--   <tt><a>getStdRandom</a> <a>randomR</a></tt> and is included in this
--   interface for historical reasons and backwards compatibility. It is
--   recommended to use <a>uniformRM</a> instead, possibly with the
--   <a>globalStdGen</a> if relying on the global state is acceptable.
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; uniformRM (2020, 2100) globalStdGen :: IO Int
--   2044
--   </pre>
randomRIO :: (Random a, MonadIO m) => (a, a) -> m a

-- | Sets the global pseudo-random number generator. Overwrites the
--   contents of <a>globalStdGen</a>
setStdGen :: MonadIO m => StdGen -> m ()

-- | 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>
--   
--   You can use type applications to disambiguate the type of the
--   generated numbers:
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XTypeApplications
--   
--   &gt;&gt;&gt; uniform @Bool pureGen
--   (True,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--   </pre>
uniform :: (Uniform a, RandomGen g) => g -> (a, g)

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

-- | Fill in a slice of a mutable byte array with randomly generated bytes.
--   This function does not fail, instead it clamps the offset and number
--   of bytes to generate into a valid range.
uniformFillMutableByteArray :: RandomGen g => MutableByteArray s -> Int -> Int -> g -> ST s g

-- | Produce a list of the supplied length with elements generated
--   uniformly.
--   
--   See <a>uniformListM</a> for a stateful counterpart.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; let gen = mkStdGen 2023
--   
--   &gt;&gt;&gt; import Data.Word (Word16)
--   
--   &gt;&gt;&gt; uniformList 5 gen :: ([Word16], StdGen)
--   ([56342,15850,25292,14347,13919],StdGen {unStdGen = SMGen 6446154349414395371 1920468677557965761})
--   </pre>
uniformList :: (Uniform a, RandomGen g) => Int -> g -> ([a], g)

-- | Produce a list of the supplied length with elements generated
--   uniformly.
--   
--   See <a>uniformListM</a> for a stateful counterpart.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; let gen = mkStdGen 2023
--   
--   &gt;&gt;&gt; uniformListR 10 (20, 30) gen :: ([Int], StdGen)
--   ([26,30,27,24,30,25,27,21,27,27],StdGen {unStdGen = SMGen 12965503083958398648 1920468677557965761})
--   </pre>
uniformListR :: (UniformRange a, RandomGen g) => Int -> (a, 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>
--   
--   You can use type applications to disambiguate the type of the
--   generated numbers:
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XTypeApplications
--   
--   &gt;&gt;&gt; uniformR @Int (1, 4) pureGen
--   (4,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--   </pre>
uniformR :: (UniformRange a, RandomGen g) => (a, a) -> g -> (a, g)

-- | Produce an infinite list of pseudo-random values in a specified range.
--   Same as <a>uniforms</a>, integrates nicely with list fusion. There is
--   no way to recover the final generator, therefore either use
--   <a>split</a> before calling <a>uniformRs</a> or use
--   <a>uniformListR</a> instead.
--   
--   Similar to <a>randomRs</a>, except it relies on <a>UniformRange</a>
--   type class instead of <a>Random</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; let gen = mkStdGen 2023
--   
--   &gt;&gt;&gt; take 5 $ uniformRs (10, 100) gen :: [Int]
--   [32,86,21,57,39]
--   </pre>
uniformRs :: (UniformRange a, RandomGen g) => (a, a) -> g -> [a]

-- | Shuffle elements of a list in a uniformly random order.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; uniformShuffleList "ELVIS" $ mkStdGen 252
--   ("LIVES",StdGen {unStdGen = SMGen 17676540583805057877 5302934877338729551})
--   </pre>
uniformShuffleList :: RandomGen g => [a] -> g -> ([a], g)

-- | Produce an infinite list of pseudo-random values. Integrates nicely
--   with list fusion. Naturally, there is no way to recover the final
--   generator, therefore either use <a>split</a> before calling
--   <a>uniforms</a> or use <a>uniformList</a> instead.
--   
--   Similar to <a>randoms</a>, except it relies on <a>Uniform</a> type
--   class instead of <a>Random</a>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; let gen = mkStdGen 2023
--   
--   &gt;&gt;&gt; import Data.Word (Word16)
--   
--   &gt;&gt;&gt; take 5 $ uniforms gen :: [Word16]
--   [56342,15850,25292,14347,13919]
--   </pre>
uniforms :: (Uniform a, RandomGen g) => g -> [a]

-- | Constructs a <a>StdGen</a> deterministically from an <a>Int</a> seed.
--   See <a>mkStdGen64</a> for a <a>Word64</a> variant that is architecture
--   agnostic.
mkStdGen :: Int -> StdGen

-- | Constructs a <a>StdGen</a> deterministically from a <a>Word64</a>
--   seed.
--   
--   The difference between <a>mkStdGen</a> is that <a>mkStdGen64</a> will
--   work the same on 64-bit and 32-bit architectures, while the former can
--   only use 32-bit of information for initializing the psuedo-random
--   number generator on 32-bit operating systems
mkStdGen64 :: Word64 -> StdGen

-- | Efficiently generates a sequence of pseudo-random bytes in a platform
--   independent manner.
uniformByteArray :: RandomGen g => Bool -> Int -> g -> (ByteArray, g)

-- | Construct a <a>Seed</a> from a <a>ByteArray</a> of expected length.
--   Whenever <a>ByteArray</a> does not match the <a>SeedSize</a> specified
--   by the pseudo-random generator, this function will <a>fail</a>.
mkSeed :: (SeedGen g, MonadFail m) => ByteArray -> m (Seed g)

-- | Just like <a>mkSeed</a>, but uses <tt>ByteString</tt> as argument.
--   Results in a memcopy of the seed.
mkSeedFromByteString :: (SeedGen g, MonadFail m) => ByteString -> m (Seed g)

-- | Convert a <a>Seed</a> to a list of 64bit words.
nonEmptyFromSeed :: SeedGen g => Seed g -> NonEmpty Word64

-- | Construct a seed from a list of 64-bit words. At most <a>SeedSize</a>
--   many bytes will be used.
nonEmptyToSeed :: SeedGen g => NonEmpty Word64 -> Seed g

-- | This is a function that shows the name of the generator type, which is
--   useful for error reporting.
seedGenTypeName :: SeedGen g => String

-- | Get the expected size of the <a>Seed</a> in number bytes
seedSize :: SeedGen g => Int

-- | Just like <a>seedSize</a>, except it accepts a proxy as an argument.
seedSizeProxy :: forall proxy g. SeedGen g => proxy g -> Int

-- | Unwrap the <a>Seed</a> and get the underlying <a>ByteArray</a>
unSeed :: Seed g -> ByteArray

-- | Just like <a>unSeed</a>, but produced a <tt>ByteString</tt>. Results
--   in a memcopy of the seed.
unSeedToByteString :: Seed g -> ByteString

-- | Helper function that allows for operating directly on the <a>Seed</a>,
--   while supplying a function that uses the pseudo-random number
--   generator that is constructed from that <a>Seed</a>.
--   
--   <h4><b>Example</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; :set -XTypeApplications
--   
--   &gt;&gt;&gt; import System.Random
--   
--   &gt;&gt;&gt; withSeed (nonEmptyToSeed (pure 2024) :: Seed StdGen) (uniform @Int)
--   (1039666877624726199,Seed [0xe9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
--   </pre>
withSeed :: SeedGen g => Seed g -> (g -> (a, g)) -> (a, Seed g)

-- | Read the seed from a file and use it for constructing a pseudo-random
--   number generator. After supplied action has been applied to the
--   constructed generator, the resulting generator will be converted back
--   to a seed and written to the same file.
withSeedFile :: (SeedGen g, MonadIO m) => FilePath -> (Seed g -> m (a, Seed g)) -> m a

-- | Same as <a>withSeed</a>, except it is useful with monadic computation
--   and frozen generators.
--   
--   See <a>withSeedMutableGen</a> for a helper that also handles seeds for
--   mutable pseduo-random number generators.
withSeedM :: (SeedGen g, Functor f) => Seed g -> (g -> f (a, g)) -> f (a, Seed g)

-- | The class of types for which random values can be generated. Most
--   instances of <a>Random</a> will produce values that are uniformly
--   distributed on the full range, but for those types without a
--   well-defined "full range" some sensible default subrange will be
--   selected.
--   
--   <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>, but usually the values
--   will simply get swapped.
--   
--   <pre>
--   &gt;&gt;&gt; let gen = mkStdGen 26
--   
--   &gt;&gt;&gt; fst $ randomR ('a', 'z') gen
--   'z'
--   
--   &gt;&gt;&gt; fst $ randomR ('a', 'z') gen
--   'z'
--   </pre>
--   
--   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.
--   
--   There is no requirement to follow the <tt>Ord</tt> instance and the
--   concept of range can be defined on per type basis. For example product
--   types will treat their values independently:
--   
--   <pre>
--   &gt;&gt;&gt; fst $ randomR (('a', 5.0), ('z', 10.0)) $ mkStdGen 26
--   ('z',5.22694980853051)
--   </pre>
--   
--   In case when a lawful range is desired <a>uniformR</a> should be used
--   instead.
randomR :: (Random a, RandomGen g) => (a, a) -> g -> (a, g)
($dmrandomR) :: (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 floating point types, the range is normally the 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)
($dmrandom) :: (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]

-- | A type class for data with a finite number of inhabitants. This type
--   class is used in the default implementation of <a>Uniform</a>.
--   
--   Users are not supposed to write instances of <a>Finite</a> manually.
--   There is a default implementation in terms of <a>Generic</a> instead.
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XDeriveGeneric -XDeriveAnyClass
--   
--   &gt;&gt;&gt; import GHC.Generics (Generic)
--   
--   &gt;&gt;&gt; data MyBool = MyTrue | MyFalse deriving (Generic, Finite)
--   
--   &gt;&gt;&gt; data Action = Code MyBool | Eat (Maybe Bool) | Sleep deriving (Generic, Finite)
--   </pre>
class Finite a

-- | <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)

-- | Same as <tt><a>uniformByteArray</a> <a>False</a></tt>, but for
--   <a>ShortByteString</a>.
--   
--   <tt>genShortByteString n g</tt> returns a <a>ShortByteString</a> of
--   length <tt>n</tt> filled with pseudo-random bytes.
--   
--   <i>Note</i> - This function will be removed from the type class in the
--   next major release as it is no longer needed because of
--   <a>unsafeUniformFillMutableByteArray</a>.

-- | <i>Deprecated: In favor of <a>uniformShortByteString</a></i>
genShortByteString :: RandomGen g => Int -> g -> (ShortByteString, g)

-- | Fill in the supplied <a>MutableByteArray</a> with uniformly generated
--   random bytes. This function is unsafe because it is not required to do
--   any bounds checking. For a safe variant use
--   <a>uniformFillMutableByteArrayM</a> instead.
--   
--   Default type class implementation uses
--   <a>defaultUnsafeUniformFillMutableByteArray</a>.
unsafeUniformFillMutableByteArray :: RandomGen g => MutableByteArray s -> Int -> Int -> g -> ST s 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.

-- | <i>Deprecated: In favor of <a>splitGen</a></i>
split :: RandomGen g => g -> (g, g)
($dmsplit) :: (RandomGen g, SplitGen g) => g -> (g, g)

-- | This is a binary form of pseudo-random number generator's state. It is
--   designed to be safe and easy to use for input/output operations like
--   restoring from file, transmitting over the network, etc.
--   
--   Constructor is not exported, becasue it is important for
--   implementation to enforce the invariant of the underlying byte array
--   being of the exact same length as the generator has specified in
--   <a>SeedSize</a>. Use <a>mkSeed</a> and <a>unSeed</a> to get access to
--   the raw bytes in a safe manner.
data Seed g

-- | Pseudo-random generators that can be split into two separate and
--   independent psuedo-random generators should provide an instance for
--   this type class.
--   
--   Historically this functionality was included in the <a>RandomGen</a>
--   type class in the <a>split</a> function, however, few pseudo-random
--   generators possess this property of splittability. This lead the old
--   <a>split</a> function being usually implemented in terms of
--   <a>error</a>.
class RandomGen g => SplitGen g

-- | Returns two distinct pseudo-random number generators.
--   
--   Implementations should take care to ensure that the resulting
--   generators are not correlated.
splitGen :: SplitGen g => g -> (g, g)

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

-- | 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

-- | Interface for converting a pure pseudo-random number generator to and
--   from non-empty sequence of bytes. Seeds are stored in Little-Endian
--   order regardless of the platform it is being used on, which provides
--   cross-platform compatibility, while providing optimal performance for
--   the most common platform type.
--   
--   Conversion to and from a <a>Seed</a> serves as a building block for
--   implementing serialization for any pure or frozen pseudo-random number
--   generator.
--   
--   It is not trivial to implement platform independence. For this reason
--   this type class has two alternative ways of creating an instance for
--   this class. The easiest way for constructing a platform indepent seed
--   is by converting the inner state of a generator to and from a list of
--   64 bit words using <a>toSeed64</a> and <a>fromSeed64</a> respectively.
--   In that case cross-platform support will be handled automaticaly.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XDataKinds -XTypeFamilies
--   
--   &gt;&gt;&gt; import Data.Word (Word8, Word32)
--   
--   &gt;&gt;&gt; import Data.Bits ((.|.), shiftR, shiftL)
--   
--   &gt;&gt;&gt; import Data.List.NonEmpty (NonEmpty ((:|)))
--   
--   &gt;&gt;&gt; data FiveByteGen = FiveByteGen Word8 Word32 deriving Show
--   
--   &gt;&gt;&gt; :{
--   instance SeedGen FiveByteGen where
--     type SeedSize FiveByteGen = 5
--     fromSeed64 (w64 :| _) =
--       FiveByteGen (fromIntegral (w64 `shiftR` 32)) (fromIntegral w64)
--     toSeed64 (FiveByteGen x1 x4) =
--       let w64 = (fromIntegral x1 `shiftL` 32) .|. fromIntegral x4
--        in (w64 :| [])
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; FiveByteGen 0x80 0x01020304
--   FiveByteGen 128 16909060
--   
--   &gt;&gt;&gt; fromSeed (toSeed (FiveByteGen 0x80 0x01020304))
--   FiveByteGen 128 16909060
--   
--   &gt;&gt;&gt; toSeed (FiveByteGen 0x80 0x01020304)
--   Seed [0x04, 0x03, 0x02, 0x01, 0x80]
--   
--   &gt;&gt;&gt; toSeed64 (FiveByteGen 0x80 0x01020304)
--   549772722948 :| []
--   </pre>
--   
--   However, when performance is of utmost importance or default handling
--   of cross platform independence is not sufficient, then an adventurous
--   developer can try implementing conversion into bytes directly with
--   <a>toSeed</a> and <a>fromSeed</a>.
--   
--   Properties that must hold:
--   
--   <pre>
--   &gt; fromSeed (toSeed gen) == gen
--   </pre>
--   
--   <pre>
--   &gt; fromSeed64 (toSeed64 gen) == gen
--   </pre>
--   
--   Note, that there is no requirement for every <a>Seed</a> to roundtrip,
--   eg. this proprty does not even hold for <a>StdGen</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let seed = nonEmptyToSeed (0xab :| [0xff00]) :: Seed StdGen
--   
--   &gt;&gt;&gt; seed == toSeed (fromSeed seed)
--   False
--   </pre>
class (KnownNat SeedSize g, 1 <= SeedSize g, Typeable g) => SeedGen g where {
    
    -- | Number of bytes that is required for storing the full state of a
    --   pseudo-random number generator. It should be big enough to satisfy the
    --   roundtrip property:
    --   
    --   <pre>
    --   &gt; fromSeed (toSeed gen) == gen
    --   </pre>
    type SeedSize g :: Nat;
}

-- | Convert from a binary representation to a pseudo-random number
--   generator
fromSeed :: SeedGen g => Seed g -> g

-- | Convert to a binary representation of a pseudo-random number generator
toSeed :: SeedGen g => g -> Seed g

-- | Construct pseudo-random number generator from a list of words.
--   Whenever list does not have enough bytes to satisfy the
--   <a>SeedSize</a> requirement, it will be padded with zeros. On the
--   other hand when it has more than necessary, extra bytes will be
--   dropped.
--   
--   For example if <a>SeedSize</a> is set to 2, then only the lower 16
--   bits of the first element in the list will be used.
fromSeed64 :: SeedGen g => NonEmpty Word64 -> g

-- | Convert pseudo-random number generator to a list of words
--   
--   In case when <a>SeedSize</a> is not a multiple of 8, then the upper
--   bits of the last word in the list will be set to zero.
toSeed64 :: SeedGen g => g -> NonEmpty Word64

-- | Number of bytes that is required for storing the full state of a
--   pseudo-random number generator. It should be big enough to satisfy the
--   roundtrip property:
--   
--   <pre>
--   &gt; fromSeed (toSeed gen) == gen
--   </pre>
type family SeedSize g :: Nat

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

-- | <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.

-- | <i>Deprecated: In favor of <a>uniformShortByteStringM</a></i>
uniformShortByteString :: StatefulGen g m => Int -> g -> m ShortByteString

-- | This class is designed for mutable pseudo-random number generators
--   that have a frozen imutable counterpart that can be manipulated in
--   pure code.
--   
--   It also works great with frozen generators that are based on pure
--   generators that have a <a>RandomGen</a> instance.
--   
--   Here are a few laws, which are important for this type class:
--   
--   <ul>
--   <li>Roundtrip and complete destruction on overwrite:</li>
--   </ul>
--   
--   <pre>
--   overwriteGen mg fg &gt;&gt; freezeGen mg = pure fg
--   </pre>
--   
--   <ul>
--   <li>Modification of a mutable generator:</li>
--   </ul>
--   
--   <pre>
--   overwriteGen mg fg = modifyGen mg (const ((), fg)
--   </pre>
--   
--   <ul>
--   <li>Freezing of a mutable generator:</li>
--   </ul>
--   
--   <pre>
--   freezeGen mg = modifyGen mg (fg -&gt; (fg, fg))
--   </pre>
class StatefulGen MutableGen f m m => FrozenGen f (m :: Type -> Type) where {
    
    -- | Represents the state of the pseudo-random number generator for use
    --   with <a>thawGen</a> and <a>freezeGen</a>.
    type MutableGen f (m :: Type -> Type) = (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

-- | Apply a pure function to the frozen pseudo-random number generator.
modifyGen :: FrozenGen f m => MutableGen f m -> (f -> (a, f)) -> m a

-- | Overwrite contents of the mutable pseudo-random number generator with
--   the supplied frozen one
overwriteGen :: FrozenGen f m => MutableGen f m -> f -> m ()

-- | Functionality for thawing frozen generators is not part of the
--   <a>FrozenGen</a> class, becase not all mutable generators support
--   functionality of creating new mutable generators, which is what
--   thawing is in its essence. For this reason <a>StateGen</a> does not
--   have an instance for this type class, but it has one for
--   <a>FrozenGen</a>.
--   
--   Here is an important law that relates this type class to
--   <a>FrozenGen</a>
--   
--   <ul>
--   <li>Roundtrip and independence of mutable generators:</li>
--   </ul>
--   
--   <pre>
--   traverse thawGen fgs &gt;&gt;= traverse freezeGen = pure fgs
--   </pre>
class FrozenGen f m => ThawedGen f (m :: Type -> Type)

-- | Create a new mutable pseudo-random number generator from its frozen
--   state.
thawGen :: ThawedGen f m => f -> m (MutableGen f m)

-- | Runs a mutable pseudo-random number generator from its
--   <a>FrozenGen</a> 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 :: ThawedGen 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_ :: ThawedGen f m => f -> (MutableGen f m -> m a) -> m a

-- | Just like <a>withMutableGen</a>, except uses a <a>Seed</a> instead of
--   a frozen generator.
--   
--   <h4><b>Examples</b></h4>
--   
--   Here is good example of how <a>withSeedMutableGen</a> can be used with
--   <a>withSeedFile</a>, which uses a locally stored seed.
--   
--   First we define a <tt>reportSeed</tt> function that will print the
--   contents of a seed file as a list of bytes:
--   
--   <pre>
--   &gt;&gt;&gt; import Data.ByteString as BS (readFile, writeFile, unpack)
--   
--   &gt;&gt;&gt; :seti -XOverloadedStrings
--   
--   &gt;&gt;&gt; let reportSeed fp = print . ("Seed: " &lt;&gt;) . show . BS.unpack =&lt;&lt; BS.readFile fp
--   </pre>
--   
--   Given a file path, write an <a>StdGen</a> seed into the file:
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XFlexibleContexts -XScopedTypeVariables
--   
--   &gt;&gt;&gt; let writeInitSeed fp = BS.writeFile fp (unSeedToByteString (toSeed (mkStdGen 2025)))
--   </pre>
--   
--   Apply a <a>StatefulGen</a> monadic action that uses <tt><a>IOGen</a>
--   <a>StdGen</a></tt>, restored from the seed in the given path:
--   
--   <pre>
--   &gt;&gt;&gt; let withMutableSeedFile fp action = withSeedFile fp (\(seed :: Seed (IOGen StdGen)) -&gt; withSeedMutableGen seed action)
--   </pre>
--   
--   Given a path and an action initialize the seed file and apply the
--   action using that seed:
--   
--   <pre>
--   &gt;&gt;&gt; let withInitSeedFile fp action = writeInitSeed fp *&gt; reportSeed fp *&gt; withMutableSeedFile fp action &lt;* reportSeed fp
--   </pre>
--   
--   For the sake of example we will use a temporary directory for storing
--   the seed. Here we report the contents of the seed file before and
--   after we shuffle a list:
--   
--   <pre>
--   &gt;&gt;&gt; import UnliftIO.Temporary (withSystemTempDirectory)
--   
--   &gt;&gt;&gt; withSystemTempDirectory "random" (\fp -&gt; withInitSeedFile (fp ++ "/seed.bin") (uniformShuffleListM [1..10]))
--   "Seed: [183,178,143,77,132,163,109,14,157,105,82,99,148,82,109,173]"
--   "Seed: [60,105,117,203,187,138,69,39,157,105,82,99,148,82,109,173]"
--   [7,5,4,3,1,8,10,6,9,2]
--   </pre>
withSeedMutableGen :: (SeedGen g, ThawedGen g m) => Seed g -> (MutableGen g m -> m a) -> m (a, Seed g)

-- | Just like <a>withSeedMutableGen</a>, except it doesn't return the
--   final generator, only the resulting value. This is slightly more
--   efficient, since it doesn't incur overhead from freezeing the mutable
--   generator
withSeedMutableGen_ :: (SeedGen g, ThawedGen g m) => Seed g -> (MutableGen g 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 139
--   
--   &gt;&gt;&gt; g &lt;- newIOGenM pureGen
--   
--   &gt;&gt;&gt; randomM g :: IO Double
--   0.33775117339631733
--   </pre>
--   
--   You can use type applications to disambiguate the type of the
--   generated numbers:
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XTypeApplications
--   
--   &gt;&gt;&gt; randomM @Double g
--   0.9156875994165681
--   </pre>
randomM :: (Random a, RandomGen g, FrozenGen g m) => MutableGen g m -> 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>
--   
--   You can use type applications to disambiguate the type of the
--   generated numbers:
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XTypeApplications
--   
--   &gt;&gt;&gt; randomRM @Int (1, 100) g
--   2
--   </pre>
randomRM :: (Random a, RandomGen g, FrozenGen g m) => (a, a) -> MutableGen g m -> m a

-- | Splits a pseudo-random number generator into two. Overwrites the
--   mutable pseudo-random number generator with one of the immutable
--   pseudo-random number generators produced by a <a>split</a> function
--   and returns the other.
splitGenM :: (SplitGen f, FrozenGen f m) => MutableGen f m -> m f

-- | Splits a pseudo-random number generator into two. Overwrites the
--   mutable wrapper with one of the resulting generators and returns the
--   other as a new mutable generator.
splitMutableGenM :: (SplitGen f, ThawedGen f m) => MutableGen f m -> m (MutableGen f m)

-- | Interface to operations on <a>RandomGen</a> wrappers like
--   <a>IOGenM</a> and <a>StateGenM</a>.

-- | <i>Deprecated: In favor of <a>FrozenGen</a></i>
class (RandomGen r, StatefulGen g m) => RandomGenM g r (m :: Type -> Type) | g -> r

-- | <i>Deprecated: In favor of <a>modifyGen</a></i>
applyRandomGenM :: RandomGenM g r m => (r -> (a, r)) -> g -> m a

-- | 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)

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

-- | 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

-- | Global mutable standard pseudo-random number generator. This is the
--   same generator that was historically used by <a>randomIO</a> and
--   <a>randomRIO</a> functions.
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad (replicateM)
--   
--   &gt;&gt;&gt; replicateM 10 (uniformRM ('a', 'z') globalStdGen)
--   "tdzxhyfvgr"
--   </pre>
globalStdGen :: AtomicGenM StdGen

-- | 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

-- | Frozen version of mutable <a>TGenM</a> generator
newtype TGen g
TGen :: g -> TGen g
[unTGen] :: TGen g -> g

-- | Wraps a <a>TVar</a> that holds a pure pseudo-random number generator.
newtype TGenM g
TGenM :: TVar g -> TGenM g
[unTGenM] :: TGenM g -> TVar g

-- | Creates a new <a>TGenM</a> in <a>STM</a>.
newTGenM :: g -> STM (TGenM g)

-- | Creates a new <a>TGenM</a> in <a>IO</a>.
newTGenMIO :: MonadIO m => g -> m (TGenM g)

-- | Applies a pure operation to the wrapped pseudo-random number
--   generator.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Concurrent.STM
--   
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; import Data.Int (Int32)
--   
--   &gt;&gt;&gt; let pureGen = mkStdGen 137
--   
--   &gt;&gt;&gt; stmGen &lt;- newTGenMIO pureGen
--   
--   &gt;&gt;&gt; atomically $ applyTGen uniform stmGen :: IO Int32
--   637238067
--   </pre>
applyTGen :: (g -> (a, g)) -> TGenM g -> STM 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.
--   
--   There is a default implementation via <a>Generic</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XDeriveGeneric -XDeriveAnyClass
--   
--   &gt;&gt;&gt; import GHC.Generics (Generic)
--   
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; data MyBool = MyTrue | MyFalse deriving (Show, Generic, Finite, Uniform)
--   
--   &gt;&gt;&gt; data Action = Code MyBool | Eat (Maybe Bool) | Sleep deriving (Show, Generic, Finite, Uniform)
--   
--   &gt;&gt;&gt; gen &lt;- newIOGenM (mkStdGen 42)
--   
--   &gt;&gt;&gt; uniformListM 10 gen :: IO [Action]
--   [Code MyTrue,Code MyTrue,Eat Nothing,Code MyFalse,Eat (Just False),Eat (Just True),Eat Nothing,Eat (Just False),Sleep,Code MyFalse]
--   </pre>
uniformM :: (Uniform a, StatefulGen g m) => g -> m a
($dmuniformM) :: (Uniform a, StatefulGen g m, Generic a, GUniform (Rep a)) => g -> m a

-- | A definition of <a>Uniform</a> for <a>Finite</a> types. If your data
--   has several fields of sub-<a>Word</a> cardinality, this instance may
--   be more efficient than one, derived via <a>Generic</a> and
--   <a>GUniform</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XDeriveGeneric -XDeriveAnyClass
--   
--   &gt;&gt;&gt; import GHC.Generics (Generic)
--   
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; data Triple = Triple Word8 Word8 Word8 deriving (Show, Generic, Finite)
--   
--   &gt;&gt;&gt; instance Uniform Triple where uniformM = uniformViaFiniteM
--   
--   &gt;&gt;&gt; gen &lt;- newIOGenM (mkStdGen 42)
--   
--   &gt;&gt;&gt; uniformListM 5 gen :: IO [Triple]
--   [Triple 60 226 48,Triple 234 194 151,Triple 112 96 95,Triple 51 251 15,Triple 6 0 208]
--   </pre>
uniformViaFiniteM :: (StatefulGen g m, Generic a, GFinite (Rep a)) => 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>
--   
--   The range is understood as defined by means of <a>isInRange</a>, so
--   
--   <pre>
--   isInRange (a, b) &lt;$&gt; uniformRM (a, b) gen == pure True
--   </pre>
--   
--   but beware of <a>floating point number caveats</a>.
--   
--   There is a default implementation via <a>Generic</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :seti -XDeriveGeneric -XDeriveAnyClass
--   
--   &gt;&gt;&gt; import GHC.Generics (Generic)
--   
--   &gt;&gt;&gt; import Data.Word (Word8)
--   
--   &gt;&gt;&gt; import Control.Monad (replicateM)
--   
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; gen &lt;- newIOGenM (mkStdGen 42)
--   
--   &gt;&gt;&gt; data Tuple = Tuple Bool Word8 deriving (Show, Generic, UniformRange)
--   
--   &gt;&gt;&gt; replicateM 10 (uniformRM (Tuple False 100, Tuple True 150) gen)
--   [Tuple False 102,Tuple True 118,Tuple False 115,Tuple True 113,Tuple True 126,Tuple False 127,Tuple True 130,Tuple False 113,Tuple False 150,Tuple False 125]
--   </pre>
uniformRM :: (UniformRange a, StatefulGen g m) => (a, a) -> g -> m a
($dmuniformRM) :: (UniformRange a, StatefulGen g m, Generic a, GUniformRange (Rep a)) => (a, a) -> g -> m a

-- | A notion of (inclusive) ranges prescribed to <tt>a</tt>.
--   
--   Ranges are symmetric:
--   
--   <pre>
--   isInRange (lo, hi) x == isInRange (hi, lo) x
--   </pre>
--   
--   Ranges include their endpoints:
--   
--   <pre>
--   isInRange (lo, hi) lo == True
--   </pre>
--   
--   When endpoints coincide, there is nothing else:
--   
--   <pre>
--   isInRange (x, x) y == x == y
--   </pre>
--   
--   Endpoints are endpoints:
--   
--   <pre>
--   isInRange (lo, hi) x ==&gt;
--   isInRange (lo, x) hi == x == hi
--   </pre>
--   
--   Ranges are transitive relations:
--   
--   <pre>
--   isInRange (lo, hi) lo' &amp;&amp; isInRange (lo, hi) hi' &amp;&amp; isInRange (lo', hi') x
--   ==&gt; isInRange (lo, hi) x
--   </pre>
--   
--   There is a default implementation of <a>isInRange</a> via
--   <a>Generic</a>. Other helper function that can be used for
--   implementing this function are <a>isInRangeOrd</a> and
--   <a>isInRangeEnum</a>.
--   
--   Note that the <tt>isRange</tt> method from <tt>Data.Ix</tt> is
--   <i>not</i> a suitable default implementation of <a>isInRange</a>.
--   Unlike <a>isInRange</a>, <tt>isRange</tt> is not required to be
--   symmetric, and many <tt>isRange</tt> implementations are not symmetric
--   in practice.
isInRange :: UniformRange a => (a, a) -> a -> Bool
($dmisInRange) :: (UniformRange a, Generic a, GUniformRange (Rep a)) => (a, a) -> a -> Bool

-- | Utilize <a>Ord</a> instance to decide if a value is within the range.
--   Designed to be used for implementing <a>isInRange</a>
isInRangeOrd :: Ord a => (a, a) -> a -> Bool

-- | Utilize <a>Enum</a> instance to decide if a value is within the range.
--   Designed to be used for implementing <a>isInRange</a>
isInRangeEnum :: Enum a => (a, a) -> a -> Bool

-- | 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]

-- | Generates a list of pseudo-random values in a specified range.
--   
--   <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; uniformListRM 10 (20, 30) g :: IO [Int]
--   [23,21,28,25,28,28,26,25,29,27]
--   </pre>
uniformListRM :: (StatefulGen g m, UniformRange a) => Int -> (a, a) -> g -> m [a]

-- | Shuffle elements of a list in a uniformly random order.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; runStateGen_ (mkStdGen 127) $ uniformShuffleListM "ELVIS"
--   "LIVES"
--   </pre>
uniformShuffleListM :: StatefulGen g m => [a] -> g -> m [a]

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

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

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

-- | Using an <a>ST</a> action that generates 8 bytes at a time fill in a
--   new <a>ByteArray</a> in architecture agnostic manner.
fillByteArrayST :: Bool -> Int -> ST s Word64 -> ST s ByteArray

-- | Efficiently fills in a new <a>ShortByteString</a> in a platform
--   independent manner.

-- | <i>Deprecated: In favor of <a>fillByteArrayST</a></i>
genShortByteStringIO :: Int -> IO Word64 -> IO ShortByteString

-- | Same as <a>genShortByteStringIO</a>, but runs in <a>ST</a>.

-- | <i>Deprecated: In favor of <a>fillByteArrayST</a>, since
--   <a>uniformShortByteString</a>, which it was used for, was also
--   deprecated</i>
genShortByteStringST :: Int -> ST s Word64 -> ST s ShortByteString

-- | Efficiently generates a sequence of pseudo-random bytes in a platform
--   independent manner.
defaultUnsafeUniformFillMutableByteArray :: RandomGen g => MutableByteArray s -> Int -> Int -> g -> ST s g

-- | 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
--   <a>UniformRange</a> 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
--   <a>UniformRange</a> 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

-- | Generates uniformly distributed <a>Enum</a>. One can use it to define
--   a <a>Uniform</a> instance:
--   
--   <pre>
--   data Colors = Red | Green | Blue deriving (Enum, Bounded)
--   instance Uniform Colors where uniformM = uniformEnumM
--   </pre>
uniformEnumM :: (Enum a, Bounded a, StatefulGen g m) => g -> m a

-- | Generates uniformly distributed <a>Enum</a> in the given range. One
--   can use it to define a <a>UniformRange</a> instance:
--   
--   <pre>
--   data Colors = Red | Green | Blue deriving (Enum)
--   instance UniformRange Colors where
--     uniformRM = uniformEnumRM
--     inInRange (lo, hi) x = isInRange (fromEnum lo, fromEnum hi) (fromEnum x)
--   </pre>
uniformEnumRM :: (Enum a, StatefulGen g m) => (a, a) -> g -> m a

-- | Architecture specific <a>Word</a> generation in the specified lower
--   range
uniformWordR :: StatefulGen g m => Word -> g -> m Word

-- | This is the function that is used to scale a floating point value from
--   random word range to the custom <tt>[low, high]</tt> range.
scaleFloating :: (RealFloat a, Integral w, Bounded w, FiniteBits w) => a -> a -> w -> a
instance GHC.Classes.Eq g => GHC.Classes.Eq (System.Random.Stateful.AtomicGen g)
instance GHC.Classes.Eq g => GHC.Classes.Eq (System.Random.Stateful.IOGen g)
instance GHC.Classes.Eq g => GHC.Classes.Eq (System.Random.Stateful.STGen g)
instance GHC.Classes.Eq g => GHC.Classes.Eq (System.Random.Stateful.TGen g)
instance (System.Random.Internal.RandomGen g, GHC.Internal.Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.FrozenGen (System.Random.Stateful.AtomicGen g) m
instance (System.Random.Internal.RandomGen g, GHC.Internal.Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.FrozenGen (System.Random.Stateful.IOGen g) m
instance System.Random.Internal.RandomGen g => System.Random.Internal.FrozenGen (System.Random.Stateful.STGen g) (GHC.Internal.ST.ST s)
instance System.Random.Internal.RandomGen g => System.Random.Internal.FrozenGen (System.Random.Stateful.TGen g) GHC.Internal.Conc.Sync.STM
instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (System.Random.Stateful.AtomicGen g)
instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (System.Random.Stateful.IOGen g)
instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (System.Random.Stateful.STGen g)
instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (System.Random.Stateful.TGen g)
instance GHC.Classes.Ord g => GHC.Classes.Ord (System.Random.Stateful.AtomicGen g)
instance GHC.Classes.Ord g => GHC.Classes.Ord (System.Random.Stateful.IOGen g)
instance GHC.Classes.Ord g => GHC.Classes.Ord (System.Random.Stateful.STGen g)
instance GHC.Classes.Ord g => GHC.Classes.Ord (System.Random.Stateful.TGen g)
instance (System.Random.Internal.RandomGen r, GHC.Internal.Control.Monad.IO.Class.MonadIO m) => System.Random.Stateful.RandomGenM (System.Random.Stateful.AtomicGenM r) r m
instance (System.Random.Internal.RandomGen r, GHC.Internal.Control.Monad.IO.Class.MonadIO m) => System.Random.Stateful.RandomGenM (System.Random.Stateful.IOGenM r) r m
instance System.Random.Internal.RandomGen r => System.Random.Stateful.RandomGenM (System.Random.Stateful.STGenM r s) r (GHC.Internal.ST.ST s)
instance (System.Random.Internal.RandomGen r, Control.Monad.State.Class.MonadState r m) => System.Random.Stateful.RandomGenM (System.Random.Internal.StateGenM r) r m
instance System.Random.Internal.RandomGen r => System.Random.Stateful.RandomGenM (System.Random.Stateful.TGenM r) r GHC.Internal.Conc.Sync.STM
instance System.Random.Internal.RandomGen g => System.Random.Internal.RandomGen (System.Random.Stateful.AtomicGen g)
instance System.Random.Internal.RandomGen g => System.Random.Internal.RandomGen (System.Random.Stateful.IOGen g)
instance System.Random.Internal.RandomGen g => System.Random.Internal.RandomGen (System.Random.Stateful.STGen g)
instance System.Random.Internal.RandomGen g => System.Random.Internal.RandomGen (System.Random.Stateful.TGen g)
instance System.Random.Seed.SeedGen g => System.Random.Seed.SeedGen (System.Random.Stateful.AtomicGen g)
instance System.Random.Seed.SeedGen g => System.Random.Seed.SeedGen (System.Random.Stateful.IOGen g)
instance System.Random.Seed.SeedGen g => System.Random.Seed.SeedGen (System.Random.Stateful.STGen g)
instance System.Random.Seed.SeedGen g => System.Random.Seed.SeedGen (System.Random.Stateful.TGen g)
instance GHC.Internal.Show.Show g => GHC.Internal.Show.Show (System.Random.Stateful.AtomicGen g)
instance GHC.Internal.Show.Show g => GHC.Internal.Show.Show (System.Random.Stateful.IOGen g)
instance GHC.Internal.Show.Show g => GHC.Internal.Show.Show (System.Random.Stateful.STGen g)
instance GHC.Internal.Show.Show g => GHC.Internal.Show.Show (System.Random.Stateful.TGen g)
instance System.Random.Internal.SplitGen g => System.Random.Internal.SplitGen (System.Random.Stateful.AtomicGen g)
instance System.Random.Internal.SplitGen g => System.Random.Internal.SplitGen (System.Random.Stateful.IOGen g)
instance System.Random.Internal.SplitGen g => System.Random.Internal.SplitGen (System.Random.Stateful.STGen g)
instance System.Random.Internal.SplitGen g => System.Random.Internal.SplitGen (System.Random.Stateful.TGen g)
instance (System.Random.Internal.RandomGen g, GHC.Internal.Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.StatefulGen (System.Random.Stateful.AtomicGenM g) m
instance (System.Random.Internal.RandomGen g, GHC.Internal.Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.StatefulGen (System.Random.Stateful.IOGenM g) m
instance System.Random.Internal.RandomGen g => System.Random.Internal.StatefulGen (System.Random.Stateful.STGenM g s) (GHC.Internal.ST.ST s)
instance System.Random.Internal.RandomGen g => System.Random.Internal.StatefulGen (System.Random.Stateful.TGenM g) GHC.Internal.Conc.Sync.STM
instance GHC.Internal.Foreign.Storable.Storable g => GHC.Internal.Foreign.Storable.Storable (System.Random.Stateful.AtomicGen g)
instance GHC.Internal.Foreign.Storable.Storable g => GHC.Internal.Foreign.Storable.Storable (System.Random.Stateful.IOGen g)
instance GHC.Internal.Foreign.Storable.Storable g => GHC.Internal.Foreign.Storable.Storable (System.Random.Stateful.STGen g)
instance GHC.Internal.Foreign.Storable.Storable g => GHC.Internal.Foreign.Storable.Storable (System.Random.Stateful.TGen g)
instance (System.Random.Internal.RandomGen g, GHC.Internal.Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.ThawedGen (System.Random.Stateful.AtomicGen g) m
instance (System.Random.Internal.RandomGen g, GHC.Internal.Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.ThawedGen (System.Random.Stateful.IOGen g) m
instance System.Random.Internal.RandomGen g => System.Random.Internal.ThawedGen (System.Random.Stateful.STGen g) (GHC.Internal.ST.ST s)
instance System.Random.Internal.RandomGen g => System.Random.Internal.ThawedGen (System.Random.Stateful.TGen g) GHC.Internal.Conc.Sync.STM
