28 Algorithms library [algorithms]

28.6 Mutating sequence operations [alg.modifying.operations]

28.6.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);


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: O(last - first).


  • 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.