std::sample
Defined in header <algorithm> |
||
---|---|---|
template< class PopulationIterator, class SampleIterator, class Distance, class URBG > SampleIterator sample( PopulationIterator first, PopulationIterator last, SampleIterator out, Distance n, URBG&& g ); |
(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.
Feature testing macro: __cpp_lib_sample
.
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) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/algorithm/sample