QRandomGenerator Class

メンバ関数のドキュメント

QRandomGenerator::QRandomGenerator(quint32 seedValue = 1)

この QRandomGenerator オブジェクトを、シード値として `seedValue ` を指定して初期化します。同じシード値で生成または再シードされた 2 つのオブジェクトは、同じ数列を生成します。

seed() およびsecurelySeeded()も参照してください 。

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

この QRandomGenerator オブジェクトを、配列 `seedBuffer ` に格納されている値をシードとして初期化します。同じシード値で生成または再シードされた 2 つのオブジェクトは、同じ数列を生成します。

seed() およびsecurelySeeded()も参照してください 。

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

この QRandomGenerator オブジェクトを、シードシーケンス `sseq ` をシードとして初期化します。同じシード値で生成または再シードされた 2 つのオブジェクトは、同じ数列を生成します。

seed() およびsecurelySeeded()も参照してください 。

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

この QRandomGenerator オブジェクトを、begin からend の範囲にある値をシードとして初期化します。同じシード値で構築または再シードされた 2 つのオブジェクトは、同じ数列を生成します。

このコンストラクタは、以下と同等です:

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

seed() およびsecurelySeeded()も参照してください 。

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

この QRandomGenerator オブジェクトを、配列 `seedBuffer ` に格納されている `len ` 値をシードとして初期化します。同じシード値で構築または再シードされた 2 つのオブジェクトは、同じ数列を生成します。

このコンストラクタは、以下と同等です。

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

seed() およびsecurelySeeded()も参照してください 。

QRandomGenerator::QRandomGenerator(const QRandomGenerator &other)

other オブジェクト内のジェネレータ状態のコピーを作成します。other がQRandomGenerator::system()であるか、そのコピーである場合、このオブジェクトもオペレーティングシステムの乱数生成機能から読み込みを行います。その場合、2つのオブジェクトによって生成されるシーケンスは異なります。

それ以外の場合は、新しい QRandomGenerator オブジェクトは、other オブジェクトと同じ確定的なシーケンスの同じ位置から開始します。この時点以降、両方のオブジェクトは同じシーケンスを生成します。

そのため、QRandomGenerator::global() のコピーを作成することは推奨されません。排他的な決定論的ジェネレータが必要な場合は、代わりにsecurelySeeded() を使用して、QRandomGenerator::global() とは一切関係のない新しいオブジェクトを取得することを検討してください。

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

QRandomGenerator のインスタンスを破棄します。

double QRandomGenerator::bounded(double highest)

0（0を含む）からhighest （ を含まない）の範囲のdouble型ランダム数値を1つ生成します。この関数は以下の関数と同等であり、次のように実装されています：

    return generateDouble() * highest;

highest パラメータが負の場合、結果も負になります。無限大または NaN の場合、結果も無限大または NaN になります（つまり、ランダムではありません）。

generateDouble() およびbounded(quint64)も参照してください 。

int QRandomGenerator::bounded(int highest)

0（含む）からhighest （除く）の範囲内の32ビットの乱数を1つ生成します。highest は正の値でなければなりません。

なお、この関数では int の 32 ビット全範囲の値を取得することはできません。その場合は、generate() を使用し、int にキャストしてください。

generate()、generate64()、およびgenerateDouble()も参照してください 。

qint64 QRandomGenerator::bounded(qint64 highest)

0（0を含む）からhighest （ を含まない）の範囲内の64ビットの乱数を1つ生成します。highest は正の値でなければなりません。

なお、この関数ではqint64 の64ビット全範囲の値を取得することはできません。その場合は、generate64() を使用してqint64型にキャストするか、あるいはこの関数の符号なしバージョンを使用してください。

関連項目： generate()、generate64()、およびgenerateDouble()。

quint32 QRandomGenerator::bounded(quint32 highest)

0（含む）からhighest （除く）の範囲内の32ビットの乱数を1つ生成します。同じ結果は、 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ビットの乱数を1つ生成します。以下の方法でも同じ結果が得られます。 std::uniform_int_distribution<quint64> パラメータに 0 とhighest - 1 を指定して呼び出すことでも、同じ結果が得られます。

なお、この関数ではquint64 の64ビット全範囲の値を取得することはできません。その場合は、generate64()を使用してください。

generate()、generate64()、およびgenerateDouble()も参照してください 。

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

lowest （両端を含む）からhighest （ を除く）の範囲内の32ビットの乱数を1つ生成します。 と はいずれも負の値をとることができますが、highest はlowest より大きくなければなりません。

なお、この関数では int の 32 ビットの全範囲にわたる値を取得することはできません。その場合は、generate() を使用し、int にキャストしてください。

generate()、generate64()、およびgenerateDouble()も参照してください 。

この関数は、パラメータの型が完全に一致しない場合のオーバーロードの解決を支援するために存在します。この関数では、小さい方の型を大きい方の型に昇格させ、適切なオーバーロードを呼び出します。

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

lowest （両端を含む）からhighest （ は含まない）の範囲内の64ビットのランダムな値を1つ生成します。両値とも負の値となる可能性がありますが、highest はlowest より大きくなければなりません。

なお、この関数では、qint64 の全64ビット範囲の値を取得することはできません。その場合は、generate64() を使用し、qint64 にキャストしてください。

generate()、generate64()、およびgenerateDouble()も参照してください 。

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

lowest （両端を含む）からhighest （ を除く）までの範囲で、32ビットの乱数を1つ生成します。highest パラメータは、lowest より大きくなければなりません。

同じ結果は、 std::uniform_int_distributionlowest および\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)

lowest （両端を含む）からhighest （ を含まない）の範囲内の64ビットの乱数を1つ生成します。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 配列に格納します。これは、乱数生成ソースへの呼び出し回数を減らすことができるため、一度に複数の数値を取得する最も効率的な方法です。

たとえば、2つの32ビットの値を生成するには、次のように記述します。

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

generate64() を 1 回呼び出し、64 ビット値の 2 つの半分に分割する方法も可能です。

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 ビット分のデータのみで初期化されます。それ以外のビットはすべて 0 になります。この範囲を 64 ビットの量で埋めるには、次のように記述します:

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

範囲が連続したメモリ（配列やQList からのデータなど）を指す場合は、fillRange()関数も使用できます。

fillRange()も参照してください 。

double QRandomGenerator::generateDouble()

標準範囲 [0, 1)（つまり、0 を含み、1 を含まない）内の qreal を 1 つ生成します。

この関数は、以下と同等です：

    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()

securelySeeded() を使用してシードが設定された、共有QRandomGenerator へのポインタを返します。この関数は、特定の用途向けに安全にシードされた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 OS（Darwin）、BSD、Linux、Windows。他のオペレーティングシステムにおいても同様である可能性があります。

また、これらの機能は、真のハードウェア乱数生成器によって支えられている可能性もあります。そのため、この関数が返すQRandomGenerator は、大量のデータ生成には使用しないでください。代わりに、QRandomGenerator や、<random>ヘッダーのランダムエンジンのシードとして使用してください。

この関数が返すオブジェクトはスレッドセーフであり、ロックなしで任意のスレッドで使用できます。また、このオブジェクトをコピーすることも可能で、その結果得られるQRandomGenerator もオペレーティングシステムの機能にアクセスしますが、同じシーケンスを生成することはありません。

注： この関数はスレッドセーフです。

関連項目: securelySeeded() およびglobal()。

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

32ビットの乱数を生成し、それを返します。

generate() およびgenerate64()も参照してください 。