6.3 KiB
[alg.random.sample]
26 Algorithms library [algorithms]
26.7 Mutating sequence operations [alg.modifying.operations]
26.7.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);
template<input_iterator I, sentinel_for S, weakly_incrementable O, class Gen> requires (forward_iterator || random_access_iterator) && indirectly_copyable<I, O> && uniform_random_bit_generator<remove_reference_t> O ranges::sample(I first, S last, O out, iter_difference_t n, Gen&& g); template<input_range R, weakly_incrementable O, class Gen> requires (forward_range || random_access_iterator) && indirectly_copyable<iterator_t, O> && uniform_random_bit_generator<remove_reference_t> O ranges::sample(R&& r, O out, range_difference_t n, Gen&& g); `
Mandates: For the overload in namespace std,Distance is an integer type and*first is writable ([iterator.requirements.general]) to out.
Preconditions: out is not in the range [first, last).
For the overload in namespace std:
-
PopulationIterator meets the Cpp17InputIterator requirements ([input.iterators]).
-
SampleIterator meets the Cpp17OutputIterator requirements ([output.iterators]).
-
SampleIterator meets the Cpp17RandomAccessIterator requirements ([random.access.iterators]) unless PopulationIterator models forward_iterator ([iterator.concept.forward]).
-
remove_reference_t meets the requirements of a uniform random bit generator type ([rand.req.urng]).
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 1:
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).
Remarks:
-
For the overload in namespace std, stable if and only if PopulationIterator models forward_iterator. For the first overload in namespace ranges, stable if and only if I models forward_iterator.
-
To the extent that the implementation of this function makes use of random numbers, the object g serves as the implementation's source of randomness.