From 984ad6124992c9831f57c2776aa2ed0a760149e6 Mon Sep 17 00:00:00 2001 From: Simon Hausmann Date: Tue, 10 Oct 2017 09:42:41 +0200 Subject: Improve readability of code that uses the Qt signed size type During the container BoF session at the Qt Contributor Summit 2017 the name of the signed size type became a subject of discussion in the context of readability of code using this type and the intention of using it for all length, size and count properties throughout the entire framework in future versions of Qt. This change proposes qsizetype as new name for qssize_t to emphasize the readability of code over POSIX compatibility, the former being potentially more relevant than the latter to the majority of users of Qt. Change-Id: Idb99cb4a8782703c054fa463a9e5af23a918e7f3 Reviewed-by: Samuel Gaist Reviewed-by: David Faure --- src/corelib/global/qrandom.cpp | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) (limited to 'src/corelib/global/qrandom.cpp') diff --git a/src/corelib/global/qrandom.cpp b/src/corelib/global/qrandom.cpp index 72ac8d332b..6769190335 100644 --- a/src/corelib/global/qrandom.cpp +++ b/src/corelib/global/qrandom.cpp @@ -93,7 +93,7 @@ DECLSPEC_IMPORT BOOLEAN WINAPI SystemFunction036(PVOID RandomBuffer, ULONG Rando QT_BEGIN_NAMESPACE #if defined(Q_PROCESSOR_X86) && QT_COMPILER_SUPPORTS_HERE(RDRND) -static qssize_t qt_random_cpu(void *buffer, qssize_t count) Q_DECL_NOTHROW; +static qsizetype qt_random_cpu(void *buffer, qsizetype count) Q_DECL_NOTHROW; # ifdef Q_PROCESSOR_X86_64 # define _rdrandXX_step _rdrand64_step @@ -101,7 +101,7 @@ static qssize_t qt_random_cpu(void *buffer, qssize_t count) Q_DECL_NOTHROW; # define _rdrandXX_step _rdrand32_step # endif -static QT_FUNCTION_TARGET(RDRND) qssize_t qt_random_cpu(void *buffer, qssize_t count) Q_DECL_NOTHROW +static QT_FUNCTION_TARGET(RDRND) qsizetype qt_random_cpu(void *buffer, qsizetype count) Q_DECL_NOTHROW { unsigned *ptr = reinterpret_cast(buffer); unsigned *end = ptr + count; @@ -122,7 +122,7 @@ out: return ptr - reinterpret_cast(buffer); } #else -static qssize_t qt_random_cpu(void *, qssize_t) +static qsizetype qt_random_cpu(void *, qsizetype) { return 0; } @@ -136,10 +136,10 @@ enum { struct QRandomGenerator::SystemGenerator { #if QT_CONFIG(getentropy) - static qssize_t fillBuffer(void *buffer, qssize_t count) Q_DECL_NOTHROW + static qsizetype fillBuffer(void *buffer, qsizetype count) Q_DECL_NOTHROW { // getentropy can read at most 256 bytes, so break the reading - qssize_t read = 0; + qsizetype read = 0; while (count - read > 256) { // getentropy can't fail under normal circumstances int ret = getentropy(reinterpret_cast(buffer) + read, 256); @@ -195,24 +195,24 @@ struct QRandomGenerator::SystemGenerator Q_DECL_CONSTEXPR SystemGenerator() : fdp1 Q_BASIC_ATOMIC_INITIALIZER(0) {} - qssize_t fillBuffer(void *buffer, qssize_t count) + qsizetype fillBuffer(void *buffer, qsizetype count) { int fd = openDevice(); if (Q_UNLIKELY(fd < 0)) return 0; qint64 n = qt_safe_read(fd, buffer, count); - return qMax(n, 0); // ignore any errors + return qMax(n, 0); // ignore any errors } #elif defined(Q_OS_WIN) && !defined(Q_OS_WINRT) - qssize_t fillBuffer(void *buffer, qssize_t count) Q_DECL_NOTHROW + qsizetype fillBuffer(void *buffer, qsizetype count) Q_DECL_NOTHROW { auto RtlGenRandom = SystemFunction036; return RtlGenRandom(buffer, ULONG(count)) ? count: 0; } #elif defined(Q_OS_WINRT) - qssize_t fillBuffer(void *, qssize_t) Q_DECL_NOTHROW + qsizetype fillBuffer(void *, qsizetype) Q_DECL_NOTHROW { // always use the fallback return 0; @@ -243,7 +243,7 @@ struct QRandomGenerator::SystemGenerator #if defined(Q_OS_WIN) static void fallback_update_seed(unsigned) {} -static void fallback_fill(quint32 *ptr, qssize_t left) Q_DECL_NOTHROW +static void fallback_fill(quint32 *ptr, qsizetype left) Q_DECL_NOTHROW { // on Windows, rand_s is a high-quality random number generator // and it requires no seeding @@ -255,14 +255,14 @@ static void fallback_fill(quint32 *ptr, qssize_t left) Q_DECL_NOTHROW } #elif QT_CONFIG(getentropy) static void fallback_update_seed(unsigned) {} -static void fallback_fill(quint32 *, qssize_t) Q_DECL_NOTHROW +static void fallback_fill(quint32 *, qsizetype) Q_DECL_NOTHROW { // no fallback necessary, getentropy cannot fail under normal circumstances Q_UNREACHABLE(); } #elif defined(Q_OS_BSD4) static void fallback_update_seed(unsigned) {} -static void fallback_fill(quint32 *ptr, qssize_t left) Q_DECL_NOTHROW +static void fallback_fill(quint32 *ptr, qsizetype left) Q_DECL_NOTHROW { // BSDs have arc4random(4) and these work even in chroot(2) arc4random_buf(ptr, left * sizeof(*ptr)); @@ -281,7 +281,7 @@ Q_NEVER_INLINE #ifdef Q_CC_GNU __attribute__((cold)) // this function is pretty big, so optimize for size #endif -static void fallback_fill(quint32 *ptr, qssize_t left) Q_DECL_NOTHROW +static void fallback_fill(quint32 *ptr, qsizetype left) Q_DECL_NOTHROW { quint32 scratch[12]; // see element count below quint32 *end = scratch; @@ -358,7 +358,7 @@ Q_NEVER_INLINE void QRandomGenerator::SystemGenerator::generate(quint32 *begin, Q_DECL_NOEXCEPT_EXPR(FillBufferNoexcept) { quint32 *buffer = begin; - qssize_t count = end - begin; + qsizetype count = end - begin; if (Q_UNLIKELY(uint(qt_randomdevice_control) & SetRandomData)) { uint value = uint(qt_randomdevice_control) & RandomDataMask; @@ -366,14 +366,14 @@ Q_NEVER_INLINE void QRandomGenerator::SystemGenerator::generate(quint32 *begin, return; } - qssize_t filled = 0; + qsizetype filled = 0; if (qt_has_hwrng() && (uint(qt_randomdevice_control) & SkipHWRNG) == 0) filled += qt_random_cpu(buffer, count); if (filled != count && (uint(qt_randomdevice_control) & SkipSystemRNG) == 0) { - qssize_t bytesFilled = - fillBuffer(buffer + filled, (count - filled) * qssize_t(sizeof(*buffer))); - filled += bytesFilled / qssize_t(sizeof(*buffer)); + qsizetype bytesFilled = + fillBuffer(buffer + filled, (count - filled) * qsizetype(sizeof(*buffer))); + filled += bytesFilled / qsizetype(sizeof(*buffer)); } if (filled) fallback_update_seed(*buffer); @@ -677,7 +677,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel */ /*! - \fn QRandomGenerator::QRandomGenerator(const quint32 *seedBuffer, qssize_t len) + \fn QRandomGenerator::QRandomGenerator(const quint32 *seedBuffer, qsizetype len) \overload Initializes this QRandomGenerator object with \a len values found in @@ -853,7 +853,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel */ /*! - \fn void QRandomGenerator::fillRange(UInt *buffer, qssize_t count) + \fn void QRandomGenerator::fillRange(UInt *buffer, qsizetype count) Generates \a count 32- or 64-bit quantities (depending on the type \c UInt) and stores them in the buffer pointed by \a buffer. This is the most -- cgit v1.2.3 From 2c6c044500a92a3a125ce4b5d936992bdf02a487 Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Fri, 24 Nov 2017 13:27:52 +0100 Subject: Fix qdoc warnings for 5.10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit src/corelib/global/qrandom.cpp:915: warning: Cannot find 'bounded(...)' in '\fn' qreal QRandomGenerator::bounded(qreal highest) src/corelib/tools/qstring.cpp:774: warning: Command '\snippet (//! [qCompareStrings-QSV-QSV])' failed at end of file 'qstring/main.cpp' src/corelib/tools/qstring.cpp:5281: warning: Cannot find 'qTrimmed(...)' in '\fn' QStringView qTrimmed(QStringView s) src/corelib/tools/qstring.cpp:5281: warning: Cannot find 'qTrimmed(...)' in '\fn' QLatin1String qTrimmed(QLatin1String s) src/corelib/global/qrandom.h:171: warning: No documentation for 'QRandomGenerator::System' src/corelib/global/qrandom.h:105: warning: No documentation for 'QRandomGenerator::bounded(double highest)' src/corelib/global/qrandom.h:84: warning: No documentation for 'QRandomGenerator::generate64()' src/corelib/global/qrandom.h:77: warning: No documentation for 'QRandomGenerator::generate()' src/corelib/global/qrandom.cpp:799: warning: No such parameter 'sseq' in QRandomGenerator::seed() src/corelib/global/qrandom.cpp:1096: warning: Can't link to 'operator()()' src/corelib/tools/qstring.cpp:8982: warning: Can't link to 'qStartsWith()' src/corelib/tools/qstring.cpp:9203: warning: Can't link to 'qTrimmed()' src/corelib/tools/qstring.cpp:4798: warning: Can't link to 'qConvertToLatin1()' src/corelib/tools/qstring.cpp:4825: warning: Can't link to 'qConvertToLocal8Bit()' src/corelib/tools/qstring.cpp:4928: warning: Can't link to 'qConvertToUcs4()' src/corelib/tools/qstring.cpp:4884: warning: Can't link to 'qConvertToUtf8()' Change-Id: I5c7c89b230d3d1de8a679c10833319a470a44e80 Reviewed-by: Mårten Nordheim Reviewed-by: Thiago Macieira --- src/corelib/global/qrandom.cpp | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) (limited to 'src/corelib/global/qrandom.cpp') diff --git a/src/corelib/global/qrandom.cpp b/src/corelib/global/qrandom.cpp index 72ac8d332b..b6e8e03909 100644 --- a/src/corelib/global/qrandom.cpp +++ b/src/corelib/global/qrandom.cpp @@ -655,6 +655,11 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel \sa QRandomGenerator64, qrand() */ +/*! + \enum QRandomGenerator::System + \internal +*/ + /*! \fn QRandomGenerator::QRandomGenerator(quint32 seedValue) @@ -694,7 +699,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel */ /*! - \fn QRandomGenerator::QRandomGenerator(const quint32 *begin, const quin32 *end) + \fn QRandomGenerator::QRandomGenerator(const quint32 *begin, const quint32 *end) \overload Initializes this QRandomGenerator object with the values found in the range @@ -762,7 +767,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel A typedef to the type that operator()() returns. That is, quint32. - \sa operator()() + \sa {QRandomGenerator::operator()}{operator()()} */ /*! @@ -773,6 +778,22 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel \sa generate(), generate64() */ +/*! + \fn quint32 QRandomGenerator::generate() + + Generates a 32-bit random quantity and returns it. + + \sa {QRandomGenerator::operator()}{operator()()}, generate64() + */ + +/*! + \fn quint64 QRandomGenerator::generate64() + + Generates a 64-bit random quantity and returns it. + + \sa {QRandomGenerator::operator()}{operator()()}, generate() + */ + /*! \fn result_type QRandomGenerator::min() @@ -800,7 +821,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel \fn void QRandomGenerator::seed(std::seed_seq &seed) \overload - Reseeds this object using the seed sequence \a sseq as the seed. + Reseeds this object using the seed sequence \a seed as the seed. */ /*! @@ -913,9 +934,9 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel */ /*! - \fn qreal QRandomGenerator::bounded(qreal highest) + \fn double QRandomGenerator::bounded(double highest) - Generates one random qreal in the range between 0 (inclusive) and \a + Generates one random double in the range between 0 (inclusive) and \a highest (exclusive). This function is equivalent to and is implemented as: \code @@ -1098,7 +1119,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel A typedef to the type that operator()() returns. That is, quint64. - \sa operator()() + \sa {QRandomGenerator64::operator()}{operator()()} */ /*! -- cgit v1.2.3 From f95d64d075f8986919db216f7ca44930c37f4ec6 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Thu, 7 Dec 2017 13:55:50 -0800 Subject: Doc: attempt to fix some qdoc errors for QRandomGenerator This fixes only those that look fixable. There are a number of errors in the online documentation that look like qdoc tool bugs, like missing functions (operator==) and documentation text that does not exist in the source code. This fixes: - QRandomGenerator(System) constructor showing up - Links for C++ reference documentation not showing up as links Change-Id: I9e2892cb6c374e93bcb7fffd14fe21db5a6969d9 Reviewed-by: Martin Smith --- src/corelib/global/qrandom.cpp | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'src/corelib/global/qrandom.cpp') diff --git a/src/corelib/global/qrandom.cpp b/src/corelib/global/qrandom.cpp index 5cb3e75791..0ee6ac9f38 100644 --- a/src/corelib/global/qrandom.cpp +++ b/src/corelib/global/qrandom.cpp @@ -847,7 +847,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel \endcode This function complies with the requirements for the function - \c{\l{http://en.cppreference.com/w/cpp/numeric/random/seed_seq/generate}{std::seed_seq::generate}}, + \l{http://en.cppreference.com/w/cpp/numeric/random/seed_seq/generate}{\c std::seed_seq::generate}, which requires unsigned 32-bit integer values. Note that if the [begin, end) range refers to an area that can store more @@ -927,7 +927,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel \endcode The same may also be obtained by using - \c{\l{http://en.cppreference.com/w/cpp/numeric/random/uniform_real_distribution}{std::uniform_real_distribution}} + \l{http://en.cppreference.com/w/cpp/numeric/random/uniform_real_distribution}{\c std::uniform_real_distribution} with parameters 0 and 1. \sa generate(), generate64(), bounded() @@ -952,7 +952,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel Generates one random 32-bit quantity in the range between 0 (inclusive) and \a highest (exclusive). The same result may also be obtained by using - \c{\l{http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution}{std::uniform_int_distribution}} + \l{http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution}{\c std::uniform_int_distribution} with parameters 0 and \c{highest - 1}. That class can also be used to obtain quantities larger than 32 bits. @@ -990,7 +990,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel Generates one random 32-bit quantity in the range between \a lowest (inclusive) and \a highest (exclusive). The same result may also be obtained by using - \c{\l{http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution}{std::uniform_int_distribution}} + \l{http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution}{\c std::uniform_int_distribution} with parameters \a lowest and \c{\a highest - 1}. That class can also be used to obtain quantities larger than 32 bits. @@ -1190,7 +1190,9 @@ QRandomGenerator64 QRandomGenerator64::securelySeeded() return result; } -/// \internal +/*! + \internal +*/ inline QRandomGenerator::QRandomGenerator(System) : type(SystemRNG) { -- cgit v1.2.3