[alg.random.sample]

# 26 Algorithms library [[algorithms]](./#algorithms)

## 26.7 Mutating sequence operations [[alg.modifying.operations]](alg.modifying.operations#alg.random.sample)

### 26.7.12 Sample [alg.random.sample]

[🔗](#lib:sample)

`template<class PopulationIterator, class SampleIterator,
         class Distance, class UniformRandomBitGenerator>
  SampleIterator sample(PopulationIterator first, PopulationIterator last,
                        SampleIterator out, Distance n,
                        UniformRandomBitGenerator&& g);

template<[input_iterator](iterator.concept.input#concept:input_iterator "24.3.4.9 Concept input_­iterator [iterator.concept.input]") I, [sentinel_for](iterator.concept.sentinel#concept:sentinel_for "24.3.4.7 Concept sentinel_­for [iterator.concept.sentinel]")<I> S, [weakly_incrementable](iterator.concept.winc#concept:weakly_incrementable "24.3.4.4 Concept weakly_­incrementable [iterator.concept.winc]") O, class Gen>
  requires ([forward_iterator](iterator.concept.forward#concept:forward_iterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]")<I> || [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_­access_­iterator [iterator.concept.random.access]")<O>) &&
           [indirectly_copyable](alg.req.ind.copy#concept:indirectly_copyable "24.3.7.3 Concept indirectly_­copyable [alg.req.ind.copy]")<I, O> &&
           [uniform_random_bit_generator](rand.req.urng#concept:uniform_random_bit_generator "29.5.3.3 Uniform random bit generator requirements [rand.req.urng]")<remove_reference_t<Gen>>
  O ranges::sample(I first, S last, O out, iter_difference_t<I> n, Gen&& g);
template<[input_range](range.refinements#concept:input_range "25.4.6 Other range refinements [range.refinements]") R, [weakly_incrementable](iterator.concept.winc#concept:weakly_incrementable "24.3.4.4 Concept weakly_­incrementable [iterator.concept.winc]") O, class Gen>
  requires ([forward_range](range.refinements#concept:forward_range "25.4.6 Other range refinements [range.refinements]")<R> || [random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_­access_­iterator [iterator.concept.random.access]")<O>) &&
           [indirectly_copyable](alg.req.ind.copy#concept:indirectly_copyable "24.3.7.3 Concept indirectly_­copyable [alg.req.ind.copy]")<iterator_t<R>, O> &&
           [uniform_random_bit_generator](rand.req.urng#concept:uniform_random_bit_generator "29.5.3.3 Uniform random bit generator requirements [rand.req.urng]")<remove_reference_t<Gen>>
  O ranges::sample(R&& r, O out, range_difference_t<R> n, Gen&& g);
`

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L8410)

*Mandates*: For the overload in namespace std,Distance is an integer type and*first is writable ([[iterator.requirements.general]](iterator.requirements.general "24.3.1 General")) to out[.](#1.sentence-1)

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L8416)

*Preconditions*: out is not in the range [first, last)[.](#2.sentence-1)

For the overload in namespace std:

- [(2.1)](#2.1)

  PopulationIterator meets
 the [*Cpp17InputIterator*](input.iterators#:Cpp17InputIterator "24.3.5.3 Input iterators [input.iterators]") requirements ([[input.iterators]](input.iterators "24.3.5.3 Input iterators"))[.](#2.1.sentence-1)

- [(2.2)](#2.2)

  SampleIterator meets
 the [*Cpp17OutputIterator*](output.iterators#:Cpp17OutputIterator "24.3.5.4 Output iterators [output.iterators]") requirements ([[output.iterators]](output.iterators "24.3.5.4 Output iterators"))[.](#2.2.sentence-1)

- [(2.3)](#2.3)

  SampleIterator meets
 the [*Cpp17RandomAccessIterator*](random.access.iterators#:Cpp17RandomAccessIterator "24.3.5.7 Random access iterators [random.access.iterators]") requirements ([[random.access.iterators]](random.access.iterators "24.3.5.7 Random access iterators"))
 unless PopulationIterator models [forward_iterator](iterator.concept.forward#concept:forward_iterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]") ([[iterator.concept.forward]](iterator.concept.forward "24.3.4.11 Concept forward_­iterator"))[.](#2.3.sentence-1)

- [(2.4)](#2.4)

  remove_reference_t<UniformRandomBitGenerator> meets
 the requirements of a uniform random bit generator type ([[rand.req.urng]](rand.req.urng "29.5.3.3 Uniform random bit generator requirements"))[.](#2.4.sentence-1)

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L8437)

*Effects*: Copies min(last - first, n) elements (the [*sample*](#def:sample "26.7.12 Sample [alg.random.sample]"))
from [first, last) (the [*population*](#def:population "26.7.12 Sample [alg.random.sample]")) to out such that each possible sample has equal probability of appearance[.](#3.sentence-1)

[*Note [1](#note-1)*:

Algorithms that obtain such effects include [*selection sampling*](#def:selection_sampling) and [*reservoir sampling*](#def:reservoir_sampling)[.](#3.sentence-2)

— *end note*]

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L8447)

*Returns*: The end of the resulting sample range[.](#4.sentence-1)

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L8451)

*Complexity*: O(last - first)[.](#5.sentence-1)

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/algorithms.tex#L8455)

*Remarks*: 

- [(6.1)](#6.1)

  For the overload in namespace std,
 stable if and only if PopulationIterator models [forward_iterator](iterator.concept.forward#concept:forward_iterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]")[.](#6.1.sentence-1)
  For the first overload in namespace ranges,
 stable if and only if I models [forward_iterator](iterator.concept.forward#concept:forward_iterator "24.3.4.11 Concept forward_­iterator [iterator.concept.forward]")[.](#6.1.sentence-2)

- [(6.2)](#6.2)

  To the extent that the implementation of this function makes use
 of random numbers, the object g serves as
 the implementation's source of randomness[.](#6.2.sentence-1)