Function std.random.dice
Get a random index into a list of weights corresponding to each index
{null} dice(Rng, Num)()
if (isNumeric!Num && isForwardRange!Rng);
size_t dice(R, Range)
(
ref R rnd,
Range proportions
)
if (isForwardRange!Range && isNumeric!(ElementType!Range) && !isArray!Range);
size_t dice(Range)
(
Range proportions
)
if (isForwardRange!Range && isNumeric!(ElementType!Range) && !isArray!Range);
{null} dice(Num)()
if (isNumeric!Num);
Similar to rolling a die with relative probabilities stored in proportions
.
Returns the index in proportions
that was chosen.
Note
Usually, dice are 'fair', meaning that each side has equal probability
to come up, in which case 1 + uniform(0, 6)
can simply be used.
In future Phobos versions, this function might get renamed to something like
weightedChoice
to avoid confusion.
Parameters
Name | Description |
---|---|
rnd | (optional) random number generator to use; if not
specified, defaults to rndGen |
proportions | forward range or list of individual values whose elements correspond to the probabilities with which to choose the corresponding index value |
Returns
Random variate drawn from the index values
[0, ... proportions
- 1], with the probability
of getting an individual index value i
being proportional to
proportions[i]
.
Example
auto d6 = 1 + dice(1, 1, 1, 1, 1, 1); // fair dice roll
auto d6b = 1 + dice(2, 1, 1, 1, 1, 1); // double the chance to roll '1'
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 20% of the time,
// and 2 10% of the time
Example
auto rnd = MinstdRand0(42);
auto z = rnd .dice(70, 20, 10);
writeln(z); // 0
z = rnd .dice(30, 20, 40, 10);
writeln(z); // 2
Example
auto rnd = Xorshift(123_456_789);
auto i = dice(rnd, 0.0, 100.0);
writeln(i); // 1
i = dice(rnd, 100.0, 0.0);
writeln(i); // 0
i = dice(100U, 0U);
writeln(i); // 0
Authors
Andrei Alexandrescu Masahiro Nakagawa (Xorshift random generator) Joseph Rushton Wakeling (Algorithm D for random sampling) Ilya Yaroshenko (Mersenne Twister implementation, adapted from mir-random)