diff options
Diffstat (limited to 'src/corelib/global')
| -rw-r--r-- | src/corelib/global/qglobal.cpp | 61 | ||||
| -rw-r--r-- | src/corelib/global/qlogging.cpp | 4 | ||||
| -rw-r--r-- | src/corelib/global/qnumeric.cpp | 7 | ||||
| -rw-r--r-- | src/corelib/global/qoperatingsystemversion.cpp | 12 | ||||
| -rw-r--r-- | src/corelib/global/qrandom.cpp | 81 |
5 files changed, 33 insertions, 132 deletions
diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index a369bbe490..5c1665fa00 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -3376,9 +3376,7 @@ QString qEnvironmentVariable(const char *varName) Returns whether the environment variable \a varName is empty. Equivalent to - \code - qgetenv(varName).isEmpty() - \endcode + \snippet code/src_corelib_global_qglobal.cpp is-empty except that it's potentially much faster, and can't throw exceptions. \sa qgetenv(), qEnvironmentVariable(), qEnvironmentVariableIsSet() @@ -3408,9 +3406,7 @@ bool qEnvironmentVariableIsEmpty(const char *varName) Q_DECL_NOEXCEPT on the success of the conversion. Equivalent to - \code - qgetenv(varName).toInt(ok, 0) - \endcode + \snippet code/src_corelib_global_qglobal.cpp to-int except that it's much faster, and can't throw exceptions. \note there's a limit on the length of the value, which is sufficient for @@ -3484,9 +3480,7 @@ int qEnvironmentVariableIntValue(const char *varName, bool *ok) Q_DECL_NOEXCEPT Returns whether the environment variable \a varName is set. Equivalent to - \code - !qgetenv(varName).isNull() - \endcode + \snippet code/src_corelib_global_qglobal.cpp is-null except that it's potentially much faster, and can't throw exceptions. \sa qgetenv(), qEnvironmentVariable(), qEnvironmentVariableIsEmpty() @@ -3662,37 +3656,21 @@ bool qunsetenv(const char *varName) Its main use in Qt is to prevent implicitly-shared Qt containers from detaching: - \code - QString s = ...; - for (QChar ch : s) // detaches 's' (performs a deep-copy if 's' was shared) - process(ch); - for (QChar ch : qAsConst(s)) // ok, no detach attempt - process(ch); - \endcode + \snippet code/src_corelib_global_qglobal.cpp as-const-0 Of course, in this case, you could (and probably should) have declared \c s as \c const in the first place: - \code - const QString s = ...; - for (QChar ch : s) // ok, no detach attempt on const objects - process(ch); - \endcode + \snippet code/src_corelib_global_qglobal.cpp as-const-1 but often that is not easily possible. It is important to note that qAsConst() does not copy its argument, it just performs a \c{const_cast<const T&>(t)}. This is also the reason why it is designed to fail for rvalues: The returned reference would go stale too soon. So while this works (but detaches the returned object): - \code - for (QChar ch : funcReturningQString()) - process(ch); // OK, the returned object is kept alive for the loop's duration - \endcode + \snippet code/src_corelib_global_qglobal.cpp as-const-2 this would not: - \code - for (QChar ch : qAsConst(funcReturningQString())) - process(ch); // ERROR: ch is copied from deleted memory - \endcode + \snippet code/src_corelib_global_qglobal.cpp as-const-3 To prevent this construct from compiling (and failing at runtime), qAsConst() has a second, deleted, overload which binds to rvalues. @@ -3705,10 +3683,7 @@ bool qunsetenv(const char *varName) \overload This overload is deleted to prevent a dangling reference in code like - \code - for (QChar ch : qAsConst(funcReturningQString())) - process(ch); // ERROR: ch is copied from deleted memory - \endcode + \snippet code/src_corelib_global_qglobal.cpp as-const-4 */ /*! @@ -4642,9 +4617,7 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters) purpose. It either expands to \c expr (if Qt is compiled without exception support or the compiler supports C++11 noexcept semantics) or to - \code - try { expr; } catch(...) { qTerminate(); } - \endcode + \snippet code/src_corelib_global_qglobal.cpp qterminate otherwise. Since this macro expands to just \c expr if the compiler supports @@ -4714,10 +4687,7 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters) The macro goes at the end of the function, usually after the \c{const}, if any: - \code - // generate error if this doesn't actually override anything: - virtual void MyWidget::paintEvent(QPaintEvent*) Q_DECL_OVERRIDE; - \endcode + \snippet code/src_corelib_global_qglobal.cpp qdecloverride \sa Q_DECL_FINAL */ @@ -4739,18 +4709,11 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters) The macro goes at the end of the function, usually after the \c{const}, if any: - \code - // more-derived classes no longer permitted to override this: - virtual void MyWidget::paintEvent(QPaintEvent*) Q_DECL_FINAL; - \endcode + \snippet code/src_corelib_global_qglobal.cpp qdeclfinal-1 For classes, it goes in front of the \c{:} in the class definition, if any: - \code - class QRect Q_DECL_FINAL { // cannot be derived from - // ... - }; - \endcode + \snippet code/src_corelib_global_qglobal.cpp qdeclfinal-2 \sa Q_DECL_OVERRIDE */ diff --git a/src/corelib/global/qlogging.cpp b/src/corelib/global/qlogging.cpp index a9c5d17aad..396aee8696 100644 --- a/src/corelib/global/qlogging.cpp +++ b/src/corelib/global/qlogging.cpp @@ -2062,9 +2062,7 @@ void qErrnoWarning(int code, const char *msg, ...) is not the default one. Example: - \code - QT_MESSAGE_PATTERN="[%{time yyyyMMdd h:mm:ss.zzz t} %{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}] %{file}:%{line} - %{message}" - \endcode + \snippet code/src_corelib_global_qlogging.cpp 0 The default \a pattern is "%{if-category}%{category}: %{endif}%{message}". diff --git a/src/corelib/global/qnumeric.cpp b/src/corelib/global/qnumeric.cpp index c03b139c9f..fc2b052edf 100644 --- a/src/corelib/global/qnumeric.cpp +++ b/src/corelib/global/qnumeric.cpp @@ -130,12 +130,7 @@ static inline quint32 f2i(float f) two 32-bit floating point numbers and all you need is an approximated 24-bit precision, you can use this function like this: - \code - if (qFloatDistance(a, b) < (1 << 7)) { // The last 7 bits are not - // significant - // precise enough - } - \endcode + \snippet code/src_corelib_global_qnumeric.cpp 0 \sa qFuzzyCompare() \since 5.2 diff --git a/src/corelib/global/qoperatingsystemversion.cpp b/src/corelib/global/qoperatingsystemversion.cpp index 2f8d339ca7..94dc261b41 100644 --- a/src/corelib/global/qoperatingsystemversion.cpp +++ b/src/corelib/global/qoperatingsystemversion.cpp @@ -106,20 +106,12 @@ QT_BEGIN_NAMESPACE major version number component of the object on the left hand side of the expression (10) is greater than that of the object on the right (9): - \code - QOperatingSystemVersion::current() >= QOperatingSystemVersion(QOperatingSystemVersion::IOS, 9) - \endcode + \snippet code/src_corelib_global_qoperatingsystemversion.cpp 0 This allows expressions for multiple operating systems to be joined with a logical OR operator and still work as expected. For example: - \code - auto current = QOperatingSystemVersion::current(); - if (current >= QOperatingSystemVersion::OSXYosemite || - current >= QOperatingSystemVersion(QOperatingSystemVersion::IOS, 8)) { - // returns true on macOS >= 10.10 and iOS >= 8.0, but false on macOS < 10.10 and iOS < 8.0 - } - \endcode + \snippet code/src_corelib_global_qoperatingsystemversion.cpp 1 A more naive comparison algorithm might incorrectly return true on all versions of macOS, including Mac OS 9. This behavior is achieved by overloading the comparison operators to return diff --git a/src/corelib/global/qrandom.cpp b/src/corelib/global/qrandom.cpp index a7d4aa303a..23e5e499b2 100644 --- a/src/corelib/global/qrandom.cpp +++ b/src/corelib/global/qrandom.cpp @@ -510,9 +510,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel those. The most common way of generating new values is to call the generate(), generate64() or fillRange() functions. One would use it as: - \code - quint32 value = QRandomGenerator::global()->generate(); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 0 Additionally, it provides a floating-point function generateDouble() that returns a number in the range [0, 1) (that is, inclusive of zero and @@ -525,11 +523,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel the numbers generated by the object will always be the same, as in the following example: - \code - QRandomGenerator prng1(1234), prng2(1234); - Q_ASSERT(prng1.generate() == prng2.generate()); - Q_ASSERT(prng1.generate64() == prng2.generate64()); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 1 The seed data takes the form of one or more 32-bit words. The ideal seed size is approximately equal to the size of the QRandomGenerator class @@ -552,12 +546,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel For ease of use, QRandomGenerator provides a global object that can be easily used, as in the following example: - \code - int x = QRandomGenerator::global()->generate(); - int y = QRandomGenerator::global()->generate(); - int w = QRandomGenerator::global()->bounded(16384); - int h = QRandomGenerator::global()->bounded(16384); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 2 \section1 System-wide random number generator @@ -645,10 +634,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel following code may be used to generate a floating-point number in the range [1, 2.5): - \code - std::uniform_real_distribution dist(1, 2.5); - return dist(*QRandomGenerator::global()); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 3 \sa QRandomGenerator64, qrand() */ @@ -688,10 +674,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel with the same seed value will produce the same number sequence. This constructor is equivalent to: - \code - std::seed_seq sseq(seedBuffer, seedBuffer + len); - QRandomGenerator generator(sseq); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 4 \sa seed(), securelySeeded() */ @@ -705,10 +688,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel with the same seed value will produce the same number sequence. This constructor is equivalent to: - \code - std::seed_seq sseq(begin, end); - QRandomGenerator generator(sseq); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 5 \sa seed(), securelySeeded() */ @@ -828,10 +808,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel Discards the next \a z entries from the sequence. This method is equivalent to calling generate() \a z times and discarding the result, as in: - \code - while (z--) - generator.generate(); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 6 */ /*! @@ -840,9 +817,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel Generates 32-bit quantities and stores them in the range between \a begin and \a end. This function is equivalent to (and is implemented as): - \code - std::generate(begin, end, [this]() { return generate(); }); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 7 This function complies with the requirements for the function \l{http://en.cppreference.com/w/cpp/numeric/random/seed_seq/generate}{\c std::seed_seq::generate}, @@ -853,9 +828,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel 32 bits of data. Any other bits will be zero. To fill the range with 64 bit quantities, one can write: - \code - std::generate(begin, end, []() { return QRandomGenerator::global()->generate64(); }); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 8 If the range refers to contiguous memory (such as an array or the data from a QVector), the fillRange() function may be used too. @@ -882,11 +855,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel For example, to fill a vector of 16 entries with random values, one may write: - \code - QVector<quint32> vector; - vector.resize(16); - QRandomGenerator::fillRange(vector.data(), vector.size()); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 9 \sa generate() */ @@ -901,10 +870,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel For example, to fill generate two 32-bit quantities, one may write: - \code - quint32 array[2]; - QRandomGenerator::fillRange(array); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 10 It would have also been possible to make one call to generate64() and then split the two halves of the 64-bit value. @@ -919,10 +885,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel inclusive of zero and exclusive of 1). This function is equivalent to: - \code - QRandomGenerator64 rd; - return std::generate_canonical<qreal, std::numeric_limits<qreal>::digits>(rd); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 11 The same may also be obtained by using \l{http://en.cppreference.com/w/cpp/numeric/random/uniform_real_distribution}{\c std::uniform_real_distribution} @@ -937,9 +900,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel Generates one random double in the range between 0 (inclusive) and \a highest (exclusive). This function is equivalent to and is implemented as: - \code - return generateDouble() * highest; - \endcode + \snippet code/src_corelib_global_qrandom.cpp 12 \sa generateDouble(), bounded() */ @@ -956,9 +917,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel For example, to obtain a value between 0 and 255 (inclusive), one would write: - \code - quint32 v = QRandomGenerator::bounded(256); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 13 Naturally, the same could also be obtained by masking the result of generate() to only the lower 8 bits. Either solution is as efficient. @@ -995,9 +954,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel For example, to obtain a value between 1000 (incl.) and 2000 (excl.), one would write: - \code - quint32 v = QRandomGenerator::bounded(1000, 2000); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 14 Note that this function cannot be used to obtain values in the full 32-bit @@ -1053,9 +1010,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel For example, the following creates a random RGB color: - \code - return QColor::fromRgb(QRandomGenerator::global()->generate()); - \endcode + \snippet code/src_corelib_global_qrandom.cpp 15 Accesses to this object are thread-safe and it may therefore be used in any thread without locks. The object may also be copied and the sequence @@ -1123,9 +1078,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel 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 + \snippet code/src_corelib_global_qrandom.cpp 16 \sa QRandomGenerator, QRandomGenerator::generate64() */ |