class QRandomGenerator#

QRandomGenerator 类允许从高质量的随机数生成器中获取随机值。更多...

继承自: QRandomGenerator64

概述#

方法#

静态函数#

备注

本文档可能包含自动从C++转换为Python的代码片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译有问题，您也可以通过在https:/bugreports.qt.io/projects/PYSIDE上创建工单来让我们知道

详细描述#

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

QRandomGenerator可用于从高质量的随机数生成器生成随机值。与C++随机引擎类似，QRandomGenerator可以通过构造函数使用用户提供的值初始化。当初始化后，此类生成数字的序列是确定的。也就是说，给定相同的种子数据，QRandomGenerator将生成相同的数字序列。但是给定的种子不同，结果应该有相当大的不同。

securelySeeded()可用于创建一个用system()安全初始化的QRandomGenerator，这意味着它生成的数字序列不容易预测。此外，global()返回一个全局实例的QRandomGenerator，Qt将确保该实例安全初始化。此对象是线程安全的，在大多数情况下可以被共享，且始终从system()初始化。

system()可用于访问系统的密码学安全随机生成器。在Unix系统上，它等效于从/dev/urandom读取，或者使用getrandom()或getentropy()系统调用。

该类可以生成32位或64位数据，或者填满具有这些位的数组。生成新值最常见的方式是调用generate()、generate64()或fillRange()函数。可以使用如下方式使用它：

value = QRandomGenerator.global().generate()

此外，它还提供了一个浮点函数generateDouble()，该函数返回范围[0, 1)内的数字（即包含0但不包含1）。同时提供了一套便利函数，用于在有限的整数范围内获取随机数。

播种和确定性#

QRandomGenerator可以使用特定的种子数据进行初始化。完成此操作后，该对象生成的数字总是相同的，如下例所示：

prng1 = QRandomGenerator(1234), prng2(1234)
Q_ASSERT(prng1.generate() == prng2.generate())
Q_ASSERT(prng1.generate64() == prng2.generate64())

种子数据的格式为一个或多个32位字。理想的种子大小大约等于QRandomGenerator类本身的尺寸。由于种子数据会混合，所以QRandomGenerator无法保证不同的种子会产生不同的序列。

global()，就像所有由securelySeeded()创建的生成器一样，总是从system()中获取种子，因此无法使它产生相同的序列。

批量数据#

在确定性模式下操作时，可以使用QRandomGenerator进行批量数据生成。实际上，不建议需要加密安全或真实随机数据的程序使用system()，而是使用常规的QRandomGenerator来满足它们的随机数据需求。

为了便于使用，QRandomGenerator提供了一个全局对象，可以像以下示例中一样轻松使用：

x = QRandomGenerator.global().generate()
y = QRandomGenerator.global().generate()
w = QRandomGenerator.global().bounded(16384)
h = QRandomGenerator.global().bounded(16384)

全局随机数生成器#

可以使用system()来访问系统范围内的随机数生成器，在Qt运行的所有系统上都是加密安全的。该函数将在有可用硬件设备时使用硬件设备生成随机数。在这些系统上，这些设备是真正的随机数生成器。然而，如果它们是真正的RNG，则这些设备具有有限的熵源，因此当熵池耗尽时可能无法产生任何结果。

如果发生这种情况，首先操作系统然后是 QRandomGenerator 将回退到质量递减的伪随机数生成器（Qt的回退生成器是最简单的）。这些生成器是否仍然是加密质量的实现是未定义的。因此，不应使用 system() 进行高频随机数生成，以免熵池空空如也。一般来说，这个类一次不应生成超过每秒一千字节的随机数据（注：这可能会因系统而异）。

如果一个应用需要大量真正的RNG数据，它应直接使用操作系统设施（如Linux上的/dev/random）并等待熵变得可用。如果一个应用需要加密质量的伪随机数生成器，但不是真正的随机数，则仍然可以使用 system()（详见下文）。

如果不需要真正的RNG或加密安全的伪随机数生成器，则应用应使用类似 QRandomGenerator 的确定模式以及C++标准库中的伪随机数生成器。可以使用 system() 对其进行初始化。

回退质量#

system() 使用操作系统的功能来获取随机数，尝试从周围环境收集真正的熵以产生真正的随机数。但是，熵池可能耗尽，在这种情况下，操作系统会暂时回退到一个伪随机引擎。在任何情况下，system() 都不会阻塞等待收集更多熵。

以下操作系统保证它们随机生成API的结果即使熵池耗尽也至少具有加密安全质量：Apple OSes (Darwin)，BSD，Linux，Windows。除非系统安装有问题（例如，当前进程不能读取/dev/urandom），否则 system() 将因此提供相同的保证。

在其他操作系统上，QRandomGenerator 将回退到具有良好数值分布的伪随机数生成器，但它不能保证在所有情况下都正确初始化。请参阅操作系统文档以获取更多信息。

需要 QRandomGenerator 不回退到非加密质量生成器的应用建议检查它们的操作系统文档或将其部署限制在上文所述之一。

重入性和线程安全性#

QRandomGenerator 是可重入的，这意味着多个线程可以同时在该类上操作，只要它们操作不同的对象。如果多个线程需要共享一个伪随机数生成器（PRNG）序列，则需要使用互斥锁进行外部锁定。

例外是 global() 和 system() 返回的对象：这些对象是线程安全的，并且可以在没有外部锁定的任何线程中使用。请注意，线程安全性不扩展到这些对象的副本来复制：它们应该始终通过引用使用。

与标准 C++ 库的兼容性#

QRandomGenerator 模仿了 C++ 标准库中对随机数发生器的要求，并且可以在几乎所有标准库引擎可以使用的上下文中使用。以下是对要求的例外情况：

  • QRandomGenerator 不支持从像 std::seed_seq 这样的序列以外的其他种子序列类似类中提取种子；

  • QRandomGenerator 不能与 std::ostream 或从 std::istream 比较或串流式处理（但可复制）。

QRandomGenerator 也与均匀分布类 std::uniform_int_distribution 和 std:uniform_real_distribution 兼容，以及自由函数 std::generate_canonical。例如，以下代码可用于生成范围在 [1, 2.5) 之间的浮点数：

std.uniform_real_distribution dist(1, 2.5)
return dist(QRandomGenerator.global())

另请参阅

QRandomGenerator64

__init__(begin, end)#
参数:

  • begin – quint32

  • end – quint32

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

这是一个重载函数。

使用从 begin 到 end 范围内找到的值作为种子来初始化这个 QRandomGenerator 对象。使用相同种子值构造或重新播种的两个对象将产生相同的数字序列。

此构造函数等同于

std.seed_seq sseq(begin, end)
generator = QRandomGenerator(sseq)

另请参阅

seed() securelySeeded()

__init__(seedBuffer, len)
参数:

  • seedBuffer – quint32

  • len – int

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

这是一个重载函数。

以数组 seedBuffer 中找到的 len 个值初始化此 QRandomGenerator 对象作为种子。使用相同种子值构建或重新初始化的两个对象将生成相同的数字序列。

此构造函数等同于

std.seed_seq sseq(seedBuffer, seedBuffer + len)
generator = QRandomGenerator(sseq)

另请参阅

seed() securelySeeded()

__init__([seedValue=1])
参数:

seedValue – int

使用 seedValue 作为种子初始化此 QRandomGenerator 对象。使用相同种子值构建或重新初始化的两个对象将生成相同的数字序列。

另请参阅

seed() securelySeeded()

__init__(other)
参数:

other – QRandomGenerator

在 other 对象中创建生成器状态的副本。如果 other 是 system() 或其副本，那么此对象也将从操作系统随机生成设施中读取。在这种情况下，两个对象生成的序列将不同。

在其他所有情况下，新的 QRandomGenerator 对象将从与 other 对象相同的确定序列位置开始。从此点开始，两个对象将生成相同的序列。

因此，不推荐创建 global() 的副本。如果需要一个专有的确定生成器，请考虑使用 securelySeeded() 以获取与 global() 无关联的新对象。

bounded(lowest, highest)#
参数:

  • lowest – int

  • highest – int

返回类型：:

int

这是一个重载函数。

生成一个介于 lowest（包含）和 highest（排除）之间的随机 64 位整数。highest 参数必须大于 lowest。

使用参数 lowest 和 highest - 1 的 std::uniform_int_distribution<quint64> ` <http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution>` 也能获得相同的结果。

请注意，此函数不能用来获取 quint64 的全部 64 位范围内的值。相反，请使用 generate64() .

备注

该函数实现为一个循环，它依赖于获得的随机值。从长远来看，平均来说它只循环不到 2 次，但如果随机生成器存在缺陷，这个函数可能需要更长的时间来执行。

另请参阅

generate() generate64() generateDouble()

bounded(lowest, highest)
参数:

  • lowest – int

  • highest – int

返回类型：:

int

bounded(lowest, highest)
参数:

  • lowest – int

  • highest – int

返回类型：:

int

bounded(highest)
参数:

highest – int

返回类型：:

int

这是一个重载函数。

生成一个介于 0（包含）和最高值（不包含）之间的 64 位随机数。使用参数 0 和 highest - 1 的 std::uniform_int_distribution<quint64> ` <http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution>` 也能得到相同的结果。

请注意，此函数不能用来获取 quint64 的全部 64 位范围内的值。相反，请使用 generate64() .

备注

该函数实现为一个循环，它依赖于获得的随机值。从长远来看，平均来说它只循环不到 2 次，但如果随机生成器存在缺陷，这个函数可能需要更长的时间来执行。

另请参阅

generate() generate64() generateDouble()

bounded(lowest, highest)
参数:

  • lowest – int

  • highest – int

返回类型：:

int

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

这是一个重载函数。

在 lowest（包含）和 highest（不包含）之间生成一个随机的 32 位数。highest 参数必须大于 lowest。

使用带有参数 lowest 和 highest - 1 的 std::uniform_int_distribution ` <http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution>` 也能得到相同的结果。该类还可以用来获取超过 32 位的数量。

例如，为了获取 1000（包含）和 2000（不包含）之间的值，您将编写：

v = QRandomGenerator.global().bounded(1000, 2000)

请注意，此函数不能用于获取 quint32 的全部 32 位范围内的值。相反，请使用 generate() .

bounded(highest)
参数:

highest – int

返回类型：:

int

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

这是一个重载函数。

生成一个介于0（包含）和 highest（不包含）之间的32位随机数。使用 std::uniform_int_distribution ` <http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution>`_ 并传入参数0和 highest - 1 也可以得到相同的结果。该类还可以用于生成大于32位的数量；对于64位，可以使用64位版本的 bounded() 赋值器。

例如，要获取介于0到255（包含）之间的值，可以这样写

v = QRandomGenerator.global().bounded(256)

自然地，使用 generate() 的结果并通过掩码仅保留较低的8位也可以得到相同的结果。两种方案效率相当。

请注意，此函数不能用于获取 quint32 的全部 32 位范围内的值。相反，请使用 generate() .

bounded(lowest, highest)
参数:

  • lowest – int

  • highest – int

返回类型：:

int

bounded(highest)
参数:

highest – int

返回类型：:

int

这是一个重载函数。

生成一个介于0（包含）和 highest（不包含）之间的64位随机数。highest 必须为正数。

注意，这个函数不能用来获取 qint64 的全部64位范围内的值。相反，使用 generate64() 并将其强制转换为 qint64，或者使用该函数的无符号版本。

备注

该函数实现为一个循环，它依赖于获得的随机值。从长远来看，平均来说它只循环不到 2 次，但如果随机生成器存在缺陷，这个函数可能需要更长的时间来执行。

另请参阅

generate() generate64() generateDouble()

bounded(lowest, highest)
参数:

  • lowest – int

  • highest – int

返回类型：:

int

bounded(lowest, highest)
参数:

  • lowest – int

  • highest – int

返回类型：:

int

这是一个重载函数。

生成一个介于 lowest（包含）和 highest（不包含）之间的32位随机数，两者可能为负，但 highest 必须大于 lowest。

注意，这个函数不能用来获取 int 的全部32位范围内的值。相反，使用 generate() 并将其强制转换为 int。

bounded(highest)
参数:

highest – int

返回类型：:

int

这是一个重载函数。

生成一个介于0（包含）和 highest（不包含）之间的32位随机数。highest 必须为正数。

注意，这个函数不能用来获取 int 的全部32位范围内的值。相反，使用 generate() 并将其强制转换为 int。

bounded(highest)
参数:

highest - 浮点数

返回类型：:

浮点数

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

生成一个介于0（包含）和 highest（不包含）之间的随机double。此函数相当于并作为一个实现

return generateDouble() * highest

如果 highest 参数为负数，则结果也将是负数；如果它是无穷大或NaN，则结果也会是无穷大或NaN（即非随机）。

bounded(lowest, highest)
参数:

  • lowest – int

  • highest – int

返回类型：:

int

这是一个重载函数。

生成一个介于 lowest（包含）和 highest（不包含）之间的64位随机数，两者可能为负，但 highest 必须大于 lowest。

请注意，这个函数不能用来获取完整的64位范围内的值qint64。相反，请使用generate64()并将其强制转换为qint64。

备注

该函数实现为一个循环，它依赖于获得的随机值。从长远来看，平均来说它只循环不到 2 次，但如果随机生成器存在缺陷，这个函数可能需要更长的时间来执行。

另请参阅

generate() generate64() generateDouble()

discard(z)#
参数:

z – int

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

从序列中丢弃下一个z个条目。此方法等价于调用generate() z次并丢弃结果，如下所示：

while z--:
    generator.generate()
generate()#
返回类型：:

int

生成一个32位随机数并返回。

另请参阅

operator()() generate64()

generate64()#
返回类型：:

int

生成一个64位随机数并返回。

另请参阅

operator()() generate()

generateDouble()#
返回类型：:

浮点数

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

生成一个在规范范围[0, 1)中的随机qreal（即包括零但不包括1）。

此函数等价于

rd = QRandomGenerator64()
return std.generate_canonical<qreal, std.numeric_limits<qreal>.digits>(rd)

也可以通过使用参数0和1的`std::uniform_real_distribution` `http://en.cppreference.com/w/cpp/numeric/random/uniform_real_distribution`>`获得同样的结果。

static global_()#
返回类型：:

QRandomGenerator

static max()#
返回类型：:

int

返回QRandomGenerator可能生成的最大值。换句话说，std::numeric_limits<result_type>::max()。

另请参阅

min() max()

静态 min()#
返回类型：:

int

返回 QRandomGenerator 可能生成的最小值。也就是说，0。

另请参阅

max() min()

__ne__(rng2)#
参数:

rng2 – QRandomGenerator

返回类型：:

bool

如果两个引擎 rng1 和 rng2 处于不同的状态，或者其中一个从操作系统设施中读取而另一个不读取，则返回 true，否则返回 false。

静态 securelySeeded()#
返回类型：:

QRandomGenerator

返回一个新的 QRandomGenerator 对象，该对象已使用 system() 的安全种子初始化。此函数将获取 QRandomGenerator 使用的算法的理想种子大小，因此是创建将保留一段时间的新 QRandomGenerator 对象的推荐方法。

鉴于安全种子确定性引擎所需的数据量，此函数相对昂贵，不应用于短期使用 QRandomGenerator （用它生成少于 2600 字节的随机数据是资源浪费）。如果使用不需要如此多的数据，请考虑使用 global() 并不存储 QRandomGenerator 对象。

另请参阅

global() system()

seed([s=1])#
参数:

s – int

使用值 seed 作为种子重新初始化此对象。

static system()#
返回类型：:

QRandomGenerator

返回一个指向共享 QRandomGenerator 的指针，该指针始终使用操作系统提供的功能生成随机数。以下操作系统上认为系统功能是密码学安全的：苹果 OS 系统 (Darwin)、BSD 系统、Linux、Windows。在其他操作系统上也可能是这样。

它们也可能由真正的硬件随机数生成器支持。因此，此函数返回的 QRandomGenerator 应不用于批量数据生成。相反，应将其用于初始化 QRandomGenerator 或来自 <random> 头文件的随机引擎。

此函数返回的对象是线程安全的，可在任何线程中使用而无需锁定。它还可以复制，所得到的 QRandomGenerator 也会访问操作系统功能，但它们不会生成相同的序列。

另请参阅

securelySeeded() global()