diff options
Diffstat (limited to 'src/corelib/tools')
-rw-r--r-- | src/corelib/tools/qbytearray.cpp | 27 | ||||
-rw-r--r-- | src/corelib/tools/qbytearraymatcher.cpp | 8 | ||||
-rw-r--r-- | src/corelib/tools/qcontiguouscache.cpp | 21 | ||||
-rw-r--r-- | src/corelib/tools/qhash.cpp | 28 | ||||
-rw-r--r-- | src/corelib/tools/qrect.cpp | 10 | ||||
-rw-r--r-- | src/corelib/tools/qregularexpression.cpp | 8 | ||||
-rw-r--r-- | src/corelib/tools/qshareddata.cpp | 17 | ||||
-rw-r--r-- | src/corelib/tools/qsharedpointer.cpp | 108 | ||||
-rw-r--r-- | src/corelib/tools/qstring.cpp | 18 | ||||
-rw-r--r-- | src/corelib/tools/qstringview.cpp | 13 |
10 files changed, 42 insertions, 216 deletions
diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp index b53a60b9bf..8f2ad8c012 100644 --- a/src/corelib/tools/qbytearray.cpp +++ b/src/corelib/tools/qbytearray.cpp @@ -2655,10 +2655,7 @@ QList<QByteArray> QByteArray::split(char sep) const Example: - \code - QByteArray ba("ab"); - ba.repeated(4); // returns "abababab" - \endcode + \snippet code/src_corelib_tools_qbytearray.cpp 49 */ QByteArray QByteArray::repeated(int times) const { @@ -4732,11 +4729,7 @@ QByteArray QByteArray::toHex() const If \a separator is not '\0', the separator character is inserted between the hex bytes. Example: - \code - QByteArray macAddress = QByteArray::fromHex("123456abcdef"); - macAddress.toHex(':'); // returns "12:34:56:ab:cd:ef" - macAddress.toHex(0); // returns "123456abcdef" - \endcode + \snippet code/src_corelib_tools_qbytearray.cpp 50 \sa fromHex() */ @@ -4812,10 +4805,7 @@ void q_fromPercentEncoding(QByteArray *ba) another (for instance, '_' or '='). For example: - \code - QByteArray text = QByteArray::fromPercentEncoding("Qt%20is%20great%33"); - text.data(); // returns "Qt is great!" - \endcode + \snippet code/src_corelib_tools_qbytearray.cpp 51 \note Given invalid input (such as a string containing the sequence "%G5", which is not a valid hexadecimal number) the output will be invalid as @@ -4937,12 +4927,7 @@ void q_normalizePercentEncoding(QByteArray *ba, const char *exclude) Example: - \code - QByteArray text = "{a fishy string?}"; - QByteArray ba = text.toPercentEncoding("{}", "s"); - qDebug(ba.constData()); - // prints "{a fi%73hy %73tring%3F}" - \endcode + \snippet code/src_corelib_tools_qbytearray.cpp 52 The hex encoding uses the numbers 0-9 and the uppercase letters A-F. @@ -5060,9 +5045,7 @@ QByteArray QByteArray::toPercentEncoding(const QByteArray &exclude, const QByteA For instance: - \code - QByteArray ba = QByteArrayLiteral("byte array contents"); - \endcode + \snippet code/src_corelib_tools_qbytearray.cpp 53 Using QByteArrayLiteral instead of a double quoted plain C++ string literal can significantly speed up creation of QByteArray instances from data known diff --git a/src/corelib/tools/qbytearraymatcher.cpp b/src/corelib/tools/qbytearraymatcher.cpp index a54afc5a9d..72f0e0519d 100644 --- a/src/corelib/tools/qbytearraymatcher.cpp +++ b/src/corelib/tools/qbytearraymatcher.cpp @@ -356,9 +356,7 @@ int qFindByteArray( value of that function in a \c{static const auto} variable, so you don't need to pass the \c{N} template parameter explicitly: - \code - static const auto matcher = qMakeStaticByteArrayMatcher("needle"); - \endcode + \snippet code/src_corelib_tools_qbytearraymatcher.cpp 0 Then call indexIn() on the QByteArray in which you want to search, just like with QByteArrayMatcher. @@ -430,9 +428,7 @@ int QStaticByteArrayMatcherBase::indexOfIn(const char *needle, uint nlen, const To take full advantage of this function, assign the result to an \c{auto} variable: - \code - static const auto matcher = qMakeStaticByteArrayMatcher("needle"); - \endcode + \snippet code/src_corelib_tools_qbytearraymatcher.cpp 1 */ diff --git a/src/corelib/tools/qcontiguouscache.cpp b/src/corelib/tools/qcontiguouscache.cpp index 2ded61c0be..64cbd7df4b 100644 --- a/src/corelib/tools/qcontiguouscache.cpp +++ b/src/corelib/tools/qcontiguouscache.cpp @@ -91,19 +91,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data) The simplest way of using a contiguous cache is to use the append() and prepend(). -\code -MyRecord record(int row) const -{ - Q_ASSERT(row >= 0 && row < count()); - - while(row > cache.lastIndex()) - cache.append(slowFetchRecord(cache.lastIndex()+1)); - while(row < cache.firstIndex()) - cache.prepend(slowFetchRecord(cache.firstIndex()-1)); - - return cache.at(row); -} -\endcode + \snippet code/src_corelib_tools_qcontiguouscache.cpp 0 If the cache is full then the item at the opposite end of the cache from where the new item is appended or prepended will be removed. @@ -463,12 +451,7 @@ MyRecord record(int row) const It is provided so that index overflows can be corrected when using the cache as a circular buffer. - \code - QContiguousCache<int> cache(10); - cache.insert(INT_MAX, 1); // cache contains one value and has valid indexes, INT_MAX to INT_MAX - cache.append(2); // cache contains two values but does not have valid indexes. - cache.normalizeIndexes(); // cache has two values, 1 and 2. New first index will be in the range of 0 to capacity(). - \endcode + \snippet code/src_corelib_tools_qcontiguouscache.cpp 1 \sa areIndexesValid(), append(), prepend() */ diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp index 8d2616865e..32e9a4269c 100644 --- a/src/corelib/tools/qhash.cpp +++ b/src/corelib/tools/qhash.cpp @@ -755,9 +755,7 @@ void QHashData::checkSanity() Types \c T1 and \c T2 must be supported by qHash(). \note The return type of this function is \e{not} the same as that of - \code - qHash(qMakePair(key.first, key.second), seed); - \endcode + \snippet code/src_corelib_tools_qhash.cpp 29 The two functions use different hashing algorithms; due to binary compatibility constraints, we cannot change the QPair algorithm to match the std::pair one before Qt 6. */ @@ -773,14 +771,10 @@ void QHashData::checkSanity() The return value of this function depends on the order of elements in the range. That means that - \code - {0, 1, 2} - \endcode + \snippet code/src_corelib_tools_qhash.cpp 30 and - \code - {1, 2, 0} - \endcode + \snippet code/src_corelib_tools_qhash.cpp 31 hash to \b{different} values. If order does not matter, for example for hash tables, use qHashRangeCommutative() instead. If you are hashing raw @@ -812,14 +806,10 @@ void QHashData::checkSanity() The return value of this function does not depend on the order of elements in the range. That means that - \code - {0, 1, 2} - \endcode + \snippet code/src_corelib_tools_qhash.cpp 30 and - \code - {1, 2, 0} - \endcode + \snippet code/src_corelib_tools_qhash.cpp 31 hash to the \b{same} values. If order matters, for example, for vectors and arrays, use qHashRange() instead. If you are hashing raw @@ -1177,13 +1167,7 @@ uint qHash(long double key, uint seed) Q_DECL_NOTHROW For a key type \c{K}, the qHash function must have one of these signatures: - \code - uint qHash(K key); - uint qHash(const K &key); - - uint qHash(K key, uint seed); - uint qHash(const K &key, uint seed); - \endcode + \snippet code/src_corelib_tools_qhash.cpp 32 The two-arguments overloads take an unsigned integer that should be used to seed the calculation of the hash function. This seed is provided by QHash diff --git a/src/corelib/tools/qrect.cpp b/src/corelib/tools/qrect.cpp index ad1885e8ce..6e51deebea 100644 --- a/src/corelib/tools/qrect.cpp +++ b/src/corelib/tools/qrect.cpp @@ -713,10 +713,7 @@ QRect QRect::normalized() const Q_DECL_NOTHROW Returns a copy of the rectangle that has its width and height exchanged: - \code - QRect r = {15, 51, 42, 24}; - r = r.transposed(); // r == {15, 51, 24, 42} - \endcode + \snippet code/src_corelib_tools_qrect.cpp 2 \sa QSize::transposed() */ @@ -1863,10 +1860,7 @@ QRectF QRectF::normalized() const Q_DECL_NOTHROW Returns a copy of the rectangle that has its width and height exchanged: - \code - QRectF r = {1.5, 5.1, 4.2, 2.4}; - r = r.transposed(); // r == {1.5, 5.1, 2.4, 4.2} - \endcode + \snippet code/src_corelib_tools_qrect.cpp 3 \sa QSizeF::transposed() */ diff --git a/src/corelib/tools/qregularexpression.cpp b/src/corelib/tools/qregularexpression.cpp index 1026d4ab28..fec5f620fc 100644 --- a/src/corelib/tools/qregularexpression.cpp +++ b/src/corelib/tools/qregularexpression.cpp @@ -1560,15 +1560,11 @@ int QRegularExpression::captureCount() const For instance, given the regular expression - \code - (?<day>\d\d)-(?<month>\d\d)-(?<year>\d\d\d\d) (\w+) (?<name>\w+) - \endcode + \snippet code/src_corelib_tools_qregularexpression.cpp 32 namedCaptureGroups() will return the following list: - \code - ("", "day", "month", "year", "", "name") - \endcode + \snippet code/src_corelib_tools_qregularexpression.cpp 33 which corresponds to the fact that the capturing group #0 (corresponding to the whole match) has no name, the capturing group #1 has name "day", the diff --git a/src/corelib/tools/qshareddata.cpp b/src/corelib/tools/qshareddata.cpp index f95d75c4a8..bc4291e20f 100644 --- a/src/corelib/tools/qshareddata.cpp +++ b/src/corelib/tools/qshareddata.cpp @@ -142,9 +142,7 @@ QT_BEGIN_NAMESPACE would just predeclare the private subclass \c EmployeeData in \c {employee.h} this way: - \code - class EmployeeData; - \endcode + \snippet code/src_corelib_tools_qshareddata.cpp 0 If we had done it that way here, the copy constructor shown would be required. Since the copy constructor is trivial, you might as well @@ -396,13 +394,7 @@ QT_BEGIN_NAMESPACE a template-specialization of this function for your own type, like the example below: - \code - template<> - EmployeeData *QSharedDataPointer<EmployeeData>::clone() - { - return d->clone(); - } - \endcode + \snippet code/src_corelib_tools_qshareddata.cpp 1 In the example above, the template specialization for the clone() function calls the \e {EmployeeData::clone()} virtual function. A @@ -554,10 +546,7 @@ QT_BEGIN_NAMESPACE \warning relying on such \c{static_cast} is potentially dangerous, because it allows code like this to compile: - \code - QExplicitlySharedDataPointer<Base> base(new Base); - QExplicitlySharedDataPointer<Derived> derived(base); // !!! DANGER !!! - \endcode + \snippet code/src_corelib_tools_qshareddata.cpp 2 Starting from Qt 5.4 the cast is disabled by default. It is possible to enable it back by defining the diff --git a/src/corelib/tools/qsharedpointer.cpp b/src/corelib/tools/qsharedpointer.cpp index 2d5fd2a00e..e58d3ab6bc 100644 --- a/src/corelib/tools/qsharedpointer.cpp +++ b/src/corelib/tools/qsharedpointer.cpp @@ -388,44 +388,14 @@ sharedFromThis() that return a QSharedPointer<T> and QSharedPointer<const T>, depending on constness, to \c this: - \code - class Y: public QEnableSharedFromThis<Y> - { - public: - QSharedPointer<Y> f() - { - return sharedFromThis(); - } - }; - - int main() - { - QSharedPointer<Y> p(new Y()); - QSharedPointer<Y> y = p->f(); - Q_ASSERT(p == y); // p and q must share ownership - } - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 0 It is also possible to get a shared pointer from an object outside of the class itself. This is especially useful in code that provides an interface to scripts, where it is currently not possible to use shared pointers. For example: - \code - class ScriptInterface : public QObject - { - Q_OBJECT - - // ... - - public slots: - void slotCalledByScript(Y *managedBySharedPointer) - { - QSharedPointer<Y> yPtr = managedBySharedPointer->sharedFromThis(); - // Some other code unrelated to scripts that expects a QSharedPointer<Y> ... - } - }; - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 1 */ /*! @@ -466,30 +436,13 @@ when the strong reference count drops to 0. This is useful, for instance, for calling \l {QObject::}{deleteLater()} on a QObject instead: - \code - static void doDeleteLater(MyObject *obj) - { - obj->deleteLater(); - } - - void otherFunction() - { - QSharedPointer<MyObject> obj = - QSharedPointer<MyObject>(new MyObject, doDeleteLater); - - // continue using obj - obj.clear(); // calls obj->deleteLater(); - } - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 2 Note that the custom deleter function will be called with a pointer to type \c X, even if the QSharedPointer template parameter \c T is not the same. It is also possible to specify a member function directly, as in: - \code - QSharedPointer<MyObject> obj = - QSharedPointer<MyObject>(new MyObject, &QObject::deleteLater); - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 3 \sa clear() */ @@ -618,9 +571,7 @@ Returns \c true if this object is not null. This function is suitable for use in \tt if-constructs, like: - \code - if (sharedptr) { ... } - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 4 \sa isNull() */ @@ -631,9 +582,7 @@ Returns \c true if this object is null. This function is suitable for use in \tt if-constructs, like: - \code - if (!sharedptr) { ... } - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 5 \sa isNull() */ @@ -766,9 +715,7 @@ Resets this QSharedPointer object to point to \a t instead. Equivalent to: - \code - QSharedPointer<T> other(t); this->swap(other); - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 6 */ /*! @@ -777,9 +724,7 @@ Resets this QSharedPointer object to point to \a t instead, with the Deleter \a deleter. Equivalent to: - \code - QSharedPointer<T> other(t, deleter); this->swap(other); - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 7 */ /*! @@ -896,9 +841,7 @@ Returns \c true if this object is not null. This function is suitable for use in \tt if-constructs, like: - \code - if (weakref) { ... } - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 8 Note that, due to the nature of weak references, the pointer that QWeakPointer references can become null at any moment, so @@ -914,9 +857,7 @@ Returns \c true if this object is null. This function is suitable for use in \tt if-constructs, like: - \code - if (!weakref) { ... } - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 9 Note that, due to the nature of weak references, the pointer that QWeakPointer references can become null at any moment, so @@ -939,9 +880,7 @@ It is ok to obtain the value of the pointer and using that value itself, like for example in debugging statements: - \code - qDebug("Tracking %p", weakref.data()); - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 10 However, dereferencing the pointer is only allowed if you can guarantee by external means that the pointer does not get deleted. For example, @@ -950,18 +889,7 @@ If that is the case, then the following code is valid: - \code - // this pointer cannot be used in another thread - // so other threads cannot delete it - QWeakPointer<int> weakref = obtainReference(); - - Object *obj = weakref.data(); - if (obj) { - // if the pointer wasn't deleted yet, we know it can't get - // deleted by our own code here nor the functions we call - otherFunction(obj); - } - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 11 Use this function with care. @@ -986,17 +914,7 @@ to a strong reference and, if it succeeded, it prints the value of the integer that was held: - \code - QWeakPointer<int> weakref; - - // ... - - QSharedPointer<int> strong = weakref.toStrongRef(); - if (strong) - qDebug() << "The value is:" << *strong; - else - qDebug() << "The value has already been deleted"; - \endcode + \snippet code/src_corelib_tools_qsharedpointer.cpp 12 \sa QSharedPointer::QSharedPointer() */ diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp index b3ed62982e..5a2d6b228d 100644 --- a/src/corelib/tools/qstring.cpp +++ b/src/corelib/tools/qstring.cpp @@ -7966,10 +7966,7 @@ QVector<QStringRef> QString::splitRef(const QRegularExpression &re, SplitBehavio Example: - \code - QString str("ab"); - str.repeated(4); // returns "abababab" - \endcode + \snippet code/src_corelib_tools_qstring.cpp 8 */ QString QString::repeated(int times) const { @@ -12096,10 +12093,7 @@ QString QString::toHtmlEscaped() const If you have code that looks like this: - \code - // hasAttribute takes a QString argument - if (node.hasAttribute("http-contents-length")) //... - \endcode + \snippet code/src_corelib_tools_qstring.cpp 9 then a temporary QString will be created to be passed as the \c{hasAttribute} function parameter. This can be quite expensive, as it involves a memory @@ -12108,9 +12102,7 @@ QString QString::toHtmlEscaped() const This cost can be avoided by using QStringLiteral instead: - \code - if (node.hasAttribute(QStringLiteral(u"http-contents-length"))) //... - \endcode + \snippet code/src_corelib_tools_qstring.cpp 10 In this case, QString's internal data will be generated at compile time; no conversion or allocation will occur at runtime. @@ -12125,9 +12117,7 @@ QString QString::toHtmlEscaped() const instance, QString::operator==() can compare to a QLatin1String directly: - \code - if (attribute.name() == QLatin1String("http-contents-length")) //... - \endcode + \snippet code/src_corelib_tools_qstring.cpp 11 \note Some compilers have bugs encoding strings containing characters outside the US-ASCII character set. Make sure you prefix your string with \c{u} in diff --git a/src/corelib/tools/qstringview.cpp b/src/corelib/tools/qstringview.cpp index ce8fdacafb..a7d9426fa6 100644 --- a/src/corelib/tools/qstringview.cpp +++ b/src/corelib/tools/qstringview.cpp @@ -74,19 +74,14 @@ QT_BEGIN_NAMESPACE string literal. QStringViews should be passed by value, not by reference-to-const: - \code - void myfun1(QStringView sv); // preferred - void myfun2(const QStringView &sv); // compiles and works, but slower - \endcode + \snippet code/src_corelib_tools_qstringview.cpp 0 If you want to give your users maximum freedom in what strings they can pass to your function, accompany the QStringView overload with overloads for \list \li \e QChar: this overload can delegate to the QStringView version: - \code - void fun(QChar ch) { fun(QStringView(&ch, 1)); } - \endcode + \snippet code/src_corelib_tools_qstringview.cpp 1 even though, for technical reasons, QStringView cannot provide a QChar constructor by itself. \li \e QString: if you store an unmodified copy of the string and thus would @@ -291,9 +286,7 @@ QT_BEGIN_NAMESPACE If you need the full array, use the constructor from pointer and size instead: - \code - auto sv = QStringView(array, std::size(array)); // using C++17 std::size() - \endcode + \snippet code/src_corelib_tools_qstringview.cpp 2 \a string must remain valid for the lifetime of this string view object. |