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


-- | Generic basis for random number generators
--   
--   Random number generation based on entropy sources able to produce a
--   small but well-defined set of primitive variates. Also includes
--   facilities for "completing" partial implementations, making it easy to
--   define new entropy sources in a way that is naturally
--   forward-compatible.
--   
--   Changes in 0.3.0.6: Fixed overzealous fix in 0.3.0.5. The people
--   responsible for sacking the people who have been sacked, etc., have
--   been sacked.
--   
--   Changes in 0.3.0.5: Renamed some internal modules and accidentally
--   some external ones too. Whoops. Please don't use this version, it will
--   only end in tears.
--   
--   Changes in 0.3.0.4: Fixed a typo that broke building with MTL-1
--   
--   Changes in 0.3.0.3: Fixes for GHC's deprecation of
--   Foreign.unsafePerformIO
--   
--   Changes in 0.3.0.2: Fixes for GHC 7.2.*'s crazy Template Haskell
--   changes.
@package random-source
@version 0.3.0.6


-- | A few little functions I found myself writing inline over and over
--   again.
module Data.Random.Internal.Words

-- | Build a word out of 2 bytes. No promises are made regarding the order
--   in which the bytes are stuffed. Note that this means that a
--   <tt>RandomSource</tt> or <tt>MonadRandom</tt> making use of the
--   default definition of <tt>getRandomWord</tt>, etc., may return
--   different random values on different platforms when started with the
--   same seed, depending on the platform's endianness.
buildWord16 :: Word8 -> Word8 -> Word16

-- | Build a word out of 4 bytes. No promises are made regarding the order
--   in which the bytes are stuffed. Note that this means that a
--   <tt>RandomSource</tt> or <tt>MonadRandom</tt> making use of the
--   default definition of <tt>getRandomWord</tt>, etc., may return
--   different random values on different platforms when started with the
--   same seed, depending on the platform's endianness.
buildWord32 :: Word8 -> Word8 -> Word8 -> Word8 -> Word32
buildWord32' :: Word16 -> Word16 -> Word32

-- | Build a word out of 8 bytes. No promises are made regarding the order
--   in which the bytes are stuffed. Note that this means that a
--   <tt>RandomSource</tt> or <tt>MonadRandom</tt> making use of the
--   default definition of <tt>getRandomWord</tt>, etc., may return
--   different random values on different platforms when started with the
--   same seed, depending on the platform's endianness.
buildWord64 :: Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> Word64
buildWord64' :: Word16 -> Word16 -> Word16 -> Word16 -> Word64
buildWord64'' :: Word32 -> Word32 -> Word64

-- | Pack the low 23 bits from a <a>Word32</a> into a <a>Float</a> in the
--   range [0,1). Used to convert a <tt>stdUniform</tt> <a>Word32</a> to a
--   <tt>stdUniform</tt> <a>Double</a>.
word32ToFloat :: Word32 -> Float

-- | Same as word32ToFloat, but also return the unused bits (as the 9 least
--   significant bits of a <a>Word32</a>)
word32ToFloatWithExcess :: Word32 -> (Float, Word32)

-- | Pack the low 23 bits from a <a>Word64</a> into a <a>Float</a> in the
--   range [0,1). Used to convert a <tt>stdUniform</tt> <a>Word64</a> to a
--   <tt>stdUniform</tt> <a>Double</a>.
wordToFloat :: Word64 -> Float

-- | Same as wordToFloat, but also return the unused bits (as the 41 least
--   significant bits of a <a>Word64</a>)
wordToFloatWithExcess :: Word64 -> (Float, Word64)

-- | Pack the low 52 bits from a <a>Word64</a> into a <a>Double</a> in the
--   range [0,1). Used to convert a <tt>stdUniform</tt> <a>Word64</a> to a
--   <tt>stdUniform</tt> <a>Double</a>.
wordToDouble :: Word64 -> Double

-- | Pack a <a>Word32</a> into a <a>Double</a> in the range [0,1). Note
--   that a Double's mantissa is 52 bits, so this does not fill all of
--   them.
word32ToDouble :: Word32 -> Double

-- | Same as wordToDouble, but also return the unused bits (as the 12 least
--   significant bits of a <a>Word64</a>)
wordToDoubleWithExcess :: Word64 -> (Double, Word64)

module Data.Random.Internal.Source

-- | A <tt>Prompt</tt> GADT describing a request for a primitive random
--   variate. Random variable definitions will request their entropy via
--   these prompts, and entropy sources will satisfy those requests. The
--   functions in <a>Data.Random.Source.Internal.TH</a> extend incomplete
--   entropy-source definitions to complete ones, essentially defining a
--   very flexible implementation-defaulting system.
--   
--   Some possible future additions: PrimFloat :: Prim Float PrimInt ::
--   Prim Int PrimPair :: Prim a -&gt; Prim b -&gt; Prim (a :*: b)
--   PrimNormal :: Prim Double PrimChoice :: [(Double :*: a)] -&gt; Prim a
--   PrimBytes :: !Int -&gt; Prim ByteString
--   
--   Unfortunately, I cannot get Haddock to accept my comments about the
--   data constructors, but hopefully they should be reasonably
--   self-explanatory.
data Prim a
[PrimWord8] :: Prim Word8
[PrimWord16] :: Prim Word16
[PrimWord32] :: Prim Word32
[PrimWord64] :: Prim Word64
[PrimDouble] :: Prim Double
[PrimNByteInteger] :: !Int -> Prim Integer

-- | A typeclass for monads with a chosen source of entropy. For example,
--   <tt>RVar</tt> is such a monad - the source from which it is
--   (eventually) sampled is the only source from which a random variable
--   is permitted to draw, so when directly requesting entropy for a random
--   variable these functions are used.
--   
--   Minimum implementation is either the internal <a>getRandomPrim</a> or
--   all other functions. Additionally, this class's interface is subject
--   to extension at any time, so it is very, very strongly recommended
--   that the <tt>monadRandom</tt> Template Haskell function be used to
--   implement this function rather than directly implementing it. That
--   function takes care of choosing default implementations for any
--   missing functions; as long as at least one function is implemented, it
--   will derive sensible implementations of all others.
--   
--   To use <tt>monadRandom</tt>, just wrap your instance declaration as
--   follows (and enable the TemplateHaskell and GADTs language
--   extensions):
--   
--   <pre>
--   $(monadRandom [d|
--           instance MonadRandom FooM where
--               getRandomDouble = return pi
--               getRandomWord16 = return 4
--               {- etc... -}
--       |])
--   </pre>
class Monad m => MonadRandom m where getRandomPrim PrimWord8 = getRandomWord8 getRandomPrim PrimWord16 = getRandomWord16 getRandomPrim PrimWord32 = getRandomWord32 getRandomPrim PrimWord64 = getRandomWord64 getRandomPrim PrimDouble = getRandomDouble getRandomPrim (PrimNByteInteger n) = getRandomNByteInteger n getRandomWord8 = getRandomPrim PrimWord8 getRandomWord16 = getRandomPrim PrimWord16 getRandomWord32 = getRandomPrim PrimWord32 getRandomWord64 = getRandomPrim PrimWord64 getRandomDouble = getRandomPrim PrimDouble getRandomNByteInteger n = getRandomPrim (PrimNByteInteger n)

-- | Generate a random value corresponding to the specified primitive.
--   
--   This is an internal interface; use at your own risk. It may change or
--   disappear at any time.
getRandomPrim :: MonadRandom m => Prim t -> m t

-- | Generate a uniformly distributed random <a>Word8</a>
getRandomWord8 :: MonadRandom m => m Word8

-- | Generate a uniformly distributed random <a>Word16</a>
getRandomWord16 :: MonadRandom m => m Word16

-- | Generate a uniformly distributed random <a>Word32</a>
getRandomWord32 :: MonadRandom m => m Word32

-- | Generate a uniformly distributed random <a>Word64</a>
getRandomWord64 :: MonadRandom m => m Word64

-- | Generate a uniformly distributed random <a>Double</a> in the range 0
--   &lt;= U &lt; 1
getRandomDouble :: MonadRandom m => m Double

-- | Generate a uniformly distributed random <a>Integer</a> in the range 0
--   &lt;= U &lt; 256^n
getRandomNByteInteger :: (MonadRandom m, MonadRandom m) => Int -> m Integer

-- | A source of entropy which can be used in the given monad.
--   
--   See also <a>MonadRandom</a>.
--   
--   Minimum implementation is either the internal <a>getRandomPrimFrom</a>
--   or all other functions. Additionally, this class's interface is
--   subject to extension at any time, so it is very, very strongly
--   recommended that the <tt>randomSource</tt> Template Haskell function
--   be used to implement this function rather than directly implementing
--   it. That function takes care of choosing default implementations for
--   any missing functions; as long as at least one function is
--   implemented, it will derive sensible implementations of all others.
--   
--   To use <tt>randomSource</tt>, just wrap your instance declaration as
--   follows (and enable the TemplateHaskell, MultiParamTypeClasses and
--   GADTs language extensions, as well as any others required by your
--   instances, such as FlexibleInstances):
--   
--   <pre>
--   $(randomSource [d|
--           instance RandomSource FooM Bar where
--               {- at least one RandomSource function... -}
--       |])
--   </pre>
class Monad m => RandomSource m s where getRandomPrimFrom src PrimWord8 = getRandomWord8From src getRandomPrimFrom src PrimWord16 = getRandomWord16From src getRandomPrimFrom src PrimWord32 = getRandomWord32From src getRandomPrimFrom src PrimWord64 = getRandomWord64From src getRandomPrimFrom src PrimDouble = getRandomDoubleFrom src getRandomPrimFrom src (PrimNByteInteger n) = getRandomNByteIntegerFrom src n getRandomWord8From src = getRandomPrimFrom src PrimWord8 getRandomWord16From src = getRandomPrimFrom src PrimWord16 getRandomWord32From src = getRandomPrimFrom src PrimWord32 getRandomWord64From src = getRandomPrimFrom src PrimWord64 getRandomDoubleFrom src = getRandomPrimFrom src PrimDouble getRandomNByteIntegerFrom src n = getRandomPrimFrom src (PrimNByteInteger n)

-- | Generate a random value corresponding to the specified primitive.
--   
--   This is an internal interface; use at your own risk. It may change or
--   disappear at any time.
getRandomPrimFrom :: RandomSource m s => s -> Prim t -> m t

-- | Generate a uniformly distributed random <a>Word8</a>
getRandomWord8From :: RandomSource m s => s -> m Word8

-- | Generate a uniformly distributed random <a>Word16</a>
getRandomWord16From :: RandomSource m s => s -> m Word16

-- | Generate a uniformly distributed random <a>Word32</a>
getRandomWord32From :: RandomSource m s => s -> m Word32

-- | Generate a uniformly distributed random <a>Word64</a>
getRandomWord64From :: RandomSource m s => s -> m Word64

-- | Generate a uniformly distributed random <a>Double</a> in the range 0
--   &lt;= U &lt; 1
getRandomDoubleFrom :: RandomSource m s => s -> m Double

-- | Generate a uniformly distributed random <a>Integer</a> in the range 0
--   &lt;= U &lt; 256^n
getRandomNByteIntegerFrom :: RandomSource m s => s -> Int -> m Integer

-- | This type provides a way to define a <a>RandomSource</a> for a monad
--   without actually having to declare an instance.
newtype GetPrim m
GetPrim :: (forall t. Prim t -> m t) -> GetPrim m
instance GHC.Base.Monad m => Data.Random.Internal.Source.RandomSource m (Data.Random.Internal.Source.GetPrim m)

module Data.Random.Source

-- | A typeclass for monads with a chosen source of entropy. For example,
--   <tt>RVar</tt> is such a monad - the source from which it is
--   (eventually) sampled is the only source from which a random variable
--   is permitted to draw, so when directly requesting entropy for a random
--   variable these functions are used.
--   
--   Minimum implementation is either the internal <a>getRandomPrim</a> or
--   all other functions. Additionally, this class's interface is subject
--   to extension at any time, so it is very, very strongly recommended
--   that the <tt>monadRandom</tt> Template Haskell function be used to
--   implement this function rather than directly implementing it. That
--   function takes care of choosing default implementations for any
--   missing functions; as long as at least one function is implemented, it
--   will derive sensible implementations of all others.
--   
--   To use <tt>monadRandom</tt>, just wrap your instance declaration as
--   follows (and enable the TemplateHaskell and GADTs language
--   extensions):
--   
--   <pre>
--   $(monadRandom [d|
--           instance MonadRandom FooM where
--               getRandomDouble = return pi
--               getRandomWord16 = return 4
--               {- etc... -}
--       |])
--   </pre>
class Monad m => MonadRandom m where getRandomPrim PrimWord8 = getRandomWord8 getRandomPrim PrimWord16 = getRandomWord16 getRandomPrim PrimWord32 = getRandomWord32 getRandomPrim PrimWord64 = getRandomWord64 getRandomPrim PrimDouble = getRandomDouble getRandomPrim (PrimNByteInteger n) = getRandomNByteInteger n getRandomWord8 = getRandomPrim PrimWord8 getRandomWord16 = getRandomPrim PrimWord16 getRandomWord32 = getRandomPrim PrimWord32 getRandomWord64 = getRandomPrim PrimWord64 getRandomDouble = getRandomPrim PrimDouble getRandomNByteInteger n = getRandomPrim (PrimNByteInteger n)

-- | Generate a uniformly distributed random <a>Word8</a>
getRandomWord8 :: MonadRandom m => m Word8

-- | Generate a uniformly distributed random <a>Word16</a>
getRandomWord16 :: MonadRandom m => m Word16

-- | Generate a uniformly distributed random <a>Word32</a>
getRandomWord32 :: MonadRandom m => m Word32

-- | Generate a uniformly distributed random <a>Word64</a>
getRandomWord64 :: MonadRandom m => m Word64

-- | Generate a uniformly distributed random <a>Double</a> in the range 0
--   &lt;= U &lt; 1
getRandomDouble :: MonadRandom m => m Double

-- | Generate a uniformly distributed random <a>Integer</a> in the range 0
--   &lt;= U &lt; 256^n
getRandomNByteInteger :: (MonadRandom m, MonadRandom m) => Int -> m Integer

-- | A source of entropy which can be used in the given monad.
--   
--   See also <a>MonadRandom</a>.
--   
--   Minimum implementation is either the internal <a>getRandomPrimFrom</a>
--   or all other functions. Additionally, this class's interface is
--   subject to extension at any time, so it is very, very strongly
--   recommended that the <tt>randomSource</tt> Template Haskell function
--   be used to implement this function rather than directly implementing
--   it. That function takes care of choosing default implementations for
--   any missing functions; as long as at least one function is
--   implemented, it will derive sensible implementations of all others.
--   
--   To use <tt>randomSource</tt>, just wrap your instance declaration as
--   follows (and enable the TemplateHaskell, MultiParamTypeClasses and
--   GADTs language extensions, as well as any others required by your
--   instances, such as FlexibleInstances):
--   
--   <pre>
--   $(randomSource [d|
--           instance RandomSource FooM Bar where
--               {- at least one RandomSource function... -}
--       |])
--   </pre>
class Monad m => RandomSource m s where getRandomPrimFrom src PrimWord8 = getRandomWord8From src getRandomPrimFrom src PrimWord16 = getRandomWord16From src getRandomPrimFrom src PrimWord32 = getRandomWord32From src getRandomPrimFrom src PrimWord64 = getRandomWord64From src getRandomPrimFrom src PrimDouble = getRandomDoubleFrom src getRandomPrimFrom src (PrimNByteInteger n) = getRandomNByteIntegerFrom src n getRandomWord8From src = getRandomPrimFrom src PrimWord8 getRandomWord16From src = getRandomPrimFrom src PrimWord16 getRandomWord32From src = getRandomPrimFrom src PrimWord32 getRandomWord64From src = getRandomPrimFrom src PrimWord64 getRandomDoubleFrom src = getRandomPrimFrom src PrimDouble getRandomNByteIntegerFrom src n = getRandomPrimFrom src (PrimNByteInteger n)

-- | Generate a uniformly distributed random <a>Word8</a>
getRandomWord8From :: RandomSource m s => s -> m Word8

-- | Generate a uniformly distributed random <a>Word16</a>
getRandomWord16From :: RandomSource m s => s -> m Word16

-- | Generate a uniformly distributed random <a>Word32</a>
getRandomWord32From :: RandomSource m s => s -> m Word32

-- | Generate a uniformly distributed random <a>Word64</a>
getRandomWord64From :: RandomSource m s => s -> m Word64

-- | Generate a uniformly distributed random <a>Double</a> in the range 0
--   &lt;= U &lt; 1
getRandomDoubleFrom :: RandomSource m s => s -> m Double

-- | Generate a uniformly distributed random <a>Integer</a> in the range 0
--   &lt;= U &lt; 256^n
getRandomNByteIntegerFrom :: RandomSource m s => s -> Int -> m Integer

-- | Complete a possibly-incomplete <a>MonadRandom</a> implementation. It
--   is recommended that this macro be used even if the implementation is
--   currently complete, as the <a>MonadRandom</a> class may be extended at
--   any time.
--   
--   To use <a>monadRandom</a>, just wrap your instance declaration as
--   follows (and enable the TemplateHaskell and GADTs language
--   extensions):
--   
--   <pre>
--   $(monadRandom [d|
--           instance MonadRandom FooM where
--               getRandomDouble = return pi
--               getRandomWord16 = return 4
--               {- etc... -}
--       |])
--   </pre>
monadRandom :: Q [Dec] -> Q [Dec]

-- | Complete a possibly-incomplete <a>RandomSource</a> implementation. It
--   is recommended that this macro be used even if the implementation is
--   currently complete, as the <a>RandomSource</a> class may be extended
--   at any time.
--   
--   To use <a>randomSource</a>, just wrap your instance declaration as
--   follows (and enable the TemplateHaskell, MultiParamTypeClasses and
--   GADTs language extensions, as well as any others required by your
--   instances, such as FlexibleInstances):
--   
--   <pre>
--   $(randomSource [d|
--           instance RandomSource FooM Bar where
--               {- at least one RandomSource function... -}
--       |])
--   </pre>
randomSource :: Q [Dec] -> Q [Dec]
instance GHC.Base.Monad m0 => Data.Random.Internal.Source.RandomSource m0 (m0 GHC.Types.Double)
instance GHC.Base.Monad m0 => Data.Random.Internal.Source.RandomSource m0 (m0 GHC.Word.Word64)
instance GHC.Base.Monad m0 => Data.Random.Internal.Source.RandomSource m0 (m0 GHC.Word.Word32)
instance GHC.Base.Monad m0 => Data.Random.Internal.Source.RandomSource m0 (m0 GHC.Word.Word16)
instance GHC.Base.Monad m0 => Data.Random.Internal.Source.RandomSource m0 (m0 GHC.Word.Word8)

module Data.Random.Source.DevRandom

-- | On systems that have it, /dev/random is a handy-dandy ready-to-use
--   source of nonsense. Keep in mind that on some systems, Linux included,
--   /dev/random collects "real" entropy, and if you don't have a good
--   source of it, such as special hardware for the purpose or a *lot* of
--   network traffic, it's pretty easy to suck the entropy pool dry with
--   entropy-intensive applications. For many purposes other than
--   cryptography, /dev/urandom is preferable because when it runs out of
--   real entropy it'll still churn out pseudorandom data.
data DevRandom
DevRandom :: DevRandom
DevURandom :: DevRandom
instance Data.Random.Internal.Source.RandomSource GHC.Types.IO Data.Random.Source.DevRandom.DevRandom
instance GHC.Show.Show Data.Random.Source.DevRandom.DevRandom
instance GHC.Classes.Eq Data.Random.Source.DevRandom.DevRandom


-- | For convenience, this module defines an instance of <a>MonadRandom</a>
--   for the <a>IO</a> monad. On Windows it uses
--   <a>Data.Random.Source.MWC</a> (or <a>Data.Random.Source.StdGen</a> on
--   older versions of GHC where the mwc-random package doesn't build) and
--   on other platforms it uses <a>Data.Random.Source.DevRandom</a>.
module Data.Random.Source.IO
instance Data.Random.Internal.Source.MonadRandom GHC.Types.IO


-- | This module defines the following instances:
--   
--   <pre>
--   instance RandomSource (ST s) (Gen s)
--   instance RandomSource IO (Gen RealWorld)
--   </pre>
module Data.Random.Source.MWC

-- | State of the pseudo-random number generator. It uses mutable state so
--   same generator shouldn't be used from the different threads
--   simultaneously.
data Gen s :: * -> *

-- | <tt>RealWorld</tt> is deeply magical. It is <i>primitive</i>, but it
--   is not <i>unlifted</i> (hence <tt>ptrArg</tt>). We never manipulate
--   values of type <tt>RealWorld</tt>; it's only used in the type system,
--   to parameterise <tt>State#</tt>.
data RealWorld :: *

-- | Create a generator for variates using a fixed seed.
create :: PrimMonad m => m (Gen (PrimState m))

-- | Create a generator for variates using the given seed, of which up to
--   256 elements will be used. For arrays of less than 256 elements, part
--   of the default seed will be used to finish initializing the
--   generator's state.
--   
--   Examples:
--   
--   <pre>
--   initialize (singleton 42)
--   </pre>
--   
--   <pre>
--   initialize (fromList [4, 8, 15, 16, 23, 42])
--   </pre>
--   
--   If a seed contains fewer than 256 elements, it is first used verbatim,
--   then its elements are <a>xor</a>ed against elements of the default
--   seed until 256 elements are reached.
--   
--   If a seed contains exactly 258 elements, then the last two elements
--   are used to set the generator's initial state. This allows for
--   complete generator reproducibility, so that e.g. <tt>gen' == gen</tt>
--   in the following example:
--   
--   <pre>
--   gen' &lt;- <a>initialize</a> . <a>fromSeed</a> =&lt;&lt; <a>save</a>
--   </pre>
initialize :: (PrimMonad m, Vector v Word32) => v Word32 -> m (Gen (PrimState m))

-- | Save the state of a <a>Gen</a>, for later use by <a>restore</a>.
save :: PrimMonad m => Gen (PrimState m) -> m Seed

-- | Create a new <a>Gen</a> that mirrors the state of a saved <a>Seed</a>.
restore :: PrimMonad m => Seed -> m (Gen (PrimState m))
instance Data.Random.Internal.Source.RandomSource GHC.Types.IO (System.Random.MWC.Gen GHC.Prim.RealWorld)
instance Data.Random.Internal.Source.RandomSource (GHC.ST.ST s0) (System.Random.MWC.Gen s0)


-- | This module provides functions useful for implementing new
--   <a>MonadRandom</a> and <a>RandomSource</a> instances for
--   state-abstractions containing <a>PureMT</a> values (the pure
--   pseudorandom generator provided by the mersenne-random-pure64
--   package), as well as instances for some common cases.
--   
--   A <a>PureMT</a> generator is immutable, so <a>PureMT</a> by itself
--   cannot be a <a>RandomSource</a> (if it were, it would always give the
--   same "random" values). Some form of mutable state must be used, such
--   as an <a>IORef</a>, <a>State</a> monad, etc.. A few default instances
--   are provided by this module along with a more-general function
--   (<a>getRandomPrimFromMTRef</a>) usable as an implementation for new
--   cases users might need.
module Data.Random.Source.PureMT

-- | <a>PureMT</a>, a pure mersenne twister pseudo-random number generator
data PureMT :: *

-- | Create a new PureMT generator, using the clocktime as the base for the
--   seed.
newPureMT :: IO PureMT

-- | Create a PureMT generator from a <a>Word64</a> seed.
pureMT :: Word64 -> PureMT

-- | Given a mutable reference to a <a>PureMT</a> generator, we can
--   implement <a>RandomSource</a> for it in any monad in which the
--   reference can be modified.
--   
--   Typically this would be used to define a new <a>RandomSource</a>
--   instance for some new reference type or new monad in which an existing
--   reference type can be modified atomically. As an example, the
--   following instance could be used to describe how <a>IORef</a>
--   <a>PureMT</a> can be a <a>RandomSource</a> in the <a>IO</a> monad:
--   
--   <pre>
--   instance RandomSource IO (IORef PureMT) where
--       supportedPrimsFrom _ _ = True
--       getSupportedRandomPrimFrom = getRandomPrimFromMTRef
--   </pre>
--   
--   (note that there is actually a more general instance declared already
--   covering this as a a special case, so there's no need to repeat this
--   declaration anywhere)
--   
--   Example usage (using some functions from <a>Data.Random</a> in the
--   random-fu package):
--   
--   <pre>
--   main = do
--       src &lt;- newIORef (pureMT 1234)          -- OR: newPureMT &gt;&gt;= newIORef
--       x &lt;- runRVar (uniform 0 100) src :: IO Double
--       print x
--   </pre>
getRandomPrimFromMTRef :: ModifyRef sr m PureMT => sr -> Prim a -> m a
instance (GHC.Base.Monad m0, Data.StateRef.Types.ModifyRef (GHC.STRef.STRef s0 System.Random.Mersenne.Pure64.Internal.PureMT) m0 System.Random.Mersenne.Pure64.Internal.PureMT) => Data.Random.Internal.Source.RandomSource m0 (GHC.STRef.STRef s0 System.Random.Mersenne.Pure64.Internal.PureMT)
instance Control.Monad.IO.Class.MonadIO m0 => Data.Random.Internal.Source.RandomSource m0 (GHC.IORef.IORef System.Random.Mersenne.Pure64.Internal.PureMT)
instance GHC.Base.Monad m0 => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.State.Strict.StateT System.Random.Mersenne.Pure64.Internal.PureMT m0)
instance GHC.Base.Monad m0 => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.State.Lazy.StateT System.Random.Mersenne.Pure64.Internal.PureMT m0)
instance (GHC.Base.Monad m10, Data.StateRef.Types.ModifyRef (Data.StateRef.Types.Ref m20 System.Random.Mersenne.Pure64.Internal.PureMT) m10 System.Random.Mersenne.Pure64.Internal.PureMT) => Data.Random.Internal.Source.RandomSource m10 (Data.StateRef.Types.Ref m20 System.Random.Mersenne.Pure64.Internal.PureMT)

module Data.Random.Source.Std

-- | A token representing the "standard" entropy source in a
--   <a>MonadRandom</a> monad. Its sole purpose is to make the following
--   true (when the types check):
--   
--   <pre>
--   runRVar x StdRandom === sampleRVar
--   </pre>
data StdRandom
StdRandom :: StdRandom
instance Data.Random.Internal.Source.MonadRandom m => Data.Random.Internal.Source.RandomSource m Data.Random.Source.Std.StdRandom


-- | This module provides functions useful for implementing new
--   <a>MonadRandom</a> and <a>RandomSource</a> instances for
--   state-abstractions containing <a>StdGen</a> values (the pure
--   pseudorandom generator provided by the System.Random module in the
--   "random" package), as well as instances for some common cases.
module Data.Random.Source.StdGen

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

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

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

-- | Given a mutable reference to a <a>RandomGen</a> generator, we can make
--   a <a>RandomSource</a> usable in any monad in which the reference can
--   be modified.
--   
--   See <a>Data.Random.Source.PureMT</a>.<tt>getRandomPrimFromMTRef</tt>
--   for more detailed usage hints - this function serves exactly the same
--   purpose except for a <a>StdGen</a> generator instead of a
--   <tt>PureMT</tt> generator.
getRandomPrimFromRandomGenRef :: (Monad m, ModifyRef sr m g, RandomGen g) => sr -> Prim a -> m a

-- | Similarly, <tt>getRandomWordFromRandomGenState x</tt> can be used in
--   any "state" monad in the mtl sense whose state is a <a>RandomGen</a>
--   generator. Additionally, the standard mtl state monads have
--   <a>MonadRandom</a> instances which do precisely that, allowing an easy
--   conversion of <tt>RVar</tt>s and other <tt>Distribution</tt> instances
--   to "pure" random variables.
--   
--   Again, see
--   <a>Data.Random.Source.PureMT</a>.<tt>getRandomPrimFromMTState</tt> for
--   more detailed usage hints - this function serves exactly the same
--   purpose except for a <a>StdGen</a> generator instead of a
--   <tt>PureMT</tt> generator.
getRandomPrimFromRandomGenState :: forall g m a. (RandomGen g, MonadState g m) => Prim a -> m a
instance (GHC.Base.Monad m1, Data.StateRef.Types.ModifyRef (Data.StateRef.Types.Ref m2 System.Random.StdGen) m1 System.Random.StdGen) => Data.Random.Internal.Source.RandomSource m1 (Data.StateRef.Types.Ref m2 System.Random.StdGen)
instance (GHC.Base.Monad m, Data.StateRef.Types.ModifyRef (GHC.IORef.IORef System.Random.StdGen) m System.Random.StdGen) => Data.Random.Internal.Source.RandomSource m (GHC.IORef.IORef System.Random.StdGen)
instance (GHC.Base.Monad m, Data.StateRef.Types.ModifyRef (GHC.STRef.STRef s System.Random.StdGen) m System.Random.StdGen) => Data.Random.Internal.Source.RandomSource m (GHC.STRef.STRef s System.Random.StdGen)
instance GHC.Base.Monad m => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.State.Lazy.StateT System.Random.StdGen m)
instance GHC.Base.Monad m => Data.Random.Internal.Source.MonadRandom (Control.Monad.Trans.State.Strict.StateT System.Random.StdGen m)
