diff options
Diffstat (limited to 'src/corelib/doc')
22 files changed, 248 insertions, 442 deletions
diff --git a/src/corelib/doc/snippets/code/doc_src_containers.cpp b/src/corelib/doc/snippets/code/doc_src_containers.cpp index 84935580c9..9b23a9056c 100644 --- a/src/corelib/doc/snippets/code/doc_src_containers.cpp +++ b/src/corelib/doc/snippets/code/doc_src_containers.cpp @@ -205,35 +205,35 @@ for (i = splitter->sizes().begin(); //! [15] -QLinkedList<QString> list; +QVector<QString> values; ... QString str; -foreach (str, list) +foreach (str, values) qDebug() << str; //! [15] //! [16] -QLinkedList<QString> list; +QVector<QString> values; ... -QLinkedListIterator<QString> i(list); +QVectorIterator<QString> i(values); while (i.hasNext()) qDebug() << i.next(); //! [16] //! [17] -QLinkedList<QString> list; +QVector<QString> values; ... -foreach (const QString &str, list) +foreach (const QString &str, values) qDebug() << str; //! [17] //! [18] -QLinkedList<QString> list; +QVector<QString> values; ... -foreach (const QString &str, list) { +foreach (const QString &str, values) { if (str.isEmpty()) break; qDebug() << str; diff --git a/src/corelib/doc/snippets/code/doc_src_properties.cpp b/src/corelib/doc/snippets/code/doc_src_properties.cpp index a67945bbcf..e026a47e23 100644 --- a/src/corelib/doc/snippets/code/doc_src_properties.cpp +++ b/src/corelib/doc/snippets/code/doc_src_properties.cpp @@ -54,7 +54,7 @@ Q_PROPERTY(type name MEMBER memberName [(READ getFunction | WRITE setFunction)]) [RESET resetFunction] [NOTIFY notifySignal] - [REVISION int] + [REVISION int | REVISION(int[, int])] [DESIGNABLE bool] [SCRIPTABLE bool] [STORED bool] diff --git a/src/corelib/doc/snippets/code/doc_src_qiterator.cpp b/src/corelib/doc/snippets/code/doc_src_qiterator.cpp index 58f4166c3e..0d0b864a83 100644 --- a/src/corelib/doc/snippets/code/doc_src_qiterator.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qiterator.cpp @@ -64,24 +64,6 @@ while (i.hasPrevious()) qDebug() << i.previous(); //! [1] - -//! [2] -QLinkedList<float> list; -... -QLinkedListIterator<float> i(list); -while (i.hasNext()) - qDebug() << i.next(); -//! [2] - - -//! [3] -QLinkedListIterator<float> i(list); -i.toBack(); -while (i.hasPrevious()) - qDebug() << i.previous(); -//! [3] - - //! [4] QVector<float> vector; ... @@ -145,37 +127,6 @@ while (i.hasNext()) { } //! [10] - -//! [11] -QLinkedList<float> list; -... -QMutableLinkedListIterator<float> i(list); -while (i.hasNext()) - qDebug() << i.next(); -//! [11] - - -//! [12] -QMutableLinkedListIterator<float> i(list); -i.toBack(); -while (i.hasPrevious()) - qDebug() << i.previous(); -//! [12] - - -//! [13] -QMutableLinkedListIterator<int> i(list); -while (i.hasNext()) { - int val = i.next(); - if (val < 0) { - i.setValue(-val); - } else if (val == 0) { - i.remove(); - } -} -//! [13] - - //! [14] QVector<float> vector; ... @@ -184,7 +135,6 @@ while (i.hasNext()) qDebug() << i.next(); //! [14] - //! [15] QMutableVectorIterator<float> i(vector); i.toBack(); @@ -232,17 +182,6 @@ while (i.hasNext()) { } //! [19] - -//! [20] -QMutableLinkedListIterator<int> i(list); -while (i.hasNext()) { - int val = i.next(); - if (val < -32768 || val > 32767) - i.remove(); -} -//! [20] - - //! [21] QMutableVectorIterator<int> i(vector); while (i.hasNext()) { @@ -271,16 +210,6 @@ while (i.hasNext()) { } //! [23] - -//! [24] -QMutableLinkedListIterator<double> i(list); -while (i.hasNext()) { - double val = i.next(); - i.setValue(std::sqrt(val)); -} -//! [24] - - //! [25] QMutableVectorIterator<double> i(list); while (i.hasNext()) { diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp index 14e72e99dd..5154dc5d68 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp @@ -93,3 +93,8 @@ ba = QByteArray("a\0b", 3); qDebug() << ba // prints: "\a\x00""b" //! [1] + +//! [toString] + QTRY_VERIFY2(list.isEmpty(), qPrintable(QString::fromLatin1( + "Expected list to be empty, but it has the following items: %1")).arg(QDebug::toString(list))); +//! [toString] diff --git a/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp index 6ddb5a9365..973ae75847 100644 --- a/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp @@ -208,10 +208,10 @@ //! [19] //! [20] - void appendList(QCborStreamWriter &writer, const QLinkedList<QString> &list) + void appendList(QCborStreamWriter &writer, const QVector<QString> &values) { writer.startArray(); - for (const QString &s : list) + for (const QString &s : values) writer.append(s); writer.endArray(); } @@ -228,10 +228,10 @@ //! [21] //! [22] - void appendMap(QCborStreamWriter &writer, const QLinkedList<QPair<int, QString>> &list) + void appendMap(QCborStreamWriter &writer, const QVector<QPair<int, QString>> &values) { writer.startMap(); - for (const auto pair : list) { + for (const auto pair : values) { writer.append(pair.first) writer.append(pair.second); } diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp index dfa9b670e7..66fa62f6b3 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp @@ -72,3 +72,106 @@ i.toBack(); while (i.hasPrevious()) qDebug() << i.previous(); //! [2] + +//! [3] +using NetworkReply = std::variant<QByteArray, QNetworkReply::NetworkError>; + +enum class IOError { FailedToRead, FailedToWrite }; +using IOResult = std::variant<QString, IOError>; +//! [3] + +//! [4] +QFuture<IOResult> future = QtConcurrent::run([url] { + ... + return NetworkReply(QNetworkReply::TimeoutError); +}).then([](NetworkReply reply) { + if (auto error = std::get_if<QNetworkReply::NetworkError>(&reply)) + return IOResult(IOError::FailedToRead); + + auto data = std::get_if<QByteArray>(&reply); + // try to write *data and return IOError::FailedToWrite on failure + ... +}); + +auto result = future.result(); +if (auto filePath = std::get_if<QString>(&result)) { + // do something with *filePath +else + // process the error +//! [4] + +//! [5] +QFuture<int> future = ...; + future.then([](QFuture<int> f) { + try { + ... + auto result = f.result(); + ... + } catch (QException &e) { + // handle the exception + } + }).then(...); +//! [5] + +//! [6] +QFuture<int> parentFuture = ...; +auto continuation = parentFuture.then([](int res1){ ... }).then([](int res2){ ... })... +... +// parentFuture throws an exception +try { + auto result = continuation.result(); +} catch (QException &e) { + // handle the exception +} +//! [6] + +//! [7] +QFuture<int> future = ...; +auto resultFuture = future.then([](int res) { + ... + throw Error(); + ... +}).onFailed([](const Error &e) { + // Handle exceptions of type Error + ... + return -1; +}).onFailed([] { + // Handle all other types of errors + ... + return -1; +}); + +auto result = resultFuture.result(); // result is -1 +//! [7] + +//! [8] +QFuture<int> future = ...; +future.then([](int res) { + ... + throw std::runtime_error("message"); + ... +}).onFailed([](const std::exception &e) { + // This handler will be invoked +}).onFailed([](const std::runtime_error &e) { + // This handler won't be invoked, because of the handler above. +}); +//! [8] + +//! [9] +QFuture<int> future = ...; +auto resultFuture = future.then([](int res) { + ... + throw Error("message"); + ... +}).onFailed([](const std::exception &e) { + // Won't be invoked +}).onFailed([](const QException &e) { + // Won't be invoked +}); + +try { + auto result = resultFuture.result(); +} catch(...) { + // Handle the exception +} +//! [9] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp index 01f620cf08..9c07a2e92c 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp @@ -372,16 +372,13 @@ a = str.toFloat(&ok); // a == 0, ok == false //! [39] QByteArray text("Qt is great!"); text.toBase64(); // returns "UXQgaXMgZ3JlYXQh" -//! [39] -//! [39bis] QByteArray text("<p>Hello?</p>"); text.toBase64(QByteArray::Base64Encoding | QByteArray::OmitTrailingEquals); // returns "PHA+SGVsbG8/PC9wPg" text.toBase64(QByteArray::Base64Encoding); // returns "PHA+SGVsbG8/PC9wPg==" text.toBase64(QByteArray::Base64UrlEncoding); // returns "PHA-SGVsbG8_PC9wPg==" text.toBase64(QByteArray::Base64UrlEncoding | QByteArray::OmitTrailingEquals); // returns "PHA-SGVsbG8_PC9wPg" -//! [39bis] - +//! [39] //! [40] QByteArray ba; @@ -422,9 +419,7 @@ QDataStream in(&data, QIODevice::ReadOnly); //! [44] QByteArray text = QByteArray::fromBase64("UXQgaXMgZ3JlYXQh"); text.data(); // returns "Qt is great!" -//! [44] -//! [44bis] QByteArray::fromBase64("PHA+SGVsbG8/PC9wPg==", QByteArray::Base64Encoding); // returns "<p>Hello?</p>" QByteArray::fromBase64("PHA-SGVsbG8_PC9wPg==", QByteArray::Base64UrlEncoding); // returns "<p>Hello?</p>" //! [44bis] @@ -442,7 +437,6 @@ if (result.decodingStatus == QByteArray::Base64DecodingStatus::Ok) process(result.decoded); //! [44quater] - //! [45] QByteArray text = QByteArray::fromHex("517420697320677265617421"); text.data(); // returns "Qt is great!" diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp index d30ad50ffc..1f2c505a02 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp @@ -149,7 +149,7 @@ inline bool operator==(const Employee &e1, const Employee &e2) && e1.dateOfBirth() == e2.dateOfBirth(); } -inline uint qHash(const Employee &key, uint seed) +inline size_t qHash(const Employee &key, size_t seed) { return qHash(key.name(), seed) ^ key.dateOfBirth().day(); } @@ -312,7 +312,7 @@ qDeleteAll(hash2.keyBegin(), hash2.keyEnd()); //! [28] //! [qhashbits] -inline uint qHash(const std::vector<int> &key, uint seed = 0) +inline size_t qHash(const std::vector<int> &key, size_t seed = 0) { if (key.empty()) return seed; @@ -322,14 +322,14 @@ inline uint qHash(const std::vector<int> &key, uint seed = 0) //! [qhashbits] //! [qhashrange] -inline uint qHash(const std::vector<int> &key, uint seed = 0) +inline size_t qHash(const std::vector<int> &key, size_t seed = 0) { return qHashRange(key.begin(), key.end(), seed); } //! [qhashrange] //! [qhashrangecommutative] -inline uint qHash(const std::unordered_set<int> &key, uint seed = 0) +inline size_t qHash(const std::unordered_set<int> &key, size_t seed = 0) { return qHashRangeCommutative(key.begin(), key.end(), seed); } @@ -348,9 +348,9 @@ qHash(qMakePair(key.first, key.second), seed); //! [31] //! [32] -uint qHash(K key); -uint qHash(const K &key); +size_t qHash(K key); +size_t qHash(const K &key); -uint qHash(K key, uint seed); -uint qHash(const K &key, uint seed); +size_t qHash(K key, size_t seed); +size_t qHash(const K &key, size_t seed); //! [32] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qlinkedlist.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qlinkedlist.cpp deleted file mode 100644 index e8754a5f34..0000000000 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qlinkedlist.cpp +++ /dev/null @@ -1,214 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [0] -QLinkedList<int> integerList; -QLinkedList<QTime> timeList; -//! [0] - - -//! [1] -QLinkedList<QString> list; -list << "one" << "two" << "three"; -// list: ["one", "two", "three"] -//! [1] - - -//! [2] -QLinkedList<QWidget *> list; -... -while (!list.isEmpty()) - delete list.takeFirst(); -//! [2] - - -//! [3] -QLinkedList<QString> list; -list.append("one"); -list.append("two"); -list.append("three"); -// list: ["one", "two", "three"] -//! [3] - - -//! [4] -QLinkedList<QString> list; -list.prepend("one"); -list.prepend("two"); -list.prepend("three"); -// list: ["three", "two", "one"] -//! [4] - - -//! [5] -QList<QString> list; -list << "sun" << "cloud" << "sun" << "rain"; -list.removeAll("sun"); -// list: ["cloud", "rain"] -//! [5] - - -//! [6] -QList<QString> list; -list << "sun" << "cloud" << "sun" << "rain"; -list.removeOne("sun"); -// list: ["cloud", "sun", "rain"] -//! [6] - - -//! [7] -QLinkedList<QString> list; -list.append("January"); -list.append("February"); -... -list.append("December"); - -QLinkedList<QString>::iterator i; -for (i = list.begin(); i != list.end(); ++i) - cout << *i << Qt::endl; -//! [7] - - -//! [8] -QLinkedList<QString> list; -... -QLinkedList<QString>::iterator it = std::find(list.begin(), - list.end(), "Joel"); -if (it != list.end()) - cout << "Found Joel" << Qt::endl; -//! [8] - - -//! [9] -QLinkedList<int>::iterator i; -for (i = list.begin(); i != list.end(); ++i) - *i += 2; -//! [9] - - -//! [10] -QLinkedList<QString> list; -... -QLinkedList<QString>::iterator i = list.begin(); -while (i != list.end()) { - if ((*i).startsWith('_')) - i = list.erase(i); - else - ++i; -} -//! [10] - - -//! [11] -QLinkedList<QString>::iterator i = list.begin(); -while (i != list.end()) { - QLinkedList<QString>::iterator previous = i; - ++i; - if ((*previous).startsWith('_')) - list.erase(previous); -} -//! [11] - - -//! [12] -// WRONG -while (i != list.end()) { - if ((*i).startsWith('_')) - list.erase(i); - ++i; -} -//! [12] - - -//! [13] -if (*it == "Hello") - *it = "Bonjour"; -//! [13] - - -//! [14] -QLinkedList<QString> list; -list.append("January"); -list.append("February"); -... -list.append("December"); - -QLinkedList<QString>::const_iterator i; -for (i = list.constBegin(); i != list.constEnd(); ++i) - cout << *i << Qt::endl; -//! [14] - - -//! [15] -QLinkedList<QString> list; -... -QLinkedList<QString>::const_iterator it = std::find(list.constBegin(), - list.constEnd(), "Joel"); -if (it != list.constEnd()) - cout << "Found Joel" << Qt::endl; -//! [15] - - -//! [16] -std::list<double> stdlist; -list.push_back(1.2); -list.push_back(0.5); -list.push_back(3.14); - -QLinkedList<double> list = QLinkedList<double>::fromStdList(stdlist); -//! [16] - - -//! [17] -QLinkedList<double> list; -list << 1.2 << 0.5 << 3.14; - -std::list<double> stdlist = list.toStdList(); -//! [17] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qregexp.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qregexp.cpp index 433b01b21a..8339ea413e 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qregexp.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qregexp.cpp @@ -232,3 +232,12 @@ s2 = QRegExp::escape("f(x)"); // s2 == "f\\(x\\)" QRegExp rx("(" + QRegExp::escape(name) + "|" + QRegExp::escape(alias) + ")"); //! [20] + +{ +//! [21] +QString p("a .*|pattern"); + +// re matches exactly the pattern string p +QRegularExpression re(QRegularExpression::anchoredPattern(p)); +//! [21] +} diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qregularexpression.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qregularexpression.cpp index 99cd4ea7a2..b451ed5253 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qregularexpression.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qregularexpression.cpp @@ -285,15 +285,6 @@ if (!invalidRe.isValid()) { } { -//! [24] -QString p("a .*|pattern"); - -// re matches exactly the pattern string p -QRegularExpression re(QRegularExpression::anchoredPattern(p)); -//! [24] -} - -{ //! [26] QString escaped = QRegularExpression::escape("a(x) = f(x) + g(x)"); // escaped == "a\\(x\\)\\ \\=\\ f\\(x\\)\\ \\+\\ g\\(x\\)" diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qstringiterator.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qstringiterator.cpp index eb09fb99e2..8085e32787 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qstringiterator.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qstringiterator.cpp @@ -62,8 +62,6 @@ QStringIterator i(string); // implicitly converted to QStringView //! [0] //! [1] -// will print 97, 32, 115, 116, etc.; -// that is, the decimal value of the code points in the Unicode string "a string" while (i.hasNext()) qDebug() << i.next(); //! [1] @@ -72,9 +70,9 @@ while (i.hasNext()) { //! [2] QStringIterator i(u"𝄞 is the G clef"); -qDebug() << Qt::hex << i.next(); // will print 1d11e (U+1D11E, MUSICAL SYMBOL G CLEF) -qDebug() << Qt::hex << i.next(); // will print 20 (U+0020, SPACE) -qDebug() << Qt::hex << i.next(); // will print 69 (U+0069, LATIN SMALL LETTER I) +qDebug() << Qt::hex << i.next(); // will print '𝄞' (U+1D11E, MUSICAL SYMBOL G CLEF) +qDebug() << Qt::hex << i.next(); // will print ' ' (U+0020, SPACE) +qDebug() << Qt::hex << i.next(); // will print 'i' (U+0069, LATIN SMALL LETTER I) //! [2] } diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qvector.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qvector.cpp index a05233049f..76a8d68f64 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qvector.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qvector.cpp @@ -115,6 +115,29 @@ vector.append(std::move(three)); //! [move-append] +//! [emplace] +QVector<QString> vector{"a", "ccc"}; +vector.emplace(1, 2, 'b'); +// vector: ["a", "bb", "ccc"] +//! [emplace] + + +//! [emplace-back] +QVector<QString> vector{"one", "two"}; +vector.emplaceBack(3, 'a'); +qDebug() << vector; +// vector: ["one", "two", "aaa"] +//! [emplace-back] + + +//! [emplace-back-ref] +QVector<QString> vector; +auto &ref = vector.emplaceBack(); +ref = "one"; +// vector: ["one"] +//! [emplace-back-ref] + + //! [8] QVector<QString> vector; vector.prepend("one"); diff --git a/src/corelib/doc/snippets/qmetaobject-revision/window.h b/src/corelib/doc/snippets/qmetaobject-revision/window.h index f93d253b6b..f519a6f2dc 100644 --- a/src/corelib/doc/snippets/qmetaobject-revision/window.h +++ b/src/corelib/doc/snippets/qmetaobject-revision/window.h @@ -58,7 +58,7 @@ class Window : public QWidget { Q_OBJECT Q_PROPERTY(int normalProperty READ normalProperty) - Q_PROPERTY(int newProperty READ newProperty REVISION 1) + Q_PROPERTY(int newProperty READ newProperty REVISION(2, 1)) public: Window(); @@ -66,7 +66,7 @@ public: int newProperty(); public slots: void normalMethod(); - Q_REVISION(1) void newMethod(); + Q_REVISION(2, 1) void newMethod(); }; //! [Window class with revision] diff --git a/src/corelib/doc/snippets/qsortfilterproxymodel-details/main.cpp b/src/corelib/doc/snippets/qsortfilterproxymodel-details/main.cpp index 1a12a3cc58..2a7b310716 100644 --- a/src/corelib/doc/snippets/qsortfilterproxymodel-details/main.cpp +++ b/src/corelib/doc/snippets/qsortfilterproxymodel-details/main.cpp @@ -94,8 +94,7 @@ Widget::Widget(QWidget *parent) //! [4] proxyModel->sort(2, Qt::AscendingOrder); //! [4] //! [5] - proxyModel->setFilterRegExp(QRegExp(".png", Qt::CaseInsensitive, - QRegExp::FixedString)); + proxyModel->setFilterRegularExpression(QRegularExpression("\.png", QRegularExpression::CaseInsensitiveOption)); proxyModel->setFilterKeyColumn(1); //! [5] } diff --git a/src/corelib/doc/snippets/qstring/main.cpp b/src/corelib/doc/snippets/qstring/main.cpp index 58d68d9375..271b6d7afc 100644 --- a/src/corelib/doc/snippets/qstring/main.cpp +++ b/src/corelib/doc/snippets/qstring/main.cpp @@ -433,14 +433,12 @@ void Widget::firstIndexOfFunction() //! [93] QString str = "the minimum"; str.indexOf(QRegularExpression("m[aeiou]"), 0); // returns 4 - //! [93] - //! [99] QString str = "the minimum"; QRegularExpressionMatch match; str.indexOf(QRegularExpression("m[aeiou]"), 0, &match); // returns 4 // match.captured() == mi - //! [99] + //! [93] } void Widget::insertFunction() @@ -490,14 +488,12 @@ void Widget::lastIndexOfFunction() //! [94] QString str = "the minimum"; str.lastIndexOf(QRegularExpression("m[aeiou]")); // returns 8 - //! [94] - //! [100] QString str = "the minimum"; QRegularExpressionMatch match; str.lastIndexOf(QRegularExpression("m[aeiou]"), -1, &match); // returns 8 // match.captured() == mu - //! [100] + //! [94] } void Widget::leftFunction() diff --git a/src/corelib/doc/src/cmake-macros.qdoc b/src/corelib/doc/src/cmake-macros.qdoc index 7c0443fba7..387cdbf729 100644 --- a/src/corelib/doc/src/cmake-macros.qdoc +++ b/src/corelib/doc/src/cmake-macros.qdoc @@ -44,9 +44,9 @@ qt5_wrap_cpp(<VAR> src_file1 [src_file2 ...] \section1 Description -Creates rules for calling \l{moc}{Meta-Object Compiler (moc)} on the given +Creates rules for calling the \l{moc}{Meta-Object Compiler (moc)} on the given source files. For each input file, an output file is generated in the build -directory. The paths of the generated files are added to\c{<VAR>}. +directory. The paths of the generated files are added to \c{<VAR>}. \note This is a low-level macro. See the \l{CMake AUTOMOC Documentation} for a more convenient way to let source files be processed with \c{moc}. diff --git a/src/corelib/doc/src/containers.qdoc b/src/corelib/doc/src/containers.qdoc index 4c7cb32aac..537bd8c884 100644 --- a/src/corelib/doc/src/containers.qdoc +++ b/src/corelib/doc/src/containers.qdoc @@ -74,12 +74,10 @@ \section1 The Container Classes - Qt provides the following sequential containers: QList, - QLinkedList, QVector, QStack, and QQueue. For most - applications, QList is the best type to use. Although it is - implemented as an array-list, it provides very fast prepends and - appends. If you really need a linked-list, use QLinkedList; if you - want your items to occupy consecutive memory locations, use QVector. + Qt provides the following sequential containers: QVector, + QStack, and QQueue. For most + applications, QVector is the best type to use. It provides very fast + appends. If you really need a linked-list, use std::list. QStack and QQueue are convenience classes that provide LIFO and FIFO semantics. @@ -95,30 +93,11 @@ \table \header \li Class \li Summary - \row \li \l{QList}<T> + \row \li \l{QVector}<T> \li This is by far the most commonly used container class. It stores a list of values of a given type (T) that can be accessed - by index. Internally, the QList is implemented using an array, - ensuring that index-based access is very fast. - - Items can be added at either end of the list using - QList::append() and QList::prepend(), or they can be inserted in - the middle using QList::insert(). More than any other container - class, QList is highly optimized to expand to as little code as - possible in the executable. QStringList inherits from - QList<QString>. - - \row \li \l{QLinkedList}<T> - \li This is similar to QList, except that it uses - iterators rather than integer indexes to access items. It also - provides better performance than QList when inserting in the - middle of a huge list, and it has nicer iterator semantics. - (Iterators pointing to an item in a QLinkedList remain valid as - long as the item exists, whereas iterators to a QList can become - invalid after any insertion or removal.) - - \row \li \l{QVector}<T> - \li This stores an array of values of a given type at adjacent + by index. Internally, it stores an array of values of a + given type at adjacent positions in memory. Inserting at the front or in the middle of a vector can be quite slow, because it can lead to large numbers of items having to be moved by one position in memory. @@ -135,9 +114,9 @@ and \l{QStack::top()}{top()}. \row \li \l{QQueue}<T> - \li This is a convenience subclass of QList that provides + \li This is a convenience subclass of QVector that provides "first in, first out" (FIFO) semantics. It adds the following - functions to those already present in QList: + functions to those already present in QQVector: \l{QQueue::enqueue()}{enqueue()}, \l{QQueue::dequeue()}{dequeue()}, and \l{QQueue::head()}{head()}. @@ -168,11 +147,11 @@ \endtable Containers can be nested. For example, it is perfectly possible - to use a QMap<QString, QList<int>>, where the key type is - QString and the value type QList<int>. + to use a QMap<QString, QVector<int>>, where the key type is + QString and the value type QVector<int>. The containers are defined in individual header files with the - same name as the container (e.g., \c <QLinkedList>). For + same name as the container (e.g., \c <QVector>). For convenience, the containers are forward declared in \c <QtContainerFwd>. @@ -188,10 +167,10 @@ double, pointer types, and Qt data types such as QString, QDate, and QTime, but it doesn't cover QObject or any QObject subclass (QWidget, QDialog, QTimer, etc.). If you attempt to instantiate a - QList<QWidget>, the compiler will complain that QWidget's copy + QVector<QWidget>, the compiler will complain that QWidget's copy constructor and assignment operators are disabled. If you want to store these kinds of objects in a container, store them as - pointers, for example as QList<QWidget *>. + pointers, for example as QVector<QWidget *>. Here's an example custom data type that meets the requirement of an assignable data type: @@ -264,11 +243,8 @@ \table \header \li Containers \li Read-only iterator \li Read-write iterator - \row \li QList<T>, QQueue<T> \li QListIterator<T> \li QMutableListIterator<T> - \row \li QLinkedList<T> \li QLinkedListIterator<T> - \li QMutableLinkedListIterator<T> - \row \li QVector<T>, QStack<T> \li QVectorIterator<T> + \row \li QVector<T>, QStack<T>, QQueue<T> \li QVectorIterator<T> \li QMutableVectorIterator<T> \row \li QSet<T> \li QSetIterator<T> \li QMutableSetIterator<T> @@ -278,9 +254,9 @@ \li QMutableHashIterator<Key, T> \endtable - In this discussion, we will concentrate on QList and QMap. The - iterator types for QLinkedList, QVector, and QSet have exactly - the same interface as QList's iterators; similarly, the iterator + In this discussion, we will concentrate on QVector and QMap. The + iterator types for QSet have exactly + the same interface as QVector's iterators; similarly, the iterator types for QHash have the same interface as QMap's iterators. Unlike STL-style iterators (covered \l{STL-style @@ -295,59 +271,59 @@ \image javaiterators1.png Here's a typical loop for iterating through all the elements of a - QList<QString> in order and printing them to the console: + QVector<QString> in order and printing them to the console: \snippet code/doc_src_containers.cpp 1 - It works as follows: The QList to iterate over is passed to the - QListIterator constructor. At that point, the iterator is located + It works as follows: The QVector to iterate over is passed to the + QVectorIterator constructor. At that point, the iterator is located just in front of the first item in the list (before item "A"). - Then we call \l{QListIterator::hasNext()}{hasNext()} to + Then we call \l{QVectorIterator::hasNext()}{hasNext()} to check whether there is an item after the iterator. If there is, we - call \l{QListIterator::next()}{next()} to jump over that + call \l{QVectorIterator::next()}{next()} to jump over that item. The next() function returns the item that it jumps over. For - a QList<QString>, that item is of type QString. + a QVector<QString>, that item is of type QString. - Here's how to iterate backward in a QList: + Here's how to iterate backward in a QVector: \snippet code/doc_src_containers.cpp 2 The code is symmetric with iterating forward, except that we - start by calling \l{QListIterator::toBack()}{toBack()} + start by calling \l{QVectorIterator::toBack()}{toBack()} to move the iterator after the last item in the list. The diagram below illustrates the effect of calling - \l{QListIterator::next()}{next()} and - \l{QListIterator::previous()}{previous()} on an iterator: + \l{QVectorIterator::next()}{next()} and + \l{QVectorIterator::previous()}{previous()} on an iterator: \image javaiterators2.png - The following table summarizes the QListIterator API: + The following table summarizes the QVectorIterator API: \table \header \li Function \li Behavior - \row \li \l{QListIterator::toFront()}{toFront()} + \row \li \l{QVectorIterator::toFront()}{toFront()} \li Moves the iterator to the front of the list (before the first item) - \row \li \l{QListIterator::toBack()}{toBack()} + \row \li \l{QVectorIterator::toBack()}{toBack()} \li Moves the iterator to the back of the list (after the last item) - \row \li \l{QListIterator::hasNext()}{hasNext()} + \row \li \l{QVectorIterator::hasNext()}{hasNext()} \li Returns \c true if the iterator isn't at the back of the list - \row \li \l{QListIterator::next()}{next()} + \row \li \l{QVectorIterator::next()}{next()} \li Returns the next item and advances the iterator by one position - \row \li \l{QListIterator::peekNext()}{peekNext()} + \row \li \l{QVectorIterator::peekNext()}{peekNext()} \li Returns the next item without moving the iterator - \row \li \l{QListIterator::hasPrevious()}{hasPrevious()} + \row \li \l{QVectorIterator::hasPrevious()}{hasPrevious()} \li Returns \c true if the iterator isn't at the front of the list - \row \li \l{QListIterator::previous()}{previous()} + \row \li \l{QVectorIterator::previous()}{previous()} \li Returns the previous item and moves the iterator back by one position - \row \li \l{QListIterator::peekPrevious()}{peekPrevious()} + \row \li \l{QVectorIterator::peekPrevious()}{peekPrevious()} \li Returns the previous item without moving the iterator \endtable - QListIterator provides no functions to insert or remove items + QVectorIterator provides no functions to insert or remove items from the list as we iterate. To accomplish this, you must use QMutableListIterator. Here's an example where we remove all - odd numbers from a QList<int> using QMutableListIterator: + odd numbers from a QVector<int> using QMutableListIterator: \snippet code/doc_src_containers.cpp 3 @@ -380,12 +356,12 @@ \snippet code/doc_src_containers.cpp 6 - As mentioned above, QLinkedList's, QVector's, and QSet's iterator - classes have exactly the same API as QList's. We will now turn to + As mentioned above QSet's iterator + classes have exactly the same API as QVector's. We will now turn to QMapIterator, which is somewhat different because it iterates on (key, value) pairs. - Like QListIterator, QMapIterator provides + Like QVectorIterator, QMapIterator provides \l{QMapIterator::toFront()}{toFront()}, \l{QMapIterator::toBack()}{toBack()}, \l{QMapIterator::hasNext()}{hasNext()}, @@ -433,11 +409,7 @@ \table \header \li Containers \li Read-only iterator \li Read-write iterator - \row \li QList<T>, QQueue<T> \li QList<T>::const_iterator - \li QList<T>::iterator - \row \li QLinkedList<T> \li QLinkedList<T>::const_iterator - \li QLinkedList<T>::iterator - \row \li QVector<T>, QStack<T> \li QVector<T>::const_iterator + \row \li QVector<T>, QStack<T>, QQueue<T> \li QVector<T>::const_iterator \li QVector<T>::iterator \row \li QSet<T> \li QSet<T>::const_iterator \li QSet<T>::iterator @@ -456,24 +428,24 @@ and the \l{QVector::iterator}{const_iterator} type is just a typedef for \c{const T *}. - In this discussion, we will concentrate on QList and QMap. The - iterator types for QLinkedList, QVector, and QSet have exactly - the same interface as QList's iterators; similarly, the iterator + In this discussion, we will concentrate on QVector and QMap. The + iterator types for QSet have exactly + the same interface as QVector's iterators; similarly, the iterator types for QHash have the same interface as QMap's iterators. Here's a typical loop for iterating through all the elements of a - QList<QString> in order and converting them to lowercase: + QVector<QString> in order and converting them to lowercase: \snippet code/doc_src_containers.cpp 10 Unlike \l{Java-style iterators}, STL-style iterators point - directly at items. The \l{QList::begin()}{begin()} function of a container returns an + directly at items. The \l{QVector::begin()}{begin()} function of a container returns an iterator that points to the first item in the container. The - \l{QList::end()}{end()} function of a container returns an iterator to the + \l{QVector::end()}{end()} function of a container returns an iterator to the imaginary item one position past the last item in the container. - \l {QList::end()}{end()} marks an invalid position; it must never be dereferenced. + \l {QVector::end()}{end()} marks an invalid position; it must never be dereferenced. It is typically used in a loop's break condition. If the list is - empty, \l{QList::begin}{begin()} equals \l{QList::end()}{end()}, so we never execute the loop. + empty, \l{QVector::begin}{begin()} equals \l{QVector::end()}{end()}, so we never execute the loop. The diagram below shows the valid iterator positions as red arrows for a vector containing four items: @@ -490,8 +462,8 @@ compilers also allow us to write \c{i->toLower()}, but some don't. - For read-only access, you can use const_iterator, \l{QList::constBegin}{constBegin()}, - and \l{QList::constEnd()}{constEnd()}. For example: + For read-only access, you can use const_iterator, \l{QVector::constBegin}{constBegin()}, + and \l{QVector::constEnd()}{constEnd()}. For example: \snippet code/doc_src_containers.cpp 12 @@ -529,7 +501,7 @@ Thanks to \l{implicit sharing}, it is very inexpensive for a function to return a container per value. The Qt API contains - dozens of functions that return a QList or QStringList per value + dozens of functions that return a QVector or QStringList per value (e.g., QSplitter::sizes()). If you want to iterate over these using an STL iterator, you should always take a copy of the container and iterate over the copy. For example: @@ -562,7 +534,7 @@ Its syntax is: \c foreach (\e variable, \e container) \e statement. For example, here's how to use \c foreach to iterate - over a QLinkedList<QString>: + over a QVector<QString>: \snippet code/doc_src_containers.cpp 15 @@ -647,9 +619,9 @@ Algorithmic complexity is concerned about how fast (or slow) each function is as the number of items in the container grow. For - example, inserting an item in the middle of a QLinkedList is an + example, inserting an item in the middle of a std::list is an extremely fast operation, irrespective of the number of items - stored in the QLinkedList. On the other hand, inserting an item + stored in the list. On the other hand, inserting an item in the middle of a QVector is potentially very expensive if the QVector contains many items, since half of the items must be moved one position in memory. @@ -667,7 +639,7 @@ \li \b{Constant time:} O(1). A function is said to run in constant time if it requires the same amount of time no matter how many items are present in the container. One example is - QLinkedList::insert(). + QVector::push_back(). \li \b{Logarithmic time:} O(log \e n). A function that runs in logarithmic time is a function whose running time is @@ -689,13 +661,11 @@ number of items stored in the container. \endlist - The following table summarizes the algorithmic complexity of Qt's - sequential container classes: + The following table summarizes the algorithmic complexity of the sequential + container QVector<T>: \table \header \li \li Index lookup \li Insertion \li Prepending \li Appending - \row \li QLinkedList<T> \li O(\e n) \li O(1) \li O(1) \li O(1) - \row \li QList<T> \li O(1) \li O(n) \li Amort. O(1) \li Amort. O(1) \row \li QVector<T> \li O(1) \li O(n) \li O(n) \li Amort. O(1) \endtable @@ -726,11 +696,8 @@ \section1 Growth Strategies QVector<T>, QString, and QByteArray store their items - contiguously in memory; QList<T> maintains an array of pointers - to the items it stores to provide fast index-based access (unless - T is a pointer type or a basic type of the size of a pointer, in - which case the value itself is stored in the array); QHash<Key, - T> keeps a hash table whose size is proportional to the number + contiguously in memory; QHash<Key, T> keeps a + hash table whose size is proportional to the number of items in the hash. To avoid reallocating the data every single time an item is added at the end of the container, these classes typically allocate more memory than necessary. @@ -764,7 +731,7 @@ on the first and last pages actually needs to be copied. \endlist - QByteArray and QList<T> use more or less the same algorithm as + QByteArray uses more or less the same algorithm as QString. QVector<T> also uses that algorithm for data types that can be diff --git a/src/corelib/doc/src/datastreamformat.qdoc b/src/corelib/doc/src/datastreamformat.qdoc index d6b60f10ce..1e23b19c1f 100644 --- a/src/corelib/doc/src/datastreamformat.qdoc +++ b/src/corelib/doc/src/datastreamformat.qdoc @@ -66,8 +66,6 @@ \li QIcon \li QImage \li QKeySequence - \li QLinkedList<T> - \li QList<T> \li QMap<Key, T> \li QMargins \li QMatrix4x4 @@ -79,7 +77,6 @@ \li QPoint \li QQuaternion \li QRect - \li QRegExp \li QRegularExpression \li QRegion \li QSize diff --git a/src/corelib/doc/src/dontdocument.qdoc b/src/corelib/doc/src/dontdocument.qdoc index 0150d07019..9ed5345777 100644 --- a/src/corelib/doc/src/dontdocument.qdoc +++ b/src/corelib/doc/src/dontdocument.qdoc @@ -29,14 +29,14 @@ \dontdocument (QMacAutoReleasePool QIncompatibleFlag QGenericAtomicOps QAtomicTraits QAtomicOps QBasicAtomicInteger QBasicAtomicPointer QBasicMutex QInternal QArgument QReturnArgument QArrayData QTypedArrayData QStaticByteArrayData - QByteRef QStaticStringData QListSpecialMethods QListData QScopedPointerDeleter + QStaticStringData QListSpecialMethods QListData QScopedPointerDeleter QScopedPointerArrayDeleter QScopedPointerPodDeleter QScopedPointerObjectDeleteLater QMetaTypeId2 QObjectData QObjectUserData QMapNodeBase QMapNode QMapDataBase QMapData QHashData QHashNode QArrayDataPointer QTextStreamManipulator QContiguousCacheData QContiguousCacheTypedData QNoDebug QUrlTwoFlags QCborValueRef QDeferredDeleteEvent QSpecialInteger QLittleEndianStorageType QBigEndianStorageType QFactoryInterface QFutureWatcherBase QJsonValuePtr - QJsonValueRefPtr QLinkedListNode QAbstractConcatenable QStringBuilderCommon + QJsonValueRefPtr QAbstractConcatenable QStringBuilderCommon QTextCodec::ConverterState QThreadStorageData QTextStreamManipulator) */ diff --git a/src/corelib/doc/src/includes/qdebug-toString.qdocinc b/src/corelib/doc/src/includes/qdebug-toString.qdocinc new file mode 100644 index 0000000000..db1e1ab453 --- /dev/null +++ b/src/corelib/doc/src/includes/qdebug-toString.qdocinc @@ -0,0 +1,9 @@ +Streams \a object into a QDebug instance that operates on a string, +and then returns that string. + +This function is useful for cases where you need the textual representation +of an object for debugging, but cannot use \c {operator<<}. For example: + +\snippet code/src_corelib_io_qdebug.cpp toString + +The string is streamed using \l nospace(). diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc index 680e5598f0..abeb9b7a54 100644 --- a/src/corelib/doc/src/objectmodel/properties.qdoc +++ b/src/corelib/doc/src/objectmodel/properties.qdoc @@ -102,8 +102,8 @@ re-evaluated in QML, for example. Qt emits automatically that signal when needed for MEMBER properties that do not have an explicit setter. - \li A \c REVISION number is optional. If included, it defines - the property and its notifier signal to be used in a particular + \li A \c REVISION number or \c REVISION() macro is optional. If included, + it defines the property and its notifier signal to be used in a particular revision of the API (usually for exposure to QML). If not included, it defaults to 0. |