25 Algorithms library [algorithms]

25.4 Mutating sequence operations [alg.modifying.operations]

25.4.12 Sample [alg.random.sample]

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

Requires:

Effects: Copies min(last - first, n) elements (the sample) from [first, last) (the population) to out such that each possible sample has equal probability of appearance. [ Note: Algorithms that obtain such effects include selection sampling and reservoir sampling.  — end note ]

Returns: The end of the resulting sample range.

Complexity: Ο(last - first).

Remarks:

  • Stable if and only if PopulationIterator satisfies the requirements of a forward iterator.

  • To the extent that the implementation of this function makes use of random numbers, the object g shall serve as the implementation's source of randomness.