std.random

Средства для генерации случайных чисел.

Источник

std/random.d

Лицензия:

Лицензия Boost 1.0.

Авторы:

Андрей Александреску Масахиро Накагава (генератор случайных чисел Xorshift) Джозеф Раштон Уэклинг (алгоритм D для случайной выборки) Илья Ярошенко (реализация Мерсенна-Твистера, адаптированная из mir-random)

Благодарности

Вся архитектура библиотеки генерации случайных чисел взята из отличной C++0X библиотеки генерации случайных чисел, предложенной Йенсом Мауэром и дополненной исследователями из Ферми-лаборатории (исключая Xorshift).

enum bool isUniformRNG(Rng, ElementType);

enum bool isUniformRNG(Rng);

Проверка, является ли Rng генератором случайных чисел. Перегрузка, принимающая ElementType, также проверяет, что Rng генерирует значения указанного типа.

Генератор случайных чисел должен иметь, по крайней мере, следующие особенности:

• он является InputRange
• он имеет поле 'bool isUniformRandom', доступное в CTFE

Примеры:

struct NoRng
{
    @property uint front() {return 0;}
    @property bool empty() {return false;}
    void popFront() {}
}
static assert(!isUniformRNG!(NoRng));

struct validRng
{
    @property uint front() {return 0;}
    @property bool empty() {return false;}
    void popFront() {}

    enum isUniformRandom = true;
}
static assert(isUniformRNG!(validRng, uint));
static assert(isUniformRNG!(validRng));

enum bool isSeedable(Rng, SeedType);

enum bool isSeedable(Rng);

Проверка, может ли Rng быть запущен с инициализирующим значением. Перегрузка, принимающая SeedType, также проверяет, можно ли инициализировать Rng значением SeedType.

Инициализируемый генератор случайных чисел имеет следующие дополнительные особенности:

• он имеет функцию 'seed(ElementType)'

Примеры:

struct validRng
{
    @property uint front() {return 0;}
    @property bool empty() {return false;}
    void popFront() {}

    enum isUniformRandom = true;
}
static assert(!isSeedable!(validRng, uint));
static assert(!isSeedable!(validRng));

struct seedRng
{
    @property uint front() {return 0;}
    @property bool empty() {return false;}
    void popFront() {}
    void seed(uint val){}
    enum isUniformRandom = true;
}
static assert(isSeedable!(seedRng, uint));
static assert(!isSeedable!(seedRng, ulong));
static assert(isSeedable!(seedRng));

struct LinearCongruentialEngine(UIntType, UIntType a, UIntType c, UIntType m) if (isUnsigned!UIntType);

Линейный конгруэнтный генератор.

Примеры:

Объявите свой собственный линейный конгруэнтный генератор

alias CPP11LCG = LinearCongruentialEngine!(uint, 48271, 0, 2_147_483_647);

// seed with a constant
auto rnd = CPP11LCG(42);
auto n = rnd.front; // same for each run
writeln(n); // 2027382

Примеры:

Объявите свой собственный линейный конгруэнтный генератор

// glibc's LCG
alias GLibcLCG = LinearCongruentialEngine!(uint, 1103515245, 12345, 2_147_483_648);

// Seed with an unpredictable value
auto rnd = GLibcLCG(unpredictableSeed);
auto n = rnd.front; // different across runs

enum bool isUniformRandom;

Отмечает это как Rng

enum bool hasFixedRange;

Имеет ли этот генератор фиксированный диапазон? (true).

enum UIntType min;

Наименьшее сгенерированное значение (1 если c == 0, 0 в противном случае).

enum UIntType max;

Наибольшее сгенерированное значение (modulus - 1).

enum UIntType multiplier;

enum UIntType increment;

enum UIntType modulus;

Параметры этого распределения. Случайное число вычисляется по формуле x = (x * multipler + increment) % modulus.

pure nothrow @nogc @safe this(UIntType x0);

Создает генератор LinearCongruentialEngine с инициализирующим значением x0.

pure nothrow @nogc @safe void seed(UIntType x0 = 1);

(Повторная) инициализация генератора.

pure nothrow @nogc @safe void popFront();

Перемещает последовательность случайных чисел.

const pure nothrow @nogc @property @safe UIntType front();

Возвращает текущее число в последовательности случайных чисел.

const pure nothrow @nogc @property @safe typeof(this) save();

enum bool empty;

Всегда false (генераторы случайных чисел — это бесконечные диапазоны).

alias MinstdRand0 = LinearCongruentialEngine!(uint, 16807u, 0u, 2147483647u).LinearCongruentialEngine;

alias MinstdRand = LinearCongruentialEngine!(uint, 48271u, 0u, 2147483647u).LinearCongruentialEngine;

Определяет генераторы LinearCongruentialEngine с хорошо подобранными параметрами. MinstdRand0 реализует генератор Park и Миллера "минимальный стандарт" генератор, использующий 16807 в качестве множителя. MinstdRand реализует вариант с немного лучшим спектральным поведением, используя множитель 48271. Оба генератора довольно простые.

Примеры:

// seed with a constant
auto rnd0 = MinstdRand0(1);
auto n = rnd0.front;
 // same for each run
writeln(n); // 16807

// Seed with an unpredictable value
rnd0.seed(unpredictableSeed);
n = rnd0.front; // different across runs

struct MersenneTwisterEngine(UIntType, size_t w, size_t n, size_t m, size_t r, UIntType a, size_t u, UIntType d, size_t s, UIntType b, size_t t, UIntType c, size_t l, UIntType f) if (isUnsigned!UIntType);

Генератор Mersenne Twister.

Примеры:

// seed with a constant
Mt19937 gen;
auto n = gen.front; // same for each run
writeln(n); // 3499211612

// Seed with an unpredictable value
gen.seed(unpredictableSeed);
n = gen.front; // different across runs

enum bool isUniformRandom;

Отмечает это как Rng

enum size_t wordSize;

enum size_t stateSize;

enum size_t shiftSize;

enum size_t maskBits;

enum UIntType xorMask;

enum size_t temperingU;

enum UIntType temperingD;

enum size_t temperingS;

enum UIntType temperingB;

enum size_t temperingT;

enum UIntType temperingC;

enum size_t temperingL;

enum UIntType initializationMultiplier;

Параметры генератора.

enum UIntType min;

Наименьшее сгенерированное значение (0).

enum UIntType max;

Наибольшее сгенерированное значение.

enum UIntType defaultSeed;

Значение инициализирующего значения по умолчанию.

pure nothrow @nogc @safe this(UIntType value);

Создает объект MersenneTwisterEngine.

pure nothrow @nogc @safe void seed()(UIntType value = defaultSeed);

Инициализирует объект MersenneTwisterEngine.

Примечание

Эта функция инициализации предоставляет 2^w начальных точек (будут использованы младшие w биты предоставленного значения). Для возможности запуска RNG в любом из его внутренних состояний используйте перегрузку seed, принимающую InputRange.

void seed(T)(T range)
Constraints: if (isInputRange!T && is(immutable(ElementType!T) == immutable(UIntType)));

Инициализирует объект MersenneTwisterEngine с использованием InputRange.

Исключения:

Exception если InputRange не предоставила достаточно элементов для инициализации генератора. Требуемое количество элементов соответствует параметру 'n' шаблона структуры MersenneTwisterEngine.

pure nothrow @nogc @safe void popFront();

Перемещает генератор.

const pure nothrow @nogc @property @safe UIntType front();

Возвращает текущее случайное значение.

const pure nothrow @nogc @property @safe typeof(this) save();

enum bool empty;

Всегда false.

alias Mt19937 = MersenneTwisterEngine!(uint, 32LU, 624LU, 397LU, 31LU, 2567483615u, 11LU, 4294967295u, 7LU, 2636928640u, 15LU, 4022730752u, 18LU, 1812433253u).MersenneTwisterEngine;

MersenneTwisterEngine, реализованный с параметрами исходного генератора MT19937, генерирующий равномерно распределённые 32-битные числа с периодом 2 в степени 19937. Рекомендуется для генерации случайных чисел, если память не сильно ограничена, в противном случае LinearCongruentialEngine будет лучшим выбором.

Примеры:

// seed with a constant
Mt19937 gen;
auto n = gen.front; // same for each run
writeln(n); // 3499211612

// Seed with an unpredictable value
gen.seed(unpredictableSeed);
n = gen.front; // different across runs

alias Mt19937_64 = MersenneTwisterEngine!(ulong, 64LU, 312LU, 156LU, 31LU, 13043109905998158313LU, 29LU, 6148914691236517205LU, 17LU, 8202884508482404352LU, 37LU, 18444473444759240704LU, 43LU, 6364136223846793005LU).MersenneTwisterEngine;

MersenneTwisterEngine, реализованный с параметрами исходного генератора MT19937-64, генерирующий равномерно распределённые 64-битные числа с периодом 2 в степени 19937.

Примеры:

// Seed with a constant
auto gen = Mt19937_64(12345);
auto n = gen.front; // same for each run
writeln(n); // 6597103971274460346

// Seed with an unpredictable value
gen.seed(unpredictableSeed!ulong);
n = gen.front; // different across runs

struct XorshiftEngine(UIntType, uint nbits, int sa, int sb, int sc) if (isUnsigned!UIntType && !(sa > 0 && (sb > 0) && (sc > 0)));

template XorshiftEngine(UIntType, int bits, int a, int b, int c) if (isUnsigned!UIntType && (a > 0) && (b > 0) && (c > 0))

Генератор Xorshift. Реализован в соответствии с Xorshift RNGs (Marsaglia, 2003), когда размер мал. Для больших размеров генератор использует оптимизацию Себастиано Вигна, используя индекс, чтобы избежать необходимости вращения внутреннего массива.

Период равен 2 ^^ nbits - 1, за исключением устаревшей 192-битной версии uint (см. примечание ниже).

Параметры:

UIntType	Размер слова этого генератора Xorshift и тип возвращаемого значения opCall.
nbits	Количество бит состояния этого генератора. Оно должно быть положительным кратным размеру в битах типа UIntType. Если nbits велико, этот структуре может занимать немного больше памяти, чем это необходимо, поэтому он может использовать круговой счётчик вместо сдвига всего массива.
sa	Направление и величина первого сдвига. Положительное значение означает влево, отрицательное — вправо.
sb	Направление и величина второго сдвига. Положительное значение означает влево, отрицательное — вправо.
sc	Направление и величина третьего сдвига. Положительное значение означает влево, отрицательное — вправо.

Примечание

Для обеспечения обратной совместимости, когда nbits == 192 и UIntType равно uint, используется устаревший гибридный PRNG, состоящий из 160-битного xorshift, комбинированного с 32-битным счётчиком. Этот комбинированный генератор имеет период, равный наименьшему общему кратному 2^^160 - 1 и 2^^32.

Предыдущие версии XorshiftEngine не предоставляли механизма для указания направлений сдвигов, принимая каждый сдвиг как абсолютное значение. Для обеспечения обратной совместимости, поскольку три сдвига в одном направлении не могут привести к XorshiftEngine с полным периодом, когда все три sa, sb, sc, are positive XorshiftEngine рассматривает их как абсолютные величины и использует направления сдвигов, чтобы соответствовать старому поведению XorshiftEngine. Не каждый набор сдвигов приводит к генератору Xorshift с полным периодом. Шаблон в настоящее время не выполняет проверку на максимальный период во время компиляции, но в будущей версии может отклонять параметры, приводящие к более коротким периодам.

Примеры:

alias Xorshift96  = XorshiftEngine!(uint, 96,  10, 5,  26);
auto rnd = Xorshift96(42);
auto num = rnd.front;  // same for each run
writeln(num); // 2704588748

enum bool isUniformRandom;

Отметить это как Rng

enum auto empty;

Всегда false (генераторы случайных чисел имеют бесконечные диапазоны).

enum UIntType min;

Наименьшее сгенерированное значение.

enum UIntType max;

Наибольшее сгенерированное значение.

pure nothrow @nogc @safe this()(UIntType x0);

Создает генератор XorshiftEngine с начальным значением x0.

Параметры:

UIntType x0

значение, используемое для детерминированного инициализации внутреннего состояния

pure nothrow @nogc @safe void seed()(UIntType x0);

(Повторно) инициализирует генератор.

Параметры:

UIntType x0

значение, используемое для детерминированного инициализации внутреннего состояния

const pure nothrow @nogc @property @safe UIntType front();

Возвращает текущее число в последовательности случайных чисел.

pure nothrow @nogc @safe void popFront();

Перемещает последовательность случайных чисел вперёд.

const pure nothrow @nogc @property @safe typeof(this) save();

Захватывает состояние последовательности.

alias Xorshift32 = XorshiftEngine!(uint, 32u, 13, -17, 15).XorshiftEngine;

alias Xorshift64 = XorshiftEngine!(uint, 64u, 10, -13, -10).XorshiftEngine;

alias Xorshift96 = XorshiftEngine!(uint, 96u, 10, -5, -26).XorshiftEngine;

alias Xorshift128 = XorshiftEngine!(uint, 128u, 11, -8, -19).XorshiftEngine;

alias Xorshift160 = XorshiftEngine!(uint, 160u, 2, -1, -4).XorshiftEngine;

alias Xorshift192 = XorshiftEngine!(uint, 192u, -2, 1, 4).XorshiftEngine;

alias Xorshift = XorshiftEngine!(uint, 128u, 11, -8, -19).XorshiftEngine;

Определяет генераторы XorshiftEngine с хорошо подобранными параметрами. См. примеры в "Xorshift RNGs" для каждого количества бит. Xorshift — это псевдоним для Xorshift128, так как реализация с 128 битами используется чаще всего.

Примеры:

// Seed with a constant
auto rnd = Xorshift(1);
auto num = rnd.front;  // same for each run
writeln(num); // 1405313047

// Seed with an unpredictable value
rnd.seed(unpredictableSeed);
num = rnd.front; // different across rnd

nothrow @nogc @property @trusted uint unpredictableSeed();

template unpredictableSeed(UIntType) if (isUnsigned!UIntType)

«Хорошее» начальное значение для инициализации генераторов случайных чисел. Инициализация с unpredictableSeed обеспечивает, что генераторы генерируют разные последовательности случайных чисел при каждом запуске.

Возвращает:

Значение начального значения, являющееся целым положительным числом, которое отличается при каждом последующем вызове.

Примечание

В общем случае периодическая повторная инициализация PRNG не улучшает его качество и в некоторых случаях может навредить ему. Например, у Mersenne Twister есть 2 ^^ 19937 - 1 различных состояний, но после вызова seed(uint) он может быть только в одном из 2 ^^ 32 различных состояний, независимо от того, насколько хорошим является источник энтропии.

Примеры:

auto rnd = Random(unpredictableSeed);
auto n = rnd.front;
static assert(is(typeof(n) == uint));

alias Random = MersenneTwisterEngine!(uint, 32LU, 624LU, 397LU, 31LU, 2567483615u, 11LU, 4294967295u, 7LU, 2636928640u, 15LU, 4022730752u, 18LU, 1812433253u).MersenneTwisterEngine;

«По умолчанию», «предпочтительный», «рекомендуемый» генератор случайных чисел на текущей платформе. Это псевдоним одного из ранее определённых генераторов. Вы можете использовать его, если (1) вам нужны случайные числа, и (2) вас не интересуют подробности используемого метода.

nothrow @nogc @property ref @safe Random rndGen();

Глобальный генератор случайных чисел, используемый различными функциями в этом модуле, когда не указан генератор. Он выделяется на поток и инициализируется случайным значением для каждого потока.

Возвращает:

Экземпляр единственного генератора случайных чисел по умолчанию

Примеры:

import std.algorithm.iteration : sum;
import std.range : take;
auto rnd = rndGen;
assert(rnd.take(3).sum > 0);

auto uniform(string boundaries = "[)", T1, T2)(T1 a, T2 b)
Constraints: if (!is(CommonType!(T1, T2) == void));

auto uniform(string boundaries = "[)", T1, T2, UniformRandomNumberGenerator)(T1 a, T2 b, ref UniformRandomNumberGenerator urng)
Constraints: if (isFloatingPoint!(CommonType!(T1, T2)) && isUniformRNG!UniformRandomNumberGenerator);

Генерирует число между a и b. Параметр boundaries управляет формой интервала (открытый или закрытый с обеих сторон). Допустимые значения для boundaries — "[]", "(]", "[)", и "()". По умолчанию интервал — закрыт слева и открыт справа. Версия, не принимающая urng, использует генератор по умолчанию rndGen.

Параметры:

T1 a	нижняя граница равномерного распределения
T2 b	верхняя граница равномерного распределения
UniformRandomNumberGenerator urng	(необязательно) генератор случайных чисел для использования; если не указан, по умолчанию используется rndGen

Возвращает:

Одно случайное значение, взятое из равномерного распределения между a и b, тип которого совпадает с общим типом этих параметров

Примеры:

auto rnd = Random(unpredictableSeed);

// Generate an integer in [0, 1023]
auto a = uniform(0, 1024, rnd);
assert(0 <= a && a < 1024);

// Generate a float in [0, 1)
auto b = uniform(0.0f, 1.0f, rnd);
assert(0 <= b && b < 1);

// Generate a float in [0, 1]
b = uniform!"[]"(0.0f, 1.0f, rnd);
assert(0 <= b && b <= 1);

// Generate a float in (0, 1)
b = uniform!"()"(0.0f, 1.0f, rnd);
assert(0 < b && b < 1);

Примеры:

Создайте массив случайных чисел, используя функции диапазона и UFCS

import std.array : array;
import std.range : generate, takeExactly;

int[] arr = generate!(() => uniform(0, 100)).takeExactly(10).array;
writeln(arr.length); // 10
assert(arr[0] >= 0 && arr[0] < 100);

auto uniform(T, UniformRandomNumberGenerator)(ref UniformRandomNumberGenerator urng)
Constraints: if (!is(T == enum) && (isIntegral!T || isSomeChar!T) && isUniformRNG!UniformRandomNumberGenerator);

auto uniform(T)()
Constraints: if (!is(T == enum) && (isIntegral!T || isSomeChar!T));

auto uniform(E, UniformRandomNumberGenerator)(ref UniformRandomNumberGenerator urng)
Constraints: if (is(E == enum) && isUniformRNG!UniformRandomNumberGenerator);

auto uniform(E)()
Constraints: if (is(E == enum));

Генерирует равномерно распределённое число в диапазоне [T.min, T.max] для любого целочисленного или символьного типа T. Если генератор случайных чисел не указан, используется генератор по умолчанию rndGen.

Если в качестве типа используется enum, случайное значение выбирается с равной вероятностью из возможных значений перечисления E.

Параметры:

UniformRandomNumberGenerator urng

(необязательно) генератор случайных чисел для использования; если не указан, по умолчанию используется rndGen

Возвращает:

Случайное значение, взятое из равномерного распределения по всем возможным значениям целочисленного, символьного или перечислительного типа T.

Примеры:

auto rnd = MinstdRand0(42);

writeln(rnd.uniform!ubyte); // 102
writeln(rnd.uniform!ulong); // 4838462006927449017

enum Fruit { apple, mango, pear }
version (X86_64) // https://issues.dlang.org/show_bug.cgi?id=15147
writeln(rnd.uniform!Fruit); // Fruit.mango

T uniform01(T = double)()
Constraints: if (isFloatingPoint!T);

T uniform01(T = double, UniformRNG)(ref UniformRNG rng)
Constraints: if (isFloatingPoint!T && isUniformRNG!UniformRNG);

Генерирует равномерно распределённое число с плавающей точкой типа T в диапазоне [0, 1). Если генератор случайных чисел не указан, будет использован по умолчанию генератор rndGen.

uniform01 обеспечивает более быструю генерацию случайных величин, чем эквивалентный uniform!"[)"(0.0, 1.0), и поэтому может быть предпочтительным для некоторых применений.

Параметры:

UniformRNG rng

(необязательно) генератор случайных чисел для использования; если не указан, используется по умолчанию rndGen

Возвращает:

Случайная величина с плавающей точкой типа T, взятая из равномерного распределения на полуоткрытом интервале [0, 1).

Примеры:

import std.math : feqrel;

auto rnd = MinstdRand0(42);

// Generate random numbers in the range in the range [0, 1)
auto u1 = uniform01(rnd);
assert(u1 >= 0 && u1 < 1);

auto u2 = rnd.uniform01!float;
assert(u2 >= 0 && u2 < 1);

// Confirm that the random values with the initial seed 42 are 0.000328707 and 0.524587
assert(u1.feqrel(0.000328707) > 20);
assert(u2.feqrel(0.524587) > 20);

F[] uniformDistribution(F = double)(size_t n, F[] useThis = null)
Ограничения: если (isFloatingPoint!F);

Генерирует равномерное вероятностное распределение размера n, т.е. массив размера n положительных чисел типа F, сумма которых равна 1. Если useThis предоставлен, он используется в качестве места хранения.

Примеры:

import std.algorithm.iteration : reduce;
import std.math : approxEqual;

auto a = uniformDistribution(5);
writeln(a.length); // 5
assert(approxEqual(reduce!"a + b"(a), 1));

a = uniformDistribution(10, a);
writeln(a.length); // 10
assert(approxEqual(reduce!"a + b"(a), 1));

ref auto choice(Range, RandomGen = Random)(auto ref Range range, ref RandomGen urng)
Ограничения: если (isRandomAccessRange!Range && hasLength!Range && isUniformRNG!RandomGen);

ref auto choice(Range)(auto ref Range range);

Возвращает случайный, равномерно выбранный, элемент e из предоставленного Range range. Если генератор случайных чисел не передан, используется по умолчанию rndGen.

Параметры:

Range range	диапазон произвольного доступа, для которого определено свойство length
RandomGen urng	(необязательно) генератор случайных чисел для использования; если не указан, используется по умолчанию rndGen

Возвращает:

Один случайный элемент, выбранный из range. Если возможно, вернёт ссылку на элемент ref в range element, в противном случае вернёт копию.

Примеры:

auto rnd = MinstdRand0(42);

auto elem  = [1, 2, 3, 4, 5].choice(rnd);
version (X86_64) // https://issues.dlang.org/show_bug.cgi?id=15147
writeln(elem); // 3

Range randomShuffle(Range, RandomGen)(Range r, ref RandomGen gen)
Ограничения: если (isRandomAccessRange!Range && isUniformRNG!RandomGen);

Range randomShuffle(Range)(Range r)
Ограничения: если (isRandomAccessRange!Range);

Перемешивает элементы r с помощью gen в качестве перемешивателя. r должен быть диапазоном произвольного доступа с длиной. Если генератор случайных чисел не указан, будет использован rndGen.

Параметры:

Range r	диапазон произвольного доступа, элементы которого должны быть перемешаны
RandomGen gen	(необязательно) генератор случайных чисел для использования; если не указан, используется по умолчанию rndGen

Возвращает:

Перемешанный диапазон произвольного доступа.

Примеры:

auto rnd = MinstdRand0(42);

auto arr = [1, 2, 3, 4, 5].randomShuffle(rnd);
version (X86_64) // https://issues.dlang.org/show_bug.cgi?id=15147
writeln(arr); // [3, 5, 2, 4, 1]

Range partialShuffle(Range, RandomGen)(Range r, in size_t n, ref RandomGen gen)
Ограничения: если (isRandomAccessRange!Range && isUniformRNG!RandomGen);

Range partialShuffle(Range)(Range r, in size_t n)
Ограничения: если (isRandomAccessRange!Range);

Частично перемешивает элементы r таким образом, что при возврате r[0 .. n] является случайным подмножеством r и упорядочен случайным образом. r[n .. r.length] будет содержать элементы, не входящие в r[0 .. n]. Они будут в неопределённом порядке, но не будут случайными в том смысле, что их порядок после того, как partialShuffle вернётся, не будет независимым от их порядка до вызова partialShuffle.

r должен быть диапазоном произвольного доступа с длиной. n должно быть меньше или равно r.length. Если генератор случайных чисел не указан, будет использован rndGen.

Параметры:

Range r	диапазон произвольного доступа, элементы которого должны быть перемешаны
size_t n	количество элементов r для перемешивания (считая с начала); должно быть меньше r.length
RandomGen gen	(необязательно) генератор случайных чисел для использования; если не указан, используется по умолчанию rndGen

Возвращает:

Перемешанный диапазон произвольного доступа.

Примеры:

auto rnd = MinstdRand0(42);

auto arr = [1, 2, 3, 4, 5, 6];
arr = arr.dup.partialShuffle(1, rnd);

version (X86_64) // https://issues.dlang.org/show_bug.cgi?id=15147
assert(arr == [2, 1, 3, 4, 5, 6]); // 1<->2

arr = arr.dup.partialShuffle(2, rnd);
version (X86_64) // https://issues.dlang.org/show_bug.cgi?id=15147
assert(arr == [1, 4, 3, 2, 5, 6]); // 1<->2, 2<->4

arr = arr.dup.partialShuffle(3, rnd);
version (X86_64) // https://issues.dlang.org/show_bug.cgi?id=15147
assert(arr == [5, 4, 6, 2, 1, 3]); // 1<->5, 2<->4, 3<->6

size_t dice(Rng, Num)(ref Rng rnd, Num[] proportions...)
Ограничения: если (isNumeric!Num && isForwardRange!Rng);

size_t dice(R, Range)(ref R rnd, Range proportions)
Ограничения: если (isForwardRange!Range && isNumeric!(ElementType!Range) && !isArray!Range);

size_t dice(Range)(Range proportions)
Ограничения: если (isForwardRange!Range && isNumeric!(ElementType!Range) && !isArray!Range);

size_t dice(Num)(Num[] proportions...)
Ограничения: если (isNumeric!Num);

Бросает кости с относительными вероятностями, хранящимися в proportions. Возвращает индекс в proportions, который был выбран.

Параметры:

Rng rnd	(необязательно) генератор случайных чисел для использования; если не указан, используется по умолчанию rndGen
Num[] proportions	диапазон или список отдельных значений, элементы которых соответствуют вероятностям выбора соответствующего индексного значения

Возвращает:

Случайная величина, взятая из индексных значений [0, ... proportions.length - 1], с вероятностью получения каждого отдельного индексного значения i пропорциональной proportions[i].

Примеры:

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

Примеры:

auto rnd = MinstdRand0(42);
auto z = rnd.dice(70, 20, 10);
writeln(z); // 0
z = rnd.dice(30, 20, 40, 10);
writeln(z); // 2

struct RandomCover(Range, UniformRNG = void) if (isRandomAccessRange!Range && (isUniformRNG!UniformRNG || is(UniformRNG == void)));

auto randomCover(Range, UniformRNG)(Range r, auto ref UniformRNG rng)
Ограничения: если (isRandomAccessRange!Range && isUniformRNG!UniformRNG);

auto randomCover(Range)(Range r)
Ограничения: если (isRandomAccessRange!Range);

Перекрывает заданный диапазон r случайным образом, т.е. проходит через каждый элемент r один раз и только один раз, но в случайном порядке. r должен быть диапазоном произвольного доступа с длиной.

Если генератор случайных чисел не передан в randomCover, будет использован глобальный генератор случайных чисел rndGen.

Параметры:

Range r	диапазон произвольного доступа для обработки
UniformRNG rng	(необязательно) генератор случайных чисел для использования; если не указан, используется по умолчанию rndGen

Возвращает:

Диапазон, элементы которого состоят из элементов r, в случайном порядке. Будет диапазоном с однонаправленным обходом, если оба r и rng являются диапазонами с однонаправленным обходом, в противном случае — диапазоном с однонаправленным обходом.

Примеры:

import std.algorithm.comparison : equal;
import std.range : iota;
auto rnd = MinstdRand0(42);

version (X86_64) // https://issues.dlang.org/show_bug.cgi?id=15147
assert(10.iota.randomCover(rnd).equal([7, 4, 2, 0, 1, 6, 8, 3, 9, 5]));

struct RandomSample(Range, UniformRNG = void) if (isInputRange!Range && (isUniformRNG!UniformRNG || is(UniformRNG == void)));

auto randomSample(Range)(Range r, size_t n, size_t total)
Ограничения: если (isInputRange!Range);

auto randomSample(Range)(Range r, size_t n)
Ограничения: если (isInputRange!Range && hasLength!Range);

auto randomSample(Range, UniformRNG)(Range r, size_t n, size_t total, auto ref UniformRNG rng)
Ограничения: если (isInputRange!Range && isUniformRNG!UniformRNG);

auto randomSample(Range, UniformRNG)(Range r, size_t n, auto ref UniformRNG rng)
Ограничения: если (isInputRange!Range && hasLength!Range && isUniformRNG!UniformRNG);

Выбирает случайную подвыборку из r, содержащую ровно n элементов. Порядок элементов такой же, как и в исходном диапазоне. Общая длина r должна быть известна. Если total передаётся, общее количество выборок считается total. В противном случае, RandomSample использует r.length.

Параметры:

Диапазон r	диапазон для выборки
size_t n	количество элементов для включения в выборку; должно быть меньше или равно общему количеству элементов в r и/или параметре total (если указан)
size_t total	(необязательно) количество элементов r из которых следует выбрать образец (считая с начала); должно быть меньше или равно общему количеству элементов в r. Может быть опущено, если у r есть свойство .length и выборка должна быть взята из всех элементов r.
UniformRNG rng	(необязательно) генератор случайных чисел для использования; если не указано, используется по умолчанию rndGen

Возвращает:

Диапазон, элементы которого состоят из случайно выбранного подмножества элементов r, в том же порядке, что и эти элементы в r. Будет направленным диапазоном, если r и rng являются направленными диапазонами, в противном случае - входным диапазоном. RandomSample реализует алгоритм D Джеффри Скотта Витера (см. Витер 1984, 1987), который выбирает образец размера n за O(n) шагов и требует O(n) случайных величин, независимо от размера данных, которые будут выбором. Исключением из этого является случай, когда обход k элементов входного диапазона сам по себе является операцией O(k) (например, при выборке строк из входного файла), в этом случае вычисление выборки неизбежно будет O(общая). RandomSample бросит исключение, если total заведомо меньше общего количества доступных элементов в входе, или если n > total. Если генератор случайных чисел не передан в randomSample, внутри будет использоваться глобальный генератор случайных чисел rndGen.

Примеры:

import std.algorithm.comparison : equal;
import std.range : iota;
auto rnd = MinstdRand0(42);
assert(10.iota.randomSample(3, rnd).equal([7, 8, 9]));

const @property bool empty();

@property ref auto front();

void popFront();

const @property typeof(this) save();

const @property size_t length();

Примитивы диапазона.

@property size_t index();

Возвращает индекс посещенной записи.