std::sample

Определён в заголовочном файле `<algorithm>`
template< class PopulationIt, class SampleIt, class Distance, class URBG > SampleIterator sample( PopulationIt first, PopulationIt last, SampleIt out, Distance n, URBG&& g );		(начиная с C++17)

Выбирает n элементов из последовательности [first, last) (без возвращения) таким образом, что все возможные выборки имеют одинаковую вероятность появления, и записывает выбранные элементы в выходной итератор out. Случайные числа генерируются с помощью генератора случайных чисел g.

Если n больше количества элементов в последовательности, выбираются все элементы последовательности.

Алгоритм является стабильным (сохраняет относительный порядок выбранных элементов) только если PopulationIt удовлетворяет требованиям LegacyForwardIterator.

Если тип значения first(до C++20)*first(начиная с C++20) нельзя записать в out, программа некорректна.

Если выполняется любое из следующих условий, поведение не определено:

out находится в [first, last).
PopulationIt не удовлетворяет требованиям LegacyInputIterator.
SampleIt не удовлетворяет требованиям LegacyOutputIterator.
Выполняются все следующие условия:

`PopulationIt` не удовлетворяет требованиям LegacyForwardIterator.	(до C++23)
`PopulationIt` не моделирует `forward_iterator`.	(начиная с C++23)

SampleIt не удовлетворяет требованиям LegacyRandomAccessIterator.
Для типа T, являющегося std::remove_reference_t<URBG>, выполняется любое из следующих условий:

T не удовлетворяет требованиям UniformRandomBitGenerator.

Тип возвращаемого значения T нельзя преобразовать в Distance.

(до C++20)

Параметры

first, last	-	пара итераторов, задающих диапазон элементов, из которого выполняется выборка (генеральную совокупность)
out	-	выходной итератор, в который записываются выбранные элементы
n	-	количество элементов для выборки
g	-	генератор случайных чисел, используемый в качестве источника случайности
Требования к типам
-`Distance` должен быть целочисленным типом.

Возвращаемое значение

Возвращает копию out, указывающую на элемент после последнего выведенного элемента выборки, то есть на конец диапазона выборки.

Сложность

Линейная относительно std::distance(first, last).

Возможная реализация

См. реализации в libstdc++, libc++ и MSVC STL.

Примечания

Эта функция может реализовывать выборку с отбором или резервуарную выборку.

Макрос проверки поддержки функции	Значение	Стандарт	Функция
`__cpp_lib_sample`	`201603L`	(C++17)	`std::sample`

Пример

#include <algorithm>
#include <iostream>
#include <iterator>
#include <random>
#include <string>

int main()
{
    std::string in {"ABCDEFGHIJK"}, out;
    std::sample(in.begin(), in.end(), std::back_inserter(out), 4,
                std::mt19937 {std::random_device{}()});
    std::cout << "Four random letters out of " << in << " : " << out << '\n';
}

Возможный вывод:

Four random letters out of ABCDEFGHIJK: EFGK

См. также

random_shuffleshuffle (до C++17)(C++11)	случайным образом переставляет элементы в диапазоне (шаблон функции и объект-функция алгоритма)
ranges::shuffle (C++20)
ranges::sample (C++20)	выбирает N случайных элементов из последовательности (объект-функция алгоритма)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/algorithm/sample