107 lines
6.3 KiB
Markdown
107 lines
6.3 KiB
Markdown
[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)
|