The Random structure
Author: John Reppy
Keywords: Standard ML, SML, SML/NJ Library

The SML of NJ Library
The `Random` structure

The `Random` structure implements a random number generator using the Mersenne Twister algorithm. The implementation is specialized to the native word size. In the description below, we assume that the default word and integer types (`Word.word` and `Int.int`) have a representation that is smaller than the native size (e.g., 63 or 32 bits on a 64-bit machine).

Note that prior to 2023.1 (and 110.99.4), this structure was implemented using a subtract-with-borrow algorithm.

## Synopsis

    structure Random :> RANDOM

## Interface

    type rand

    val rand : (int * int) -> rand

    val fromList : NativeWord.word list -> rand

    val toBytes : rand -> Word8Vector.vector
    val fromBytes : Word8Vector.vector -> rand

    val toString : rand -> string
    val fromString : string -> rand

    val randNativeInt : rand -> NativeInt.int

    val randNativeWord : rand -> NativeWord.word

    val randInt : rand -> int

    val randWord : rand -> int

    val randNat : rand -> int

    val randReal : rand -> real

    val randRange : (int * int) -> rand -> int

## Description

`type rand`

  Represents the internal state of a random number generator.

`val rand : (int * int) -> rand`

  `rand (n1, n2)` creates a random number generator from the initial seed specified by the pair `(n1, n2)`. This function is kept for backward compatibility with the old implementation, but it is recommended that one use the `fromList` function in new code.

`val fromList : NativeWord.word list -> rand`

  creates a random number generator from the given list of initial seeds.

`val toBytes : rand -> Word8Vector.vector`

  `toBytes rand` returns a byte vector representing the current state of the generator.

`val fromBytes : Word8Vector.vector -> rand`

  `fromBytes bv` creates a generator with the initial state that was encoded in the byte vector `bv`. This expression will raise `Fail` exception if the byte vector is invalid.

`val toString : rand -> string`

  `toString rand` returns a string representing the random-number-generator state `rand`. This string is a `Base64` encoding of the result of `toBytes rand`.

`val fromString : string -> rand`

  `fromString s` returns the random-number-generator encoded as the string `s` (presumably generated by `toString`). This expression will raise `Fail` exception if the string `s` does not have the proper form.

`val randNativeWord : rand -> NativeWord.word`

  `randNativeWord rand` generates a uniform random number in the range \([0 .. 2^k-1\)], where \(k\) is the host platform’s native word size (e.g., 32 or 64).

`val randNativeInt : rand -> NativeInt.int`

  `randNativeInt rand` generates a random word a uniform distribution in the range \([0 .. 2^{k-1}-1\)], where \(k\) is the host platform’s native word size (e.g., 32 or 64).

`val randInt : rand -> int`

  `randInt rand` generates a random integer with a uniform distribution in the range \([-2^{k-1} .. 2^{k-1}-1\)], where \(k\) is the size of the `Int.int` type.

`val randWord : rand -> word`

  `randWord rand` generates a random word with a uniform distribution in the range \([0 .. 2^k-1\)], where \(k\) is the number of bits in the `Word.word` type.

`val randNat : rand -> int`

  `randNat rand` generates a random integer with a uniform distribution in the range \([0 .. 2^{k-1}-1\)], where \(k\) is the number of bits in the `Int.int` type.

`val randReal : rand -> real`

  `randReal rand` generates a random real number in the range `[0..1)`.

`val randRange : (int * int) -> rand -> int`

  `randRange (lo, hi) rand` generates a random number in the `[lo..hi]`. This function will raise the `Fail` exception if `hi < lo`.

## See Also

`Rand`, The Util Library

SML/NJ Version 110.99.9 (November 4, 2025)
Last updated 2025-11-04 15:48:25 UTC