haskell98-1.1.0.1: Compatibility with Haskell 98

Random

Synopsis

- class RandomGen g where
  - next :: g -> (Int, g)
  - split :: g -> (g, g)
  - genRange :: g -> (Int, Int)
- data StdGen
- mkStdGen :: Int -> 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
- getStdRandom :: (StdGen -> (a, StdGen)) -> IO a
- getStdGen :: IO StdGen
- setStdGen :: StdGen -> IO ()
- newStdGen :: IO StdGen

# Documentation

class RandomGen g where Source

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

Minimal complete definition: `next` and `split`.

Methods

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

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

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

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

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

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`.

Instances

RandomGen StdGen |

data StdGen Source

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

Read StdGen |
Show StdGen |
RandomGen StdGen |

mkStdGen :: Int -> StdGen Source

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.

class Random a where Source

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`.

Methods

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

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

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]Source

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

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

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

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

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

randomIO :: IO aSource

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

Instances

Random Bool |
Random Char |
Random Double |
Random Float |
Random Int |
Random Integer |

getStdRandom :: (StdGen -> (a, StdGen)) -> IO aSource

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 Source

Gets the global random number generator.

setStdGen :: StdGen -> IO ()Source

Sets the global random number generator.

newStdGen :: IO StdGen Source

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