std::sample

Определено в заголовке <algorithm>

Определено в заголовке `<algorithm>`
template< class PopulationIterator, class SampleIterator, class Distance, class URBG > SampleIterator sample( PopulationIterator first, PopulationIterator last, SampleIterator out, Distance n, URBG&& g );		(с C++17)

template< class PopulationIterator, class SampleIterator,
          class Distance, class URBG >
SampleIterator sample( PopulationIterator first, PopulationIterator last,
                       SampleIterator out, Distance n,
                       URBG&& g );

(с C++17)

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

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

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

Поведение неопределено, если out находится в [first, last).

Параметры

first, last	-	пара итераторов, образующих диапазон, из которого нужно сделать выборку (генеральная совокупность)
out	-	выходной итератор, в который записываются выборки
n	-	количество выборок
g	-	генератор случайных чисел, используемый в качестве источника случайности
Требования к типу
-`PopulationIterator` должен удовлетворять требованиям LegacyInputIterator.
-`SampleIterator` должен удовлетворять требованиям LegacyOutputIterator.
-`SampleIterator` также должен удовлетворять требованиям LegacyRandomAccessIterator, если `PopulationIterator` не удовлетворяет LegacyForwardIterator
- Тип значения `PopulationIterator` должен быть записываемым в `out`
- `Distance` должен быть целым типом
- `std::remove_reference_t<URBG>` должен удовлетворять требованиям UniformRandomBitGenerator, а его возвращаемый тип должен быть приводим к `Distance`

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

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

Сложность

Линейная по std::distance(first, last).

Примечания

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

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

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

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

Пример

#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::sample (C++20)	выбор N случайных элементов из последовательности (функциональность)

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