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>

4 files changed, 63 insertions, 45 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;