HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Modulerandom-1.2.1.3Haskell2010

System.Random.Internal

This library deals with the common task of pseudo-random number generation.

  • 3 types
  • 5 classes
  • 19 values
  • Packagerandom-1.2.1.3
  • Exports27
  • LanguageHaskell2010
  • LicenceBSD-3-Clause
  • SourceInternal.hs

Pure and monadic pseudo-random number generator interfaces

3 declarations
classclass RandomGen g where
#

RandomGen is an interface to pure pseudo-random number generators.

StdGen is the standard RandomGen instance provided by this library.

Methods

  • next :: g -> (Int, 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.

  • genWord8 :: g -> (Word8, g)

    Returns a Word8 that is uniformly distributed over the entire Word8 range.

  • genWord16 :: g -> (Word16, g)

    Returns a Word16 that is uniformly distributed over the entire Word16 range.

  • genWord32 :: g -> (Word32, g)

    Returns a Word32 that is uniformly distributed over the entire Word32 range.

  • genWord64 :: g -> (Word64, g)

    Returns a Word64 that is uniformly distributed over the entire Word64 range.

  • genWord32R :: Word32 -> g -> (Word32, g)

    genWord32R upperBound g returns a Word32 that is uniformly distributed over the range [0, upperBound].

  • genWord64R :: Word64 -> g -> (Word64, g)

    genWord64R upperBound g returns a Word64 that is uniformly distributed over the range [0, upperBound].

  • genShortByteString :: Int -> g -> (ShortByteString, g)

    genShortByteString n g returns a ShortByteString of length n filled with pseudo-random bytes.

  • genRange :: g -> (Int, Int)

    Yields the range of values returned by next.

    It is required that:

    • If (a, b) = genRange g, then a < b.

    • genRange must not examine its argument so the value it returns is determined only by the instance of RandomGen.

    The default definition spans the full range of Int.

  • split :: g -> (g, g)

    Returns two distinct pseudo-random number generators.

    Implementations should take care to ensure that the resulting generators are not correlated. Some pseudo-random number generators are not splittable. In that case, the split implementation should fail with a descriptive error message.

Instances8RandomGen, …
classclass Monad m => StatefulGen g (m :: Type -> Type) where
#

StatefulGen is an interface to monadic pseudo-random number generators.

Methods

Instances5StatefulGen
classclass StatefulGen (MutableGen f m) m => FrozenGen f (m :: Type -> Type) where
#

This class is designed for stateful pseudo-random number generators that can be saved as and restored from an immutable data type.

Associated types

Methods

  • freezeGen :: MutableGen f m -> m f

    Saves the state of the pseudo-random number generator as a frozen seed.

  • thawGen :: f -> m (MutableGen f m)

    Restores the pseudo-random number generator from its frozen seed.

Instances5FrozenGen

Standard pseudo-random number generator

newtypenewtype StdGen
#

The standard pseudo-random number generator.

Constructors

Instances4Eq, Show, NFData, RandomGen
  • Eq StdGenDefined in random-1.2.1.3 · System.Random.Internal
  • Show StdGenDefined in random-1.2.1.3 · System.Random.Internal
  • NFData StdGenDefined in random-1.2.1.3 · System.Random.Internal
  • RandomGen StdGenDefined in random-1.2.1.3 · System.Random.Internal

Monadic adapters for pure pseudo-random number generators

0 declarations

Pure adapter

newtypenewtype StateGen g
#

Wrapper for pure state gen, which acts as an immutable seed for the corresponding stateful generator StateGenM

Constructors

Instances8Eq, Ord, Show, Storable, NFData, RandomGen, …
valuesplitGen :: (MonadState g m, RandomGen g) => m g
#

Splits a pseudo-random number generator into two. Updates the state with one of the resulting generators and returns the other.

valuerunStateGen :: 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.

Examples
Example3 expressions
import System.Random.Statefullet pureGen = mkStdGen 137runStateGen pureGen randomM :: (Int, StdGen)(7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
valuerunStateGen_ :: RandomGen g => g -> (StateGenM g -> State g a) -> a
#

Runs a monadic generating action in the State monad using a pure pseudo-random number generator. Returns only the resulting pseudo-random value.

Examples
Example3 expressions
import System.Random.Statefullet pureGen = mkStdGen 137runStateGen_ pureGen randomM :: Int7879794327570578227
valuerunStateGenT
  1. :: RandomGen g
  2. => g
  3. -> StateGenM g -> StateT g m a
  4. -> m (a, g)
#

Runs a monadic generating action in the StateT monad using a pure pseudo-random number generator.

Examples
Example3 expressions
import System.Random.Statefullet pureGen = mkStdGen 137runStateGenT pureGen randomM :: IO (Int, StdGen)(7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})
valuerunStateGenT_
  1. :: (RandomGen g, Functor f)
  2. => g
  3. -> StateGenM g -> StateT g f a
  4. -> f a
#

Runs a monadic generating action in the StateT monad using a pure pseudo-random number generator. Returns only the resulting pseudo-random value.

Examples
Example3 expressions
import System.Random.Statefullet pureGen = mkStdGen 137runStateGenT_ pureGen randomM :: IO Int7879794327570578227

Pseudo-random values of various types

10 declarations
classclass Uniform a where
#

The class of types for which a uniformly distributed value can be drawn from all possible values of the type.

Methods

  • uniformM :: StatefulGen g m => g -> m a

    Generates a value uniformly distributed over all possible values of that type.

    There is a default implementation via Generic:

    Example7 expressions
    :set -XDeriveGeneric -XDeriveAnyClassimport GHC.Generics (Generic)import System.Random.Statefuldata MyBool = MyTrue | MyFalse deriving (Show, Generic, Finite, Uniform)data Action = Code MyBool | Eat (Maybe Bool) | Sleep deriving (Show, Generic, Finite, Uniform)gen <- newIOGenM (mkStdGen 42)uniformListM 10 gen :: IO [Action][Code MyTrue,Code MyTrue,Eat Nothing,Code MyFalse,Eat (Just False),Eat (Just True),Eat Nothing,Eat (Just False),Sleep,Code MyFalse]
Instances39Uniform, …
valueuniformViaFiniteM
  1. :: (StatefulGen g m, Generic a, GFinite (Rep a))
  2. => g
  3. -> m a
#

A definition of Uniform for Finite types. If your data has several fields of sub-Word cardinality, this instance may be more efficient than one, derived via Generic and GUniform.

Example7 expressions
:set -XDeriveGeneric -XDeriveAnyClassimport GHC.Generics (Generic)import System.Random.Statefuldata Triple = Triple Word8 Word8 Word8 deriving (Show, Generic, Finite)instance Uniform Triple where uniformM = uniformViaFiniteMgen <- newIOGenM (mkStdGen 42)uniformListM 5 gen :: IO [Triple][Triple 60 226 48,Triple 234 194 151,Triple 112 96 95,Triple 51 251 15,Triple 6 0 208]
classclass UniformRange a where
#

The class of types for which a uniformly distributed value can be drawn from a range.

Methods

  • uniformRM :: StatefulGen g m => (a, a) -> g -> m a

    Generates a value uniformly distributed over the provided range, which is interpreted as inclusive in the lower and upper bound.

    • uniformRM (1 :: Int, 4 :: Int) generates values uniformly from the set \{1,2,3,4\}

    • uniformRM (1 :: Float, 4 :: Float) generates values uniformly from the set \{x\;|\;1 \le x \le 4\}

    The following law should hold to make the function always defined:

    uniformRM (a, b) = uniformRM (b, a)
Instances39UniformRange, …
valueuniformEnumM :: (Enum a, Bounded a, StatefulGen g m) => g -> m a
#

Generates uniformly distributed Enum. One can use it to define a Uniform instance:

data Colors = Red | Green | Blue deriving (Enum, Bounded)
instance Uniform Colors where uniformM = uniformEnumM
valueuniformEnumRM :: (Enum a, StatefulGen g m) => (a, a) -> g -> m a
#

Generates uniformly distributed Enum in the given range. One can use it to define a UniformRange instance:

data Colors = Red | Green | Blue deriving (Enum)
instance UniformRange Colors where
  uniformRM = uniformEnumRM
  inInRange (lo, hi) x = isInRange (fromEnum lo, fromEnum hi) (fromEnum x)

Generators for sequences of pseudo-random bytes

2 declarations