QRandomGenerator Class

成员函数文档

QRandomGenerator::QRandomGenerator(quint32 seedValue = 1)

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

另请参阅 seed() 和securelySeeded()。

template <qsizetype N> QRandomGenerator::QRandomGenerator(const quint32 (&seedBuffer)[N])

使用数组seedBuffer 中的值作为种子，初始化此QRandomGenerator对象。使用相同种子值构造或重新初始化的两个对象将生成相同的数列。

另请参阅 seed() 和securelySeeded()。

[noexcept] QRandomGenerator::QRandomGenerator(std::seed_seq &sseq)

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

另请参阅 seed() 和securelySeeded()。

QRandomGenerator::QRandomGenerator(const quint32 *begin, const quint32 *end)

使用范围为begin 到end 内的值作为种子来初始化此 QRandomGenerator 对象。使用相同种子值构造或重新初始化的两个对象将生成相同的数列。

此构造函数等同于：

    std::seed_seq sseq(begin, end);
    QRandomGenerator generator(sseq);

另请参阅 seed() 和securelySeeded()。

QRandomGenerator::QRandomGenerator(const quint32 *seedBuffer, qsizetype len)

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

此构造函数等同于：

    std::seed_seq sseq(seedBuffer, seedBuffer + len);
    QRandomGenerator generator(sseq);

另请参阅 seed() 和securelySeeded()。

QRandomGenerator::QRandomGenerator(const QRandomGenerator &other)

在other 对象中创建生成器状态的副本。如果other 是QRandomGenerator::system()或其副本，则该对象也将从操作系统的随机数生成机制中读取数据。在这种情况下，这两个对象生成的序列将不同。

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

因此，不建议创建QRandomGenerator::global()的副本。如果需要一个完全独立的确定性生成器，请考虑使用securelySeeded()来获取一个与QRandomGenerator::global()没有任何关联的新对象。

[constexpr noexcept default] QRandomGenerator::~QRandomGenerator()

销毁QRandomGenerator 的实例。

double QRandomGenerator::bounded(double highest)

生成一个介于 0（含）与highest （不含）之间的随机双精度数值。该函数等同于以下实现：

    return generateDouble() * highest;

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

另请参阅 generateDouble() 和bounded(quint64)。

int QRandomGenerator::bounded(int highest)

生成一个位于 0（含）至highest （不含）范围内的 32 位随机数。highest 必须为正数。

请注意，此函数无法用于获取 int 类型完整的 32 位范围内的值。此时，请使用generate() 并将其强制转换为 int。

另请参阅 generate()、generate64() 和generateDouble()。

qint64 QRandomGenerator::bounded(qint64 highest)

生成一个随机 64 位数值，其范围在 0（包含）到highest （不包含）之间。highest 必须为正数。

请注意，此函数无法用于获取qint64 这一完整64位范围内的值。此时，请使用generate64()并将其强制转换为qint64类型，或者改用该函数的无符号版本。

另请参阅 generate()、generate64() 和generateDouble()。

quint32 QRandomGenerator::bounded(quint32 highest)

生成一个随机 32 位数值，其取值范围在 0（含）到highest （不含）之间。也可以通过使用 std::uniform_int_distribution 并设置参数 0 和highest - 1 也能得到相同的结果。该类还可用于生成大于 32 位的数值；若需 64 位数值，也可使用 64 位的 bounded() 重载方法。

例如，要获得介于 0 和 255（含）之间的值，应这样写：

    quint32 v = QRandomGenerator::global()->bounded(256);

当然，也可以通过对generate() 的返回结果进行掩码，仅保留低 8 位来获得相同结果。这两种方法的效率相当。

请注意，该函数无法用于获取 quint32 的完整 32 位范围内的值。此时应使用generate()。

另请参见 generate()、generate64() 和generateDouble()。

quint64 QRandomGenerator::bounded(quint64 highest)

生成一个取值范围在 0（包含）到highest （不包含）之间的 64 位随机数。也可以通过使用 std::uniform_int_distribution<quint64> 并指定参数 0 和highest - 1 也可得到相同结果。

请注意，此函数无法用于获取quint64 的完整64位范围内的值。如需获取该范围内的值，请使用generate64()。

另请参阅 generate()、generate64() 以及generateDouble()。

int QRandomGenerator::bounded(int lowest, int highest)

生成一个随机 32 位数值，其取值范围在lowest （包含该值）和highest （不包含该值）之间；这两个值均可为负数，但highest 必须大于lowest 。

请注意，此函数无法用于获取 int 类型完整 32 位范围内的值。若需获取该范围内的值，请使用generate() 并将其强制转换为 int 类型。

另请参阅 generate()、generate64() 和generateDouble()。

该函数的作用是在参数类型不完全匹配时，协助进行重载解析。它会将较小的类型提升为较大类型的类型，并调用正确的重载。

qint64 QRandomGenerator::bounded(qint64 lowest, qint64 highest)

生成一个随机 64 位数值，其取值范围在lowest （含）到highest （不含）之间，这两个数值都可能是负数，但highest 必须大于lowest 。

请注意，此函数无法用于获取qint64 的完整 64 位范围内的值。请改用generate64() 并将其强制转换为 qint64。

另请参阅 generate()、generate64() 和generateDouble()。

quint32 QRandomGenerator::bounded(quint32 lowest, quint32 highest)

生成一个随机 32 位数值，其取值范围在lowest （包含该值）到highest （不包含该值）之间。highest 参数必须大于lowest 。

也可以通过使用 std::uniform_int_distribution 并设置参数lowest 和\a highest - 1 也可获得相同结果。该类还可用于生成大于 32 位的数值。

例如，要获取介于 1000（含）和 2000（不含）之间的值，应编写如下代码：

    quint32 v = QRandomGenerator::global()->bounded(1000, 2000);

请注意，此函数无法用于获取 quint32 的完整 32 位范围内的值。此时应使用generate()。

另请参阅 generate()、generate64() 和generateDouble()。

quint64 QRandomGenerator::bounded(quint64 lowest, quint64 highest)

生成一个随机 64 位数值，其取值范围在lowest （包含）与highest （不包含）之间。参数highest 必须大于lowest 。

也可以通过使用 std::uniform_int_distribution<quint64> 并使用参数lowest 和\a highest - 1 也可获得相同结果。

请注意，此函数无法用于获取quint64 的完整 64 位范围内的值。此时应使用generate64()。

另请参阅 generate()、generate64() 和generateDouble()。

void QRandomGenerator::discard(unsigned long long z)

从序列中移除接下来的z 个条目。该方法等同于调用generate()z 次并丢弃结果，如下所示：

    while (z--)
        generator.generate();

template < typename UInt, size_t N, QRandomGenerator::IfValidUInt<UInt> = true > void QRandomGenerator::fillRange(UInt (&buffer)[N])

生成N 个32位或64位随机数（具体取决于类型UInt ），并将它们存储在buffer 数组中。这是同时获取多个随机数的最有效方法，因为它减少了调用随机数生成器源代码的次数。

例如，要生成两个32位数值，可以这样编写：

    quint32 array[2];
    QRandomGenerator::global()->fillRange(array);

当然，也可以先调用一次generate64()，然后将64位值的两半拆分出来。

另请参阅 generate()。

template <typename UInt, QRandomGenerator::IfValidUInt<UInt> = true> void QRandomGenerator::fillRange(UInt *buffer, qsizetype count)

生成count 个32位或64位随机数（具体取决于类型UInt ），并将它们存储在buffer 所指向的缓冲区中。这是同时获取多个随机数的最有效方法，因为它减少了调用随机数生成器源代码的次数。

例如，要将一个包含 16 个条目的列表填充为随机值，可以这样编写：

    QList<quint32> list;
    list.resize(16);
    QRandomGenerator::global()->fillRange(list.data(), list.size());

另请参阅 generate()。

quint64 QRandomGenerator::generate64()

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

另请参阅 operator()() 和generate()。

quint32 QRandomGenerator::generate()

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

另请参阅 operator()() 和generate64()。

template <typename ForwardIterator> void QRandomGenerator::generate(ForwardIterator begin, ForwardIterator end)

生成 32 位量，并将它们存储在begin 到end 之间的范围内。该函数等同于（且实现为）：

    std::generate(begin, end, [this]() { return generate(); });

该函数符合函数 std::seed_seq::generate的要求，该函数要求无符号 32 位整数值。

请注意，如果 [begin, end) 范围指向的区域每个元素可存储超过 32 位的数据，这些元素仍将仅初始化为 32 位数据。其余位将设为零。若要用 64 位量填充该范围，可编写如下代码：

    std::generate(begin, end, []() { return QRandomGenerator::global()->generate64(); });

如果该范围指向连续的内存（例如数组或QList 中的数据），也可以使用fillRange()函数。

另请参阅 fillRange()。

double QRandomGenerator::generateDouble()

生成一个位于规范区间 [0, 1)（即包含 0，不包含 1）内的随机 qreal 值。

该函数等同于：

    QRandomGenerator64 rd;
    return std::generate_canonical<qreal, std::numeric_limits<qreal>::digits>(rd);

也可以通过使用 std::uniform_real_distribution 并传入参数 0 和 1 也能得到相同的结果。

另请参阅 generate()、generate64()，以及bounded()。

[static] QRandomGenerator *QRandomGenerator::global()

返回指向一个共享QRandomGenerator 的指针，该对象已使用securelySeeded()进行初始化。应使用此函数来生成随机数据，从而避免为特定用途创建开销较大的、经过安全初始化的QRandomGenerator ，也无需存储体积较大的QRandomGenerator 对象。

例如，以下代码生成一个随机的 RGB 颜色：

    return QColor::fromRgb(QRandomGenerator::global()->generate());

对该对象的访问是线程安全的，因此无需加锁即可在任何线程中使用。该对象还可以被复制，复制后生成的序列将与共享对象生成的序列相同。但请注意，如果其他线程正在访问该全局对象，这些线程获取样本的时间间隔可能是不可预测的。

注意：此函数是线程安全的。

另请参阅 securelySeeded() 和system()。

[static constexpr] QRandomGenerator::result_type QRandomGenerator::max()

返回QRandomGenerator 可能生成的最大值。即std::numeric_limits<result_type>::max() 。

另请参阅 min()。

[static constexpr] QRandomGenerator::result_type QRandomGenerator::min()

返回QRandomGenerator 可能生成的最小值。即0。

另请参阅 max()。

[static] QRandomGenerator QRandomGenerator::securelySeeded()

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

鉴于为确定性引擎安全初始化所需的數據量较大，该函数的执行成本较高，因此不应用于QRandomGenerator 的短期用途（若用于生成少于2600字节的随机数据，实际上是浪费资源）。 如果使用场景不需要那么多的数据，请考虑使用QRandomGenerator::global() 函数，并避免存储QRandomGenerator 对象。

另请参阅 global() 和system()。

void QRandomGenerator::seed(quint32 seed = 1)

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

[noexcept] void QRandomGenerator::seed(std::seed_seq &seed)

使用种子序列seed 作为种子，对该对象进行重新初始化。

[static] QRandomGenerator *QRandomGenerator::system()

返回指向共享QRandomGenerator 的指针，该随机数生成器始终使用操作系统提供的功能来生成随机数。在以下操作系统上，这些系统功能被认为在密码学上是安全的：Apple操作系统（Darwin）、BSD、Linux、Windows。在其他操作系统上可能也是如此。

此外，这些随机数生成机制可能由真正的硬件随机数生成器提供支持。因此，不应将本函数返回的QRandomGenerator 用于批量数据生成。相反，应将其用于为QRandomGenerator 或<random>头文件中的随机引擎提供种子。

该函数返回的对象是线程安全的，可在任何线程中无锁使用。该对象也可被复制，生成的QRandomGenerator 同样会调用操作系统功能，但生成的随机数序列将不相同。

注意：此函数是线程安全的。

另请参阅 securelySeeded() 和global()。

QRandomGenerator::result_type QRandomGenerator::operator()()

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

另请参阅 generate() 和generate64()。