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


-- | A fast, pseudorandom number generator.
--   
--   A fast pseudorandom number generator, as presented by M.E. O'Neill on
--   http://www.pcg-random.org, See that site for information on the
--   particulars of the technique used. This particular implementation uses
--   two Word64 of internal data and produces a Word32 of output per step.
--   On 64-bit machines it's two to three times as fast as StdGen and uses
--   the same amount of space.
@package pcgen
@version 1.0.0


-- | This module contains a permuted linear congruential pseudorandom
--   number generator, as described by M.E. O'Neill
--   (<a>pcg-random.org</a>). This version holds two Word64 values and
--   outputs a Word32 of randomness each time you use it. Compared to the
--   StdGen type from System.Random, it's around a 2.5x to 3x speedup on a
--   64-bit system. Runs somewhat slower than StdGen on a 32-bit system
--   (the Word64 values must be emulated after all), but there aren't too
--   many of those in play these days anyway.
--   
--   The first Word64 is the "state", which changes each step of the
--   generator. The second Word64 is the "inc", which stays fixed from step
--   to step. The inc must always be odd for the gerator to work properly
--   (so there are 2^63 possible inc values), though the smart constructors
--   will ensure this. The state value eventually returns to it's initial
--   position after 2^64 uses, and each inc value is a different sequence
--   of states.
module Data.PCGen

-- | The PCGen data type. You generally create values of this type with
--   mkPCGen and use them with stepGen or the next method of the RandomGen
--   instance. Possibly in combination with a State, StateT, MonadRandom,
--   etc.
--   
--   Note that (at the moment) the Read instance is simply derived by the
--   compiler, so it won't be able to ensure an odd inc value. It's
--   guaranteed that any String you get from the Show instance of this data
--   type (also derived) will be correct as long as the original value was
--   made with <a>mkPCGen</a>, but otherwise you must be careful. This will
--   be fixed later.
data PCGen

-- | Creates a new PCGen value by using the Integral given as both the
--   "state" and "inc" values for the generator. If the value given isn't
--   odd, then it's bumped to the next higher odd value for the inc. The
--   state of the generator is then advanced once, because otherwise the
--   first result tends to be 0 with human picked seeds. See also
--   <a>mkPCGenDetailed</a>.
mkPCGen :: Integral i => i -> PCGen

-- | Creates a PCGen using the specified state and inc values and returns
--   it without an initial generator use. It still bumps the inc value up
--   to the next odd value if an even value is given.
mkPCGenDetailed :: Word64 -> Word64 -> PCGen

-- | Advances the given generator one step, giving back a Word32 of output
--   and the resultant generator as well. This is the most basic way to
--   advance the generator, and if this is all you're going for then you
--   might want to look at the RandomGen instance and its <a>next</a>
--   method. Other functions in this module let you generate values in
--   batches and so forth, such as for rolling dice.
stepGen :: PCGen -> (Word32, PCGen)
instance GHC.Classes.Ord Data.PCGen.PCGen
instance GHC.Classes.Eq Data.PCGen.PCGen
instance GHC.Show.Show Data.PCGen.PCGen
instance GHC.Read.Read Data.PCGen.PCGen
instance System.Random.RandomGen Data.PCGen.PCGen
instance System.Random.Random Data.PCGen.PCGen