summaryrefslogtreecommitdiffstats
path: root/src/corelib/tools
diff options
context:
space:
mode:
Diffstat (limited to 'src/corelib/tools')
-rw-r--r--src/corelib/tools/qbytearray.cpp27
-rw-r--r--src/corelib/tools/qbytearraymatcher.cpp8
-rw-r--r--src/corelib/tools/qcontiguouscache.cpp21
-rw-r--r--src/corelib/tools/qhash.cpp28
-rw-r--r--src/corelib/tools/qrect.cpp10
-rw-r--r--src/corelib/tools/qregularexpression.cpp8
-rw-r--r--src/corelib/tools/qshareddata.cpp17
-rw-r--r--src/corelib/tools/qsharedpointer.cpp108
-rw-r--r--src/corelib/tools/qstring.cpp18
-rw-r--r--src/corelib/tools/qstringview.cpp13
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.
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-18 07:11:50 +0000