std::experimental::sample - cppreference.com (original) (raw)

Defined in header <experimental/algorithm>
template< class PopulationIterator, class SampleIterator, class Distance, class URBG >SampleIterator sample( PopulationIterator first, PopulationIterator last, SampleIterator out, Distance n, URBG&& g );	(1)	(library fundamentals TS)
template< class PopulationIterator, class SampleIterator, class Distance > SampleIterator sample( PopulationIterator first, PopulationIterator last, SampleIterator out, Distance n );	(2)	(library fundamentals TS v2)

Selects n elements from the sequence [first, last) such that each possible sample has equal probability of appearance, and writes those selected elements into the output iterator out.

If n is greater than the number of elements in the sequence, selects last - first elements.

The algorithm is stable only if PopulationIterator meets the requirements of LegacyForwardIterator.

Random numbers are generated using the random number generator g.

[edit] Parameters

first, last	-	pair of iterators forming the range from which to make the sampling (the population)
out	-	the output iterator where the samples are written. Must not be in the range [first, last)
n	-	number of samples to make
g	-	the random number generator used as the source of randomness
-PopulationIterator must meet the requirements of LegacyInputIterator.
-SampleIterator must meet the requirements of LegacyOutputIterator.
-SampleIterator must also meet the requirements of LegacyRandomAccessIterator if PopulationIterator doesn't meet LegacyForwardIterator.
-PopulationIterator's value type must be writeable to out.
-Distance must be an integer type.
-URBG must meet the requirements of UniformRandomBitGenerator and its return type must be convertible to Distance.

[edit] Return value

Returns a copy of out after the last sample that was output, that is, end of the sample range.

[edit] Complexity

Linear in std::distance(first, last).

[edit] Notes

This function may implement selection sampling or reservoir sampling.

[edit] Example

#include <experimental/algorithm> #include #include #include #include int main() { std::string in = "abcdefgh", out; std::experimental::sample(in.begin(), in.end(), std::back_inserter(out), 5, std::mt19937{std::random_device{}()}); std::cout << "five random letters out of " << in << " : " << out << '\n'; }

Possible output: