home | help 
std::experimental::sample(3)   C++ Standard Libary  std::experimental::sample(3)

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 fun-
     damentals TS)
	PopulationIterator last,
			       SampleIterator out, Distance
	n,

			       URBG&& g );
	template< class PopulationIterator, class
	SampleIterator, class Distance >

	SampleIterator sample( PopulationIterator first,      (2) (library  fun-
     damentals TS
	PopulationIterator last,				  v2)

			       SampleIterator out, Distance n
	);

	Selects n elements from the sequence [first, last) such that each possi-
     ble 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 require-
     ments 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 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 LegacyRandomAccessIt-
     erator 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 re-
     turn 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 <experimental/algorithm>
      #include <iostream>
      #include <iterator>
      #include <random>
      #include <string>

      int main()
      {
	  std::string in = "abcdefgh", out;
	  std::experimental::sample(in.begin(),      in.end(),	   std::back_in-
     serter(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)

Category:
	  * Noindexed pages

http://cppreference.com 	   2024.06.10	    std::experimental::sample(3)
home | help