QRandomGenerator: update API to better name

"generate" is better than "get", and we already have "generate(it, it)"
which uses std::generate(). This changes:

 - get32()    →   generate()
 - get64()    →   generate64() and QRandomGenerator64::generate()
 - getReal()  →   generateDouble()

Change-Id: I6e1fe42ae4b742a7b811fffd14e5d7bd69abcdb3
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

5 files changed, 91 insertions, 73 deletions

diff --git a/src/corelib/global/qrandom.cpp b/src/corelib/global/qrandom.cpp
index 395bf0b0cb..2247394363 100644
--- a/src/corelib/global/qrandom.cpp
+++ b/src/corelib/global/qrandom.cpp
@@ -458,14 +458,14 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
     reliable sequence, which may be needed for debugging.
 
     The class can generate 32-bit or 64-bit quantities, or fill an array of
-    those. The most common way of generating new values is to call the get32(),
+    those. The most common way of generating new values is to call the generate(),
     get64() or fillRange() functions. One would use it as:
 
     \code
-        quint32 value = QRandomGenerator::get32();
+        quint32 value = QRandomGenerator::generate();
     \endcode
 
-    Additionally, it provides a floating-point function getReal() that returns
+    Additionally, it provides a floating-point function generateDouble() that returns
     a number in the range [0, 1) (that is, inclusive of zero and exclusive of
     1). There's also a set of convenience functions that facilitate obtaining a
     random number in a bounded, integral range.
@@ -567,7 +567,7 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
 
     Generates a 32-bit random quantity and returns it.
 
-    \sa QRandomGenerator::get32(), QRandomGenerator::get64()
+    \sa QRandomGenerator::generate(), QRandomGenerator::generate64()
  */
 
 /*!
@@ -611,7 +611,7 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
     and \a end. This function is equivalent to (and is implemented as):
 
     \code
-        std::generate(begin, end, []() { return get32(); });
+        std::generate(begin, end, []() { return generate(); });
     \endcode
 
     This function complies with the requirements for the function
@@ -683,7 +683,7 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
  */
 
 /*!
-    \fn qreal QRandomGenerator::getReal()
+    \fn qreal QRandomGenerator::generateReal()
 
     Generates one random qreal in the canonical range [0, 1) (that is,
     inclusive of zero and exclusive of 1).
@@ -698,7 +698,7 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
     \c{\l{http://en.cppreference.com/w/cpp/numeric/random/uniform_real_distribution}{std::uniform_real_distribution}}
     with parameters 0 and 1.
 
-    \sa get32(), get64(), bounded()
+    \sa generate(), get64(), bounded()
  */
 
 /*!
@@ -708,10 +708,10 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
     sup (exclusive). This function is equivalent to and is implemented as:
 
     \code
-        return getReal() * sup;
+        return generateDouble() * sup;
     \endcode
 
-    \sa getReal(), bounded()
+    \sa generateDouble(), bounded()
  */
 
 /*!
@@ -730,13 +730,13 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
         quint32 v = QRandomGenerator::bounded(256);
     \endcode
 
-    Naturally, the same could also be obtained by masking the result of get32()
+    Naturally, the same could also be obtained by masking the result of generate()
     to only the lower 8 bits. Either solution is as efficient.
 
     Note that this function cannot be used to obtain values in the full 32-bit
-    range of quint32. Instead, use get32().
+    range of quint32. Instead, use generate().
 
-    \sa get32(), get64(), getReal()
+    \sa generate(), get64(), generateDouble()
  */
 
 /*!
@@ -747,9 +747,9 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
     \a sup (exclusive). \a sup must not be negative.
 
     Note that this function cannot be used to obtain values in the full 32-bit
-    range of int. Instead, use get32() and cast to int.
+    range of int. Instead, use generate() and cast to int.
 
-    \sa get32(), get64(), getReal()
+    \sa generate(), get64(), generateDouble()
  */
 
 /*!
@@ -771,9 +771,9 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
 
 
     Note that this function cannot be used to obtain values in the full 32-bit
-    range of quint32. Instead, use get32().
+    range of quint32. Instead, use generate().
 
-    \sa get32(), get64(), getReal()
+    \sa generate(), get64(), generateDouble()
  */
 
 /*!
@@ -784,9 +784,9 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
     (inclusive) and \a sup (exclusive), both of which may be negative.
 
     Note that this function cannot be used to obtain values in the full 32-bit
-    range of int. Instead, use get32() and cast to int.
+    range of int. Instead, use generate() and cast to int.
 
-    \sa get32(), get64(), getReal()
+    \sa generate(), get64(), generateDouble()
  */
 
 /*!
@@ -798,7 +798,7 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
     from a high-quality, seed-less Random Number Generator.
 
     QRandomGenerator64 is a simple adaptor class around QRandomGenerator, making the
-    QRandomGenerator::get64() function the default for operator()(), instead of the
+    QRandomGenerator::generate64() function the default for operator()(), instead of the
     function that returns 32-bit quantities. This class is intended to be used
     in conjunction with Standard Library algorithms that need 64-bit quantities
     instead of 32-bit ones.
@@ -824,11 +824,28 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
  */
 
 /*!
+    \fn quint64 QRandomGenerator64::generate()
+
+    Generates one 64-bit random value and returns it.
+
+    Note about casting to a signed integer: all bits returned by this function
+    are random, so there's a 50% chance that the most significant bit will be
+    set. If you wish to cast the returned value to qint64 and keep it positive,
+    you should mask the sign bit off:
+
+    \code
+        qint64 value = QRandomGenerator64::generate() & std::numeric_limits<qint64>::max();
+    \endcode
+
+    \sa QRandomGenerator, QRandomGenerator::generate64()
+ */
+
+/*!
     \fn result_type QRandomGenerator64::operator()()
 
     Generates a 64-bit random quantity and returns it.
 
-    \sa QRandomGenerator::get32(), QRandomGenerator::get64()
+    \sa QRandomGenerator::generate(), QRandomGenerator::generate64()
  */
 
 /*!
@@ -874,12 +891,12 @@ static Q_NEVER_INLINE void fill(void *buffer, void *bufferEnd)
     you should mask the sign bit off:
 
     \code
-        int value = QRandomGenerator::get32() & std::numeric_limits<int>::max();
+        int value = QRandomGenerator::generate() & std::numeric_limits<int>::max();
     \endcode
 
-    \sa get64(), getReal()
+    \sa get64(), generateDouble()
  */
-quint32 QRandomGenerator::get32()
+quint32 QRandomGenerator::generate()
 {
     quint32 ret;
     fill(&ret, &ret + 1);
@@ -895,12 +912,12 @@ quint32 QRandomGenerator::get32()
     you should mask the sign bit off:
 
     \code
-        qint64 value = QRandomGenerator::get64() & std::numeric_limits<qint64>::max();
+        qint64 value = QRandomGenerator::generate64() & std::numeric_limits<qint64>::max();
     \endcode
 
-    \sa get32(), getReal(), QRandomGenerator64
+    \sa generate(), generateDouble(), QRandomGenerator64
  */
-quint64 QRandomGenerator::get64()
+quint64 QRandomGenerator::generate64()
 {
     quint64 ret;
     fill(&ret, &ret + 1);
diff --git a/src/corelib/global/qrandom.h b/src/corelib/global/qrandom.h
index 3bede87fa6..7f96cd6749 100644
--- a/src/corelib/global/qrandom.h
+++ b/src/corelib/global/qrandom.h
@@ -53,29 +53,27 @@ class QRandomGenerator
 public:
     QRandomGenerator() = default;
 
-    static Q_CORE_EXPORT quint32 get32();
-    static Q_CORE_EXPORT quint64 get64();
-    static qreal getReal()
+    // ### REMOVE BEFORE 5.10
+    static quint32 get32() { return generate(); }
+    static quint64 get64() { return generate64(); }
+    static qreal getReal() { return generateDouble(); }
+
+    static Q_CORE_EXPORT quint32 generate();
+    static Q_CORE_EXPORT quint64 generate64();
+    static double generateDouble()
     {
-        const int digits = std::numeric_limits<qreal>::digits;
-        if (digits < std::numeric_limits<quint32>::digits) {
-            // use get32()
-            return qreal(get32()) / ((max)() + qreal(1.0));
-        } else {
-            // use get64()
-            // we won't have enough bits for a __float128 though
-            return qreal(get64()) / ((std::numeric_limits<quint64>::max)() + qreal(1.0));
-        }
+        // use get64() to get enough bits
+        return double(generate64()) / ((std::numeric_limits<quint64>::max)() + double(1.0));
     }
 
     static qreal bounded(qreal sup)
     {
-        return getReal() * sup;
+        return generateDouble() * sup;
     }
 
     static quint32 bounded(quint32 sup)
     {
-        quint64 value = get32();
+        quint64 value = generate();
         value *= sup;
         value /= (max)() + quint64(1);
         return quint32(value);
@@ -112,7 +110,8 @@ public:
     template <typename ForwardIterator>
     void generate(ForwardIterator begin, ForwardIterator end)
     {
-        std::generate(begin, end, &QRandomGenerator::get32);
+        auto generator = static_cast<quint32 (*)()>(&QRandomGenerator::generate);
+        std::generate(begin, end, generator);
     }
 
     void generate(quint32 *begin, quint32 *end)
@@ -122,7 +121,7 @@ public:
 
     // API like std::random_device
     typedef quint32 result_type;
-    result_type operator()() { return get32(); }
+    result_type operator()() { return generate(); }
     double entropy() const Q_DECL_NOTHROW { return 0.0; }
     static Q_DECL_CONSTEXPR result_type min() { return (std::numeric_limits<result_type>::min)(); }
     static Q_DECL_CONSTEXPR result_type max() { return (std::numeric_limits<result_type>::max)(); }
@@ -137,9 +136,11 @@ class QRandomGenerator64
 public:
     QRandomGenerator64() = default;
 
+    static quint64 generate() { return QRandomGenerator::generate64(); }
+
     // API like std::random_device
     typedef quint64 result_type;
-    result_type operator()() { return QRandomGenerator::get64(); }
+    result_type operator()() { return QRandomGenerator::generate64(); }
     double entropy() const Q_DECL_NOTHROW { return 0.0; }
     static Q_DECL_CONSTEXPR result_type min() { return (std::numeric_limits<result_type>::min)(); }
     static Q_DECL_CONSTEXPR result_type max() { return (std::numeric_limits<result_type>::max)(); }
diff --git a/src/corelib/io/qtemporaryfile.cpp b/src/corelib/io/qtemporaryfile.cpp
index 3ecc24a5db..5865d9e19a 100644
--- a/src/corelib/io/qtemporaryfile.cpp
+++ b/src/corelib/io/qtemporaryfile.cpp
@@ -165,7 +165,7 @@ QFileSystemEntry::NativePath QTemporaryFileName::generateNext()
 
         Char *rIter = placeholderEnd;
         while (rIter != placeholderStart) {
-            quint32 rnd = QRandomGenerator::get32();
+            quint32 rnd = QRandomGenerator::generate();
             auto applyOne = [&]() {
                 quint32 v = rnd & ((1 << BitsPerCharacter) - 1);
                 rnd >>= BitsPerCharacter;
diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp
index e336b7e618..485c6591c2 100644
--- a/src/corelib/tools/qhash.cpp
+++ b/src/corelib/tools/qhash.cpp
@@ -296,7 +296,7 @@ static uint qt_create_qhash_seed()
         return seed;
     }
 
-    seed = QRandomGenerator::get32();
+    seed = QRandomGenerator::generate();
 #endif // QT_BOOTSTRAPPED
 
     return seed;
diff --git a/tests/auto/corelib/global/qrandomgenerator/tst_qrandomgenerator.cpp b/tests/auto/corelib/global/qrandomgenerator/tst_qrandomgenerator.cpp
index 71c6c4e9cd..bf43f6d710 100644
--- a/tests/auto/corelib/global/qrandomgenerator/tst_qrandomgenerator.cpp
+++ b/tests/auto/corelib/global/qrandomgenerator/tst_qrandomgenerator.cpp
@@ -73,37 +73,37 @@ public slots:
     void cleanup() { setRNGControl(0); }
 
 private slots:
-    void get32_data();
-    void get32();
-    void get64_data() { get32_data(); }
-    void get64();
-    void quality_data() { get32_data(); }
+    void generate32_data();
+    void generate32();
+    void generate64_data() { generate32_data(); }
+    void generate64();
+    void quality_data() { generate32_data(); }
     void quality();
-    void fillRangeUInt_data() { get32_data(); }
+    void fillRangeUInt_data() { generate32_data(); }
     void fillRangeUInt();
-    void fillRangeULong_data() { get32_data(); }
+    void fillRangeULong_data() { generate32_data(); }
     void fillRangeULong();
-    void fillRangeULLong_data() { get32_data(); }
+    void fillRangeULLong_data() { generate32_data(); }
     void fillRangeULLong();
-    void generateUInt_data() { get32_data(); }
+    void generateUInt_data() { generate32_data(); }
     void generateUInt();
-    void generateULLong_data() { get32_data(); }
+    void generateULLong_data() { generate32_data(); }
     void generateULLong();
-    void generateNonContiguous_data() { get32_data(); }
+    void generateNonContiguous_data() { generate32_data(); }
     void generateNonContiguous();
 
     void bounded_data();
     void bounded();
-    void boundedQuality_data() { get32_data(); }
+    void boundedQuality_data() { generate32_data(); }
     void boundedQuality();
 
-    void getReal_data() { get32_data(); }
-    void getReal();
+    void generateReal_data() { generate32_data(); }
+    void generateReal();
 
     void seedStdRandomEngines();
     void stdUniformIntDistribution_data();
     void stdUniformIntDistribution();
-    void stdGenerateCanonical_data() { getReal_data(); }
+    void stdGenerateCanonical_data() { generateReal_data(); }
     void stdGenerateCanonical();
     void stdUniformRealDistribution_data();
     void stdUniformRealDistribution();
@@ -114,7 +114,7 @@ using namespace std;
 QT_WARNING_DISABLE_GCC("-Wfloat-equal")
 QT_WARNING_DISABLE_CLANG("-Wfloat-equal")
 
-void tst_QRandomGenerator::get32_data()
+void tst_QRandomGenerator::generate32_data()
 {
     QTest::addColumn<uint>("control");
     QTest::newRow("default") << 0U;
@@ -127,42 +127,42 @@ void tst_QRandomGenerator::get32_data()
 #endif
 }
 
-void tst_QRandomGenerator::get32()
+void tst_QRandomGenerator::generate32()
 {
     QFETCH(uint, control);
     setRNGControl(control);
 
     for (int i = 0; i < 4; ++i) {
         QVERIFY_3TIMES([] {
-            quint32 value = QRandomGenerator::get32();
+            quint32 value = QRandomGenerator::generate();
             return value != 0 && value != RandomValue32;
         }());
     }
 
     // and should hopefully be different from repeated calls
     for (int i = 0; i < 4; ++i)
-        QVERIFY_3TIMES(QRandomGenerator::get32() != QRandomGenerator::get32());
+        QVERIFY_3TIMES(QRandomGenerator::generate() != QRandomGenerator::generate());
 }
 
-void tst_QRandomGenerator::get64()
+void tst_QRandomGenerator::generate64()
 {
     QFETCH(uint, control);
     setRNGControl(control);
 
     for (int i = 0; i < 4; ++i) {
         QVERIFY_3TIMES([] {
-            quint64 value = QRandomGenerator::get32();
+            quint64 value = QRandomGenerator::generate();
             return value != 0 && value != RandomValue32 && value != RandomValue64;
         }());
     }
 
     // and should hopefully be different from repeated calls
     for (int i = 0; i < 4; ++i)
-        QVERIFY_3TIMES(QRandomGenerator::get64() != QRandomGenerator::get64());
+        QVERIFY_3TIMES(QRandomGenerator::generate64() != QRandomGenerator::generate64());
     for (int i = 0; i < 4; ++i)
-        QVERIFY_3TIMES(QRandomGenerator::get32() != quint32(QRandomGenerator::get64()));
+        QVERIFY_3TIMES(QRandomGenerator::generate() != quint32(QRandomGenerator::generate64()));
     for (int i = 0; i < 4; ++i)
-        QVERIFY_3TIMES(QRandomGenerator::get32() != (QRandomGenerator::get64() >> 32));
+        QVERIFY_3TIMES(QRandomGenerator::generate() != (QRandomGenerator::generate64() >> 32));
 }
 
 void tst_QRandomGenerator::quality()
@@ -200,7 +200,7 @@ void tst_QRandomGenerator::quality()
         // test the quality of the generator
         quint32 buffer[BufferCount];
         memset(buffer, 0xcc, sizeof(buffer));
-        generate_n(buffer, +BufferCount, [] { return QRandomGenerator::get32(); });
+        generate_n(buffer, +BufferCount, [] { return QRandomGenerator::generate(); });
 
         quint8 *ptr = reinterpret_cast<quint8 *>(buffer);
         quint8 *end = ptr + sizeof(buffer);
@@ -439,21 +439,21 @@ void tst_QRandomGenerator::boundedQuality()
              << "at" << std::min_element(begin(histogram), end(histogram)) - histogram;
 }
 
-void tst_QRandomGenerator::getReal()
+void tst_QRandomGenerator::generateReal()
 {
     QFETCH(uint, control);
     setRNGControl(control);
 
     for (int i = 0; i < 4; ++i) {
         QVERIFY_3TIMES([] {
-            qreal value = QRandomGenerator::getReal();
+            qreal value = QRandomGenerator::generateDouble();
             return value > 0 && value < 1 && value != RandomValueFP;
         }());
     }
 
     // and should hopefully be different from repeated calls
     for (int i = 0; i < 4; ++i)
-        QVERIFY_3TIMES(QRandomGenerator::getReal() != QRandomGenerator::getReal());
+        QVERIFY_3TIMES(QRandomGenerator::generateDouble() != QRandomGenerator::generateDouble());
 }
 
 template <typename Engine> void seedStdRandomEngine()