std::sample
Defined in header <algorithm>
|
||
template< class PopulationIterator, class SampleIterator, class Distance, class URBG > |
(since C++17) | |
Selects n
elements from the sequence [first; last) (without replacement) such that each possible sample has equal probability of appearance, and writes those selected elements into the output iterator out
. Random numbers are generated using the random number generator g
.
If n
is greater than the number of elements in the sequence, selects last-first elements.
The algorithm is stable (preserves the relative order of the selected elements) only if PopulationIterator
meets the requirements of LegacyForwardIterator
The behavior is undefined if out
is in [first; last).
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 |
n | - | number of samples to make |
g | - | the random number generator used as the source of randomness |
Type requirements | ||
-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
| ||
-std::remove_reference_t<URBG> must meet the requirements of UniformRandomBitGenerator and its return type must be convertible to Distance
|
Return value
Returns a copy of out
after the last sample that was output, that is, end of the sample range.
Complexity
Linear in std::distance(first,last).
Notes
This function may implement selection sampling or reservoir sampling.
Possible implementation
See the implementations in libstdc++, libc++ and MSVC STL.
Example
#include <iostream> #include <random> #include <string> #include <iterator> #include <algorithm> int main() { std::string in = "hgfedcba", out; std::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:
five random letters out of hgfedcba: gfcba
See also
(until C++17)(C++11) |
randomly re-orders elements in a range (function template) |
(C++20) |
selects n random elements from a sequence (niebloid) |