View source code Display the source code in std/random.d from which this page was generated on github. Improve this page Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone. Page wiki View or edit the community-maintained wiki page associated with this page.

Module `std.random`

Facilities for random number generation.

The new-style generator objects hold their own state so they are immune of threading issues. The generators feature a number of well-known and well-documented methods of generating random numbers. An overall fast and reliable means to generate random numbers is the Mt19937 generator, which derives its name from "Mersenne Twister with a period of 2 to the power of 19937". In memory-constrained situations, linear congruential generators such as MinstdRand0 and MinstdRand might be useful. The standard library provides an alias Random for whichever generator it considers the most fit for the target environment.

Example

// Generate a uniformly-distributed integer in the range [0, 14]
auto i = uniform(0, 15);
// Generate a uniformly-distributed real in the range [0, 100)
// using a specific random generator
Random gen;
auto r = uniform(0.0L, 100.0L, gen);

In addition to random number generators, this module features distributions, which skew a generator's output statistical distribution in various ways. So far the uniform distribution for integers and real numbers have been implemented.

Upgrading

rand()"> can be replaced with uniform!uint().

Credits

The entire random number library architecture is derived from the excellent C++0X random number facility proposed by Jens Maurer and contributed to by researchers at the Fermi laboratory (excluding Xorshift).

Functions

Name	Description
`dice`	Rolls a `dice` with relative probabilities stored in `proportions`. Returns the index in `proportions` that was chosen.
`partialShuffle`	Partially shuffles the elements of `r` such that upon returning `r[0..n]` is a random subset of `r` and is randomly ordered. `r[n..r.length]` will contain the elements not in `r[0..n]`. These will be in an undefined order, but will not be random in the sense that their order after `partialShuffle` returns will not be independent of their order before `partialShuffle` was called.
`randomCover`	Covers a given range `r` in a random manner, i.e. goes through each element of `r` once and only once, just in a random order. `r` must be a random-access range with length.
`randomSample`	Selects a random subsample out of `r`, containing exactly `n` elements. The order of elements is the same as in the original range. The `total` length of `r` must be known. If `total` is passed in, the `total` number of sample is considered to be `total`. Otherwise, `RandomSample` uses `r.length`.
`randomShuffle`	Shuffles elements of `r` using `gen` as a shuffler. `r` must be a random-access range with length. If no RNG is specified, `rndGen` will be used.
`rndGen`	Global random number generator used by various functions in this module whenever no generator is specified. It is allocated per-thread and initialized to an unpredictable value for each thread.
`uniform`	Returns a uniformly selected member of enum `E`. If no random number generator is passed, uses the default `rndGen`.
`uniform`	Generates a uniformly-distributed number in the range `[T.min, T.max]` for any integral or character type `T`. If no random number generator is passed, uses the default `rndGen`.
`uniform`	Generates `a` number between `a` and `b`. The `boundaries` parameter controls the shape of the interval (open vs. closed on either side). Valid values for `boundaries` are `"[]"`, `"(]"`, `"[)"`, and `"()"`. The default interval is closed to the left and open to the right. The version that does not take `urng` uses the default generator `rndGen`.
`uniform`	Generates a uniformly-distributed number in the range `[T.min, T.max]` for any integral or character type `T`. If no random number generator is passed, uses the default `rndGen`.
`uniform01`	Generates a uniformly-distributed floating point number of type `T` in the range [0, 1). If no random number generator is specified, the default RNG `rndGen` will be used as the source of randomness.
`uniformDistribution`	Generates a `uniform` probability distribution of size `n`, i.e., an array of size `n` of positive numbers of type `F` that sum to `1`. If `useThis` is provided, it is used as storage.
`unpredictableSeed`	A "good" seed for initializing random number engines. Initializing with `unpredictableSeed` makes engines generate different random number sequences every run.

Structs

Name	Description
`LinearCongruentialEngine`	Linear Congruential generator.
`MersenneTwisterEngine`	The Mersenne Twister generator.
`RandomCover`	Covers a given range `r` in a random manner, i.e. goes through each element of `r` once and only once, just in a random order. `r` must be a random-access range with length.
`RandomSample`	Selects a random subsample out of `r`, containing exactly `n` elements. The order of elements is the same as in the original range. The total `length` of `r` must be known. If `total` is passed in, the total number of sample is considered to be `total`. Otherwise, `RandomSample` uses `r.length`.
`XorshiftEngine`	`Xorshift` generator using 32bit algorithm.

Enum values

Name	Type	Description
`isSeedable`		Test if Rng is seedable. The overload taking a SeedType also makes sure that the Rng can be seeded with SeedType.
`isUniformRNG`		Test if Rng is a random-number generator. The overload taking a ElementType also makes sure that the Rng generates values of that type.

Aliases

Name	Type	Description
`MinstdRand`	`LinearCongruentialEngine!(uint,48271,0,2147483647)`	Define `LinearCongruentialEngine` generators with well-chosen parameters. `MinstdRand0` implements Park and Miller's "minimal standard" generator that uses 16807 for the multiplier. `MinstdRand` implements a variant that has slightly better spectral behavior by using the multiplier 48271. Both generators are rather simplistic.
`MinstdRand0`	`LinearCongruentialEngine!(uint,16807,0,2147483647)`	Define `LinearCongruentialEngine` generators with well-chosen parameters. `MinstdRand0` implements Park and Miller's "minimal standard" generator that uses 16807 for the multiplier. `MinstdRand` implements a variant that has slightly better spectral behavior by using the multiplier 48271. Both generators are rather simplistic.
`Mt19937`	`MersenneTwisterEngine!(uint,32L,624L,397L,31L,2567483615,11L,7L,2636928640,15L,4022730752,18L)`	A `MersenneTwisterEngine` instantiated with the parameters of the original engine MT19937, generating uniformly-distributed 32-bit numbers with a period of 2 to the power of 19937. Recommended for random number generation unless memory is severely restricted, in which case a `LinearCongruentialEngine` would be the generator of choice.
`Random`	`MersenneTwisterEngine!(uint,32L,624L,397L,31L,2567483615,11L,7L,2636928640,15L,4022730752,18L)`	The "default", "favorite", "suggested" random number generator type on the current platform. It is an alias for one of the previously-defined generators. You may want to use it if (1) you need to generate some nice random numbers, and (2) you don't care for the minutiae of the method being used.
`Xorshift`	`XorshiftEngine!(uint,128,11,8,19)`	Define `XorshiftEngine` generators with well-chosen parameters. See each bits examples of "`Xorshift` RNGs". `Xorshift` is a `Xorshift128`'s alias because 128bits implementation is mostly used.
`Xorshift128`	`XorshiftEngine!(uint,128,11,8,19)`	Define `XorshiftEngine` generators with well-chosen parameters. See each bits examples of "`Xorshift` RNGs". `Xorshift` is a `Xorshift128`'s alias because 128bits implementation is mostly used.
`Xorshift160`	`XorshiftEngine!(uint,160,2,1,4)`	Define `XorshiftEngine` generators with well-chosen parameters. See each bits examples of "`Xorshift` RNGs". `Xorshift` is a `Xorshift128`'s alias because 128bits implementation is mostly used.
`Xorshift192`	`XorshiftEngine!(uint,192,2,1,4)`	Define `XorshiftEngine` generators with well-chosen parameters. See each bits examples of "`Xorshift` RNGs". `Xorshift` is a `Xorshift128`'s alias because 128bits implementation is mostly used.
`Xorshift32`	`XorshiftEngine!(uint,32,13,17,15)`	Define `XorshiftEngine` generators with well-chosen parameters. See each bits examples of "`Xorshift` RNGs". `Xorshift` is a `Xorshift128`'s alias because 128bits implementation is mostly used.
`Xorshift64`	`XorshiftEngine!(uint,64,10,13,10)`	Define `XorshiftEngine` generators with well-chosen parameters. See each bits examples of "`Xorshift` RNGs". `Xorshift` is a `Xorshift128`'s alias because 128bits implementation is mostly used.
`Xorshift96`	`XorshiftEngine!(uint,96,10,5,26)`	Define `XorshiftEngine` generators with well-chosen parameters. See each bits examples of "`Xorshift` RNGs". `Xorshift` is a `Xorshift128`'s alias because 128bits implementation is mostly used.

Authors

Andrei Alexandrescu Masahiro Nakagawa (Xorshift random generator) Joseph Rushton Wakeling (Algorithm D for random sampling)

License

Boost License 1.0.