# std::experimental::sample

< cpp‎ | experimental

定义于头文件 `<experimental/algorithm>` |  |
template< class PopulationIterator, class SampleIterator, class Distance, class URBG > SampleIterator sample( PopulationIterator first, PopulationIterator last, SampleIterator out, Distance n, URBG&& g); | (1) | (库基础 TS)
template< class PopulationIterator, class SampleIterator, class Distance > SampleIterator sample( PopulationIterator first, PopulationIterator last, SampleIterator out, Distance n); | (2) | (库基础 TS v2)

在序列 [first; last) 中选择 `n` 个元素，使得每个元素拥有相等的出现概率，并写入被选择元素到输出迭代器 `out` 。

若`n` 大于序列中的元素数，则选择 last-first 个元素。

仅若 `PopulationIterator` 满足老式向前迭代器 (LegacyForwardIterator) 的要求，算法才稳定。

1) 用随机数生成器 `g` 生成随机数。
2) 用逐线程引擎生成随机数。

### 参数

first, last | - | 指示从中抽样的范围（总体）的一对迭代器
out | - | 要写入样本到其中的输出迭代器。必须不在 [first;last) 范围中
n | - | 样本数
g | - | 用作随机源的随机数生成器
- `PopulationIterator` 必须满足老式输入迭代器 (LegacyInputIterator) 的要求。
- `SampleIterator` 必须满足老式输出迭代器 (LegacyOutputIterator) 的要求。
- 若 `PopulationIterator` 不满足老式向前迭代器 (LegacyForwardIterator) ，则 `SampleIterator` 必须亦满足老式随机访问迭代器 (LegacyRandomAccessIterator) 的要求
- `PopulationIterator` 的 value_type 必须可写入到 `out`
- `Distance` 必须为整数类型
- `URBG` 必须满足均匀随机位生成器 (UniformRandomBitGenerator) 的要求，而其返回类型必须可转换为 `Distance`

### 返回值

返回输出的最后样本后的 `out` 的副本，即样本范围的末尾。

### 复杂度

与 std::distance(first,last) 成线性。

### 注意

此函数可以实现选择抽样或蓄水池抽样。

### 示例

    #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';
    }

可能的输出：

    five random letters out of abcdefgh : cdefg

### 参阅

random_shuffle shuffle (C++17 前)(C++11) | 随机重排范围中的元素 (函数模板)