# Documentation

class RandomGen g where

The class `RandomGen`

provides a common interface to random number
generators.

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)

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

The `genRange`

operation yields the range of values returned by
the generator.

It is required that:

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`

.

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, `read`

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.

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.

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:

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.

A variant of `randomR`

that uses the global random number generator
(see System.Random).

A variant of `random`

that uses the global random number generator
(see System.Random).

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