-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Pseudo-random number generation -- -- This package provides basic pseudo-random number generation, including -- the ability to split random number generators. -- --
-- >>> let roll = uniformR (1, 6) :: RandomGen g => g -> (Word, g) -- -- >>> let rolls = unfoldr (Just . roll) :: RandomGen g => g -> [Word] -- -- >>> let pureGen = mkStdGen 42 -- -- >>> take 10 (rolls pureGen) :: [Word] -- [1,1,3,2,4,5,3,4,6,2] ---- -- See System.Random for more details. -- --
-- >>> let rollM = uniformRM (1, 6) :: StatefulGen g m => g -> m Word -- -- >>> let pureGen = mkStdGen 42 -- -- >>> runStateGen_ pureGen (replicateM 10 . rollM) :: [Word] -- [1,1,3,2,4,5,3,4,6,2] ---- -- The monadic adapter System.Random.Stateful.runGenState_ is used -- here to lift the pure pseudo-random number generator pureGen -- into the System.Random.Stateful.StatefulGen 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 mwc-random package: -- --
-- >>> import System.Random.MWC as MWC -- -- >>> let rollM = uniformRM (1, 6) :: StatefulGen g m => g -> m Word -- -- >>> monadicGen <- MWC.create -- -- >>> replicateM 10 (rollM monadicGen) :: IO [Word] -- [2,3,6,6,4,4,3,1,5,4] ---- -- See System.Random.Stateful for more details. @package random @version 1.2.0 -- | This library deals with the common task of pseudo-random number -- generation. module System.Random -- | RandomGen is an interface to pure pseudo-random number -- generators. -- -- StdGen is the standard RandomGen instance provided by -- this library. class RandomGen g -- | Returns an Int that is uniformly distributed over the range -- returned by genRange (including both end points), and a new -- generator. Using next is inefficient as all operations go via -- Integer. See here for more details. It is thus -- deprecated. -- | Deprecated: No longer used next :: RandomGen g => g -> (Int, g) -- | Returns a Word8 that is uniformly distributed over the entire -- Word8 range. genWord8 :: RandomGen g => g -> (Word8, g) -- | Returns a Word16 that is uniformly distributed over the entire -- Word16 range. genWord16 :: RandomGen g => g -> (Word16, g) -- | Returns a Word32 that is uniformly distributed over the entire -- Word32 range. genWord32 :: RandomGen g => g -> (Word32, g) -- | Returns a Word64 that is uniformly distributed over the entire -- Word64 range. genWord64 :: RandomGen g => g -> (Word64, g) -- | genWord32R upperBound g returns a Word32 that is -- uniformly distributed over the range [0, upperBound]. genWord32R :: RandomGen g => Word32 -> g -> (Word32, g) -- | genWord64R upperBound g returns a Word64 that is -- uniformly distributed over the range [0, upperBound]. genWord64R :: RandomGen g => Word64 -> g -> (Word64, g) -- | genShortByteString n g returns a ShortByteString of -- length n filled with pseudo-random bytes. genShortByteString :: RandomGen g => Int -> g -> (ShortByteString, g) -- | Yields the range of values returned by next. -- -- It is required that: -- --
-- >>> import System.Random
--
-- >>> let pureGen = mkStdGen 137
--
-- >>> uniform pureGen :: (Bool, StdGen)
-- (True,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--
uniform :: (RandomGen g, Uniform a) => g -> (a, g)
-- | Generates a value uniformly distributed over the provided range, which
-- is interpreted as inclusive in the lower and upper bound.
--
-- -- uniformR (a, b) = uniformR (b, a) ---- -- This is a pure version of uniformRM. -- --
-- >>> import System.Random
--
-- >>> let pureGen = mkStdGen 137
--
-- >>> uniformR (1 :: Int, 4 :: Int) pureGen
-- (4,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--
uniformR :: (RandomGen g, UniformRange a) => (a, a) -> g -> (a, g)
-- | Generates a ByteString of the specified size using a pure
-- pseudo-random number generator. See uniformByteString for the
-- monadic version.
--
-- -- >>> import System.Random -- -- >>> import Data.ByteString -- -- >>> let pureGen = mkStdGen 137 -- -- >>> unpack . fst . genByteString 10 $ pureGen -- [51,123,251,37,49,167,90,109,1,4] --genByteString :: RandomGen g => Int -> g -> (ByteString, g) -- | The class of types for which uniformly distributed values can be -- generated. -- -- Random exists primarily for backwards compatibility with -- version 1.1 of this library. In new code, use the better specified -- Uniform and UniformRange instead. class Random a -- | Takes a range (lo,hi) and a pseudo-random number generator -- g, and returns a pseudo-random value uniformly distributed over -- the closed interval [lo,hi], together with a new generator. It -- is unspecified what happens if lo>hi. For continuous types -- there is no requirement that the values lo and hi are -- ever produced, but they may be, depending on the implementation and -- the interval. randomR :: (Random a, RandomGen g) => (a, a) -> g -> (a, g) -- | Takes a range (lo,hi) and a pseudo-random number generator -- g, and returns a pseudo-random value uniformly distributed over -- the closed interval [lo,hi], together with a new generator. It -- is unspecified what happens if lo>hi. For continuous types -- there is no requirement that the values lo and hi are -- ever produced, but they may be, depending on the implementation and -- the interval. randomR :: (Random a, RandomGen g, UniformRange a) => (a, a) -> g -> (a, g) -- | The same as randomR, but using a default range determined by -- the type: -- --
-- rollDice :: IO Int -- rollDice = getStdRandom (randomR (1,6)) --getStdRandom :: MonadIO m => (StdGen -> (a, StdGen)) -> m a -- | Gets the global pseudo-random number generator. getStdGen :: MonadIO m => m StdGen -- | Sets the global pseudo-random number generator. setStdGen :: MonadIO m => StdGen -> m () -- | Applies split to the current global pseudo-random generator, -- updates it with one of the results, and returns the other. newStdGen :: MonadIO m => m StdGen -- | A variant of random that uses the global pseudo-random number -- generator. randomIO :: (Random a, MonadIO m) => m a -- | A variant of randomR that uses the global pseudo-random number -- generator. randomRIO :: (Random a, MonadIO m) => (a, a) -> m a instance System.Random.Random GHC.Integer.Type.Integer instance System.Random.Random GHC.Int.Int8 instance System.Random.Random GHC.Int.Int16 instance System.Random.Random GHC.Int.Int32 instance System.Random.Random GHC.Int.Int64 instance System.Random.Random GHC.Types.Int instance System.Random.Random GHC.Types.Word instance System.Random.Random GHC.Word.Word8 instance System.Random.Random GHC.Word.Word16 instance System.Random.Random GHC.Word.Word32 instance System.Random.Random GHC.Word.Word64 instance System.Random.Random Foreign.C.Types.CChar instance System.Random.Random Foreign.C.Types.CSChar instance System.Random.Random Foreign.C.Types.CUChar instance System.Random.Random Foreign.C.Types.CShort instance System.Random.Random Foreign.C.Types.CUShort instance System.Random.Random Foreign.C.Types.CInt instance System.Random.Random Foreign.C.Types.CUInt instance System.Random.Random Foreign.C.Types.CLong instance System.Random.Random Foreign.C.Types.CULong instance System.Random.Random Foreign.C.Types.CPtrdiff instance System.Random.Random Foreign.C.Types.CSize instance System.Random.Random Foreign.C.Types.CWchar instance System.Random.Random Foreign.C.Types.CSigAtomic instance System.Random.Random Foreign.C.Types.CLLong instance System.Random.Random Foreign.C.Types.CULLong instance System.Random.Random Foreign.C.Types.CIntPtr instance System.Random.Random Foreign.C.Types.CUIntPtr instance System.Random.Random Foreign.C.Types.CIntMax instance System.Random.Random Foreign.C.Types.CUIntMax instance System.Random.Random Foreign.C.Types.CFloat instance System.Random.Random Foreign.C.Types.CDouble instance System.Random.Random GHC.Types.Char instance System.Random.Random GHC.Types.Bool instance System.Random.Random GHC.Types.Double instance System.Random.Random GHC.Types.Float -- | This library deals with the common task of pseudo-random number -- generation. module System.Random.Stateful -- | StatefulGen is an interface to monadic pseudo-random number -- generators. class Monad m => StatefulGen g m -- | uniformWord32R upperBound g generates a Word32 that is -- uniformly distributed over the range [0, upperBound]. uniformWord32R :: StatefulGen g m => Word32 -> g -> m Word32 -- | uniformWord64R upperBound g generates a Word64 that is -- uniformly distributed over the range [0, upperBound]. uniformWord64R :: StatefulGen g m => Word64 -> g -> m Word64 -- | Generates a Word8 that is uniformly distributed over the entire -- Word8 range. -- -- The default implementation extracts a Word8 from -- uniformWord32. uniformWord8 :: StatefulGen g m => g -> m Word8 -- | Generates a Word16 that is uniformly distributed over the -- entire Word16 range. -- -- The default implementation extracts a Word16 from -- uniformWord32. uniformWord16 :: StatefulGen g m => g -> m Word16 -- | Generates a Word32 that is uniformly distributed over the -- entire Word32 range. -- -- The default implementation extracts a Word32 from -- uniformWord64. uniformWord32 :: StatefulGen g m => g -> m Word32 -- | Generates a Word64 that is uniformly distributed over the -- entire Word64 range. -- -- The default implementation combines two Word32 from -- uniformWord32 into one Word64. uniformWord64 :: StatefulGen g m => g -> m Word64 -- | uniformShortByteString n g generates a ShortByteString -- of length n filled with pseudo-random bytes. uniformShortByteString :: StatefulGen g m => Int -> g -> m ShortByteString -- | uniformShortByteString n g generates a ShortByteString -- of length n filled with pseudo-random bytes. uniformShortByteString :: (StatefulGen g m, MonadIO m) => Int -> g -> m ShortByteString -- | This class is designed for stateful pseudo-random number generators -- that can be saved as and restored from an immutable data type. class StatefulGen (MutableGen f m) m => FrozenGen f m where { -- | Represents the state of the pseudo-random number generator for use -- with thawGen and freezeGen. type family MutableGen f m = (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 -- | Restores the pseudo-random number generator from its frozen seed. thawGen :: FrozenGen f m => f -> m (MutableGen f m) -- | Interface to operations on RandomGen wrappers like -- IOGenM and StateGenM. class (RandomGen r, StatefulGen g m) => RandomGenM g r m | g -> r applyRandomGenM :: RandomGenM g r m => (r -> (a, r)) -> g -> m a -- | Runs a mutable pseudo-random number generator from its Frozen -- state. -- --
-- >>> import Data.Int (Int8)
--
-- >>> withMutableGen (IOGen (mkStdGen 217)) (uniformListM 5) :: IO ([Int8], IOGen StdGen)
-- ([-74,37,-50,-2,3],IOGen {unIOGen = StdGen {unStdGen = SMGen 4273268533320920145 15251669095119325999}})
--
withMutableGen :: FrozenGen f m => f -> (MutableGen f m -> m a) -> m (a, f)
-- | Same as withMutableGen, but only returns the generated value.
--
-- -- >>> import System.Random.Stateful -- -- >>> let pureGen = mkStdGen 137 -- -- >>> withMutableGen_ (IOGen pureGen) (uniformRM (1 :: Int, 6 :: Int)) -- 4 --withMutableGen_ :: FrozenGen f m => f -> (MutableGen f m -> m a) -> m a -- | Generates a pseudo-random value using monadic interface and -- Random instance. -- --
-- >>> import System.Random.Stateful -- -- >>> let pureGen = mkStdGen 137 -- -- >>> g <- newIOGenM pureGen -- -- >>> randomM g :: IO Double -- 0.5728354935654512 --randomM :: (RandomGenM g r m, Random a) => g -> m a -- | Generates a pseudo-random value using monadic interface and -- Random instance. -- --
-- >>> import System.Random.Stateful -- -- >>> let pureGen = mkStdGen 137 -- -- >>> g <- newIOGenM pureGen -- -- >>> randomRM (1, 100) g :: IO Int -- 52 --randomRM :: (RandomGenM g r m, Random a) => (a, a) -> g -> m a -- | Splits a pseudo-random number generator into two. Overwrites the -- mutable wrapper with one of the resulting generators and returns the -- other. splitGenM :: RandomGenM g r m => g -> m r -- | Wrapper for pure state gen, which acts as an immutable seed for the -- corresponding stateful generator StateGenM 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 State monad using a -- pure pseudo-random number generator. -- --
-- >>> import System.Random.Stateful
--
-- >>> let pureGen = mkStdGen 137
--
-- >>> runStateGen pureGen randomM :: (Int, StdGen)
-- (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--
runStateGen :: RandomGen g => g -> (StateGenM g -> State g a) -> (a, g)
-- | Runs a monadic generating action in the State monad using a
-- pure pseudo-random number generator. Returns only the resulting
-- pseudo-random value.
--
-- -- >>> import System.Random.Stateful -- -- >>> let pureGen = mkStdGen 137 -- -- >>> runStateGen_ pureGen randomM :: Int -- 7879794327570578227 --runStateGen_ :: RandomGen g => g -> (StateGenM g -> State g a) -> a -- | Runs a monadic generating action in the StateT monad using a -- pure pseudo-random number generator. -- --
-- >>> import System.Random.Stateful
--
-- >>> let pureGen = mkStdGen 137
--
-- >>> runStateGenT pureGen randomM :: IO (Int, StdGen)
-- (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--
runStateGenT :: RandomGen g => g -> (StateGenM g -> StateT g m a) -> m (a, g)
-- | Runs a monadic generating action in the StateT monad using a
-- pure pseudo-random number generator. Returns only the resulting
-- pseudo-random value.
--
-- -- >>> import System.Random.Stateful -- -- >>> let pureGen = mkStdGen 137 -- -- >>> runStateGenT_ pureGen randomM :: IO Int -- 7879794327570578227 --runStateGenT_ :: (RandomGen g, Functor f) => g -> (StateGenM g -> StateT g f a) -> f a -- | Runs a monadic generating action in the ST monad using a pure -- pseudo-random number generator. runStateGenST :: RandomGen g => g -> (forall s. StateGenM g -> StateT g (ST s) a) -> (a, g) -- | Frozen version of mutable AtomicGenM generator newtype AtomicGen g AtomicGen :: g -> AtomicGen g [unAtomicGen] :: AtomicGen g -> g -- | Wraps an IORef that holds a pure pseudo-random number -- generator. All operations are performed atomically. -- --
-- >>> import System.Random.Stateful -- -- >>> let pureGen = mkStdGen 137 -- -- >>> g <- newAtomicGenM pureGen -- -- >>> applyAtomicGen random g :: IO Int -- 7879794327570578227 --applyAtomicGen :: MonadIO m => (g -> (a, g)) -> AtomicGenM g -> m a -- | Frozen version of mutable IOGenM generator newtype IOGen g IOGen :: g -> IOGen g [unIOGen] :: IOGen g -> g -- | Wraps an IORef that holds a pure pseudo-random number -- generator. -- --
-- >>> import UnliftIO.Temporary (withSystemTempFile) -- -- >>> import Data.ByteString (hPutStr) -- -- >>> let ioGen g = withSystemTempFile "foo.bin" $ \_ h -> uniformRM (0, 100) g >>= flip uniformByteStringM g >>= hPutStr h ---- -- and then run it: -- --
-- >>> newIOGenM (mkStdGen 1729) >>= ioGen --newtype IOGenM g IOGenM :: IORef g -> IOGenM g [unIOGenM] :: IOGenM g -> IORef g -- | Creates a new IOGenM. newIOGenM :: MonadIO m => g -> m (IOGenM g) -- | Applies a pure operation to the wrapped pseudo-random number -- generator. -- --
-- >>> import System.Random.Stateful -- -- >>> let pureGen = mkStdGen 137 -- -- >>> g <- newIOGenM pureGen -- -- >>> applyIOGen random g :: IO Int -- 7879794327570578227 --applyIOGen :: MonadIO m => (g -> (a, g)) -> IOGenM g -> m a -- | Frozen version of mutable STGenM generator newtype STGen g STGen :: g -> STGen g [unSTGen] :: STGen g -> g -- | Wraps an STRef that holds a pure pseudo-random number -- generator. -- --
-- >>> import System.Random.Stateful
--
-- >>> let pureGen = mkStdGen 137
--
-- >>> (runSTGen pureGen (\g -> applySTGen random g)) :: (Int, StdGen)
-- (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--
applySTGen :: (g -> (a, g)) -> STGenM g s -> ST s a
-- | Runs a monadic generating action in the ST monad using a pure
-- pseudo-random number generator.
--
--
-- >>> import System.Random.Stateful
--
-- >>> let pureGen = mkStdGen 137
--
-- >>> (runSTGen pureGen (\g -> applySTGen random g)) :: (Int, StdGen)
-- (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
--
runSTGen :: RandomGen g => g -> (forall s. STGenM g s -> ST s a) -> (a, g)
-- | Runs a monadic generating action in the ST monad using a pure
-- pseudo-random number generator. Returns only the resulting
-- pseudo-random value.
--
-- -- >>> import System.Random.Stateful -- -- >>> let pureGen = mkStdGen 137 -- -- >>> (runSTGen_ pureGen (\g -> applySTGen random g)) :: Int -- 7879794327570578227 --runSTGen_ :: RandomGen g => g -> (forall s. STGenM g s -> ST s a) -> 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. uniformM :: (Uniform a, StatefulGen g m) => g -> m a -- | Generates a list of pseudo-random values. -- --
-- >>> import System.Random.Stateful -- -- >>> let pureGen = mkStdGen 137 -- -- >>> g <- newIOGenM pureGen -- -- >>> uniformListM 10 g :: IO [Bool] -- [True,True,True,True,False,True,True,False,False,False] --uniformListM :: (StatefulGen g m, Uniform a) => Int -> 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. -- --
-- uniformRM (a, b) = uniformRM (b, a) --uniformRM :: (UniformRange a, StatefulGen g m) => (a, a) -> g -> m a -- | Efficiently generates a sequence of pseudo-random bytes in a platform -- independent manner. genShortByteStringIO :: MonadIO m => Int -> m Word64 -> m ShortByteString -- | Same as genShortByteStringIO, but runs in ST. genShortByteStringST :: Int -> ST s Word64 -> ST s ShortByteString -- | Generates a pseudo-random ByteString of the specified size. uniformByteStringM :: StatefulGen g m => Int -> g -> m ByteString -- | Generates uniformly distributed Double in the range -- <math>. Numbers are generated by generating uniform -- Word64 and dividing it by <math>. It's used to implement -- UniformR instance for Double. uniformDouble01M :: StatefulGen g m => g -> m Double -- | Generates uniformly distributed Double in the range -- <math>. Number is generated as <math>. Constant is 1/2 of -- smallest nonzero value which could be generated by -- uniformDouble01M. uniformDoublePositive01M :: StatefulGen g m => g -> m Double -- | Generates uniformly distributed Float in the range -- <math>. Numbers are generated by generating uniform -- Word32 and dividing it by <math>. It's used to implement -- UniformR instance for Float uniformFloat01M :: StatefulGen g m => g -> m Float -- | Generates uniformly distributed Float in the range -- <math>. Number is generated as <math>. Constant is 1/2 of -- smallest nonzero value which could be generated by -- uniformFloat01M. uniformFloatPositive01M :: StatefulGen g m => g -> m Float instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (System.Random.Stateful.STGen g) instance Foreign.Storable.Storable g => Foreign.Storable.Storable (System.Random.Stateful.STGen g) instance System.Random.Internal.RandomGen g => System.Random.Internal.RandomGen (System.Random.Stateful.STGen g) instance GHC.Show.Show g => GHC.Show.Show (System.Random.Stateful.STGen g) instance GHC.Classes.Ord g => GHC.Classes.Ord (System.Random.Stateful.STGen g) instance GHC.Classes.Eq g => GHC.Classes.Eq (System.Random.Stateful.STGen g) instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (System.Random.Stateful.IOGen g) instance Foreign.Storable.Storable g => Foreign.Storable.Storable (System.Random.Stateful.IOGen g) instance System.Random.Internal.RandomGen g => System.Random.Internal.RandomGen (System.Random.Stateful.IOGen g) instance GHC.Show.Show g => GHC.Show.Show (System.Random.Stateful.IOGen g) instance GHC.Classes.Ord g => GHC.Classes.Ord (System.Random.Stateful.IOGen g) instance GHC.Classes.Eq g => GHC.Classes.Eq (System.Random.Stateful.IOGen g) instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (System.Random.Stateful.AtomicGen g) instance Foreign.Storable.Storable g => Foreign.Storable.Storable (System.Random.Stateful.AtomicGen g) instance System.Random.Internal.RandomGen g => System.Random.Internal.RandomGen (System.Random.Stateful.AtomicGen g) instance GHC.Show.Show g => GHC.Show.Show (System.Random.Stateful.AtomicGen g) instance GHC.Classes.Ord g => GHC.Classes.Ord (System.Random.Stateful.AtomicGen g) instance GHC.Classes.Eq g => GHC.Classes.Eq (System.Random.Stateful.AtomicGen g) instance System.Random.Internal.RandomGen g => System.Random.Internal.FrozenGen (System.Random.Stateful.STGen g) (GHC.ST.ST s) instance System.Random.Internal.RandomGen r => System.Random.Stateful.RandomGenM (System.Random.Stateful.STGenM r s) r (GHC.ST.ST s) instance System.Random.Internal.RandomGen g => System.Random.Internal.StatefulGen (System.Random.Stateful.STGenM g s) (GHC.ST.ST s) instance (System.Random.Internal.RandomGen g, Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.FrozenGen (System.Random.Stateful.IOGen g) m instance (System.Random.Internal.RandomGen r, Control.Monad.IO.Class.MonadIO m) => System.Random.Stateful.RandomGenM (System.Random.Stateful.IOGenM r) r m instance (System.Random.Internal.RandomGen g, Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.StatefulGen (System.Random.Stateful.IOGenM g) m instance (System.Random.Internal.RandomGen g, Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.FrozenGen (System.Random.Stateful.AtomicGen g) m instance (System.Random.Internal.RandomGen r, Control.Monad.IO.Class.MonadIO m) => System.Random.Stateful.RandomGenM (System.Random.Stateful.AtomicGenM r) r m instance (System.Random.Internal.RandomGen g, Control.Monad.IO.Class.MonadIO m) => System.Random.Internal.StatefulGen (System.Random.Stateful.AtomicGenM g) m instance (System.Random.Internal.RandomGen r, Control.Monad.State.Class.MonadState r m) => System.Random.Stateful.RandomGenM (System.Random.Internal.StateGenM r) r m