random package:random

Pseudo-random number generation This package provides basic pseudo-random number generation, including the ability to split random number generators.

System.Random: pure pseudo-random number interface

In pure code, use System.Random.uniform and System.Random.uniformR from System.Random to generate pseudo-random numbers with a pure pseudo-random number generator like System.Random.StdGen. As an example, here is how you can simulate rolls of a six-sided die using System.Random.uniformR:

>>> let roll = uniformR (1, 6)        :: RandomGen g => g -> (Word, g)

>>> let rolls = unfoldr (Just . roll) :: RandomGen g => g -> [Word]

>>> let pureGen = mkStdGen 42

>>> take 10 (rolls pureGen)           :: [Word]
[1,1,3,2,4,5,3,4,6,2]

See System.Random for more details.

System.Random.Stateful: monadic pseudo-random number interface

In monadic code, use System.Random.Stateful.uniformM and System.Random.Stateful.uniformRM from System.Random.Stateful to generate pseudo-random numbers with a monadic pseudo-random number generator, or using a monadic adapter. As an example, here is how you can simulate rolls of a six-sided die using System.Random.Stateful.uniformRM:

>>> let rollM = uniformRM (1, 6)                 :: StatefulGen g m => g -> m Word

>>> let pureGen = mkStdGen 42

>>> runStateGen_ pureGen (replicateM 10 . rollM) :: [Word]
[1,1,3,2,4,5,3,4,6,2]

The monadic adapter System.Random.Stateful.runStateGen_ is used here to lift the pure pseudo-random number generator pureGen into the System.Random.Stateful.StatefulGen context. The monadic interface can also be used with existing monadic pseudo-random number generators. In this example, we use the one provided in the mwc-random package:

>>> import System.Random.MWC as MWC

>>> let rollM = uniformRM (1, 6)       :: StatefulGen g m => g -> m Word

>>> monadicGen <- MWC.create

>>> replicateM 10 (rollM monadicGen) :: IO [Word]
[2,3,6,6,4,4,3,1,5,4]

See System.Random.Stateful for more details.

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.

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.

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

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.

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

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.

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.

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

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

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

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

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

RandomGen is an interface to pure pseudo-random number generators. StdGen is the standard RandomGen instance provided by this library.

Deprecated: In favor of FrozenGen

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]

Deprecated: In favor of modifyGen