Random Numbers

This module imports part of the Java standard random number generator (java.util.Random) API to SCL.

The following description is an extract from class Random Javadoc:

An instance of this class is used to generate a stream of pseudorandom numbers. The class uses a 48-bit seed, which is modified using a linear congruential formula. (See Donald Knuth, The Art of Computer Programming, Volume 2, Section 3.2.1.)

If two instances of Random are created with the same seed, and the same sequence of method calls is made for each, they will generate and return identical sequences of numbers. In order to guarantee this property, particular algorithms are specified for the class Random. Java implementations must use all the algorithms shown here for the class Random, for the sake of absolute portability of Java code. However, subclasses of class Random are permitted to use other algorithms, so long as they adhere to the general contracts for all the methods.

The algorithms implemented by class Random use a protected utility method that on each invocation can supply up to 32 pseudorandomly generated bits.

Instances of java.util.Random are threadsafe. Instances of java.util.Random are not cryptographically secure.

Generator Initialization

runRandom :: <Random,b> a -> <Proc,b> a
result = runRandom (random* functions of this module)

Executes functions defined in this module so that functions which have the effect <Random> will have access to a random generator. The random generator is be initialized with a random seed that is very likely to be distinct from any other invocation of this function.

withSeed :: Long -> <Random,b> a -> <b> a
result = withSeed seedValue (random* functions of this module)

Executes functions defined in this module so that functions which have the effect <Random> will have access to a random generator. The random generator is initialized with the specified seed value.

Random Number Generation

randomN :: Integer -> <Random> Integer

Returns a pseudorandom, uniformly distributed integer value between 0 (inclusive) and the specified bound (exclusive), drawn from this random number generator's sequence.

The general contract of randomN is that one integer value in the specified range is pseudorandomly generated and returned. All bound possible integer values are produced with (approximately) equal probability.

bound must be positive.

See Javadoc for more information.

randomInteger :: <Random> Integer

Returns the next pseudorandom, uniformly distributed integer value from this random number generator's sequence.

The general contract of randomInteger is that one integer value is pseudorandomly generated and returned. All 2^32 possible integer values are produced with (approximately) equal probability.

randomLong :: <Random> Long

Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence. The general contract of randomLong is that one long value is pseudorandomly generated and returned.

Because class Random uses a seed with only 48 bits, this algorithm will not return all possible long values.

randomDouble :: <Random> Double

Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.

The general contract of randomDouble is that one double value, chosen (approximately) uniformly from the range 0.0d (inclusive) to 1.0d (exclusive), is pseudorandomly generated and returned.

randomFloat :: <Random> Float

Returns the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence.

The general contract of randomFloat is that one float value, chosen (approximately) uniformly from the range 0.0f (inclusive) to 1.0f (exclusive), is pseudorandomly generated and returned. All 2^24 possible float values of the form m x 2^-24, where m is a positive integer less than 2^24, are produced with (approximately) equal probability.

randomBoolean :: <Random> Boolean

Returns the next pseudorandom, uniformly distributed boolean value from this random number generator's sequence.

The general contract of randomBoolean is that one boolean value is pseudorandomly generated and returned. The values true and false are produced with (approximately) equal probability.