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


-- | High-quality splittable pseudorandom number generator
--   
--   This package contains an implementation of a high-quality splittable
--   pseudorandom number generator. The generator is based on a
--   cryptographic hash function built on top of the ThreeFish block
--   cipher. See the paper <i>Splittable Pseudorandom Number Generators
--   Using Cryptographic Hashing</i> by Claessen, Pałka for details and the
--   rationale of the design.
--   
--   The package provides the following:
--   
--   <ul>
--   <li>A splittable PRNG that implements the standard
--   <a>System.Random.RandomGen</a> class.</li>
--   <li>The generator also implements an alternative version of the
--   <a>System.Random.TF.Gen.RandomGen</a> class (exported from
--   <a>System.Random.TF.Gen</a>), which requires the generator to return
--   pseudorandom integers from the full 32-bit range, and contains an
--   n-way split function.</li>
--   <li>An alternative version of the <tt>Random</tt> class is provided,
--   which is linked to the new <tt>RandomGen</tt> class, together with
--   <tt>Random</tt> instances for some integral types.</li>
--   <li>Two functions for initialising the generator with a
--   non-deterministic seed: one using the system time, and one using the
--   <tt>/dev/urandom</tt> UNIX special file.</li>
--   </ul>
--   
--   The package uses an adapted version of the reference C implementation
--   of ThreeFish from the reference package of the Skein hash function
--   (<a>https://www.schneier.com/skein.html</a>), originally written by
--   Doug Whiting.
--   
--   Please note that even though the generator provides very high-quality
--   pseudorandom numbers, it has not been designed with cryptographic
--   applications in mind.
@package tf-random
@version 0.5


-- | This module provides the <a>TFGen</a> generator and the alternative
--   <a>RandomGen</a> class. <a>TFGen</a> also implements the standard
--   <a>RandomGen</a> class.
module System.Random.TF.Gen

-- | The generator type
data TFGen

-- | Alternative <a>RandomGen</a> class with a modified <a>next</a>
--   operation, and added <a>splitn</a> and <a>level</a> operations.
--   
--   Using the generator requires that no more than one operation is called
--   on the same generator state, as the implementation does not guarantee
--   pseudorandomness otherwise. As an exception, calling <a>splitn</a>
--   many times on the same generator state is allowed as long as the
--   'bits' argument is the same for all the calls.
class RandomGen g
next :: RandomGen g => g -> (Word32, g)
split :: RandomGen g => g -> (g, g)
splitn :: RandomGen g => g -> Int -> Word32 -> g
level :: RandomGen g => g -> g

-- | Create a generator from a random seed.
seedTFGen :: (Word64, Word64, Word64, Word64) -> TFGen
instance Show TFGenR
instance Read TFGenR
instance RandomGen TFGen
instance RandomGen TFGen
instance Read TFGen
instance Show TFGen
instance Read Hex
instance Show Hex

module System.Random.TF.Init

-- | Derive a new generator instance from the global RNG using split. This
--   is the default way of obtaining a new RNG instance. Initial generator
--   is seeded using <a>mkSeedUnix</a> on UNIX, and <a>mkSeedTime</a>
--   otherwise. This should be eventually replaced with proper seeding.
newTFGen :: IO TFGen

-- | Quick and dirty way of creating a deterministically seeded generator.
mkTFGen :: Int -> TFGen

-- | Use system time create the random seed. This method of seeding may not
--   be relible.
mkSeedTime :: IO (Word64, Word64, Word64, Word64)

-- | Use the UNIX special file <tt>/dev/urandom</tt> to create the seed.
--   Inspired by <tt>random-mwc</tt>.
mkSeedUnix :: IO (Word64, Word64, Word64, Word64)

-- | Create a seed and used it to seed an instance of TFGen. Uses
--   <a>mkSeedUnix</a> on UNIX, and <a>mkSeedTime</a> otherwise.
initTFGen :: IO TFGen


-- | This module defines alternative <a>Random</a> instances for common
--   integral types, which make use of the <a>RandomGen</a> class from
--   <a>System.Random.TF.Gen</a>.
module System.Random.TF.Instances
class Random a where randomRs ival g = myUnfoldr (randomR ival) g randoms g = myUnfoldr random g
randomR :: (Random a, RandomGen g) => (a, a) -> g -> (a, g)
random :: (Random a, RandomGen g) => g -> (a, g)
randomRs :: (Random a, RandomGen g) => (a, a) -> g -> [a]
randoms :: (Random a, RandomGen g) => g -> [a]
randomEnum :: (Enum a, RandomGen g) => (a, a) -> g -> (a, g)
instance Random Int16
instance Random Word16
instance Random Int8
instance Random Word8
instance Random Int64
instance Random Int32
instance Random Word64
instance Random Word32
instance Random Integer
instance Random Bool
instance Random Char
instance Random Int


-- | This module exports <a>System.Random.TF.Gen</a> and
--   <a>System.Random.TF.Init</a> modules without exporting the alternative
--   <a>RandomGen</a> class from <a>System.Random.TF.Gen</a>. To use this
--   class and the <a>Random</a> instances written for it, please import
--   <a>System.Random.TF.Gen</a> and <a>System.Random.TF.Instances</a>
--   directly.
module System.Random.TF
