std::sample

在标头 `<algorithm>` 定义
template< class PopulationIt, class SampleIt, class Distance, class URBG > SampleIterator sample( PopulationIt first, PopulationIt last, SampleIt out, Distance n, URBG&& g );		(C++17 起)

从序列 [first, last)（不重复地）选择 n 个元素，使得每个样本拥有相等的出现概率，并将这些被选择的元素写入到输出迭代器 out。用随机数生成器 g 生成随机数。

如果 n 大于序列中的元素数量，那么就会选择序列中的所有元素。

算法只有在 PopulationIterator 满足老式向前迭代器 (LegacyForwardIterator) 的要求时才稳定（保持被选择元素的相对顺序）。

如果 first 的值类型 (C++20 前)*first (C++20 起) 不可写入 out，那么程序非良构。

如果满足以下任意条件，那么行为未定义：

out 在 [first, last) 中。
PopulationIt 不满足老式输入迭代器 (LegacyInputIterator) 的要求。
SampleIt 不满足老式输出迭代器 (LegacyOutputIterator) 的要求。
满足以下所有条件：

`PopulationIt` 不满足老式向前迭代器 (LegacyForwardIterator) 的要求。	(C++23 前)
`PopulationIt` 没有实现 `forward_iterator`。	(C++23 起)

SampleIt 不满足老式随机访问迭代器 (LegacyRandomAccessIterator) 的要求。

给定类型 T 为 std::remove_reference_t<URBG>，满足以下任意条件：

T 不满足均匀随机位生成器 (UniformRandomBitGenerator) 的要求。

T 的返回类型不可转换到 Distance。

(C++20 前)

参数

first, last	-	组成从中采样的范围（总体）的一对迭代器
out	-	要写入样本的输出迭代器
n	-	要抽取的样本数
g	-	用作随机源的随机数生成器
类型要求
- `Distance` 必须是整数类型。

返回值

在输出最后样本后返回 out 的副本，即采样范围的结尾。

复杂度

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

可能的实现

参阅 libstdc++、libc++ 与 MSVC STL 中的实现。

注解

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

功能特性测试宏	值	标准	功能特性
`__cpp_lib_sample`	201603L	(C++17)	`std::sample`

示例

运行此代码

#include <algorithm>
#include <iostream>
#include <iterator>
#include <random>
#include <string>
 
int main()
{
    std::string in {"ABCDEFGHIJK"}, out;
    std::sample(in.begin(), in.end(), std::back_inserter(out), 4,
                std::mt19937 {std::random_device{}()});
    std::cout << "从 " << in << " 中随机选取四个字母：" << out << '\n';
}

可能的输出：

从 ABCDEFGHIJK 中随机选取四个字母：EFGK

参阅

random_shuffleshuffle (C++17 前)(C++11)	随机重排范围中的元素 (函数模板)
ranges::sample (C++20)	从序列中随机选择 n 个元素 (niebloid)

编译器支持
自立实现与有宿主实现
语言
标准库
标准库标头
具名要求
功能特性测试宏 (C++20)
语言支持库
概念库 (C++20)
元编程库 (C++11)
诊断库
通用工具库
字符串库
容器库
迭代器库
范围库 (C++20)
算法库
数值库
本地化库
输入/输出库
文件系统库 (C++17)
正则表达式库 (C++11)
并发支持库 (C++11)
技术规范
符号索引
外部库

std::sample

参数

返回值

复杂度

可能的实现

注解

示例

参阅

导航