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.

std.random.random_cover - multiple declarations

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

If no random number generator is passed to randomCover, the thread-global RNG rndGen will be used internally.

Prototypes

auto randomCover(Range, UniformRNG)(
  Range r,
  UniformRNG rng
)
if (isRandomAccessRange!Range && isUniformRNG!UniformRNG);

auto randomCover(Range)(
  Range r
)
if (isRandomAccessRange!Range);

Parameters

NameDescription
r random-access range to cover
rng (optional) random number generator to use; if not specified, defaults to rndGen

Returns

Range whose elements consist of the elements of r, in random order. Will be a forward range if both r and rng are forward ranges, an input range otherwise.

Example

int[] a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ];
foreach (e; randomCover(a))
{
    writeln(e);
}

WARNING: If an alternative RNG is desired, it is essential for this to be a new RNG seeded in an unpredictable manner. Passing it a RNG used elsewhere in the program will result in unintended correlations, due to the current implementation of RNGs as value types.

Example

int[] a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ];
foreach (e; randomCover(a, Random(unpredictableSeed)))  // correct!
{
    writeln(e);
}

foreach (e; randomCover(a, rndGen))  // DANGEROUS!! rndGen gets copied by value
{
    writeln(e);
}

foreach (e; randomCover(a, rndGen))  // ... so this second random cover
{                                    // will output the same sequence as
    writeln(e);                      // the previous one.
}

These issues will be resolved in a second-generation std.random that re-implements random number generators as reference types.

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

If no random number generator is passed to randomCover, the thread-global RNG rndGen will be used internally.

Parameters

NameDescription
r random-access range to cover
rng (optional) random number generator to use; if not specified, defaults to rndGen

Returns

Range whose elements consist of the elements of r, in random order. Will be a forward range if both r and rng are forward ranges, an input range otherwise.

Example

int[] a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ];
foreach (e; randomCover(a))
{
    writeln(e);
}

WARNING: If an alternative RNG is desired, it is essential for this to be a new RNG seeded in an unpredictable manner. Passing it a RNG used elsewhere in the program will result in unintended correlations, due to the current implementation of RNGs as value types.

Example

int[] a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ];
foreach (e; randomCover(a, Random(unpredictableSeed)))  // correct!
{
    writeln(e);
}

foreach (e; randomCover(a, rndGen))  // DANGEROUS!! rndGen gets copied by value
{
    writeln(e);
}

foreach (e; randomCover(a, rndGen))  // ... so this second random cover
{                                    // will output the same sequence as
    writeln(e);                      // the previous one.
}

These issues will be resolved in a second-generation std.random that re-implements random number generators as reference types.

Authors

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

License

Boost License 1.0.

Comments