NAME¶

std::experimental::sample - std::experimental::sample

Synopsis¶

Defined in header <experimental/algorithm>
template< class PopulationIterator, class
SampleIterator,

class Distance, class URBG >
SampleIterator sample( PopulationIterator first, (1) (library fundamentals TS)
PopulationIterator last,
SampleIterator out, Distance n,

URBG&& g);
template< class PopulationIterator, class
SampleIterator, class Distance >
(library fundamentals TS
SampleIterator sample( PopulationIterator first, (2) v2)
PopulationIterator last,

SampleIterator out, Distance n);

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

1) Random numbers are generated using the random number generator g.
2) Random numbers are generated using the per-thread engine.

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 [first;last) range
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

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.

Example¶

// Run this code

#include <iostream>
#include <random>
#include <string>
#include <iterator>
#include <experimental/algorithm>

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:¶

five random letters out of abcdefgh : cdefg

See also¶

random_shuffle
shuffle randomly re-orders elements in a range
(until C++17) (function template)
(C++11)