random-1.1: random number library

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file LICENSE in the 'random' repository)
Maintainer | libraries@haskell.org
Stability | stable
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell98

System.Random

Contents

- Random number generators
  - Standard random number generators
  - The global random number generator
- Random values of various types
- References

Description

This library deals with the common task of pseudo-random number generation. The library makes it possible to generate repeatable results, by starting with a specified initial random number generator, or to get different results on each run by using the system-initialised generator or by supplying a seed from some other source.

The library is split into two layers:

- A core random number generator provides a supply of bits. The class `RandomGen` provides a common interface to such generators. The library provides one instance of `RandomGen`, the abstract data type `StdGen`. Programmers may, of course, supply their own instances of `RandomGen`.
- The class `Random` provides a way to extract values of a particular type from a random number generator. For example, the `Float` instance of `Random` allows one to generate random values of type `Float`.

This implementation uses the Portable Combined Generator of L'Ecuyer [System.Random] for 32-bit computers, transliterated by Lennart Augustsson. It has a period of roughly 2.30584e18.

Synopsis

- class RandomGen g where
  - next :: g -> (Int, g)
  - genRange :: g -> (Int, Int)
  - split :: g -> (g, g)
- data StdGen
- mkStdGen :: Int -> StdGen
- getStdRandom :: (StdGen -> (a, StdGen)) -> IO a
- getStdGen :: IO StdGen
- setStdGen :: StdGen -> IO ()
- newStdGen :: IO StdGen
- class Random a where
  - randomR :: RandomGen g => (a, a) -> g -> (a, g)
  - random :: RandomGen g => g -> (a, g)
  - randomRs :: RandomGen g => (a, a) -> g -> [a]
  - randoms :: RandomGen g => g -> [a]
  - randomRIO :: (a, a) -> IO a
  - randomIO :: IO a

# Random number generators

class RandomGen g where #

The class `RandomGen` provides a common interface to random number generators.

Minimal complete definition

next, split

Methods

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

The `next` operation returns an `Int` that is uniformly distributed in the range returned by `genRange` (including both end points), and a new generator.

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

The `genRange` operation yields the range of values returned by the generator.

It is required that:

- If `(a,b) = `genRange` g`, then `a < b`.
- `genRange` always returns a pair of defined `Int`s.

The second condition ensures that `genRange` cannot examine its argument, and hence the value it returns can be determined only by the instance of `RandomGen`. That in turn allows an implementation to make a single call to `genRange` to establish a generator's range, without being concerned that the generator returned by (say) `next` might have a different range to the generator passed to `next`.

The default definition spans the full range of `Int`.

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

The `split` operation allows one to obtain two distinct random number generators. This is very useful in functional programs (for example, when passing a random number generator down to recursive calls), but very little work has been done on statistically robust implementations of `split` ([System.Random, System.Random] are the only examples we know of).

#### Instances

Instances details

RandomGen StdGen # |
Instance details Defined in System.Random Methods next :: StdGen -> (Int, StdGen) # genRange :: StdGen -> (Int, Int) # split :: StdGen -> (StdGen, StdGen) #

## Standard random number generators

data StdGen #

The `StdGen` instance of `RandomGen` has a `genRange` of at least 30 bits.

The result of repeatedly using `next` should be at least as statistically robust as the Minimal Standard Random Number Generator described by [System.Random, System.Random]. Until more is known about implementations of `split`, all we require is that `split` deliver generators that are (a) not identical and (b) independently robust in the sense just given.

The `Show` and `Read` instances of `StdGen` provide a primitive way to save the state of a random number generator. It is required that ``read` (`show` g) == g`.

In addition, `reads` may be used to map an arbitrary string (not necessarily one produced by `show`) onto a value of type `StdGen`. In general, the `Read` instance of `StdGen` has the following properties:

- It guarantees to succeed on any string.
- It guarantees to consume only a finite portion of the string.
- Different argument strings are likely to result in different results.

#### Instances

Instances details

Read StdGen # |
Instance details Defined in System.Random Methods readsPrec :: Int -> ReadS StdGen # readList :: ReadS [StdGen] # readPrec :: ReadPrec StdGen # readListPrec :: ReadPrec [StdGen] #
Show StdGen # |
Instance details Defined in System.Random Methods showsPrec :: Int -> StdGen -> ShowS # show :: StdGen -> String # showList :: [StdGen] -> ShowS #
RandomGen StdGen # |
Instance details Defined in System.Random Methods next :: StdGen -> (Int, StdGen) # genRange :: StdGen -> (Int, Int) # split :: StdGen -> (StdGen, StdGen) #

mkStdGen :: Int -> StdGen #

The function `mkStdGen` provides an alternative way of producing an initial generator, by mapping an `Int` into a generator. Again, distinct arguments should be likely to produce distinct generators.

## The global random number generator

There is a single, implicit, global random number generator of type `StdGen`, held in some global variable maintained by the `IO` monad. It is initialised automatically in some system-dependent fashion, for example, by using the time of day, or Linux's kernel random number generator. To get deterministic behaviour, use `setStdGen`.

getStdRandom :: (StdGen -> (a, StdGen)) -> IO 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` gets a random integer between 1 and 6:

     rollDice :: IO Int
     rollDice = getStdRandom (randomR (1,6))

getStdGen :: IO StdGen #

Gets the global random number generator.

setStdGen :: StdGen -> IO () #

Sets the global random number generator.

newStdGen :: IO StdGen #

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

# Random values of various types

class Random a where #

With a source of random number supply in hand, the `Random` class allows the programmer to extract random values of a variety of types.

Minimal complete definition: `randomR` and `random`.

Minimal complete definition

randomR, random

Methods

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

Takes a range (lo,hi) and a random number generator g, and returns a random value uniformly distributed in the closed interval [lo,hi], together with a new generator. It is unspecified what happens if lo>hi. For continuous types there is no requirement that the values lo and hi are ever produced, but they may be, depending on the implementation and the interval.

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 fractional types, the range is normally the semi-closed interval `[0,1)`.
- For `Integer`, the range is (arbitrarily) the range of `Int`.

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

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

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

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

randomRIO :: (a, a) -> IO a #

A variant of `randomR` that uses the global random number generator (see System.Random).

randomIO :: IO a #

A variant of `random` that uses the global random number generator (see System.Random).

#### Instances

Instances details

Random Bool # |
Instance details 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] # randomRIO :: (Bool, Bool) -> IO Bool # randomIO :: IO Bool #
Random Char # |
Instance details 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] # randomRIO :: (Char, Char) -> IO Char # randomIO :: IO Char #
Random Double # |
Instance details 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] # randomRIO :: (Double, Double) -> IO Double # randomIO :: IO Double #
Random Float # |
Instance details 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] # randomRIO :: (Float, Float) -> IO Float # randomIO :: IO Float #
Random Int # |
Instance details 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] # randomRIO :: (Int, Int) -> IO Int # randomIO :: IO Int #
Random Int8 # |
Instance details 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] # randomRIO :: (Int8, Int8) -> IO Int8 # randomIO :: IO Int8 #
Random Int16 # |
Instance details 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] # randomRIO :: (Int16, Int16) -> IO Int16 # randomIO :: IO Int16 #
Random Int32 # |
Instance details 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] # randomRIO :: (Int32, Int32) -> IO Int32 # randomIO :: IO Int32 #
Random Int64 # |
Instance details 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] # randomRIO :: (Int64, Int64) -> IO Int64 # randomIO :: IO Int64 #
Random Integer # |
Instance details 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] # randomRIO :: (Integer, Integer) -> IO Integer # randomIO :: IO Integer #
Random Word # |
Instance details 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] # randomRIO :: (Word, Word) -> IO Word # randomIO :: IO Word #
Random Word8 # |
Instance details 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] # randomRIO :: (Word8, Word8) -> IO Word8 # randomIO :: IO Word8 #
Random Word16 # |
Instance details 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] # randomRIO :: (Word16, Word16) -> IO Word16 # randomIO :: IO Word16 #
Random Word32 # |
Instance details 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] # randomRIO :: (Word32, Word32) -> IO Word32 # randomIO :: IO Word32 #
Random Word64 # |
Instance details 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] # randomRIO :: (Word64, Word64) -> IO Word64 # randomIO :: IO Word64 #
Random CChar # |
Instance details 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] # randomRIO :: (CChar, CChar) -> IO CChar # randomIO :: IO CChar #
Random CSChar # |
Instance details 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] # randomRIO :: (CSChar, CSChar) -> IO CSChar # randomIO :: IO CSChar #
Random CUChar # |
Instance details 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] # randomRIO :: (CUChar, CUChar) -> IO CUChar # randomIO :: IO CUChar #
Random CShort # |
Instance details 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] # randomRIO :: (CShort, CShort) -> IO CShort # randomIO :: IO CShort #
Random CUShort # |
Instance details 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] # randomRIO :: (CUShort, CUShort) -> IO CUShort # randomIO :: IO CUShort #
Random CInt # |
Instance details 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] # randomRIO :: (CInt, CInt) -> IO CInt # randomIO :: IO CInt #
Random CUInt # |
Instance details 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] # randomRIO :: (CUInt, CUInt) -> IO CUInt # randomIO :: IO CUInt #
Random CLong # |
Instance details 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] # randomRIO :: (CLong, CLong) -> IO CLong # randomIO :: IO CLong #
Random CULong # |
Instance details 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] # randomRIO :: (CULong, CULong) -> IO CULong # randomIO :: IO CULong #
Random CLLong # |
Instance details 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] # randomRIO :: (CLLong, CLLong) -> IO CLLong # randomIO :: IO CLLong #
Random CULLong # |
Instance details 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] # randomRIO :: (CULLong, CULLong) -> IO CULLong # randomIO :: IO CULLong #
Random CFloat # |
Instance details 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] # randomRIO :: (CFloat, CFloat) -> IO CFloat # randomIO :: IO CFloat #
Random CDouble # |
Instance details 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] # randomRIO :: (CDouble, CDouble) -> IO CDouble # randomIO :: IO CDouble #
Random CPtrdiff # |
Instance details 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] # randomRIO :: (CPtrdiff, CPtrdiff) -> IO CPtrdiff # randomIO :: IO CPtrdiff #
Random CSize # |
Instance details 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] # randomRIO :: (CSize, CSize) -> IO CSize # randomIO :: IO CSize #
Random CWchar # |
Instance details 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] # randomRIO :: (CWchar, CWchar) -> IO CWchar # randomIO :: IO CWchar #
Random CSigAtomic # |
Instance details 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] # randomRIO :: (CSigAtomic, CSigAtomic) -> IO CSigAtomic # randomIO :: IO CSigAtomic #
Random CIntPtr # |
Instance details 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] # randomRIO :: (CIntPtr, CIntPtr) -> IO CIntPtr # randomIO :: IO CIntPtr #
Random CUIntPtr # |
Instance details 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] # randomRIO :: (CUIntPtr, CUIntPtr) -> IO CUIntPtr # randomIO :: IO CUIntPtr #
Random CIntMax # |
Instance details 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] # randomRIO :: (CIntMax, CIntMax) -> IO CIntMax # randomIO :: IO CIntMax #
Random CUIntMax # |
Instance details 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] # randomRIO :: (CUIntMax, CUIntMax) -> IO CUIntMax # randomIO :: IO CUIntMax #

# References

1. FW Burton and RL Page, Distributed random number generation, Journal of Functional Programming, 2(2):203-212, April 1992.
2. SK Park, and KW Miller, /Random number generators - good ones are hard to find/, Comm ACM 31(10), Oct 1988, pp1192-1201.
3. DG Carta, /Two fast implementations of the minimal standard random number generator/, Comm ACM, 33(1), Jan 1990, pp87-88.
4. P Hellekalek, Don't trust parallel Monte Carlo, Department of Mathematics, University of Salzburg, http://random.mat.sbg.ac.at/~peter/pads98.ps, 1998.
5. Pierre L'Ecuyer, /Efficient and portable combined random number generators/, Comm ACM, 31(6), Jun 1988, pp742-749.

The Web site http://random.mat.sbg.ac.at/ is a great source of information.