std::experimental::sample

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Technical specifications

Filesystem library (filesystem TS)

Library fundamentals (library fundamentals TS)

Library fundamentals 2 (library fundamentals 2 TS)

Extensions for parallelism (parallelism TS)

Concepts (concepts TS)

Extensions for concurrency (concurrency TS)

 

Library fundamentals

experimental::optional

experimental::any

experimental::basic_string_view

experimental::sample

experimental::apply

experimental::search

experimental::default_searcher experimental::make_default_searcher

experimental::boyer_moore_searcher experimental::make_boyer_moore_searcher

experimental::boyer_moore_horspool_searcher experimental::make_boyer_moore_horspool_searcher

type-erased and polymorphic allocators

variable templates for type traits

 

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

Using the random number generator g, 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 ForwardIterator

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 InputIterator.
- SampleIterator must meet the requirements of OutputIterator.
- SampleIterator must also meet the requirements of RandomAccessIterator if PopulationIterator doesn't meet ForwardIterator
- PopulationIterator's value type must be writeable to out
- Distance must be an integer type
- UniformRandomNumberGenerator must meet the requirements of UniformRandomNumberGenerator 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_shuffleshuffle (until C++17)(C++11)

randomly re-orders elements in a range (function template)