-- 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 Splittable Pseudorandom Number Generators
--   Using Cryptographic Hashing by Claessen, Palka for details and the
--   rationale of the design.
--   
--   The package provides the following:
--   
--   
--   
- A splittable PRNG that implements the standard
--   System.Random.RandomGen class.
--   
- The generator also implements an alternative version of the
--   System.Random.TF.Gen.RandomGen class (exported from
--   System.Random.TF.Gen), which requires the generator to return
--   pseudorandom integers from the full 32-bit range, and contains an
--   n-way split function.
--   
- An alternative version of the Random class is provided,
--   which is linked to the new RandomGen class, together with
--   Random instances for some integral types.
--   
- Two functions for initialising the generator with a
--   non-deterministic seed: one using the system time, and one using the
--   /dev/urandom UNIX special file.
--   
--   
--   The package uses an adapted version of the reference C implementation
--   of ThreeFish from the reference package of the Skein hash function
--   (https://www.schneier.com/skein.html), 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 TFGen generator and the alternative
--   RandomGen class. TFGen also implements the standard
--   RandomGen class.
module System.Random.TF.Gen

-- | The generator type
data TFGen

-- | Alternative RandomGen class with a modified next
--   operation, and added splitn and level 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 splitn
--   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 returns a Word32 that appears to have been chosen
--   uniformly at random, and a new generator state.
next :: RandomGen g => g -> (Word32, g)

-- | split returns two derived generator states that appear to be
--   independent pseudorandom number generators.
split :: RandomGen g => g -> (g, g)

-- | splitn is the n-way split operation used to create many derived
--   generator states in one go. Application of splitn to two first
--   arguments should be shared between different applications of the index
--   argument to avoid unnecessary repeated computations.
--   
--   The following code creates ten 'independent' generator states. Number
--   '4' comes from the fact that at least four bits are needed to encode
--   ten different indices.
--   
--   
--   f :: RandomGen g => g -> [g]
--   f r = map (splitn r 4) [0..9]
--   
splitn :: RandomGen g => g -> Int -> Word32 -> g

-- | level is a 'hint' operation that may cause an iteration of work
--   of the generator be performed prematurely in order to prevent the
--   subsequent operations from being expensive. It is meant to be called
--   before a splitn operation, which is expected to be evaluated a
--   very large number indices. Calling level in such case might
--   decrease the total amount of work performed.
level :: RandomGen g => g -> g

-- | Create a generator from a random seed.
seedTFGen :: (Word64, Word64, Word64, Word64) -> TFGen
instance System.Random.Internal.RandomGen System.Random.TF.Gen.TFGen
instance System.Random.TF.Gen.RandomGen System.Random.TF.Gen.TFGen
instance GHC.Internal.Read.Read System.Random.TF.Gen.Hex
instance GHC.Internal.Read.Read System.Random.TF.Gen.TFGen
instance GHC.Internal.Read.Read System.Random.TF.Gen.TFGenR
instance GHC.Internal.Show.Show System.Random.TF.Gen.Hex
instance GHC.Internal.Show.Show System.Random.TF.Gen.TFGen
instance GHC.Internal.Show.Show System.Random.TF.Gen.TFGenR

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 mkSeedUnix on UNIX, and mkSeedTime
--   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 /dev/urandom to create the seed.
--   Inspired by random-mwc.
mkSeedUnix :: IO (Word64, Word64, Word64, Word64)

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

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

-- | The generator type
data TFGen

-- | Create a generator from a random seed.
seedTFGen :: (Word64, Word64, Word64, Word64) -> TFGen

-- | 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 mkSeedUnix on UNIX, and mkSeedTime
--   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 /dev/urandom to create the seed.
--   Inspired by random-mwc.
mkSeedUnix :: IO (Word64, Word64, Word64, Word64)

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