Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

NAME
       std::sample - std::sample

Synopsis
	  Defined in header <algorithm>
	  template< class PopulationIterator, class SampleIterator,

	  class	Distance, class	URBG >
	  SampleIterator  sample( PopulationIterator first, PopulationIterator
       (since C++17)
	  last,
	  SampleIterator out, Distance n,

	  URBG&& g );

	  Selects n elements from the sequence [first; last) (without replace-
       ment) 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 se-
       lected elements)	only
	  if PopulationIterator	meets the requirements of  LegacyForwardItera-
       tor

	  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  LegacyInputItera-
       tor.
	  -
	  SampleIterator must meet the requirements of LegacyOutputIterator.
	  -
	  SampleIterator must also meet	the requirements of LegacyRandomAcces-
       sIterator 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  sam-
       pling.

	  Feature-test macro: __cpp_lib_sample

Possible implementation
	  See the implementations in libstdc++,	libc++ and MSVC	STL.

Example
       // Run this code

	#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
	  random_shuffle
	  shuffle	 randomly re-orders elements in	a range
	  (until C++17)	 (function template)
	  (C++11)
	  ranges::sample selects n random elements from	a sequence
	  (C++20)	 (niebloid)

http://cppreference.com		  2022.07.31			std::sample(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::sample&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help