std.random
Facilities for random number generation. The old-style functions rand_seed and rand will soon be deprecated as they rely on global state and as such are subjected to various thread-related issues.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 finds the most fit for the target environment.
Example:
Random gen; // Generate a uniformly-distributed integer in the range [0, 15] auto i = uniform!(int)(gen, 0, 15); // Generate a uniformly-distributed real in the range [0, 100) auto r = uniform!(real)(gen, 0.0L, 100.0L);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.
Author:
Andrei Alexandrescu
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.
- Linear Congruential generator.
- Alias for the generated type UIntType.
- Does this generator have a fixed range? (true).
- Lowest generated value.
- Highest generated value.
- The parameters of this distribution. The random number is x =
(x * a + c) % m.
- The parameters of this distribution. The random number is x =
(x * a + c) % m.
- The parameters of this distribution. The random number is x =
(x * a + c) % m.
- Constructs a LinearCongruentialEngine generator.
- (Re)seeds the generator.
- Returns the next number in the random sequence.
- Discards next n samples.
- Compares against rhs for equality.
- Define LinearCongruentialEngine generators with "good"
parameters.
Example:
// seed with a constant auto rnd0 = MinstdRand0(1); auto n = rnd0.next; // same for each run // Seed with an unpredictable value rnd0.seed(unpredictableSeed); n = rnd0.next; // different across runs
- The Mersenne Twister generator.
- Result type (an alias for UIntType).
- Parameter for the generator.
- Parameter for the generator.
- Parameter for the generator.
- Parameter for the generator.
- Parameter for the generator.
- Parameter for the generator.
- Parameter for the generator.
- Parameter for the generator.
- Parameter for the generator.
- Parameter for the generator.
- Parameter for the generator.
- Smallest generated value (0).
- Largest generated value.
- The default seed value.
- Constructs a MersenneTwisterEngine object
- Constructs a MersenneTwisterEngine object
- Returns the next random value.
- Discards next n samples.
- 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.
Example:
// seed with a constant Mt19937 gen; auto n = gen.next; // same for each run // Seed with an unpredictable value gen.seed(unpredictableSeed); n = gen.next; // different across runs
- The "default", "favorite", "suggested" random number generator on the
current platform. It is a typedef 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.
- A "good" seed for initializing random number engines. Initializing
with unpredictableSeed makes engines generate different
random number sequences every run.
Example:
auto rnd = Random(unpredictableSeed); auto n = rnd.next; ...
- ;
Example:
auto a = new double[20]; Random gen; auto rndIndex = UniformDistribution!(uint)(0, a.length); auto rndValue = UniformDistribution!(double)(0, 1); // Get a random index into the array auto i = rndIndex.next(gen); // Get a random probability, i.e., a real number in [0, 1) auto p = rndValue.next(gen); // Assign that value to that array element a[i] = p; auto digits = UniformDistribution!(char, "[]")('0', '9'); auto percentages = UniformDistribution!(double, "(]")(0.0, 100.0); // Get a digit in ['0', '9'] auto digit = digits.next(gen); // Get a number in (0.0, 100.0] auto p = percentages.next(gen);
- Constructs a UniformDistribution able to generate numbers between
a and b. The bounds of the interval are controlled by the
template argument, e.g. UniformDistribution!(double, "[]")(0, 1)
generates numbers in the interval [0.0, 1.0].
- Returns the left bound of the random value generated.
- Returns the the right bound of the random value generated.
- Does nothing (provided for conformity with other distributions).
- Returns a random number using UniformRandomNumberGenerator as
back-end.
- Returns a random number using UniformRandomNumberGenerator as
back-end.
Example:
Random gen(unpredictableSeed); // Generate an integer in [0, 1024) auto a = uniform(gen, 0, 1024); // Generate a float in [0, 1) auto a = uniform(gen, 0.0f, 1.0f);
Example:
auto x = dice(0.5, 0.5); // x is 0 or 1 in equal proportions auto y = dice(50, 50); // y is 0 or 1 in equal proportions auto z = dice(70, 20, 10); // z is 0 70% of the time, 1 30% of the time, // and 2 10% of the time
Note:
This is more random, but slower, than C's rand() function. To use C's rand() instead, import std.c.stdlib.
BUGS:
Shares a global single state, not multithreaded. SCHEDULED FOR DEPRECATION.
BUGS:
Shares a global single state, not multithreaded. SCHEDULED FOR DEPRECATION.