System.Random.Stateful

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

Pure Random Generator

class RandomGen g where

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

StdGen is the standard RandomGen instance provided by this library.

Since: 1.0.0

Minimal complete definition

(genWord32 | genWord64 | next, genRange)

Methods

next :: g -> (Int, g)

Deprecated: No longer used

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.

Since: 1.0.0

genWord8 :: g -> (Word8, g)

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

Since: 1.2.0

genWord16 :: g -> (Word16, g)

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

Since: 1.2.0

genWord32 :: g -> (Word32, g)

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

Since: 1.2.0

genWord64 :: g -> (Word64, g)

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

Since: 1.2.0

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

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

Since: 1.2.0

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

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

Since: 1.2.0

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

Deprecated: In favor of uniformShortByteString

Same as uniformByteArray False, but for ShortByteString.

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

Note - This function will be removed from the type class in the next major release as it is no longer needed because of unsafeUniformFillMutableByteArray.

Since: 1.2.0

unsafeUniformFillMutableByteArray

Arguments

:: MutableByteArray s

Mutable array to fill with random bytes

-> Int

Offset into a mutable array from the beginning in number of bytes. Offset must be non-negative, but this will not be checked

-> Int

Number of randomly generated bytes to write into the array. Number of bytes must be non-negative and less then the total size of the array, minus the offset. This also will be checked.

-> g

-> ST s g

Fill in the supplied MutableByteArray with uniformly generated random bytes. This function is unsafe because it is not required to do any bounds checking. For a safe variant use uniformFillMutableByteArrayM instead.

Default type class implementation uses defaultUnsafeUniformFillMutableByteArray.

Since: 1.3.0

genRange :: g -> (Int, Int)

Deprecated: No longer used

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.

Since: 1.0.0

split :: g -> (g, g)

Deprecated: In favor of splitGen

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.

Since: 1.0.0

default split :: SplitGen g => g -> (g, g)

Instances

RandomGen StdGen

Defined in System.Random.Internal

Methods

next :: StdGen -> (Int, StdGen)

genWord8 :: StdGen -> (Word8, StdGen)

genWord16 :: StdGen -> (Word16, StdGen)

genWord32 :: StdGen -> (Word32, StdGen)

genWord64 :: StdGen -> (Word64, StdGen)

genWord32R :: Word32 -> StdGen -> (Word32, StdGen)

genWord64R :: Word64 -> StdGen -> (Word64, StdGen)

genShortByteString :: Int -> StdGen -> (ShortByteString, StdGen)

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> StdGen -> ST s StdGen

genRange :: StdGen -> (Int, Int)

split :: StdGen -> (StdGen, StdGen)

RandomGen SMGen

Defined in System.Random.Internal

Methods

next :: SMGen -> (Int, SMGen)

genWord8 :: SMGen -> (Word8, SMGen)

genWord16 :: SMGen -> (Word16, SMGen)

genWord32 :: SMGen -> (Word32, SMGen)

genWord64 :: SMGen -> (Word64, SMGen)

genWord32R :: Word32 -> SMGen -> (Word32, SMGen)

genWord64R :: Word64 -> SMGen -> (Word64, SMGen)

genShortByteString :: Int -> SMGen -> (ShortByteString, SMGen)

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> SMGen -> ST s SMGen

genRange :: SMGen -> (Int, Int)

split :: SMGen -> (SMGen, SMGen)

RandomGen SMGen

Defined in System.Random.Internal

Methods

next :: SMGen -> (Int, SMGen)

genWord8 :: SMGen -> (Word8, SMGen)

genWord16 :: SMGen -> (Word16, SMGen)

genWord32 :: SMGen -> (Word32, SMGen)

genWord64 :: SMGen -> (Word64, SMGen)

genWord32R :: Word32 -> SMGen -> (Word32, SMGen)

genWord64R :: Word64 -> SMGen -> (Word64, SMGen)

genShortByteString :: Int -> SMGen -> (ShortByteString, SMGen)

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> SMGen -> ST s SMGen

genRange :: SMGen -> (Int, Int)

split :: SMGen -> (SMGen, SMGen)

RandomGen g => RandomGen (StateGen g)

Defined in System.Random.Internal

Methods

next :: StateGen g -> (Int, StateGen g)

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

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

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

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

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

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

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

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> StateGen g -> ST s (StateGen g)

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

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

RandomGen g => RandomGen (AtomicGen g)

Defined in System.Random.Stateful

Methods

next :: AtomicGen g -> (Int, AtomicGen g)

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

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

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

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

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

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

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

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> AtomicGen g -> ST s (AtomicGen g)

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

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

RandomGen g => RandomGen (IOGen g)

Defined in System.Random.Stateful

Methods

next :: IOGen g -> (Int, IOGen g)

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

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

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

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

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

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

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

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> IOGen g -> ST s (IOGen g)

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

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

RandomGen g => RandomGen (STGen g)

Defined in System.Random.Stateful

Methods

next :: STGen g -> (Int, STGen g)

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

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

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

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

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

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

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

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> STGen g -> ST s (STGen g)

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

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

RandomGen g => RandomGen (TGen g)

Defined in System.Random.Stateful

Methods

next :: TGen g -> (Int, TGen g)

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

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

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

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

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

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

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

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> TGen g -> ST s (TGen g)

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

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

class RandomGen g => SplitGen g where

Pseudo-random generators that can be split into two separate and independent psuedo-random generators should provide an instance for this type class.

Historically this functionality was included in the RandomGen type class in the split function, however, few pseudo-random generators possess this property of splittability. This lead the old split function being usually implemented in terms of error.

Since: 1.3.0

Methods

splitGen :: g -> (g, g)

Returns two distinct pseudo-random number generators.

Implementations should take care to ensure that the resulting generators are not correlated.

Since: 1.3.0

Instances

SplitGen StdGen

Defined in System.Random.Internal

Methods

splitGen :: StdGen -> (StdGen, StdGen)

SplitGen SMGen

Defined in System.Random.Internal

Methods

splitGen :: SMGen -> (SMGen, SMGen)

SplitGen SMGen

Defined in System.Random.Internal

Methods

splitGen :: SMGen -> (SMGen, SMGen)

SplitGen g => SplitGen (AtomicGen g)

Defined in System.Random.Stateful

Methods

splitGen :: AtomicGen g -> (AtomicGen g, AtomicGen g)

SplitGen g => SplitGen (IOGen g)

Defined in System.Random.Stateful

Methods

splitGen :: IOGen g -> (IOGen g, IOGen g)

SplitGen g => SplitGen (STGen g)

Defined in System.Random.Stateful

Methods

splitGen :: STGen g -> (STGen g, STGen g)

SplitGen g => SplitGen (TGen g)

Defined in System.Random.Stateful

Methods

splitGen :: TGen g -> (TGen g, TGen g)

class Random a where

The class of types for which random values can be generated. Most instances of Random will produce values that are uniformly distributed on the full range, but for those types without a well-defined "full range" some sensible default subrange will be selected.

Random exists primarily for backwards compatibility with version 1.1 of this library. In new code, use the better specified Uniform and UniformRange instead.

Since: 1.0.0

Minimal complete definition

Nothing

Methods

randomR :: 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, but usually the values will simply get swapped.

>>> let gen = mkStdGen 26
>>> fst $ randomR ('a', 'z') gen
'z'
>>> fst $ randomR ('a', 'z') gen
'z'

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.

There is no requirement to follow the Ord instance and the concept of range can be defined on per type basis. For example product types will treat their values independently:

>>> fst $ randomR (('a', 5.0), ('z', 10.0)) $ mkStdGen 26
('z',5.22694980853051)

In case when a lawful range is desired uniformR should be used instead.

Since: 1.0.0

default randomR :: (RandomGen g, UniformRange a) => (a, a) -> g -> (a, g)

random :: RandomGen g => g -> (a, g)

The same as randomR, but using a default range determined by the type:

• For bounded types (instances of Bounded, such as Char), the range is normally the whole type.
• For floating point types, the range is normally the closed interval [0,1].
• For Integer, the range is (arbitrarily) the range of Int.

Since: 1.0.0

default random :: (RandomGen g, Uniform a) => g -> (a, g)

randomRs :: RandomGen g => (a, a) -> g -> [a]

Plural variant of randomR, producing an infinite list of pseudo-random values instead of returning a new generator.

Since: 1.0.0

randoms :: RandomGen g => g -> [a]

Plural variant of random, producing an infinite list of pseudo-random values instead of returning a new generator.

Since: 1.0.0

Instances

Random CBool

Defined in System.Random

Methods

randomR :: RandomGen g => (CBool, CBool) -> g -> (CBool, g)

random :: RandomGen g => g -> (CBool, g)

randomRs :: RandomGen g => (CBool, CBool) -> g -> [CBool]

randoms :: RandomGen g => g -> [CBool]

Random CChar

Defined in System.Random

Methods

randomR :: RandomGen g => (CChar, CChar) -> g -> (CChar, g)

random :: RandomGen g => g -> (CChar, g)

randomRs :: RandomGen g => (CChar, CChar) -> g -> [CChar]

randoms :: RandomGen g => g -> [CChar]

Random CDouble

Note - random produces values in the closed range [0,1].

Defined in System.Random

Methods

randomR :: RandomGen g => (CDouble, CDouble) -> g -> (CDouble, g)

random :: RandomGen g => g -> (CDouble, g)

randomRs :: RandomGen g => (CDouble, CDouble) -> g -> [CDouble]

randoms :: RandomGen g => g -> [CDouble]

Random CFloat

Note - random produces values in the closed range [0,1].

Defined in System.Random

Methods

randomR :: RandomGen g => (CFloat, CFloat) -> g -> (CFloat, g)

random :: RandomGen g => g -> (CFloat, g)

randomRs :: RandomGen g => (CFloat, CFloat) -> g -> [CFloat]

randoms :: RandomGen g => g -> [CFloat]

Random CInt

Defined in System.Random

Methods

randomR :: RandomGen g => (CInt, CInt) -> g -> (CInt, g)

random :: RandomGen g => g -> (CInt, g)

randomRs :: RandomGen g => (CInt, CInt) -> g -> [CInt]

randoms :: RandomGen g => g -> [CInt]

Random CIntMax

Defined in System.Random

Methods

randomR :: RandomGen g => (CIntMax, CIntMax) -> g -> (CIntMax, g)

random :: RandomGen g => g -> (CIntMax, g)

randomRs :: RandomGen g => (CIntMax, CIntMax) -> g -> [CIntMax]

randoms :: RandomGen g => g -> [CIntMax]

Random CIntPtr

Defined in System.Random

Methods

randomR :: RandomGen g => (CIntPtr, CIntPtr) -> g -> (CIntPtr, g)

random :: RandomGen g => g -> (CIntPtr, g)

randomRs :: RandomGen g => (CIntPtr, CIntPtr) -> g -> [CIntPtr]

randoms :: RandomGen g => g -> [CIntPtr]

Random CLLong

Defined in System.Random

Methods

randomR :: RandomGen g => (CLLong, CLLong) -> g -> (CLLong, g)

random :: RandomGen g => g -> (CLLong, g)

randomRs :: RandomGen g => (CLLong, CLLong) -> g -> [CLLong]

randoms :: RandomGen g => g -> [CLLong]

Random CLong

Defined in System.Random

Methods

randomR :: RandomGen g => (CLong, CLong) -> g -> (CLong, g)

random :: RandomGen g => g -> (CLong, g)

randomRs :: RandomGen g => (CLong, CLong) -> g -> [CLong]

randoms :: RandomGen g => g -> [CLong]

Random CPtrdiff

Defined in System.Random

Methods

randomR :: RandomGen g => (CPtrdiff, CPtrdiff) -> g -> (CPtrdiff, g)

random :: RandomGen g => g -> (CPtrdiff, g)

randomRs :: RandomGen g => (CPtrdiff, CPtrdiff) -> g -> [CPtrdiff]

randoms :: RandomGen g => g -> [CPtrdiff]

Random CSChar

Defined in System.Random

Methods

randomR :: RandomGen g => (CSChar, CSChar) -> g -> (CSChar, g)

random :: RandomGen g => g -> (CSChar, g)

randomRs :: RandomGen g => (CSChar, CSChar) -> g -> [CSChar]

randoms :: RandomGen g => g -> [CSChar]

Random CShort

Defined in System.Random

Methods

randomR :: RandomGen g => (CShort, CShort) -> g -> (CShort, g)

random :: RandomGen g => g -> (CShort, g)

randomRs :: RandomGen g => (CShort, CShort) -> g -> [CShort]

randoms :: RandomGen g => g -> [CShort]

Random CSigAtomic

Defined in System.Random

Methods

randomR :: RandomGen g => (CSigAtomic, CSigAtomic) -> g -> (CSigAtomic, g)

random :: RandomGen g => g -> (CSigAtomic, g)

randomRs :: RandomGen g => (CSigAtomic, CSigAtomic) -> g -> [CSigAtomic]

randoms :: RandomGen g => g -> [CSigAtomic]

Random CSize

Defined in System.Random

Methods

randomR :: RandomGen g => (CSize, CSize) -> g -> (CSize, g)

random :: RandomGen g => g -> (CSize, g)

randomRs :: RandomGen g => (CSize, CSize) -> g -> [CSize]

randoms :: RandomGen g => g -> [CSize]

Random CUChar

Defined in System.Random

Methods

randomR :: RandomGen g => (CUChar, CUChar) -> g -> (CUChar, g)

random :: RandomGen g => g -> (CUChar, g)

randomRs :: RandomGen g => (CUChar, CUChar) -> g -> [CUChar]

randoms :: RandomGen g => g -> [CUChar]

Random CUInt

Defined in System.Random

Methods

randomR :: RandomGen g => (CUInt, CUInt) -> g -> (CUInt, g)

random :: RandomGen g => g -> (CUInt, g)

randomRs :: RandomGen g => (CUInt, CUInt) -> g -> [CUInt]

randoms :: RandomGen g => g -> [CUInt]

Random CUIntMax

Defined in System.Random

Methods

randomR :: RandomGen g => (CUIntMax, CUIntMax) -> g -> (CUIntMax, g)

random :: RandomGen g => g -> (CUIntMax, g)

randomRs :: RandomGen g => (CUIntMax, CUIntMax) -> g -> [CUIntMax]

randoms :: RandomGen g => g -> [CUIntMax]

Random CUIntPtr

Defined in System.Random

Methods

randomR :: RandomGen g => (CUIntPtr, CUIntPtr) -> g -> (CUIntPtr, g)

random :: RandomGen g => g -> (CUIntPtr, g)

randomRs :: RandomGen g => (CUIntPtr, CUIntPtr) -> g -> [CUIntPtr]

randoms :: RandomGen g => g -> [CUIntPtr]

Random CULLong

Defined in System.Random

Methods

randomR :: RandomGen g => (CULLong, CULLong) -> g -> (CULLong, g)

random :: RandomGen g => g -> (CULLong, g)

randomRs :: RandomGen g => (CULLong, CULLong) -> g -> [CULLong]

randoms :: RandomGen g => g -> [CULLong]

Random CULong

Defined in System.Random

Methods

randomR :: RandomGen g => (CULong, CULong) -> g -> (CULong, g)

random :: RandomGen g => g -> (CULong, g)

randomRs :: RandomGen g => (CULong, CULong) -> g -> [CULong]

randoms :: RandomGen g => g -> [CULong]

Random CUShort

Defined in System.Random

Methods

randomR :: RandomGen g => (CUShort, CUShort) -> g -> (CUShort, g)

random :: RandomGen g => g -> (CUShort, g)

randomRs :: RandomGen g => (CUShort, CUShort) -> g -> [CUShort]

randoms :: RandomGen g => g -> [CUShort]

Random CWchar

Defined in System.Random

Methods

randomR :: RandomGen g => (CWchar, CWchar) -> g -> (CWchar, g)

random :: RandomGen g => g -> (CWchar, g)

randomRs :: RandomGen g => (CWchar, CWchar) -> g -> [CWchar]

randoms :: RandomGen g => g -> [CWchar]

Random Int16

Defined in System.Random

Methods

randomR :: RandomGen g => (Int16, Int16) -> g -> (Int16, g)

random :: RandomGen g => g -> (Int16, g)

randomRs :: RandomGen g => (Int16, Int16) -> g -> [Int16]

randoms :: RandomGen g => g -> [Int16]

Random Int32

Defined in System.Random

Methods

randomR :: RandomGen g => (Int32, Int32) -> g -> (Int32, g)

random :: RandomGen g => g -> (Int32, g)

randomRs :: RandomGen g => (Int32, Int32) -> g -> [Int32]

randoms :: RandomGen g => g -> [Int32]

Random Int64

Defined in System.Random

Methods

randomR :: RandomGen g => (Int64, Int64) -> g -> (Int64, g)

random :: RandomGen g => g -> (Int64, g)

randomRs :: RandomGen g => (Int64, Int64) -> g -> [Int64]

randoms :: RandomGen g => g -> [Int64]

Random Int8

Defined in System.Random

Methods

randomR :: RandomGen g => (Int8, Int8) -> g -> (Int8, g)

random :: RandomGen g => g -> (Int8, g)

randomRs :: RandomGen g => (Int8, Int8) -> g -> [Int8]

randoms :: RandomGen g => g -> [Int8]

Random Word16

Defined in System.Random

Methods

randomR :: RandomGen g => (Word16, Word16) -> g -> (Word16, g)

random :: RandomGen g => g -> (Word16, g)

randomRs :: RandomGen g => (Word16, Word16) -> g -> [Word16]

randoms :: RandomGen g => g -> [Word16]

Random Word32

Defined in System.Random

Methods

randomR :: RandomGen g => (Word32, Word32) -> g -> (Word32, g)

random :: RandomGen g => g -> (Word32, g)

randomRs :: RandomGen g => (Word32, Word32) -> g -> [Word32]

randoms :: RandomGen g => g -> [Word32]

Random Word64

Defined in System.Random

Methods

randomR :: RandomGen g => (Word64, Word64) -> g -> (Word64, g)

random :: RandomGen g => g -> (Word64, g)

randomRs :: RandomGen g => (Word64, Word64) -> g -> [Word64]

randoms :: RandomGen g => g -> [Word64]

Random Word8

Defined in System.Random

Methods

randomR :: RandomGen g => (Word8, Word8) -> g -> (Word8, g)

random :: RandomGen g => g -> (Word8, g)

randomRs :: RandomGen g => (Word8, Word8) -> g -> [Word8]

randoms :: RandomGen g => g -> [Word8]

Random Integer

Note - random generates values in the Int range

Defined in System.Random

Methods

randomR :: RandomGen g => (Integer, Integer) -> g -> (Integer, g)

random :: RandomGen g => g -> (Integer, g)

randomRs :: RandomGen g => (Integer, Integer) -> g -> [Integer]

randoms :: RandomGen g => g -> [Integer]

Random Bool

Defined in System.Random

Methods

randomR :: RandomGen g => (Bool, Bool) -> g -> (Bool, g)

random :: RandomGen g => g -> (Bool, g)

randomRs :: RandomGen g => (Bool, Bool) -> g -> [Bool]

randoms :: RandomGen g => g -> [Bool]

Random Char

Defined in System.Random

Methods

randomR :: RandomGen g => (Char, Char) -> g -> (Char, g)

random :: RandomGen g => g -> (Char, g)

randomRs :: RandomGen g => (Char, Char) -> g -> [Char]

randoms :: RandomGen g => g -> [Char]

Random Double

Note - random produces values in the closed range [0,1].

Defined in System.Random

Methods

randomR :: RandomGen g => (Double, Double) -> g -> (Double, g)

random :: RandomGen g => g -> (Double, g)

randomRs :: RandomGen g => (Double, Double) -> g -> [Double]

randoms :: RandomGen g => g -> [Double]

Random Float

Note - random produces values in the closed range [0,1].

Defined in System.Random

Methods

randomR :: RandomGen g => (Float, Float) -> g -> (Float, g)

random :: RandomGen g => g -> (Float, g)

randomRs :: RandomGen g => (Float, Float) -> g -> [Float]

randoms :: RandomGen g => g -> [Float]

Random Int

Defined in System.Random

Methods

randomR :: RandomGen g => (Int, Int) -> g -> (Int, g)

random :: RandomGen g => g -> (Int, g)

randomRs :: RandomGen g => (Int, Int) -> g -> [Int]

randoms :: RandomGen g => g -> [Int]

Random Word

Defined in System.Random

Methods

randomR :: RandomGen g => (Word, Word) -> g -> (Word, g)

random :: RandomGen g => g -> (Word, g)

randomRs :: RandomGen g => (Word, Word) -> g -> [Word]

randoms :: RandomGen g => g -> [Word]

(Random a, Random b) => Random (a, b)

Note - randomR treats a and b types independently

Defined in System.Random

Methods

randomR :: RandomGen g => ((a, b), (a, b)) -> g -> ((a, b), g)

random :: RandomGen g => g -> ((a, b), g)

randomRs :: RandomGen g => ((a, b), (a, b)) -> g -> [(a, b)]

randoms :: RandomGen g => g -> [(a, b)]

(Random a, Random b, Random c) => Random (a, b, c)

Note - randomR treats a, b and c types independently

Defined in System.Random

Methods

randomR :: RandomGen g => ((a, b, c), (a, b, c)) -> g -> ((a, b, c), g)

random :: RandomGen g => g -> ((a, b, c), g)

randomRs :: RandomGen g => ((a, b, c), (a, b, c)) -> g -> [(a, b, c)]

randoms :: RandomGen g => g -> [(a, b, c)]

(Random a, Random b, Random c, Random d) => Random (a, b, c, d)

Note - randomR treats a, b, c and d types independently

Defined in System.Random

Methods

randomR :: RandomGen g => ((a, b, c, d), (a, b, c, d)) -> g -> ((a, b, c, d), g)

random :: RandomGen g => g -> ((a, b, c, d), g)

randomRs :: RandomGen g => ((a, b, c, d), (a, b, c, d)) -> g -> [(a, b, c, d)]

randoms :: RandomGen g => g -> [(a, b, c, d)]

(Random a, Random b, Random c, Random d, Random e) => Random (a, b, c, d, e)

Note - randomR treats a, b, c, d and e types independently

Defined in System.Random

Methods

randomR :: RandomGen g => ((a, b, c, d, e), (a, b, c, d, e)) -> g -> ((a, b, c, d, e), g)

random :: RandomGen g => g -> ((a, b, c, d, e), g)

randomRs :: RandomGen g => ((a, b, c, d, e), (a, b, c, d, e)) -> g -> [(a, b, c, d, e)]

randoms :: RandomGen g => g -> [(a, b, c, d, e)]

(Random a, Random b, Random c, Random d, Random e, Random f) => Random (a, b, c, d, e, f)

Note - randomR treats a, b, c, d, e and f types independently

Defined in System.Random

Methods

randomR :: RandomGen g => ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> g -> ((a, b, c, d, e, f), g)

random :: RandomGen g => g -> ((a, b, c, d, e, f), g)

randomRs :: RandomGen g => ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> g -> [(a, b, c, d, e, f)]

randoms :: RandomGen g => g -> [(a, b, c, d, e, f)]

(Random a, Random b, Random c, Random d, Random e, Random f, Random g) => Random (a, b, c, d, e, f, g)

Note - randomR treats a, b, c, d, e, f and g types independently

Defined in System.Random

Methods

randomR :: RandomGen g0 => ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> g0 -> ((a, b, c, d, e, f, g), g0)

random :: RandomGen g0 => g0 -> ((a, b, c, d, e, f, g), g0)

randomRs :: RandomGen g0 => ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> g0 -> [(a, b, c, d, e, f, g)]

randoms :: RandomGen g0 => g0 -> [(a, b, c, d, e, f, g)]

class Uniform a

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

Since: 1.2.0

Instances

Uniform CBool

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CBool

Uniform CChar

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CChar

Uniform CInt

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CInt

Uniform CIntMax

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CIntMax

Uniform CIntPtr

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CIntPtr

Uniform CLLong

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CLLong

Uniform CLong

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CLong

Uniform CPtrdiff

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CPtrdiff

Uniform CSChar

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CSChar

Uniform CShort

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CShort

Uniform CSigAtomic

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CSigAtomic

Uniform CSize

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CSize

Uniform CUChar

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CUChar

Uniform CUInt

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CUInt

Uniform CUIntMax

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CUIntMax

Uniform CUIntPtr

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CUIntPtr

Uniform CULLong

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CULLong

Uniform CULong

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CULong

Uniform CUShort

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CUShort

Uniform CWchar

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CWchar

Uniform Int16

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Int16

Uniform Int32

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Int32

Uniform Int64

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Int64

Uniform Int8

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Int8

Uniform Word16

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Word16

Uniform Word32

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Word32

Uniform Word64

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Word64

Uniform Word8

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Word8

Uniform ()

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m ()

Uniform Bool

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Bool

Uniform Char

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Char

Uniform Int

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Int

Uniform Word

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Word

SeedGen g => Uniform (Seed g)

Defined in System.Random.Seed

Methods

uniformM :: StatefulGen g0 m => g0 -> m (Seed g)

(Finite a, Uniform a) => Uniform (Maybe a)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (Maybe a)

(Finite a, Uniform a, Finite b, Uniform b) => Uniform (Either a b)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (Either a b)

(Uniform a, Uniform b) => Uniform (a, b)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (a, b)

(Uniform a, Uniform b, Uniform c) => Uniform (a, b, c)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (a, b, c)

(Uniform a, Uniform b, Uniform c, Uniform d) => Uniform (a, b, c, d)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (a, b, c, d)

(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e) => Uniform (a, b, c, d, e)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (a, b, c, d, e)

(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f) => Uniform (a, b, c, d, e, f)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (a, b, c, d, e, f)

(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f, Uniform g) => Uniform (a, b, c, d, e, f, g)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g0 m => g0 -> m (a, b, c, d, e, f, g)

class UniformRange a

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

Since: 1.2.0

Instances

UniformRange CBool

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CBool, CBool) -> g -> m CBool

isInRange :: (CBool, CBool) -> CBool -> Bool

UniformRange CChar

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CChar, CChar) -> g -> m CChar

isInRange :: (CChar, CChar) -> CChar -> Bool

UniformRange CDouble

See Floating point number caveats.

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CDouble, CDouble) -> g -> m CDouble

isInRange :: (CDouble, CDouble) -> CDouble -> Bool

UniformRange CFloat

See Floating point number caveats.

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CFloat, CFloat) -> g -> m CFloat

isInRange :: (CFloat, CFloat) -> CFloat -> Bool

UniformRange CInt

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CInt, CInt) -> g -> m CInt

isInRange :: (CInt, CInt) -> CInt -> Bool

UniformRange CIntMax

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CIntMax, CIntMax) -> g -> m CIntMax

isInRange :: (CIntMax, CIntMax) -> CIntMax -> Bool

UniformRange CIntPtr

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CIntPtr, CIntPtr) -> g -> m CIntPtr

isInRange :: (CIntPtr, CIntPtr) -> CIntPtr -> Bool

UniformRange CLLong

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CLLong, CLLong) -> g -> m CLLong

isInRange :: (CLLong, CLLong) -> CLLong -> Bool

UniformRange CLong

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CLong, CLong) -> g -> m CLong

isInRange :: (CLong, CLong) -> CLong -> Bool

UniformRange CPtrdiff

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CPtrdiff, CPtrdiff) -> g -> m CPtrdiff

isInRange :: (CPtrdiff, CPtrdiff) -> CPtrdiff -> Bool

UniformRange CSChar

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CSChar, CSChar) -> g -> m CSChar

isInRange :: (CSChar, CSChar) -> CSChar -> Bool

UniformRange CShort

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CShort, CShort) -> g -> m CShort

isInRange :: (CShort, CShort) -> CShort -> Bool

UniformRange CSigAtomic

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CSigAtomic, CSigAtomic) -> g -> m CSigAtomic

isInRange :: (CSigAtomic, CSigAtomic) -> CSigAtomic -> Bool

UniformRange CSize

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CSize, CSize) -> g -> m CSize

isInRange :: (CSize, CSize) -> CSize -> Bool

UniformRange CUChar

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CUChar, CUChar) -> g -> m CUChar

isInRange :: (CUChar, CUChar) -> CUChar -> Bool

UniformRange CUInt

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CUInt, CUInt) -> g -> m CUInt

isInRange :: (CUInt, CUInt) -> CUInt -> Bool

UniformRange CUIntMax

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CUIntMax, CUIntMax) -> g -> m CUIntMax

isInRange :: (CUIntMax, CUIntMax) -> CUIntMax -> Bool

UniformRange CUIntPtr

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CUIntPtr, CUIntPtr) -> g -> m CUIntPtr

isInRange :: (CUIntPtr, CUIntPtr) -> CUIntPtr -> Bool

UniformRange CULLong

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CULLong, CULLong) -> g -> m CULLong

isInRange :: (CULLong, CULLong) -> CULLong -> Bool

UniformRange CULong

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CULong, CULong) -> g -> m CULong

isInRange :: (CULong, CULong) -> CULong -> Bool

UniformRange CUShort

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CUShort, CUShort) -> g -> m CUShort

isInRange :: (CUShort, CUShort) -> CUShort -> Bool

UniformRange CWchar

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CWchar, CWchar) -> g -> m CWchar

isInRange :: (CWchar, CWchar) -> CWchar -> Bool

UniformRange Int16

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Int16, Int16) -> g -> m Int16

isInRange :: (Int16, Int16) -> Int16 -> Bool

UniformRange Int32

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Int32, Int32) -> g -> m Int32

isInRange :: (Int32, Int32) -> Int32 -> Bool

UniformRange Int64

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Int64, Int64) -> g -> m Int64

isInRange :: (Int64, Int64) -> Int64 -> Bool

UniformRange Int8

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Int8, Int8) -> g -> m Int8

isInRange :: (Int8, Int8) -> Int8 -> Bool

UniformRange Word16

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Word16, Word16) -> g -> m Word16

isInRange :: (Word16, Word16) -> Word16 -> Bool

UniformRange Word32

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Word32, Word32) -> g -> m Word32

isInRange :: (Word32, Word32) -> Word32 -> Bool

UniformRange Word64

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Word64, Word64) -> g -> m Word64

isInRange :: (Word64, Word64) -> Word64 -> Bool

UniformRange Word8

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Word8, Word8) -> g -> m Word8

isInRange :: (Word8, Word8) -> Word8 -> Bool

UniformRange Integer

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Integer, Integer) -> g -> m Integer

isInRange :: (Integer, Integer) -> Integer -> Bool

UniformRange Natural

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Natural, Natural) -> g -> m Natural

isInRange :: (Natural, Natural) -> Natural -> Bool

UniformRange ()

Defined in System.Random.Internal

Methods

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

isInRange :: ((), ()) -> () -> Bool

UniformRange Bool

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Bool, Bool) -> g -> m Bool

isInRange :: (Bool, Bool) -> Bool -> Bool

UniformRange Char

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Char, Char) -> g -> m Char

isInRange :: (Char, Char) -> Char -> Bool

UniformRange Double

See Floating point number caveats.

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Double, Double) -> g -> m Double

isInRange :: (Double, Double) -> Double -> Bool

UniformRange Float

See Floating point number caveats.

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Float, Float) -> g -> m Float

isInRange :: (Float, Float) -> Float -> Bool

UniformRange Int

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Int, Int) -> g -> m Int

isInRange :: (Int, Int) -> Int -> Bool

UniformRange Word

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Word, Word) -> g -> m Word

isInRange :: (Word, Word) -> Word -> Bool

(UniformRange a, UniformRange b) => UniformRange (a, b)

Defined in System.Random.Internal

Methods

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

isInRange :: ((a, b), (a, b)) -> (a, b) -> Bool

(UniformRange a, UniformRange b, UniformRange c) => UniformRange (a, b, c)

Defined in System.Random.Internal

Methods

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

isInRange :: ((a, b, c), (a, b, c)) -> (a, b, c) -> Bool

(UniformRange a, UniformRange b, UniformRange c, UniformRange d) => UniformRange (a, b, c, d)

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => ((a, b, c, d), (a, b, c, d)) -> g -> m (a, b, c, d)

isInRange :: ((a, b, c, d), (a, b, c, d)) -> (a, b, c, d) -> Bool

(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e) => UniformRange (a, b, c, d, e)

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => ((a, b, c, d, e), (a, b, c, d, e)) -> g -> m (a, b, c, d, e)

isInRange :: ((a, b, c, d, e), (a, b, c, d, e)) -> (a, b, c, d, e) -> Bool

(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e, UniformRange f) => UniformRange (a, b, c, d, e, f)

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> g -> m (a, b, c, d, e, f)

isInRange :: ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> (a, b, c, d, e, f) -> Bool

(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e, UniformRange f, UniformRange g) => UniformRange (a, b, c, d, e, f, g)

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g0 m => ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> g0 -> m (a, b, c, d, e, f, g)

isInRange :: ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> (a, b, c, d, e, f, g) -> Bool

class Finite a

A type class for data with a finite number of inhabitants. This type class is used in the default implementation of Uniform.

Users are not supposed to write instances of Finite manually. There is a default implementation in terms of Generic instead.

>>> :seti -XDeriveGeneric -XDeriveAnyClass
>>> import GHC.Generics (Generic)
>>> data MyBool = MyTrue | MyFalse deriving (Generic, Finite)
>>> data Action = Code MyBool | Eat (Maybe Bool) | Sleep deriving (Generic, Finite)

Instances

Finite Void

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Void -> Cardinality

toFinite :: Integer -> Void

fromFinite :: Void -> Integer

Finite Int16

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Int16 -> Cardinality

toFinite :: Integer -> Int16

fromFinite :: Int16 -> Integer

Finite Int32

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Int32 -> Cardinality

toFinite :: Integer -> Int32

fromFinite :: Int32 -> Integer

Finite Int64

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Int64 -> Cardinality

toFinite :: Integer -> Int64

fromFinite :: Int64 -> Integer

Finite Int8

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Int8 -> Cardinality

toFinite :: Integer -> Int8

fromFinite :: Int8 -> Integer

Finite Word16

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Word16 -> Cardinality

toFinite :: Integer -> Word16

fromFinite :: Word16 -> Integer

Finite Word32

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Word32 -> Cardinality

toFinite :: Integer -> Word32

fromFinite :: Word32 -> Integer

Finite Word64

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Word64 -> Cardinality

toFinite :: Integer -> Word64

fromFinite :: Word64 -> Integer

Finite Word8

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Word8 -> Cardinality

toFinite :: Integer -> Word8

fromFinite :: Word8 -> Integer

Finite Ordering

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Ordering -> Cardinality

toFinite :: Integer -> Ordering

fromFinite :: Ordering -> Integer

Finite ()

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# () -> Cardinality

toFinite :: Integer -> ()

fromFinite :: () -> Integer

Finite Bool

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Bool -> Cardinality

toFinite :: Integer -> Bool

fromFinite :: Bool -> Integer

Finite Char

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Char -> Cardinality

toFinite :: Integer -> Char

fromFinite :: Char -> Integer

Finite Int

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Int -> Cardinality

toFinite :: Integer -> Int

fromFinite :: Int -> Integer

Finite Word

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# Word -> Cardinality

toFinite :: Integer -> Word

fromFinite :: Word -> Integer

Finite a => Finite (Maybe a)

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# (Maybe a) -> Cardinality

toFinite :: Integer -> Maybe a

fromFinite :: Maybe a -> Integer

(Finite a, Finite b) => Finite (Either a b)

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# (Either a b) -> Cardinality

toFinite :: Integer -> Either a b

fromFinite :: Either a b -> Integer

(Finite a, Finite b) => Finite (a, b)

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# (a, b) -> Cardinality

toFinite :: Integer -> (a, b)

fromFinite :: (a, b) -> Integer

(Finite a, Finite b, Finite c) => Finite (a, b, c)

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# (a, b, c) -> Cardinality

toFinite :: Integer -> (a, b, c)

fromFinite :: (a, b, c) -> Integer

(Finite a, Finite b, Finite c, Finite d) => Finite (a, b, c, d)

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# (a, b, c, d) -> Cardinality

toFinite :: Integer -> (a, b, c, d)

fromFinite :: (a, b, c, d) -> Integer

(Finite a, Finite b, Finite c, Finite d, Finite e) => Finite (a, b, c, d, e)

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# (a, b, c, d, e) -> Cardinality

toFinite :: Integer -> (a, b, c, d, e)

fromFinite :: (a, b, c, d, e) -> Integer

(Finite a, Finite b, Finite c, Finite d, Finite e, Finite f) => Finite (a, b, c, d, e, f)

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# (a, b, c, d, e, f) -> Cardinality

toFinite :: Integer -> (a, b, c, d, e, f)

fromFinite :: (a, b, c, d, e, f) -> Integer

(Finite a, Finite b, Finite c, Finite d, Finite e, Finite f, Finite g) => Finite (a, b, c, d, e, f, g)

Defined in System.Random.GFinite

Methods

cardinality :: Proxy# (a, b, c, d, e, f, g) -> Cardinality

toFinite :: Integer -> (a, b, c, d, e, f, g)

fromFinite :: (a, b, c, d, e, f, g) -> Integer

data Seed g

This is a binary form of pseudo-random number generator's state. It is designed to be safe and easy to use for input/output operations like restoring from file, transmitting over the network, etc.

Constructor is not exported, becasue it is important for implementation to enforce the invariant of the underlying byte array being of the exact same length as the generator has specified in SeedSize. Use mkSize and unSize to get access to the raw bytes in a safe manner.

Since: 1.3.0

Instances

Show (Seed g)

Defined in System.Random.Internal

Methods

showsPrec :: Int -> Seed g -> ShowS

show :: Seed g -> String

showList :: [Seed g] -> ShowS

Eq (Seed g)

Defined in System.Random.Internal

Methods

(==) :: Seed g -> Seed g -> Bool

(/=) :: Seed g -> Seed g -> Bool

Ord (Seed g)

Defined in System.Random.Internal

Methods

compare :: Seed g -> Seed g -> Ordering

(<) :: Seed g -> Seed g -> Bool

(<=) :: Seed g -> Seed g -> Bool

(>) :: Seed g -> Seed g -> Bool

(>=) :: Seed g -> Seed g -> Bool

max :: Seed g -> Seed g -> Seed g

min :: Seed g -> Seed g -> Seed g

SeedGen g => Uniform (Seed g)

Defined in System.Random.Seed

Methods

uniformM :: StatefulGen g0 m => g0 -> m (Seed g)

data StdGen

The standard pseudo-random number generator.

Instances

Show StdGen

Defined in System.Random.Internal

Methods

showsPrec :: Int -> StdGen -> ShowS

show :: StdGen -> String

showList :: [StdGen] -> ShowS

NFData StdGen

Defined in System.Random.Internal

Methods

rnf :: StdGen -> ()

Eq StdGen

Defined in System.Random.Internal

Methods

(==) :: StdGen -> StdGen -> Bool

(/=) :: StdGen -> StdGen -> Bool

RandomGen StdGen

Defined in System.Random.Internal

Methods

next :: StdGen -> (Int, StdGen)

genWord8 :: StdGen -> (Word8, StdGen)

genWord16 :: StdGen -> (Word16, StdGen)

genWord32 :: StdGen -> (Word32, StdGen)

genWord64 :: StdGen -> (Word64, StdGen)

genWord32R :: Word32 -> StdGen -> (Word32, StdGen)

genWord64R :: Word64 -> StdGen -> (Word64, StdGen)

genShortByteString :: Int -> StdGen -> (ShortByteString, StdGen)

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> StdGen -> ST s StdGen

genRange :: StdGen -> (Int, Int)

split :: StdGen -> (StdGen, StdGen)

SplitGen StdGen

Defined in System.Random.Internal

Methods

splitGen :: StdGen -> (StdGen, StdGen)

SeedGen StdGen

Defined in System.Random.Seed

Associated Types

type SeedSize StdGen :: Nat

Methods

fromSeed :: Seed StdGen -> StdGen

toSeed :: StdGen -> Seed StdGen

fromSeed64 :: NonEmpty Word64 -> StdGen

toSeed64 :: StdGen -> NonEmpty Word64

type SeedSize StdGen

Defined in System.Random.Seed

type SeedSize StdGen = SeedSize SMGen

class (KnownNat (SeedSize g), 1 <= SeedSize g, Typeable g) => SeedGen g where

Interface for converting a pure pseudo-random number generator to and from non-empty sequence of bytes. Seeds are stored in Little-Endian order regardless of the platform it is being used on, which provides cross-platform compatibility, while providing optimal performance for the most common platform type.

Conversion to and from a Seed serves as a building block for implementing serialization for any pure or frozen pseudo-random number generator.

It is not trivial to implement platform independence. For this reason this type class has two alternative ways of creating an instance for this class. The easiest way for constructing a platform indepent seed is by converting the inner state of a generator to and from a list of 64 bit words using toSeed64 and fromSeed64 respectively. In that case cross-platform support will be handled automaticaly.

>>> :set -XDataKinds -XTypeFamilies
>>> import Data.Word (Word8, Word32)
>>> import Data.Bits ((.|.), shiftR, shiftL)
>>> import Data.List.NonEmpty (NonEmpty ((:|)))
>>> data FiveByteGen = FiveByteGen Word8 Word32 deriving Show
>>> :{
instance SeedGen FiveByteGen where
  type SeedSize FiveByteGen = 5
  fromSeed64 (w64 :| _) =
    FiveByteGen (fromIntegral (w64 `shiftR` 32)) (fromIntegral w64)
  toSeed64 (FiveByteGen x1 x4) =
    let w64 = (fromIntegral x1 `shiftL` 32) .|. fromIntegral x4
     in (w64 :| [])
:}

>>> FiveByteGen 0x80 0x01020304
FiveByteGen 128 16909060
>>> fromSeed (toSeed (FiveByteGen 0x80 0x01020304))
FiveByteGen 128 16909060
>>> toSeed (FiveByteGen 0x80 0x01020304)
Seed [0x04, 0x03, 0x02, 0x01, 0x80]
>>> toSeed64 (FiveByteGen 0x80 0x01020304)
549772722948 :| []

However, when performance is of utmost importance or default handling of cross platform independence is not sufficient, then an adventurous developer can try implementing conversion into bytes directly with toSeed and fromSeed.

Properties that must hold:

> fromSeed (toSeed gen) == gen

> fromSeed64 (toSeed64 gen) == gen

Note, that there is no requirement for every Seed to roundtrip, eg. this proprty does not even hold for StdGen:

>>> let seed = nonEmptyToSeed (0xab :| [0xff00]) :: Seed StdGen
>>> seed == toSeed (fromSeed seed)
False

Since: 1.3.0

Minimal complete definition

fromSeed, toSeed | fromSeed64, toSeed64

Associated Types

type SeedSize g :: Nat

Number of bytes that is required for storing the full state of a pseudo-random number generator. It should be big enough to satisfy the roundtrip property:

> fromSeed (toSeed gen) == gen

Methods

fromSeed :: Seed g -> g

Convert from a binary representation to a pseudo-random number generator

Since: 1.3.0

toSeed :: g -> Seed g

Convert to a binary representation of a pseudo-random number generator

Since: 1.3.0

fromSeed64 :: NonEmpty Word64 -> g

Construct pseudo-random number generator from a list of words. Whenever list does not have enough bytes to satisfy the SeedSize requirement, it will be padded with zeros. On the other hand when it has more than necessary, extra bytes will be dropped.

For example if SeedSize is set to 2, then only the lower 16 bits of the first element in the list will be used.

Since: 1.3.0

toSeed64 :: g -> NonEmpty Word64

Convert pseudo-random number generator to a list of words

In case when SeedSize is not a multiple of 8, then the upper bits of the last word in the list will be set to zero.

Since: 1.3.0

Instances

SeedGen StdGen

Defined in System.Random.Seed

Associated Types

type SeedSize StdGen :: Nat

Methods

fromSeed :: Seed StdGen -> StdGen

toSeed :: StdGen -> Seed StdGen

fromSeed64 :: NonEmpty Word64 -> StdGen

toSeed64 :: StdGen -> NonEmpty Word64

SeedGen SMGen

Defined in System.Random.Seed

Associated Types

type SeedSize SMGen :: Nat

Methods

fromSeed :: Seed SMGen -> SMGen

toSeed :: SMGen -> Seed SMGen

fromSeed64 :: NonEmpty Word64 -> SMGen

toSeed64 :: SMGen -> NonEmpty Word64

SeedGen SMGen

Defined in System.Random.Seed

Associated Types

type SeedSize SMGen :: Nat

Methods

fromSeed :: Seed SMGen -> SMGen

toSeed :: SMGen -> Seed SMGen

fromSeed64 :: NonEmpty Word64 -> SMGen

toSeed64 :: SMGen -> NonEmpty Word64

SeedGen g => SeedGen (StateGen g)

Defined in System.Random.Seed

Associated Types

type SeedSize (StateGen g) :: Nat

Methods

fromSeed :: Seed (StateGen g) -> StateGen g

toSeed :: StateGen g -> Seed (StateGen g)

fromSeed64 :: NonEmpty Word64 -> StateGen g

toSeed64 :: StateGen g -> NonEmpty Word64

SeedGen g => SeedGen (AtomicGen g)

Defined in System.Random.Stateful

Associated Types

type SeedSize (AtomicGen g) :: Nat

Methods

fromSeed :: Seed (AtomicGen g) -> AtomicGen g

toSeed :: AtomicGen g -> Seed (AtomicGen g)

fromSeed64 :: NonEmpty Word64 -> AtomicGen g

toSeed64 :: AtomicGen g -> NonEmpty Word64

SeedGen g => SeedGen (IOGen g)

Defined in System.Random.Stateful

Associated Types

type SeedSize (IOGen g) :: Nat

Methods

fromSeed :: Seed (IOGen g) -> IOGen g

toSeed :: IOGen g -> Seed (IOGen g)

fromSeed64 :: NonEmpty Word64 -> IOGen g

toSeed64 :: IOGen g -> NonEmpty Word64

SeedGen g => SeedGen (STGen g)

Defined in System.Random.Stateful

Associated Types

type SeedSize (STGen g) :: Nat

Methods

fromSeed :: Seed (STGen g) -> STGen g

toSeed :: STGen g -> Seed (STGen g)

fromSeed64 :: NonEmpty Word64 -> STGen g

toSeed64 :: STGen g -> NonEmpty Word64

SeedGen g => SeedGen (TGen g)

Defined in System.Random.Stateful

Associated Types

type SeedSize (TGen g) :: Nat

Methods

fromSeed :: Seed (TGen g) -> TGen g

toSeed :: TGen g -> Seed (TGen g)

fromSeed64 :: NonEmpty Word64 -> TGen g

toSeed64 :: TGen g -> NonEmpty Word64

uniform :: (Uniform a, RandomGen g) => g -> (a, g)

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

This is a pure version of uniformM.

Examples

>>> import System.Random
>>> let pureGen = mkStdGen 137
>>> uniform pureGen :: (Bool, StdGen)
(True,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

You can use type applications to disambiguate the type of the generated numbers:

>>> :seti -XTypeApplications
>>> uniform @Bool pureGen
(True,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

uniformR :: (UniformRange a, RandomGen g) => (a, 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 (1 :: Int, 4 :: Int) generates values uniformly from the set \(\{1,2,3,4\}\)
• uniformR (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:

uniformR (a, b) = uniformR (b, a)

This is a pure version of uniformRM.

Examples

>>> import System.Random
>>> let pureGen = mkStdGen 137
>>> uniformR (1 :: Int, 4 :: Int) pureGen
(4,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

You can use type applications to disambiguate the type of the generated numbers:

>>> :seti -XTypeApplications
>>> uniformR @Int (1, 4) pureGen
(4,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

uniforms :: (Uniform a, RandomGen g) => g -> [a]

Produce an infinite list of pseudo-random values. Integrates nicely with list fusion. Naturally, there is no way to recover the final generator, therefore either use split before calling uniforms or use uniformList instead.

Similar to randoms, except it relies on Uniform type class instead of Random

Examples

>>> let gen = mkStdGen 2023
>>> import Data.Word (Word16)
>>> take 5 $ uniforms gen :: [Word16]
[56342,15850,25292,14347,13919]

Since: 1.3.0

uniformRs :: (UniformRange a, RandomGen g) => (a, a) -> g -> [a]

Produce an infinite list of pseudo-random values in a specified range. Same as uniforms, integrates nicely with list fusion. There is no way to recover the final generator, therefore either use split before calling uniformRs or use uniformListR instead.

Similar to randomRs, except it relies on UniformRange type class instead of Random.

Examples

>>> let gen = mkStdGen 2023
>>> take 5 $ uniformRs (10, 100) gen :: [Int]
[32,86,21,57,39]

Since: 1.3.0

uniformList :: (Uniform a, RandomGen g) => Int -> g -> ([a], g)

Produce a list of the supplied length with elements generated uniformly.

See uniformListM for a stateful counterpart.

Examples

>>> let gen = mkStdGen 2023
>>> import Data.Word (Word16)
>>> uniformList 5 gen :: ([Word16], StdGen)
([56342,15850,25292,14347,13919],StdGen {unStdGen = SMGen 6446154349414395371 1920468677557965761})

Since: 1.3.0

uniformListR :: (UniformRange a, RandomGen g) => Int -> (a, a) -> g -> ([a], g)

Produce a list of the supplied length with elements generated uniformly.

See uniformListM for a stateful counterpart.

Examples

>>> let gen = mkStdGen 2023
>>> uniformListR 10 (20, 30) gen :: ([Int], StdGen)
([26,30,27,24,30,25,27,21,27,27],StdGen {unStdGen = SMGen 12965503083958398648 1920468677557965761})

Since: 1.3.0

uniformShuffleList :: RandomGen g => [a] -> g -> ([a], g)

Shuffle elements of a list in a uniformly random order.

Examples

>>> uniformShuffleList "ELVIS" $ mkStdGen 252
("LIVES",StdGen {unStdGen = SMGen 17676540583805057877 5302934877338729551})

Since: 1.3.0

uniformByteArray

Arguments

:: RandomGen g

=> Bool

Should byte array be allocted in pinned or unpinned memory.

-> Int

Number of bytes to generate

-> g

Pure pseudo-random numer generator

-> (ByteArray, g)

Efficiently generates a sequence of pseudo-random bytes in a platform independent manner.

Since: 1.3.0

uniformByteString :: RandomGen g => Int -> g -> (ByteString, g)

Generates a ByteString of the specified size using a pure pseudo-random number generator. See uniformByteStringM for the monadic version.

Examples

>>> import System.Random
>>> import Data.ByteString (unpack)
>>> let pureGen = mkStdGen 137
>>> unpack . fst $ uniformByteString 10 pureGen
[51,123,251,37,49,167,90,109,1,4]

Since: 1.3.0

uniformFillMutableByteArray

Arguments

:: RandomGen g

=> MutableByteArray s

Mutable array to fill with random bytes

-> Int

Offset into a mutable array from the beginning in number of bytes. Offset will be clamped into the range between 0 and the total size of the mutable array

-> Int

Number of randomly generated bytes to write into the array. This number will be clamped between 0 and the total size of the array without the offset.

-> g

-> ST s g

Fill in a slice of a mutable byte array with randomly generated bytes. This function does not fail, instead it clamps the offset and number of bytes to generate into a valid range.

Since: 1.3.0

genByteString :: RandomGen g => Int -> g -> (ByteString, g)

Deprecated: In favor of uniformByteString

Generates a ByteString of the specified size using a pure pseudo-random number generator. See uniformByteStringM for the monadic version.

Examples

>>> import System.Random
>>> import Data.ByteString
>>> let pureGen = mkStdGen 137
>>> :seti -Wno-deprecations
>>> unpack . fst . genByteString 10 $ pureGen
[51,123,251,37,49,167,90,109,1,4]

Since: 1.2.0

mkStdGen :: Int -> StdGen

Constructs a StdGen deterministically from an Int seed. See mkStdGen64 for a Word64 variant that is architecture agnostic.

mkStdGen64 :: Word64 -> StdGen

Constructs a StdGen deterministically from a Word64 seed.

The difference between mkStdGen is that mkStdGen64 will work the same on 64-bit and 32-bit architectures, while the former can only use 32-bit of information for initializing the psuedo-random number generator on 32-bit operating systems

Since: 1.3.0

initStdGen :: MonadIO m => m StdGen

Initialize StdGen using system entropy (i.e. /dev/urandom) when it is available, while falling back on using system time as the seed.

Since: 1.2.1

getStdRandom :: MonadIO m => (StdGen -> (a, StdGen)) -> m a

Uses the supplied function to get a value from the current global random generator, and updates the global generator with the new generator returned by the function. For example, rollDice produces a pseudo-random integer between 1 and 6:

>>> rollDice = getStdRandom (randomR (1, 6))
>>> replicateM 10 (rollDice :: IO Int)
[1,1,1,4,5,6,1,2,2,5]

This is an outdated function and it is recommended to switch to its equivalent applyAtomicGen instead, possibly with the globalStdGen if relying on the global state is acceptable.

>>> import System.Random.Stateful
>>> rollDice = applyAtomicGen (uniformR (1, 6)) globalStdGen
>>> replicateM 10 (rollDice :: IO Int)
[2,1,1,5,4,3,6,6,3,2]

Since: 1.0.0

getStdGen :: MonadIO m => m StdGen

Gets the global pseudo-random number generator. Extracts the contents of globalStdGen

Since: 1.0.0

setStdGen :: MonadIO m => StdGen -> m ()

Sets the global pseudo-random number generator. Overwrites the contents of globalStdGen

Since: 1.0.0

newStdGen :: MonadIO m => m StdGen

Applies split to the current global pseudo-random generator globalStdGen, updates it with one of the results, and returns the other.

Since: 1.0.0

randomIO :: (Random a, MonadIO m) => m a

A variant of randomM that uses the global pseudo-random number generator globalStdGen.

>>> import Data.Int
>>> randomIO :: IO Int32
114794456

This function is equivalent to getStdRandom random and is included in this interface for historical reasons and backwards compatibility. It is recommended to use uniformM instead, possibly with the globalStdGen if relying on the global state is acceptable.

>>> import System.Random.Stateful
>>> uniformM globalStdGen :: IO Int32
-1768545016

Since: 1.0.0

randomRIO :: (Random a, MonadIO m) => (a, a) -> m a

A variant of randomRM that uses the global pseudo-random number generator globalStdGen

>>> randomRIO (2020, 2100) :: IO Int
2028

Similar to randomIO, this function is equivalent to getStdRandom randomR and is included in this interface for historical reasons and backwards compatibility. It is recommended to use uniformRM instead, possibly with the globalStdGen if relying on the global state is acceptable.

>>> import System.Random.Stateful
>>> uniformRM (2020, 2100) globalStdGen :: IO Int
2044

Since: 1.0.0

seedSize :: forall g. SeedGen g => Int

Get the expected size of the Seed in number bytes

Since: 1.3.0

seedSizeProxy :: forall proxy g. SeedGen g => proxy g -> Int

Just like seedSize, except it accepts a proxy as an argument.

Since: 1.3.0

mkSeed :: forall g m. (SeedGen g, MonadFail m) => ByteArray -> m (Seed g)

Construct a Seed from a ByteArray of expected length. Whenever ByteArray does not match the SeedSize specified by the pseudo-random generator, this function will fail.

Since: 1.3.0

unSeed :: Seed g -> ByteArray

Unwrap the Seed and get the underlying ByteArray

Since: 1.3.0

mkSeedFromByteString :: (SeedGen g, MonadFail m) => ByteString -> m (Seed g)

Just like mkSeed, but uses ByteString as argument. Results in a memcopy of the seed.

Since: 1.3.0

unSeedToByteString :: Seed g -> ByteString

Just like unSeed, but produced a ByteString. Results in a memcopy of the seed.

Since: 1.3.0

withSeed :: SeedGen g => Seed g -> (g -> (a, g)) -> (a, Seed g)

Helper function that allows for operating directly on the Seed, while supplying a function that uses the pseudo-random number generator that is constructed from that Seed.

Example

>>> :set -XTypeApplications
>>> import System.Random
>>> withSeed (nonEmptyToSeed (pure 2024) :: Seed StdGen) (uniform @Int)
(1039666877624726199,Seed [0xe9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])

Since: 1.3.0

withSeedM :: (SeedGen g, Functor f) => Seed g -> (g -> f (a, g)) -> f (a, Seed g)

Same as withSeed, except it is useful with monadic computation and frozen generators.

See withSeedMutableGen for a helper that also handles seeds for mutable pseduo-random number generators.

Since: 1.3.0

withSeedFile :: (SeedGen g, MonadIO m) => FilePath -> (Seed g -> m (a, Seed g)) -> m a

Read the seed from a file and use it for constructing a pseudo-random number generator. After supplied action has been applied to the constructed generator, the resulting generator will be converted back to a seed and written to the same file.

Since: 1.3.0

seedGenTypeName :: forall g. SeedGen g => String

This is a function that shows the name of the generator type, which is useful for error reporting.

Since: 1.3.0

nonEmptyToSeed :: forall g. SeedGen g => NonEmpty Word64 -> Seed g

Construct a seed from a list of 64-bit words. At most SeedSize many bytes will be used.

Since: 1.3.0

nonEmptyFromSeed :: forall g. SeedGen g => Seed g -> NonEmpty Word64

Convert a Seed to a list of 64bit words.

Since: 1.3.0

Monadic Random Generator

This module provides type classes and instances for the following concepts:

Monadic pseudo-random number generators

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

Monadic adapters

StateGenM, AtomicGenM, IOGenM, STGenM and TGenM turn a RandomGen instance into a StatefulGen instance.

Drawing from a range

UniformRange is used to generate a value of a type uniformly within a range.

This library provides instances of UniformRange for many common numeric types.

Drawing from the entire domain of a type

Uniform is used to generate a value of a type uniformly over all possible values of that type.

This library provides instances of Uniform for many common bounded numeric types.

Usage

In monadic code, use the relevant Uniform and UniformRange instances to generate pseudo-random values via uniformM and uniformRM, respectively.

As an example, rollsM generates n pseudo-random values of Word in the range [1, 6] in a StatefulGen context; given a monadic pseudo-random number generator, you can run this probabilistic computation using mwc-random as follows:

>>> import Control.Monad (replicateM)
>>> :{
let rollsM :: StatefulGen g m => Int -> g -> m [Word]
    rollsM n = replicateM n . uniformRM (1, 6)
:}

import qualified System.Random.MWC as MWC
>>> monadicGen <- MWC.create
>>> rollsM 10 monadicGen :: IO [Word]
[3,4,3,1,4,6,1,6,1,4]

Given a pure pseudo-random number generator, you can run the monadic pseudo-random number computation rollsM in StateT, IO, ST or STM context by applying a monadic adapter like StateGenM, AtomicGenM, IOGenM, STGenM or TGenM (see monadic-adapters) to the pure pseudo-random number generator.

>>> let pureGen = mkStdGen 42
>>> newIOGenM pureGen >>= rollsM 10 :: IO [Word]
[1,1,3,2,4,5,3,4,6,2]

Mutable pseudo-random number generator interfaces

Pseudo-random number generators come in two flavours: pure and monadic.

RandomGen: pure pseudo-random number generators

See System.Random module.

StatefulGen: monadic pseudo-random number generators

These generators mutate their own state as they produce pseudo-random values. They generally live in StateT, ST, IO or STM or some other transformer on top of those monads.

class Monad m => StatefulGen g m where

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

Since: 1.2.0

Minimal complete definition

uniformWord32 | uniformWord64

Methods

uniformWord32R :: Word32 -> g -> m Word32

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

Since: 1.2.0

uniformWord64R :: Word64 -> g -> m Word64

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

Since: 1.2.0

uniformWord8 :: g -> m Word8

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

The default implementation extracts a Word8 from uniformWord32.

Since: 1.2.0

uniformWord16 :: g -> m Word16

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

The default implementation extracts a Word16 from uniformWord32.

Since: 1.2.0

uniformWord32 :: g -> m Word32

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

The default implementation extracts a Word32 from uniformWord64.

Since: 1.2.0

uniformWord64 :: g -> m Word64

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

The default implementation combines two Word32 from uniformWord32 into one Word64.

Since: 1.2.0

uniformShortByteString :: Int -> g -> m ShortByteString

Deprecated: In favor of uniformShortByteStringM

uniformShortByteString n g generates a ShortByteString of length n filled with pseudo-random bytes.

Since: 1.2.0

Instances

(RandomGen g, MonadState g m) => StatefulGen (StateGenM g) m

Defined in System.Random.Internal

Methods

uniformWord32R :: Word32 -> StateGenM g -> m Word32

uniformWord64R :: Word64 -> StateGenM g -> m Word64

uniformWord8 :: StateGenM g -> m Word8

uniformWord16 :: StateGenM g -> m Word16

uniformWord32 :: StateGenM g -> m Word32

uniformWord64 :: StateGenM g -> m Word64

uniformByteArrayM :: Bool -> Int -> StateGenM g -> m ByteArray

uniformShortByteString :: Int -> StateGenM g -> m ShortByteString

(RandomGen g, MonadIO m) => StatefulGen (AtomicGenM g) m

Defined in System.Random.Stateful

Methods

uniformWord32R :: Word32 -> AtomicGenM g -> m Word32

uniformWord64R :: Word64 -> AtomicGenM g -> m Word64

uniformWord8 :: AtomicGenM g -> m Word8

uniformWord16 :: AtomicGenM g -> m Word16

uniformWord32 :: AtomicGenM g -> m Word32

uniformWord64 :: AtomicGenM g -> m Word64

uniformByteArrayM :: Bool -> Int -> AtomicGenM g -> m ByteArray

uniformShortByteString :: Int -> AtomicGenM g -> m ShortByteString

(RandomGen g, MonadIO m) => StatefulGen (IOGenM g) m

Defined in System.Random.Stateful

Methods

uniformWord32R :: Word32 -> IOGenM g -> m Word32

uniformWord64R :: Word64 -> IOGenM g -> m Word64

uniformWord8 :: IOGenM g -> m Word8

uniformWord16 :: IOGenM g -> m Word16

uniformWord32 :: IOGenM g -> m Word32

uniformWord64 :: IOGenM g -> m Word64

uniformByteArrayM :: Bool -> Int -> IOGenM g -> m ByteArray

uniformShortByteString :: Int -> IOGenM g -> m ShortByteString

RandomGen g => StatefulGen (TGenM g) STM

Since: 1.2.1

Defined in System.Random.Stateful

Methods

uniformWord32R :: Word32 -> TGenM g -> STM Word32

uniformWord64R :: Word64 -> TGenM g -> STM Word64

uniformWord8 :: TGenM g -> STM Word8

uniformWord16 :: TGenM g -> STM Word16

uniformWord32 :: TGenM g -> STM Word32

uniformWord64 :: TGenM g -> STM Word64

uniformByteArrayM :: Bool -> Int -> TGenM g -> STM ByteArray

uniformShortByteString :: Int -> TGenM g -> STM ShortByteString

RandomGen g => StatefulGen (STGenM g s) (ST s)

Defined in System.Random.Stateful

Methods

uniformWord32R :: Word32 -> STGenM g s -> ST s Word32

uniformWord64R :: Word64 -> STGenM g s -> ST s Word64

uniformWord8 :: STGenM g s -> ST s Word8

uniformWord16 :: STGenM g s -> ST s Word16

uniformWord32 :: STGenM g s -> ST s Word32

uniformWord64 :: STGenM g s -> ST s Word64

uniformByteArrayM :: Bool -> Int -> STGenM g s -> ST s ByteArray

uniformShortByteString :: Int -> STGenM g s -> ST s ShortByteString

class StatefulGen (MutableGen f m) m => FrozenGen f m where

This class is designed for mutable pseudo-random number generators that have a frozen imutable counterpart that can be manipulated in pure code.

It also works great with frozen generators that are based on pure generators that have a RandomGen instance.

Here are a few laws, which are important for this type class:

• Roundtrip and complete destruction on overwrite:

overwriteGen mg fg >> freezeGen mg = pure fg

• Modification of a mutable generator:

overwriteGen mg fg = modifyGen mg (const ((), fg)

• Freezing of a mutable generator:

freezeGen mg = modifyGen mg (fg -> (fg, fg))

Since: 1.2.0

Minimal complete definition

(modifyGen | freezeGen, overwriteGen)

Associated Types

type MutableGen f m = (g :: Type) | g -> f

Represents the state of the pseudo-random number generator for use with thawGen and freezeGen.

Since: 1.2.0

Methods

freezeGen :: MutableGen f m -> m f

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

Since: 1.2.0

modifyGen :: MutableGen f m -> (f -> (a, f)) -> m a

Apply a pure function to the frozen pseudo-random number generator.

Since: 1.3.0

overwriteGen :: MutableGen f m -> f -> m ()

Overwrite contents of the mutable pseudo-random number generator with the supplied frozen one

Since: 1.3.0

Instances

(RandomGen g, MonadState g m) => FrozenGen (StateGen g) m

Defined in System.Random.Internal

Associated Types

type MutableGen (StateGen g) m = (g :: Type)

Methods

freezeGen :: MutableGen (StateGen g) m -> m (StateGen g)

modifyGen :: MutableGen (StateGen g) m -> (StateGen g -> (a, StateGen g)) -> m a

overwriteGen :: MutableGen (StateGen g) m -> StateGen g -> m ()

(RandomGen g, MonadIO m) => FrozenGen (AtomicGen g) m

Defined in System.Random.Stateful

Associated Types

type MutableGen (AtomicGen g) m = (g :: Type)

Methods

freezeGen :: MutableGen (AtomicGen g) m -> m (AtomicGen g)

modifyGen :: MutableGen (AtomicGen g) m -> (AtomicGen g -> (a, AtomicGen g)) -> m a

overwriteGen :: MutableGen (AtomicGen g) m -> AtomicGen g -> m ()

(RandomGen g, MonadIO m) => FrozenGen (IOGen g) m

Defined in System.Random.Stateful

Associated Types

type MutableGen (IOGen g) m = (g :: Type)

Methods

freezeGen :: MutableGen (IOGen g) m -> m (IOGen g)

modifyGen :: MutableGen (IOGen g) m -> (IOGen g -> (a, IOGen g)) -> m a

overwriteGen :: MutableGen (IOGen g) m -> IOGen g -> m ()

RandomGen g => FrozenGen (TGen g) STM

Since: 1.2.1

Defined in System.Random.Stateful

Associated Types

type MutableGen (TGen g) STM = (g :: Type)

Methods

freezeGen :: MutableGen (TGen g) STM -> STM (TGen g)

modifyGen :: MutableGen (TGen g) STM -> (TGen g -> (a, TGen g)) -> STM a

overwriteGen :: MutableGen (TGen g) STM -> TGen g -> STM ()

RandomGen g => FrozenGen (STGen g) (ST s)

Defined in System.Random.Stateful

Associated Types

type MutableGen (STGen g) (ST s) = (g :: Type)

Methods

freezeGen :: MutableGen (STGen g) (ST s) -> ST s (STGen g)

modifyGen :: MutableGen (STGen g) (ST s) -> (STGen g -> (a, STGen g)) -> ST s a

overwriteGen :: MutableGen (STGen g) (ST s) -> STGen g -> ST s ()

class FrozenGen f m => ThawedGen f m where

Functionality for thawing frozen generators is not part of the FrozenGen class, becase not all mutable generators support functionality of creating new mutable generators, which is what thawing is in its essence. For this reason StateGen does not have an instance for this type class, but it has one for FrozenGen.

Here is an important law that relates this type class to FrozenGen

• Roundtrip and independence of mutable generators:

traverse thawGen fgs >>= traverse freezeGen = pure fgs

Since: 1.3.0

Methods

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

Create a new mutable pseudo-random number generator from its frozen state.

Since: 1.2.0

Instances

(RandomGen g, MonadIO m) => ThawedGen (AtomicGen g) m

Defined in System.Random.Stateful

Methods

thawGen :: AtomicGen g -> m (MutableGen (AtomicGen g) m)

(RandomGen g, MonadIO m) => ThawedGen (IOGen g) m

Defined in System.Random.Stateful

Methods

thawGen :: IOGen g -> m (MutableGen (IOGen g) m)

RandomGen g => ThawedGen (TGen g) STM

Defined in System.Random.Stateful

Methods

thawGen :: TGen g -> STM (MutableGen (TGen g) STM)

RandomGen g => ThawedGen (STGen g) (ST s)

Defined in System.Random.Stateful

Methods

thawGen :: STGen g -> ST s (MutableGen (STGen g) (ST s))

withMutableGen :: ThawedGen f m => f -> (MutableGen f m -> m a) -> m (a, f)

Runs a mutable pseudo-random number generator from its FrozenGen state.

Examples

>>> 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}})

Since: 1.2.0

withMutableGen_ :: ThawedGen f m => f -> (MutableGen f m -> m a) -> m a

Same as withMutableGen, but only returns the generated value.

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> withMutableGen_ (IOGen pureGen) (uniformRM (1 :: Int, 6 :: Int))
4

Since: 1.2.0

withSeedMutableGen :: (SeedGen g, ThawedGen g m) => Seed g -> (MutableGen g m -> m a) -> m (a, Seed g)

Just like withMutableGen, except uses a Seed instead of a frozen generator.

Examples

Here is good example of how withSeedMutableGen can be used with withSeedFile, which uses a locally stored seed.

First we define a reportSeed function that will print the contents of a seed file as a list of bytes:

>>> import Data.ByteString as BS (readFile, writeFile, unpack)
>>> :seti -XOverloadedStrings
>>> let reportSeed fp = print . ("Seed: " <>) . show . BS.unpack =<< BS.readFile fp

Given a file path, write an StdGen seed into the file:

>>> :seti -XFlexibleContexts -XScopedTypeVariables
>>> let writeInitSeed fp = BS.writeFile fp (unSeedToByteString (toSeed (mkStdGen 2025)))

Apply a StatefulGen monadic action that uses IOGen StdGen, restored from the seed in the given path:

>>> let withMutableSeedFile fp action = withSeedFile fp (\(seed :: Seed (IOGen StdGen)) -> withSeedMutableGen seed action)

Given a path and an action initialize the seed file and apply the action using that seed:

>>> let withInitSeedFile fp action = writeInitSeed fp *> reportSeed fp *> withMutableSeedFile fp action <* reportSeed fp

For the sake of example we will use a temporary directory for storing the seed. Here we report the contents of the seed file before and after we shuffle a list:

>>> import UnliftIO.Temporary (withSystemTempDirectory)
>>> withSystemTempDirectory "random" (\fp -> withInitSeedFile (fp ++ "/seed.bin") (uniformShuffleListM [1..10]))
"Seed: [183,178,143,77,132,163,109,14,157,105,82,99,148,82,109,173]"
"Seed: [60,105,117,203,187,138,69,39,157,105,82,99,148,82,109,173]"
[7,5,4,3,1,8,10,6,9,2]

Since: 1.3.0

withSeedMutableGen_ :: (SeedGen g, ThawedGen g m) => Seed g -> (MutableGen g m -> m a) -> m a

Just like withSeedMutableGen, except it doesn't return the final generator, only the resulting value. This is slightly more efficient, since it doesn't incur overhead from freezeing the mutable generator

Since: 1.3.0

randomM :: forall a g m. (Random a, RandomGen g, FrozenGen g m) => MutableGen g m -> m a

Generates a pseudo-random value using monadic interface and Random instance.

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 139
>>> g <- newIOGenM pureGen
>>> randomM g :: IO Double
0.33775117339631733

You can use type applications to disambiguate the type of the generated numbers:

>>> :seti -XTypeApplications
>>> randomM @Double g
0.9156875994165681

Since: 1.2.0

randomRM :: forall a g m. (Random a, RandomGen g, FrozenGen g m) => (a, a) -> MutableGen g m -> m a

Generates a pseudo-random value using monadic interface and Random instance.

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> g <- newIOGenM pureGen
>>> randomRM (1, 100) g :: IO Int
52

You can use type applications to disambiguate the type of the generated numbers:

>>> :seti -XTypeApplications
>>> randomRM @Int (1, 100) g
2

Since: 1.2.0

splitGenM :: (SplitGen f, FrozenGen f m) => MutableGen f m -> m f

Splits a pseudo-random number generator into two. Overwrites the mutable pseudo-random number generator with one of the immutable pseudo-random number generators produced by a split function and returns the other.

Since: 1.3.0

splitMutableGenM :: (SplitGen f, ThawedGen f m) => MutableGen f m -> m (MutableGen f m)

Splits a pseudo-random number generator into two. Overwrites the mutable wrapper with one of the resulting generators and returns the other as a new mutable generator.

Since: 1.3.0

Deprecated

class (RandomGen r, StatefulGen g m) => RandomGenM g r m | g -> r where

Deprecated: In favor of FrozenGen

Interface to operations on RandomGen wrappers like IOGenM and StateGenM.

Since: 1.2.0

Methods

applyRandomGenM :: (r -> (a, r)) -> g -> m a

Deprecated: In favor of modifyGen

Instances

(RandomGen r, MonadState r m) => RandomGenM (StateGenM r) r m

Defined in System.Random.Stateful

Methods

applyRandomGenM :: (r -> (a, r)) -> StateGenM r -> m a

(RandomGen r, MonadIO m) => RandomGenM (AtomicGenM r) r m

Defined in System.Random.Stateful

Methods

applyRandomGenM :: (r -> (a, r)) -> AtomicGenM r -> m a

(RandomGen r, MonadIO m) => RandomGenM (IOGenM r) r m

Defined in System.Random.Stateful

Methods

applyRandomGenM :: (r -> (a, r)) -> IOGenM r -> m a

RandomGen r => RandomGenM (TGenM r) r STM

Defined in System.Random.Stateful

Methods

applyRandomGenM :: (r -> (a, r)) -> TGenM r -> STM a

RandomGen r => RandomGenM (STGenM r s) r (ST s)

Defined in System.Random.Stateful

Methods

applyRandomGenM :: (r -> (a, r)) -> STGenM r s -> ST s a

Monadic adapters for pure pseudo-random number generators

Pure pseudo-random number generators can be used in monadic code via the adapters StateGenM, AtomicGenM, IOGenM, STGenM and TGenM

• StateGenM can be used in any state monad. With strict StateT there is no performance overhead compared to using the RandomGen instance directly. StateGenM is not safe to use in the presence of exceptions and concurrency.
• AtomicGenM is safe in the presence of exceptions and concurrency since it performs all actions atomically.
• IOGenM is a wrapper around an IORef that holds a pure generator. IOGenM is safe in the presence of exceptions, but not concurrency.
• STGenM is a wrapper around an STRef that holds a pure generator. STGenM is safe in the presence of exceptions, but not concurrency.
• TGenM is a wrapper around a TVar that holds a pure generator. TGenM can be used in a software transactional memory monad STM. It is not as performant as AtomicGenM, but it can provide stronger guarantees in a concurrent setting.

Pure adapter in MonadState

newtype StateGen g

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

Since: 1.2.0

Constructors

StateGen

Fields

• unStateGen :: g

Instances

Storable g => Storable (StateGen g)

Defined in System.Random.Internal

Methods

sizeOf :: StateGen g -> Int

alignment :: StateGen g -> Int

peekElemOff :: Ptr (StateGen g) -> Int -> IO (StateGen g)

pokeElemOff :: Ptr (StateGen g) -> Int -> StateGen g -> IO ()

peekByteOff :: Ptr b -> Int -> IO (StateGen g)

pokeByteOff :: Ptr b -> Int -> StateGen g -> IO ()

peek :: Ptr (StateGen g) -> IO (StateGen g)

poke :: Ptr (StateGen g) -> StateGen g -> IO ()

Show g => Show (StateGen g)

Defined in System.Random.Internal

Methods

showsPrec :: Int -> StateGen g -> ShowS

show :: StateGen g -> String

showList :: [StateGen g] -> ShowS

NFData g => NFData (StateGen g)

Defined in System.Random.Internal

Methods

rnf :: StateGen g -> ()

Eq g => Eq (StateGen g)

Defined in System.Random.Internal

Methods

(==) :: StateGen g -> StateGen g -> Bool

(/=) :: StateGen g -> StateGen g -> Bool

Ord g => Ord (StateGen g)

Defined in System.Random.Internal

Methods

compare :: StateGen g -> StateGen g -> Ordering

(<) :: StateGen g -> StateGen g -> Bool

(<=) :: StateGen g -> StateGen g -> Bool

(>) :: StateGen g -> StateGen g -> Bool

(>=) :: StateGen g -> StateGen g -> Bool

max :: StateGen g -> StateGen g -> StateGen g

min :: StateGen g -> StateGen g -> StateGen g

RandomGen g => RandomGen (StateGen g)

Defined in System.Random.Internal

Methods

next :: StateGen g -> (Int, StateGen g)

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

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

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

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

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

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

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

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> StateGen g -> ST s (StateGen g)

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

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

SeedGen g => SeedGen (StateGen g)

Defined in System.Random.Seed

Associated Types

type SeedSize (StateGen g) :: Nat

Methods

fromSeed :: Seed (StateGen g) -> StateGen g

toSeed :: StateGen g -> Seed (StateGen g)

fromSeed64 :: NonEmpty Word64 -> StateGen g

toSeed64 :: StateGen g -> NonEmpty Word64

(RandomGen g, MonadState g m) => FrozenGen (StateGen g) m

Defined in System.Random.Internal

Associated Types

type MutableGen (StateGen g) m = (g :: Type)

Methods

freezeGen :: MutableGen (StateGen g) m -> m (StateGen g)

modifyGen :: MutableGen (StateGen g) m -> (StateGen g -> (a, StateGen g)) -> m a

overwriteGen :: MutableGen (StateGen g) m -> StateGen g -> m ()

type SeedSize (StateGen g)

Defined in System.Random.Seed

type SeedSize (StateGen g) = SeedSize g

type MutableGen (StateGen g) m

Defined in System.Random.Internal

type MutableGen (StateGen g) m = StateGenM g

data StateGenM g

Opaque data type that carries the type of a pure pseudo-random number generator.

Since: 1.2.0

Constructors

StateGenM

Instances

(RandomGen g, MonadState g m) => StatefulGen (StateGenM g) m

Defined in System.Random.Internal

Methods

uniformWord32R :: Word32 -> StateGenM g -> m Word32

uniformWord64R :: Word64 -> StateGenM g -> m Word64

uniformWord8 :: StateGenM g -> m Word8

uniformWord16 :: StateGenM g -> m Word16

uniformWord32 :: StateGenM g -> m Word32

uniformWord64 :: StateGenM g -> m Word64

uniformByteArrayM :: Bool -> Int -> StateGenM g -> m ByteArray

uniformShortByteString :: Int -> StateGenM g -> m ShortByteString

(RandomGen r, MonadState r m) => RandomGenM (StateGenM r) r m

Defined in System.Random.Stateful

Methods

applyRandomGenM :: (r -> (a, r)) -> StateGenM r -> m a

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.

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> runStateGen pureGen randomM :: (Int, StdGen)
(7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

runStateGen_ :: 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

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> runStateGen_ pureGen randomM :: Int
7879794327570578227

Since: 1.2.0

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.

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> runStateGenT pureGen randomM :: IO (Int, StdGen)
(7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

runStateGenT_ :: (RandomGen g, Functor f) => g -> (StateGenM g -> StateT g f a) -> 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

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> runStateGenT_ pureGen randomM :: IO Int
7879794327570578227

Since: 1.2.1

runStateGenST :: RandomGen g => g -> (forall s. StateGenM g -> StateT g (ST s) a) -> (a, g)

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

Since: 1.2.0

runStateGenST_ :: RandomGen g => g -> (forall s. StateGenM g -> StateT g (ST s) a) -> a

Runs a monadic generating action in the ST monad using a pure pseudo-random number generator. Same as runStateGenST, but discards the resulting generator.

Since: 1.2.1

Mutable thread-safe adapter in IO

newtype AtomicGen g

Frozen version of mutable AtomicGenM generator

Since: 1.2.0

Constructors

AtomicGen

Fields

• unAtomicGen :: g

Instances

Storable g => Storable (AtomicGen g)

Defined in System.Random.Stateful

Methods

sizeOf :: AtomicGen g -> Int

alignment :: AtomicGen g -> Int

peekElemOff :: Ptr (AtomicGen g) -> Int -> IO (AtomicGen g)

pokeElemOff :: Ptr (AtomicGen g) -> Int -> AtomicGen g -> IO ()

peekByteOff :: Ptr b -> Int -> IO (AtomicGen g)

pokeByteOff :: Ptr b -> Int -> AtomicGen g -> IO ()

peek :: Ptr (AtomicGen g) -> IO (AtomicGen g)

poke :: Ptr (AtomicGen g) -> AtomicGen g -> IO ()

Show g => Show (AtomicGen g)

Defined in System.Random.Stateful

Methods

showsPrec :: Int -> AtomicGen g -> ShowS

show :: AtomicGen g -> String

showList :: [AtomicGen g] -> ShowS

NFData g => NFData (AtomicGen g)

Defined in System.Random.Stateful

Methods

rnf :: AtomicGen g -> ()

Eq g => Eq (AtomicGen g)

Defined in System.Random.Stateful

Methods

(==) :: AtomicGen g -> AtomicGen g -> Bool

(/=) :: AtomicGen g -> AtomicGen g -> Bool

Ord g => Ord (AtomicGen g)

Defined in System.Random.Stateful

Methods

compare :: AtomicGen g -> AtomicGen g -> Ordering

(<) :: AtomicGen g -> AtomicGen g -> Bool

(<=) :: AtomicGen g -> AtomicGen g -> Bool

(>) :: AtomicGen g -> AtomicGen g -> Bool

(>=) :: AtomicGen g -> AtomicGen g -> Bool

max :: AtomicGen g -> AtomicGen g -> AtomicGen g

min :: AtomicGen g -> AtomicGen g -> AtomicGen g

RandomGen g => RandomGen (AtomicGen g)

Defined in System.Random.Stateful

Methods

next :: AtomicGen g -> (Int, AtomicGen g)

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

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

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

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

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

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

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

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> AtomicGen g -> ST s (AtomicGen g)

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

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

SplitGen g => SplitGen (AtomicGen g)

Defined in System.Random.Stateful

Methods

splitGen :: AtomicGen g -> (AtomicGen g, AtomicGen g)

SeedGen g => SeedGen (AtomicGen g)

Defined in System.Random.Stateful

Associated Types

type SeedSize (AtomicGen g) :: Nat

Methods

fromSeed :: Seed (AtomicGen g) -> AtomicGen g

toSeed :: AtomicGen g -> Seed (AtomicGen g)

fromSeed64 :: NonEmpty Word64 -> AtomicGen g

toSeed64 :: AtomicGen g -> NonEmpty Word64

(RandomGen g, MonadIO m) => FrozenGen (AtomicGen g) m

Defined in System.Random.Stateful

Associated Types

type MutableGen (AtomicGen g) m = (g :: Type)

Methods

freezeGen :: MutableGen (AtomicGen g) m -> m (AtomicGen g)

modifyGen :: MutableGen (AtomicGen g) m -> (AtomicGen g -> (a, AtomicGen g)) -> m a

overwriteGen :: MutableGen (AtomicGen g) m -> AtomicGen g -> m ()

(RandomGen g, MonadIO m) => ThawedGen (AtomicGen g) m

Defined in System.Random.Stateful

Methods

thawGen :: AtomicGen g -> m (MutableGen (AtomicGen g) m)

type SeedSize (AtomicGen g)

Defined in System.Random.Stateful

type SeedSize (AtomicGen g) = SeedSize g

type MutableGen (AtomicGen g) m

Defined in System.Random.Stateful

type MutableGen (AtomicGen g) m = AtomicGenM g

newtype AtomicGenM g

Wraps an IORef that holds a pure pseudo-random number generator. All operations are performed atomically.

• AtomicGenM is safe in the presence of exceptions and concurrency.
• AtomicGenM is the slowest of the monadic adapters due to the overhead of its atomic operations.

Since: 1.2.0

Constructors

AtomicGenM

Fields

• unAtomicGenM :: IORef g

Instances

(RandomGen g, MonadIO m) => StatefulGen (AtomicGenM g) m

Defined in System.Random.Stateful

Methods

uniformWord32R :: Word32 -> AtomicGenM g -> m Word32

uniformWord64R :: Word64 -> AtomicGenM g -> m Word64

uniformWord8 :: AtomicGenM g -> m Word8

uniformWord16 :: AtomicGenM g -> m Word16

uniformWord32 :: AtomicGenM g -> m Word32

uniformWord64 :: AtomicGenM g -> m Word64

uniformByteArrayM :: Bool -> Int -> AtomicGenM g -> m ByteArray

uniformShortByteString :: Int -> AtomicGenM g -> m ShortByteString

(RandomGen r, MonadIO m) => RandomGenM (AtomicGenM r) r m

Defined in System.Random.Stateful

Methods

applyRandomGenM :: (r -> (a, r)) -> AtomicGenM r -> m a

newAtomicGenM :: MonadIO m => g -> m (AtomicGenM g)

Creates a new AtomicGenM.

Since: 1.2.0

applyAtomicGen :: MonadIO m => (g -> (a, g)) -> AtomicGenM g -> m a

Atomically applies a pure operation to the wrapped pseudo-random number generator.

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> g <- newAtomicGenM pureGen
>>> applyAtomicGen random g :: IO Int
7879794327570578227

Since: 1.2.0

globalStdGen :: AtomicGenM StdGen

Global mutable standard pseudo-random number generator. This is the same generator that was historically used by randomIO and randomRIO functions.

>>> import Control.Monad (replicateM)
>>> replicateM 10 (uniformRM ('a', 'z') globalStdGen)
"tdzxhyfvgr"

Since: 1.2.1

Mutable adapter in IO

newtype IOGen g

Frozen version of mutable IOGenM generator

Since: 1.2.0

Constructors

IOGen

Fields

• unIOGen :: g

Instances

Storable g => Storable (IOGen g)

Defined in System.Random.Stateful

Methods

sizeOf :: IOGen g -> Int

alignment :: IOGen g -> Int

peekElemOff :: Ptr (IOGen g) -> Int -> IO (IOGen g)

pokeElemOff :: Ptr (IOGen g) -> Int -> IOGen g -> IO ()

peekByteOff :: Ptr b -> Int -> IO (IOGen g)

pokeByteOff :: Ptr b -> Int -> IOGen g -> IO ()

peek :: Ptr (IOGen g) -> IO (IOGen g)

poke :: Ptr (IOGen g) -> IOGen g -> IO ()

Show g => Show (IOGen g)

Defined in System.Random.Stateful

Methods

showsPrec :: Int -> IOGen g -> ShowS

show :: IOGen g -> String

showList :: [IOGen g] -> ShowS

NFData g => NFData (IOGen g)

Defined in System.Random.Stateful

Methods

rnf :: IOGen g -> ()

Eq g => Eq (IOGen g)

Defined in System.Random.Stateful

Methods

(==) :: IOGen g -> IOGen g -> Bool

(/=) :: IOGen g -> IOGen g -> Bool

Ord g => Ord (IOGen g)

Defined in System.Random.Stateful

Methods

compare :: IOGen g -> IOGen g -> Ordering

(<) :: IOGen g -> IOGen g -> Bool

(<=) :: IOGen g -> IOGen g -> Bool

(>) :: IOGen g -> IOGen g -> Bool

(>=) :: IOGen g -> IOGen g -> Bool

max :: IOGen g -> IOGen g -> IOGen g

min :: IOGen g -> IOGen g -> IOGen g

RandomGen g => RandomGen (IOGen g)

Defined in System.Random.Stateful

Methods

next :: IOGen g -> (Int, IOGen g)

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

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

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

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

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

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

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

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> IOGen g -> ST s (IOGen g)

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

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

SplitGen g => SplitGen (IOGen g)

Defined in System.Random.Stateful

Methods

splitGen :: IOGen g -> (IOGen g, IOGen g)

SeedGen g => SeedGen (IOGen g)

Defined in System.Random.Stateful

Associated Types

type SeedSize (IOGen g) :: Nat

Methods

fromSeed :: Seed (IOGen g) -> IOGen g

toSeed :: IOGen g -> Seed (IOGen g)

fromSeed64 :: NonEmpty Word64 -> IOGen g

toSeed64 :: IOGen g -> NonEmpty Word64

(RandomGen g, MonadIO m) => FrozenGen (IOGen g) m

Defined in System.Random.Stateful

Associated Types

type MutableGen (IOGen g) m = (g :: Type)

Methods

freezeGen :: MutableGen (IOGen g) m -> m (IOGen g)

modifyGen :: MutableGen (IOGen g) m -> (IOGen g -> (a, IOGen g)) -> m a

overwriteGen :: MutableGen (IOGen g) m -> IOGen g -> m ()

(RandomGen g, MonadIO m) => ThawedGen (IOGen g) m

Defined in System.Random.Stateful

Methods

thawGen :: IOGen g -> m (MutableGen (IOGen g) m)

type SeedSize (IOGen g)

Defined in System.Random.Stateful

type SeedSize (IOGen g) = SeedSize g

type MutableGen (IOGen g) m

Defined in System.Random.Stateful

type MutableGen (IOGen g) m = IOGenM g

newtype IOGenM g

Wraps an IORef that holds a pure pseudo-random number generator.

• IOGenM is safe in the presence of exceptions, but not concurrency.
• IOGenM is slower than StateGenM due to the extra pointer indirection.
• IOGenM is faster than AtomicGenM since the IORef operations used by IOGenM are not atomic.

An example use case is writing pseudo-random bytes into a file:

>>> 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

Since: 1.2.0

Constructors

IOGenM

Fields

• unIOGenM :: IORef g

Instances

(RandomGen g, MonadIO m) => StatefulGen (IOGenM g) m

Defined in System.Random.Stateful

Methods

uniformWord32R :: Word32 -> IOGenM g -> m Word32

uniformWord64R :: Word64 -> IOGenM g -> m Word64

uniformWord8 :: IOGenM g -> m Word8

uniformWord16 :: IOGenM g -> m Word16

uniformWord32 :: IOGenM g -> m Word32

uniformWord64 :: IOGenM g -> m Word64

uniformByteArrayM :: Bool -> Int -> IOGenM g -> m ByteArray

uniformShortByteString :: Int -> IOGenM g -> m ShortByteString

(RandomGen r, MonadIO m) => RandomGenM (IOGenM r) r m

Defined in System.Random.Stateful

Methods

applyRandomGenM :: (r -> (a, r)) -> IOGenM r -> m a

newIOGenM :: MonadIO m => g -> m (IOGenM g)

Creates a new IOGenM.

Since: 1.2.0

applyIOGen :: MonadIO m => (g -> (a, g)) -> IOGenM g -> m a

Applies a pure operation to the wrapped pseudo-random number generator.

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> g <- newIOGenM pureGen
>>> applyIOGen random g :: IO Int
7879794327570578227

Since: 1.2.0

Mutable adapter in ST

newtype STGen g

Frozen version of mutable STGenM generator

Since: 1.2.0

Constructors

STGen

Fields

• unSTGen :: g

Instances

Storable g => Storable (STGen g)

Defined in System.Random.Stateful

Methods

sizeOf :: STGen g -> Int

alignment :: STGen g -> Int

peekElemOff :: Ptr (STGen g) -> Int -> IO (STGen g)

pokeElemOff :: Ptr (STGen g) -> Int -> STGen g -> IO ()

peekByteOff :: Ptr b -> Int -> IO (STGen g)

pokeByteOff :: Ptr b -> Int -> STGen g -> IO ()

peek :: Ptr (STGen g) -> IO (STGen g)

poke :: Ptr (STGen g) -> STGen g -> IO ()

Show g => Show (STGen g)

Defined in System.Random.Stateful

Methods

showsPrec :: Int -> STGen g -> ShowS

show :: STGen g -> String

showList :: [STGen g] -> ShowS

NFData g => NFData (STGen g)

Defined in System.Random.Stateful

Methods

rnf :: STGen g -> ()

Eq g => Eq (STGen g)

Defined in System.Random.Stateful

Methods

(==) :: STGen g -> STGen g -> Bool

(/=) :: STGen g -> STGen g -> Bool

Ord g => Ord (STGen g)

Defined in System.Random.Stateful

Methods

compare :: STGen g -> STGen g -> Ordering

(<) :: STGen g -> STGen g -> Bool

(<=) :: STGen g -> STGen g -> Bool

(>) :: STGen g -> STGen g -> Bool

(>=) :: STGen g -> STGen g -> Bool

max :: STGen g -> STGen g -> STGen g

min :: STGen g -> STGen g -> STGen g

RandomGen g => RandomGen (STGen g)

Defined in System.Random.Stateful

Methods

next :: STGen g -> (Int, STGen g)

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

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

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

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

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

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

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

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> STGen g -> ST s (STGen g)

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

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

SplitGen g => SplitGen (STGen g)

Defined in System.Random.Stateful

Methods

splitGen :: STGen g -> (STGen g, STGen g)

SeedGen g => SeedGen (STGen g)

Defined in System.Random.Stateful

Associated Types

type SeedSize (STGen g) :: Nat

Methods

fromSeed :: Seed (STGen g) -> STGen g

toSeed :: STGen g -> Seed (STGen g)

fromSeed64 :: NonEmpty Word64 -> STGen g

toSeed64 :: STGen g -> NonEmpty Word64

RandomGen g => FrozenGen (STGen g) (ST s)

Defined in System.Random.Stateful

Associated Types

type MutableGen (STGen g) (ST s) = (g :: Type)

Methods

freezeGen :: MutableGen (STGen g) (ST s) -> ST s (STGen g)

modifyGen :: MutableGen (STGen g) (ST s) -> (STGen g -> (a, STGen g)) -> ST s a

overwriteGen :: MutableGen (STGen g) (ST s) -> STGen g -> ST s ()

RandomGen g => ThawedGen (STGen g) (ST s)

Defined in System.Random.Stateful

Methods

thawGen :: STGen g -> ST s (MutableGen (STGen g) (ST s))

type SeedSize (STGen g)

Defined in System.Random.Stateful

type SeedSize (STGen g) = SeedSize g

type MutableGen (STGen g) (ST s)

Defined in System.Random.Stateful

type MutableGen (STGen g) (ST s) = STGenM g s

newtype STGenM g s

Wraps an STRef that holds a pure pseudo-random number generator.

• STGenM is safe in the presence of exceptions, but not concurrency.
• STGenM is slower than StateGenM due to the extra pointer indirection.

Since: 1.2.0

Constructors

STGenM

Fields

• unSTGenM :: STRef s g

Instances

RandomGen r => RandomGenM (STGenM r s) r (ST s)

Defined in System.Random.Stateful

Methods

applyRandomGenM :: (r -> (a, r)) -> STGenM r s -> ST s a

RandomGen g => StatefulGen (STGenM g s) (ST s)

Defined in System.Random.Stateful

Methods

uniformWord32R :: Word32 -> STGenM g s -> ST s Word32

uniformWord64R :: Word64 -> STGenM g s -> ST s Word64

uniformWord8 :: STGenM g s -> ST s Word8

uniformWord16 :: STGenM g s -> ST s Word16

uniformWord32 :: STGenM g s -> ST s Word32

uniformWord64 :: STGenM g s -> ST s Word64

uniformByteArrayM :: Bool -> Int -> STGenM g s -> ST s ByteArray

uniformShortByteString :: Int -> STGenM g s -> ST s ShortByteString

newSTGenM :: g -> ST s (STGenM g s)

Creates a new STGenM.

Since: 1.2.0

applySTGen :: (g -> (a, g)) -> STGenM g s -> ST s a

Applies a pure operation to the wrapped pseudo-random number generator.

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> (runSTGen pureGen (\g -> applySTGen random g)) :: (Int, StdGen)
(7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

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.

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> (runSTGen pureGen (\g -> applySTGen random g)) :: (Int, StdGen)
(7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

runSTGen_ :: RandomGen g => g -> (forall s. STGenM g s -> ST s a) -> a

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

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> (runSTGen_ pureGen (\g -> applySTGen random g)) :: Int
7879794327570578227

Since: 1.2.0

Mutable thread-safe adapter in STM

newtype TGen g

Frozen version of mutable TGenM generator

Since: 1.2.1

Constructors

TGen

Fields

• unTGen :: g

Instances

Storable g => Storable (TGen g)

Defined in System.Random.Stateful

Methods

sizeOf :: TGen g -> Int

alignment :: TGen g -> Int

peekElemOff :: Ptr (TGen g) -> Int -> IO (TGen g)

pokeElemOff :: Ptr (TGen g) -> Int -> TGen g -> IO ()

peekByteOff :: Ptr b -> Int -> IO (TGen g)

pokeByteOff :: Ptr b -> Int -> TGen g -> IO ()

peek :: Ptr (TGen g) -> IO (TGen g)

poke :: Ptr (TGen g) -> TGen g -> IO ()

Show g => Show (TGen g)

Defined in System.Random.Stateful

Methods

showsPrec :: Int -> TGen g -> ShowS

show :: TGen g -> String

showList :: [TGen g] -> ShowS

NFData g => NFData (TGen g)

Defined in System.Random.Stateful

Methods

rnf :: TGen g -> ()

Eq g => Eq (TGen g)

Defined in System.Random.Stateful

Methods

(==) :: TGen g -> TGen g -> Bool

(/=) :: TGen g -> TGen g -> Bool

Ord g => Ord (TGen g)

Defined in System.Random.Stateful

Methods

compare :: TGen g -> TGen g -> Ordering

(<) :: TGen g -> TGen g -> Bool

(<=) :: TGen g -> TGen g -> Bool

(>) :: TGen g -> TGen g -> Bool

(>=) :: TGen g -> TGen g -> Bool

max :: TGen g -> TGen g -> TGen g

min :: TGen g -> TGen g -> TGen g

RandomGen g => RandomGen (TGen g)

Defined in System.Random.Stateful

Methods

next :: TGen g -> (Int, TGen g)

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

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

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

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

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

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

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

unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> TGen g -> ST s (TGen g)

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

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

SplitGen g => SplitGen (TGen g)

Defined in System.Random.Stateful

Methods

splitGen :: TGen g -> (TGen g, TGen g)

SeedGen g => SeedGen (TGen g)

Defined in System.Random.Stateful

Associated Types

type SeedSize (TGen g) :: Nat

Methods

fromSeed :: Seed (TGen g) -> TGen g

toSeed :: TGen g -> Seed (TGen g)

fromSeed64 :: NonEmpty Word64 -> TGen g

toSeed64 :: TGen g -> NonEmpty Word64

RandomGen g => FrozenGen (TGen g) STM

Since: 1.2.1

Defined in System.Random.Stateful

Associated Types

type MutableGen (TGen g) STM = (g :: Type)

Methods

freezeGen :: MutableGen (TGen g) STM -> STM (TGen g)

modifyGen :: MutableGen (TGen g) STM -> (TGen g -> (a, TGen g)) -> STM a

overwriteGen :: MutableGen (TGen g) STM -> TGen g -> STM ()

RandomGen g => ThawedGen (TGen g) STM

Defined in System.Random.Stateful

Methods

thawGen :: TGen g -> STM (MutableGen (TGen g) STM)

type SeedSize (TGen g)

Defined in System.Random.Stateful

type SeedSize (TGen g) = SeedSize g

type MutableGen (TGen g) STM

Defined in System.Random.Stateful

type MutableGen (TGen g) STM = TGenM g

newtype TGenM g

Wraps a TVar that holds a pure pseudo-random number generator.

Since: 1.2.1

Constructors

TGenM

Fields

• unTGenM :: TVar g

Instances

RandomGen g => StatefulGen (TGenM g) STM

Since: 1.2.1

Defined in System.Random.Stateful

Methods

uniformWord32R :: Word32 -> TGenM g -> STM Word32

uniformWord64R :: Word64 -> TGenM g -> STM Word64

uniformWord8 :: TGenM g -> STM Word8

uniformWord16 :: TGenM g -> STM Word16

uniformWord32 :: TGenM g -> STM Word32

uniformWord64 :: TGenM g -> STM Word64

uniformByteArrayM :: Bool -> Int -> TGenM g -> STM ByteArray

uniformShortByteString :: Int -> TGenM g -> STM ShortByteString

RandomGen r => RandomGenM (TGenM r) r STM

Defined in System.Random.Stateful

Methods

applyRandomGenM :: (r -> (a, r)) -> TGenM r -> STM a

newTGenM :: g -> STM (TGenM g)

Creates a new TGenM in STM.

Since: 1.2.1

newTGenMIO :: MonadIO m => g -> m (TGenM g)

Creates a new TGenM in IO.

Since: 1.2.1

applyTGen :: (g -> (a, g)) -> TGenM g -> STM a

Applies a pure operation to the wrapped pseudo-random number generator.

Examples

>>> import Control.Concurrent.STM
>>> import System.Random.Stateful
>>> import Data.Int (Int32)
>>> let pureGen = mkStdGen 137
>>> stmGen <- newTGenMIO pureGen
>>> atomically $ applyTGen uniform stmGen :: IO Int32
637238067

Since: 1.2.1

Pseudo-random values of various types

This library provides two type classes to generate pseudo-random values:

• UniformRange is used to generate a value of a type uniformly within a range.
• Uniform is used to generate a value of a type uniformly over all possible values of that type.

Types may have instances for both or just one of UniformRange and Uniform. A few examples illustrate this:

• Int, Word16 and Bool are instances of both UniformRange and Uniform.
• Integer, Float and Double each have an instance for UniformRange but no Uniform instance.
• A hypothetical type Radian representing angles by taking values in the range [0, 2π) has a trivial Uniform instance, but no UniformRange instance: the problem is that two given Radian values always span two ranges, one clockwise and one anti-clockwise.
• It is trivial to construct a Uniform (a, b) instance given Uniform a and Uniform b (and this library provides this tuple instance).
• On the other hand, there is no correct way to construct a UniformRange (a, b) instance based on just UniformRange a and UniformRange b.

class Uniform a where

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

Since: 1.2.0

Minimal complete definition

Nothing

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:

>>> :seti -XDeriveGeneric -XDeriveAnyClass
>>> import GHC.Generics (Generic)
>>> import System.Random.Stateful
>>> data 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]

Since: 1.2.0

default uniformM :: (StatefulGen g m, Generic a, GUniform (Rep a)) => g -> m a

Instances

Uniform CBool

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CBool

Uniform CChar

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CChar

Uniform CInt

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CInt

Uniform CIntMax

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CIntMax

Uniform CIntPtr

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CIntPtr

Uniform CLLong

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CLLong

Uniform CLong

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CLong

Uniform CPtrdiff

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CPtrdiff

Uniform CSChar

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CSChar

Uniform CShort

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CShort

Uniform CSigAtomic

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CSigAtomic

Uniform CSize

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CSize

Uniform CUChar

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CUChar

Uniform CUInt

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CUInt

Uniform CUIntMax

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CUIntMax

Uniform CUIntPtr

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CUIntPtr

Uniform CULLong

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CULLong

Uniform CULong

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CULong

Uniform CUShort

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CUShort

Uniform CWchar

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m CWchar

Uniform Int16

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Int16

Uniform Int32

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Int32

Uniform Int64

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Int64

Uniform Int8

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Int8

Uniform Word16

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Word16

Uniform Word32

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Word32

Uniform Word64

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Word64

Uniform Word8

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Word8

Uniform ()

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m ()

Uniform Bool

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Bool

Uniform Char

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Char

Uniform Int

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Int

Uniform Word

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m Word

SeedGen g => Uniform (Seed g)

Defined in System.Random.Seed

Methods

uniformM :: StatefulGen g0 m => g0 -> m (Seed g)

(Finite a, Uniform a) => Uniform (Maybe a)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (Maybe a)

(Finite a, Uniform a, Finite b, Uniform b) => Uniform (Either a b)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (Either a b)

(Uniform a, Uniform b) => Uniform (a, b)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (a, b)

(Uniform a, Uniform b, Uniform c) => Uniform (a, b, c)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (a, b, c)

(Uniform a, Uniform b, Uniform c, Uniform d) => Uniform (a, b, c, d)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (a, b, c, d)

(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e) => Uniform (a, b, c, d, e)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (a, b, c, d, e)

(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f) => Uniform (a, b, c, d, e, f)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g m => g -> m (a, b, c, d, e, f)

(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f, Uniform g) => Uniform (a, b, c, d, e, f, g)

Defined in System.Random.Internal

Methods

uniformM :: StatefulGen g0 m => g0 -> m (a, b, c, d, e, f, g)

uniformViaFiniteM :: (StatefulGen g m, Generic a, GFinite (Rep a)) => g -> 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.

>>> :seti -XDeriveGeneric -XDeriveAnyClass
>>> import GHC.Generics (Generic)
>>> import System.Random.Stateful
>>> data Triple = Triple Word8 Word8 Word8 deriving (Show, Generic, Finite)
>>> instance Uniform Triple where uniformM = uniformViaFiniteM
>>> gen <- 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]

class UniformRange a where

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

Since: 1.2.0

Minimal complete definition

Nothing

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)

The range is understood as defined by means of isInRange, so

isInRange (a, b) <$> uniformRM (a, b) gen == pure True

but beware of floating point number caveats.

There is a default implementation via Generic:

>>> :seti -XDeriveGeneric -XDeriveAnyClass
>>> import GHC.Generics (Generic)
>>> import Data.Word (Word8)
>>> import Control.Monad (replicateM)
>>> import System.Random.Stateful
>>> gen <- newIOGenM (mkStdGen 42)
>>> data Tuple = Tuple Bool Word8 deriving (Show, Generic, UniformRange)
>>> replicateM 10 (uniformRM (Tuple False 100, Tuple True 150) gen)
[Tuple False 102,Tuple True 118,Tuple False 115,Tuple True 113,Tuple True 126,Tuple False 127,Tuple True 130,Tuple False 113,Tuple False 150,Tuple False 125]

Since: 1.2.0

default uniformRM :: (StatefulGen g m, Generic a, GUniformRange (Rep a)) => (a, a) -> g -> m a

isInRange :: (a, a) -> a -> Bool

A notion of (inclusive) ranges prescribed to a.

Ranges are symmetric:

isInRange (lo, hi) x == isInRange (hi, lo) x

Ranges include their endpoints:

isInRange (lo, hi) lo == True

When endpoints coincide, there is nothing else:

isInRange (x, x) y == x == y

Endpoints are endpoints:

isInRange (lo, hi) x ==>
isInRange (lo, x) hi == x == hi

Ranges are transitive relations:

isInRange (lo, hi) lo' && isInRange (lo, hi) hi' && isInRange (lo', hi') x
==> isInRange (lo, hi) x

There is a default implementation of isInRange via Generic. Other helper function that can be used for implementing this function are isInRangeOrd and isInRangeEnum

Since: 1.3.0

default isInRange :: (Generic a, GUniformRange (Rep a)) => (a, a) -> a -> Bool

Instances

UniformRange CBool

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CBool, CBool) -> g -> m CBool

isInRange :: (CBool, CBool) -> CBool -> Bool

UniformRange CChar

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CChar, CChar) -> g -> m CChar

isInRange :: (CChar, CChar) -> CChar -> Bool

UniformRange CDouble

See Floating point number caveats.

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CDouble, CDouble) -> g -> m CDouble

isInRange :: (CDouble, CDouble) -> CDouble -> Bool

UniformRange CFloat

See Floating point number caveats.

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CFloat, CFloat) -> g -> m CFloat

isInRange :: (CFloat, CFloat) -> CFloat -> Bool

UniformRange CInt

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CInt, CInt) -> g -> m CInt

isInRange :: (CInt, CInt) -> CInt -> Bool

UniformRange CIntMax

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CIntMax, CIntMax) -> g -> m CIntMax

isInRange :: (CIntMax, CIntMax) -> CIntMax -> Bool

UniformRange CIntPtr

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CIntPtr, CIntPtr) -> g -> m CIntPtr

isInRange :: (CIntPtr, CIntPtr) -> CIntPtr -> Bool

UniformRange CLLong

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CLLong, CLLong) -> g -> m CLLong

isInRange :: (CLLong, CLLong) -> CLLong -> Bool

UniformRange CLong

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CLong, CLong) -> g -> m CLong

isInRange :: (CLong, CLong) -> CLong -> Bool

UniformRange CPtrdiff

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CPtrdiff, CPtrdiff) -> g -> m CPtrdiff

isInRange :: (CPtrdiff, CPtrdiff) -> CPtrdiff -> Bool

UniformRange CSChar

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CSChar, CSChar) -> g -> m CSChar

isInRange :: (CSChar, CSChar) -> CSChar -> Bool

UniformRange CShort

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CShort, CShort) -> g -> m CShort

isInRange :: (CShort, CShort) -> CShort -> Bool

UniformRange CSigAtomic

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CSigAtomic, CSigAtomic) -> g -> m CSigAtomic

isInRange :: (CSigAtomic, CSigAtomic) -> CSigAtomic -> Bool

UniformRange CSize

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CSize, CSize) -> g -> m CSize

isInRange :: (CSize, CSize) -> CSize -> Bool

UniformRange CUChar

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CUChar, CUChar) -> g -> m CUChar

isInRange :: (CUChar, CUChar) -> CUChar -> Bool

UniformRange CUInt

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CUInt, CUInt) -> g -> m CUInt

isInRange :: (CUInt, CUInt) -> CUInt -> Bool

UniformRange CUIntMax

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CUIntMax, CUIntMax) -> g -> m CUIntMax

isInRange :: (CUIntMax, CUIntMax) -> CUIntMax -> Bool

UniformRange CUIntPtr

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CUIntPtr, CUIntPtr) -> g -> m CUIntPtr

isInRange :: (CUIntPtr, CUIntPtr) -> CUIntPtr -> Bool

UniformRange CULLong

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CULLong, CULLong) -> g -> m CULLong

isInRange :: (CULLong, CULLong) -> CULLong -> Bool

UniformRange CULong

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CULong, CULong) -> g -> m CULong

isInRange :: (CULong, CULong) -> CULong -> Bool

UniformRange CUShort

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CUShort, CUShort) -> g -> m CUShort

isInRange :: (CUShort, CUShort) -> CUShort -> Bool

UniformRange CWchar

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (CWchar, CWchar) -> g -> m CWchar

isInRange :: (CWchar, CWchar) -> CWchar -> Bool

UniformRange Int16

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Int16, Int16) -> g -> m Int16

isInRange :: (Int16, Int16) -> Int16 -> Bool

UniformRange Int32

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Int32, Int32) -> g -> m Int32

isInRange :: (Int32, Int32) -> Int32 -> Bool

UniformRange Int64

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Int64, Int64) -> g -> m Int64

isInRange :: (Int64, Int64) -> Int64 -> Bool

UniformRange Int8

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Int8, Int8) -> g -> m Int8

isInRange :: (Int8, Int8) -> Int8 -> Bool

UniformRange Word16

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Word16, Word16) -> g -> m Word16

isInRange :: (Word16, Word16) -> Word16 -> Bool

UniformRange Word32

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Word32, Word32) -> g -> m Word32

isInRange :: (Word32, Word32) -> Word32 -> Bool

UniformRange Word64

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Word64, Word64) -> g -> m Word64

isInRange :: (Word64, Word64) -> Word64 -> Bool

UniformRange Word8

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Word8, Word8) -> g -> m Word8

isInRange :: (Word8, Word8) -> Word8 -> Bool

UniformRange Integer

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Integer, Integer) -> g -> m Integer

isInRange :: (Integer, Integer) -> Integer -> Bool

UniformRange Natural

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Natural, Natural) -> g -> m Natural

isInRange :: (Natural, Natural) -> Natural -> Bool

UniformRange ()

Defined in System.Random.Internal

Methods

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

isInRange :: ((), ()) -> () -> Bool

UniformRange Bool

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Bool, Bool) -> g -> m Bool

isInRange :: (Bool, Bool) -> Bool -> Bool

UniformRange Char

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Char, Char) -> g -> m Char

isInRange :: (Char, Char) -> Char -> Bool

UniformRange Double

See Floating point number caveats.

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Double, Double) -> g -> m Double

isInRange :: (Double, Double) -> Double -> Bool

UniformRange Float

See Floating point number caveats.

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Float, Float) -> g -> m Float

isInRange :: (Float, Float) -> Float -> Bool

UniformRange Int

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Int, Int) -> g -> m Int

isInRange :: (Int, Int) -> Int -> Bool

UniformRange Word

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => (Word, Word) -> g -> m Word

isInRange :: (Word, Word) -> Word -> Bool

(UniformRange a, UniformRange b) => UniformRange (a, b)

Defined in System.Random.Internal

Methods

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

isInRange :: ((a, b), (a, b)) -> (a, b) -> Bool

(UniformRange a, UniformRange b, UniformRange c) => UniformRange (a, b, c)

Defined in System.Random.Internal

Methods

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

isInRange :: ((a, b, c), (a, b, c)) -> (a, b, c) -> Bool

(UniformRange a, UniformRange b, UniformRange c, UniformRange d) => UniformRange (a, b, c, d)

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => ((a, b, c, d), (a, b, c, d)) -> g -> m (a, b, c, d)

isInRange :: ((a, b, c, d), (a, b, c, d)) -> (a, b, c, d) -> Bool

(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e) => UniformRange (a, b, c, d, e)

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => ((a, b, c, d, e), (a, b, c, d, e)) -> g -> m (a, b, c, d, e)

isInRange :: ((a, b, c, d, e), (a, b, c, d, e)) -> (a, b, c, d, e) -> Bool

(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e, UniformRange f) => UniformRange (a, b, c, d, e, f)

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g m => ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> g -> m (a, b, c, d, e, f)

isInRange :: ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> (a, b, c, d, e, f) -> Bool

(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e, UniformRange f, UniformRange g) => UniformRange (a, b, c, d, e, f, g)

Defined in System.Random.Internal

Methods

uniformRM :: StatefulGen g0 m => ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> g0 -> m (a, b, c, d, e, f, g)

isInRange :: ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> (a, b, c, d, e, f, g) -> Bool

isInRangeOrd :: Ord a => (a, a) -> a -> Bool

Utilize Ord instance to decide if a value is within the range. Designed to be used for implementing isInRange

Since: 1.3.0

isInRangeEnum :: Enum a => (a, a) -> a -> Bool

Utilize Enum instance to decide if a value is within the range. Designed to be used for implementing isInRange

Since: 1.3.0

Lists

uniformListM :: (StatefulGen g m, Uniform a) => Int -> g -> m [a]

Generates a list of pseudo-random values.

Examples

>>> 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]

Since: 1.2.0

uniformListRM :: (StatefulGen g m, UniformRange a) => Int -> (a, a) -> g -> m [a]

Generates a list of pseudo-random values in a specified range.

Examples

>>> import System.Random.Stateful
>>> let pureGen = mkStdGen 137
>>> g <- newIOGenM pureGen
>>> uniformListRM 10 (20, 30) g :: IO [Int]
[23,21,28,25,28,28,26,25,29,27]

Since: 1.3.0

uniformShuffleListM :: StatefulGen g m => [a] -> g -> m [a]

Shuffle elements of a list in a uniformly random order.

Examples

>>> import System.Random.Stateful
>>> runStateGen_ (mkStdGen 127) $ uniformShuffleListM "ELVIS"
"LIVES"

Since: 1.3.0

Generators for sequences of pseudo-random bytes

uniformByteArrayM

Arguments

:: StatefulGen g m

=> Bool

Should ByteArray be allocated as pinned memory or not

-> Int

Size of the newly created ByteArray in number of bytes.

-> g

Generator to use for filling in the newly created ByteArray

-> m ByteArray

uniformByteArrayM n g generates a ByteArray of length n filled with pseudo-random bytes.

Since: 1.3.0

uniformByteStringM :: StatefulGen g m => Int -> g -> m ByteString

Generates a pseudo-random ByteString of the specified size.

Since: 1.2.0

uniformShortByteStringM :: StatefulGen g m => Int -> g -> m ShortByteString

uniformShortByteString n g generates a ShortByteString of length n filled with pseudo-random bytes.

Since: 1.3.0

Helper functions for createing instances

Sequences of bytes

fillByteArrayST :: Bool -> Int -> ST s Word64 -> ST s ByteArray

Using an ST action that generates 8 bytes at a time fill in a new ByteArray in architecture agnostic manner.

Since: 1.3.0

genShortByteStringIO

Arguments

:: Int

Number of bytes to generate

-> IO Word64

IO action that can generate 8 random bytes at a time

-> IO ShortByteString

Deprecated: In favor of fillByteArrayST

Efficiently fills in a new ShortByteString in a platform independent manner.

Since: 1.2.0

genShortByteStringST :: Int -> ST s Word64 -> ST s ShortByteString

Deprecated: In favor of fillByteArrayST, since uniformShortByteString, which it was used for, was also deprecated

Same as genShortByteStringIO, but runs in ST.

Since: 1.2.0

defaultUnsafeUniformFillMutableByteArray

Arguments

:: RandomGen g

=> MutableByteArray s

-> Int

Starting offset

-> Int

Number of random bytes to write into the array

-> g

ST action that can generate 8 random bytes at a time

-> ST s g

Efficiently generates a sequence of pseudo-random bytes in a platform independent manner.

Since: 1.2.0

Floating point numbers

uniformDouble01M :: forall g m. StatefulGen g m => g -> m Double

Generates uniformly distributed Double in the range \([0, 1]\). Numbers are generated by generating uniform Word64 and dividing it by \(2^{64}\). It's used to implement UniformRange instance for Double.

Since: 1.2.0

uniformDoublePositive01M :: forall g m. StatefulGen g m => g -> m Double

Generates uniformly distributed Double in the range \((0, 1]\). Number is generated as \(2^{-64}/2+\operatorname{uniformDouble01M}\). Constant is 1/2 of smallest nonzero value which could be generated by uniformDouble01M.

Since: 1.2.0

uniformFloat01M :: forall g m. StatefulGen g m => g -> m Float

Generates uniformly distributed Float in the range \([0, 1]\). Numbers are generated by generating uniform Word32 and dividing it by \(2^{32}\). It's used to implement UniformRange instance for Float.

Since: 1.2.0

uniformFloatPositive01M :: forall g m. StatefulGen g m => g -> m Float

Generates uniformly distributed Float in the range \((0, 1]\). Number is generated as \(2^{-32}/2+\operatorname{uniformFloat01M}\). Constant is 1/2 of smallest nonzero value which could be generated by uniformFloat01M.

Since: 1.2.0

Enum types

uniformEnumM :: forall a g m. (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

Since: 1.3.0

uniformEnumRM :: forall a g m. (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)

Since: 1.3.0

Word

uniformWordR

Arguments

:: StatefulGen g m

=> Word

Maximum value to generate

-> g

Stateful generator

-> m Word

Architecture specific Word generation in the specified lower range

Since: 1.3.0

Appendix

How to implement StatefulGen

Typically, a monadic pseudo-random number generator has facilities to save and restore its internal state in addition to generating pseudo-random numbers.

Here is an example instance for the monadic pseudo-random number generator from the mwc-random package:

import qualified System.Random.MWC as MWC
import qualified Data.Vector.Generic as G

instance (s ~ PrimState m, PrimMonad m) => StatefulGen (MWC.Gen s) m where
  uniformWord8 = MWC.uniform
  uniformWord16 = MWC.uniform
  uniformWord32 = MWC.uniform
  uniformWord64 = MWC.uniform
  uniformByteArrayM isPinned n g = stToPrim (fillByteArrayST isPinned n (MWC.uniform g))

instance PrimMonad m => FrozenGen MWC.Seed m where
  type MutableGen MWC.Seed m = MWC.Gen (PrimState m)
  freezeGen = MWC.save
  overwriteGen (Gen mv) (Seed v) = G.copy mv v

instance PrimMonad m => ThawedGen MWC.Seed m where
  thawGen = MWC.restore

FrozenGen

FrozenGen gives us ability to use most of stateful pseudo-random number generator in its immutable form, if one exists that is. The biggest benefit that can be drawn from a polymorphic access to a stateful pseudo-random number generator in a frozen form is the ability to serialize, deserialize and possibly even use the stateful generator in a pure setting without knowing the actual type of a generator ahead of time. For example we can write a function that accepts a frozen state of some pseudo-random number generator and produces a short list with random even integers.

>>> import Data.Int (Int8)
>>> import Control.Monad (replicateM)
>>> :{
myCustomRandomList :: ThawedGen f m => f -> m [Int8]
myCustomRandomList f =
  withMutableGen_ f $ \gen -> do
    len <- uniformRM (5, 10) gen
    replicateM len $ do
      x <- uniformM gen
      pure $ if even x then x else x + 1
:}

and later we can apply it to a frozen version of a stateful generator, such as STGen:

>>> print $ runST $ myCustomRandomList (STGen (mkStdGen 217))
[-50,-2,4,-8,-58,-40,24,-32,-110,24]

Alternatively, instead of discarding the final state of the generator, as it happens above, we could have used withMutableGen, which together with the result would give us back its frozen form. This would allow us to store the end state of our generator somewhere for the later reuse.

Floating point number caveats

scaleFloating

Arguments

:: forall a w. (RealFloat a, Integral w, Bounded w, FiniteBits w)

=> a

Low

-> a

High

-> w

Uniformly distributed unsigned integral value that will be used for converting to a floating point value and subsequent scaling to the specified range

-> a

This is the function that is used to scale a floating point value from random word range to the custom [low, high] range.

Since: 1.3.0

Due to rounding errors, floating point operations are neither associative nor distributive the way the corresponding operations on real numbers are. Additionally, floating point numbers admit special values NaN as well as negative and positive infinity.

The UniformRange instances for Float and Double use the following procedure to generate a random value in a range for uniformRM (l, h) g:

• If l == h, return: l.
• If isInfinite l == True or isInfinite h == True, return: l + h

• Otherwise:

  1. Generate an unsigned integral of matching width w uniformly.

  2. Check whether h - l overflows to infinity and, if it does, then convert w to a floating point number in [0.0, 1.0] range through division of w by the highest possible value:

     x = fromIntegral w / fromIntegral maxBound
     

     Then we scale and clamp it before returning it:

     max (min (x * l + (1 - x) * h) (max l h)) (min l h)
     

     Clamping is necessary, because otherwise it would be possible to run into a degenerate case when a scaled value is outside the specified range due to rounding errors.

  3. Whenever h - l does not overflow, we use this common formula for scaling: l + (h - l) * x. However, instead of using [0.0, 1.0] range we use the top most bit of w to decide whether we will treat the generated floating point value as [0.0, 0.5] range or [0.5, 1.0] range and use the left over bits to produce a floating point value in the half unit range:

     x = fromIntegral (clearBit w 31) / fromIntegral maxBound
     

     Further scaling depends on the top most bit:

     if testBit w 31
        then l + (h - l) * x
        else h + (l - h) * x
     

     Because of this clever technique the result does not need clamping, since scaled values are guaranteed to stay within the specified range. Another reason why this tecnique is used for the common case instead of the one described in 2. is because it avoids usage of 1 - x, which consequently reduces loss of randomness due to rounding.

What happens when NaN or Infinity are given to uniformRM? We first define them as constants:

>>> nan = read "NaN" :: Float
>>> inf = read "Infinity" :: Float
>>> g <- newIOGenM (mkStdGen 2024)

• If at least one of \(l\) or \(h\) is NaN, the result is NaN.

  >>> uniformRM (nan, 1) g
  NaN
  >>> uniformRM (-1, nan) g
  NaN
  

• If \(l\) and \(h\) are both Infinity with opposing signs, then the result is NaN.

  >>> uniformRM (-inf, inf) g
  NaN
  >>> uniformRM (inf, -inf) g
  NaN
  

• Otherwise, if \(l\) is Infinity or -Infinity, the result is \(l\).

  >>> uniformRM (inf, 1) g
  Infinity
  >>> uniformRM (-inf, 1) g
  -Infinity
  

• Otherwise, if \(h\) is Infinity or -Infinity, the result is \(h\).

  >>> uniformRM (1, inf) g
  Infinity
  >>> uniformRM (1, -inf) g
  -Infinity
  

Note that the GCC 10.1.0 C++ standard library, the Java 10 standard library and CPython 3.8 use a similar procedure to generate floating point values in a range.

References

1. Guy L. Steele, Jr., Doug Lea, and Christine H. Flood. 2014. Fast splittable pseudorandom number generators. In Proceedings of the 2014 ACM International Conference on Object Oriented Programming Systems Languages & Applications (OOPSLA '14). ACM, New York, NY, USA, 453-472. DOI: https://doi.org/10.1145/2660193.2660195