From 5d76c49e9cf6b7f7fb15857ca184541b6044a220 Mon Sep 17 00:00:00 2001 From: Ahmad Samir Date: Thu, 29 Dec 2022 18:31:59 +0200 Subject: [PATCH] Use more documentation snippets for QString and its siblings Pick-to: 6.5 Change-Id: Ia569806b586923473f68b9fe1d98a3628ba46a58 Reviewed-by: Paul Wicking --- src/corelib/doc/src/includes/qstring.qdocinc | 24 +++ src/corelib/text/qbytearray.cpp | 8 +- src/corelib/text/qbytearrayview.qdoc | 9 +- src/corelib/text/qstring.cpp | 202 +++++++------------ src/corelib/text/qstringview.cpp | 73 +++---- 5 files changed, 139 insertions(+), 177 deletions(-) create mode 100644 src/corelib/doc/src/includes/qstring.qdocinc diff --git a/src/corelib/doc/src/includes/qstring.qdocinc b/src/corelib/doc/src/includes/qstring.qdocinc new file mode 100644 index 0000000000..a3c8810a8b --- /dev/null +++ b/src/corelib/doc/src/includes/qstring.qdocinc @@ -0,0 +1,24 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +// \1 is either "search" or "comparison" +//! [search-comparison-case-sensitivity] +If \a cs is Qt::CaseSensitive (the default), the \1 is case-sensitive; +otherwise the \1 is case-insensitive. +//! [search-comparison-case-sensitivity] + +//! [negative-index-start-search-from-end] +If \a from is -1, the search starts at the last character; if it is +-2, at the next to last character and so on. +//! [negative-index-start-search-from-end] + +//! [qstring-first-index-of] +Returns the index position of the first occurrence of the \1 \a \2 +in this string, searching forward from index position \a from. +Returns -1 if \a \2 is not found. +//! [qstring-first-index-of] + +//! [qstring-last-index-of] +Returns the index position of the last occurrence of the \1 \a \2 +in this string, searching backward from index position \a from. +//! [qstring-last-index-of] diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp index f4b4523b68..c92ab16564 100644 --- a/src/corelib/text/qbytearray.cpp +++ b/src/corelib/text/qbytearray.cpp @@ -2717,9 +2717,11 @@ qsizetype QtPrivate::lastIndexOf(QByteArrayView haystack, qsizetype from, QByteA Returns the index position of the start of the last occurrence of the sequence of bytes viewed by \a bv in this byte array, searching backward - from index position \a from. If \a from is -1, the search starts at - the last character; if \a from is -2, at the next to last character - and so on. Returns -1 if no match is found. + from index position \a from. + + \include qstring.qdocinc negative-index-start-search-from-end + + Returns -1 if no match is found. Example: \snippet code/src_corelib_text_qbytearray.cpp 23 diff --git a/src/corelib/text/qbytearrayview.qdoc b/src/corelib/text/qbytearrayview.qdoc index 79cf9a2fa4..6afcba1eef 100644 --- a/src/corelib/text/qbytearrayview.qdoc +++ b/src/corelib/text/qbytearrayview.qdoc @@ -949,8 +949,7 @@ respectively, in this byte array view, searching forward from index position \a from.Returns -1 if no match is found. - If \a from is -1, the search starts at the last character; if it is - -2, at the next to last character and so on. + \include qstring.qdocinc negative-index-start-search-from-end \sa lastIndexOf(), contains() */ @@ -973,8 +972,10 @@ Returns the index position of either the start of the last occurrence of the sequence of bytes viewed by \a bv or the last occurrence of byte \a ch, respectively, in this byte array view, searching backward from index position - \a from. If \a from is -1, the search starts at the last character; - if \a from is -2, at the next to last character and so on. + \a from. + + \include qstring.qdocinc negative-index-start-search-from-end + Returns -1 if no match is found. \note When searching for a 0-length \a bv, the match at the end of diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp index bc1cdd343c..8927bbeb57 100644 --- a/src/corelib/text/qstring.cpp +++ b/src/corelib/text/qstring.cpp @@ -1466,8 +1466,7 @@ bool QAnyStringView::equal(QAnyStringView lhs, QAnyStringView rhs) noexcept Returns an integer that compares to 0 as \a lhs compares to \a rhs. - If \a cs is Qt::CaseSensitive (the default), the comparison is case-sensitive; - otherwise the comparison is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} Case-sensitive comparison is based exclusively on the numeric Unicode values of the characters and is very fast, but is not what a human would expect. @@ -1490,8 +1489,7 @@ int QtPrivate::compareStrings(QStringView lhs, QStringView rhs, Qt::CaseSensitiv Returns an integer that compares to 0 as \a lhs compares to \a rhs. - If \a cs is Qt::CaseSensitive (the default), the comparison is case-sensitive; - otherwise the comparison is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} Case-sensitive comparison is based exclusively on the numeric Unicode values of the characters and is very fast, but is not what a human would expect. @@ -1536,8 +1534,7 @@ int QtPrivate::compareStrings(QLatin1StringView lhs, QStringView rhs, Qt::CaseSe Returns an integer that compares to 0 as \a lhs compares to \a rhs. - If \a cs is Qt::CaseSensitive (the default), the comparison is case-sensitive; - otherwise the comparison is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} Case-sensitive comparison is based exclusively on the numeric Latin-1 values of the characters and is very fast, but is not what a human would expect. @@ -3346,8 +3343,7 @@ static void removeStringImpl(QString &s, const T &needle, Qt::CaseSensitivity cs Removes every occurrence of the given \a str string in this string, and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} This is the same as \c replace(str, "", cs). @@ -3372,8 +3368,7 @@ QString &QString::remove(const QString &str, Qt::CaseSensitivity cs) Removes every occurrence of the given \a str string in this string, and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} This is the same as \c replace(str, "", cs). @@ -3424,8 +3419,7 @@ QString &QString::remove(QLatin1StringView str, Qt::CaseSensitivity cs) Removes every occurrence of the character \a ch in this string, and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} Example: @@ -3553,8 +3547,7 @@ QString &QString::replace(qsizetype pos, qsizetype len, QChar after) Replaces every occurrence of the string \a before with the string \a after and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} Example: @@ -3663,8 +3656,7 @@ void QString::replace_helper(size_t *indices, qsizetype nIndices, qsizetype blen characters of \a before with the first \a alen characters of \a after and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} */ QString &QString::replace(const QChar *before, qsizetype blen, const QChar *after, qsizetype alen, @@ -3734,8 +3726,7 @@ QString &QString::replace(const QChar *before, qsizetype blen, Replaces every occurrence of the character \a ch in the string with \a after and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} */ QString& QString::replace(QChar ch, const QString &after, Qt::CaseSensitivity cs) { @@ -3785,8 +3776,7 @@ QString& QString::replace(QChar ch, const QString &after, Qt::CaseSensitivity cs Replaces every occurrence of the character \a before with the character \a after and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} */ QString& QString::replace(QChar before, QChar after, Qt::CaseSensitivity cs) { @@ -3822,8 +3812,7 @@ QString& QString::replace(QChar before, QChar after, Qt::CaseSensitivity cs) Replaces every occurrence of the string \a before with the string \a after and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \note The text is not rescanned after a replacement. */ @@ -3846,8 +3835,7 @@ QString &QString::replace(QLatin1StringView before, QLatin1StringView after, Qt: Replaces every occurrence of the string \a before with the string \a after and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \note The text is not rescanned after a replacement. */ @@ -3868,8 +3856,7 @@ QString &QString::replace(QLatin1StringView before, const QString &after, Qt::Ca Replaces every occurrence of the string \a before with the string \a after and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \note The text is not rescanned after a replacement. */ @@ -3890,8 +3877,7 @@ QString &QString::replace(const QString &before, QLatin1StringView after, Qt::Ca Replaces every occurrence of the character \a c with the string \a after and returns a reference to this string. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \note The text is not rescanned after a replacement. */ @@ -4224,19 +4210,15 @@ QString &QString::replace(QChar c, QLatin1StringView after, Qt::CaseSensitivity */ /*! - Returns the index position of the first occurrence of the string \a - str in this string, searching forward from index position \a - from. Returns -1 if \a str is not found. + \include qstring.qdocinc {qstring-first-index-of} {string} {str} - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} Example: \snippet qstring/main.cpp 24 - If \a from is -1, the search starts at the last character; if it is - -2, at the next to last character and so on. + \include qstring.qdocinc negative-index-start-search-from-end \sa lastIndexOf(), contains(), count() */ @@ -4250,34 +4232,27 @@ qsizetype QString::indexOf(const QString &str, qsizetype from, Qt::CaseSensitivi \since 5.14 \overload indexOf() - Returns the index position of the first occurrence of the string view \a str - in this string, searching forward from index position \a from. - Returns -1 if \a str is not found. + \include qstring.qdocinc {qstring-first-index-of} {string view} {str} - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} - If \a from is -1, the search starts at the last character; if it is - -2, at the next to last character and so on. + \include qstring.qdocinc negative-index-start-search-from-end \sa QStringView::indexOf(), lastIndexOf(), contains(), count() */ /*! \since 4.5 - Returns the index position of the first occurrence of the string \a - str in this string, searching forward from index position \a - from. Returns -1 if \a str is not found. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include {qstring.qdocinc} {qstring-first-index-of} {string} {str} + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} Example: \snippet qstring/main.cpp 24 - If \a from is -1, the search starts at the last character; if it is - -2, at the next to last character and so on. + \include qstring.qdocinc negative-index-start-search-from-end \sa lastIndexOf(), contains(), count() */ @@ -4290,9 +4265,7 @@ qsizetype QString::indexOf(QLatin1StringView str, qsizetype from, Qt::CaseSensit /*! \overload indexOf() - Returns the index position of the first occurrence of the - character \a ch in the string, searching forward from index - position \a from. Returns -1 if \a ch could not be found. + \include qstring.qdocinc {qstring-first-index-of} {character} {ch} */ qsizetype QString::indexOf(QChar ch, qsizetype from, Qt::CaseSensitivity cs) const { @@ -4300,14 +4273,13 @@ qsizetype QString::indexOf(QChar ch, qsizetype from, Qt::CaseSensitivity cs) con } /*! - Returns the index position of the last occurrence of the string \a - str in this string, searching backward from index position \a - from. If \a from is -1, the search starts at the last - character; if \a from is -2, at the next to last character and so - on. Returns -1 if \a str is not found. + \include qstring.qdocinc {qstring-last-index-of} {string} {str} - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc negative-index-start-search-from-end + + Returns -1 if \a str is not found. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} Example: @@ -4335,8 +4307,7 @@ qsizetype QString::lastIndexOf(const QString &str, qsizetype from, Qt::CaseSensi Returns the index position of the last occurrence of the string \a str in this string. Returns -1 if \a str is not found. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} Example: @@ -4350,14 +4321,13 @@ qsizetype QString::lastIndexOf(const QString &str, qsizetype from, Qt::CaseSensi \since 4.5 \overload lastIndexOf() - Returns the index position of the last occurrence of the string \a - str in this string, searching backward from index position \a - from. If \a from is -1, the search starts at the last - character; if \a from is -2, at the next to last character and so - on. Returns -1 if \a str is not found. + \include qstring.qdocinc {qstring-last-index-of} {string} {str} - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc negative-index-start-search-from-end + + Returns -1 if \a str is not found. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} Example: @@ -4385,8 +4355,7 @@ qsizetype QString::lastIndexOf(QLatin1StringView str, qsizetype from, Qt::CaseSe Returns the index position of the last occurrence of the string \a str in this string. Returns -1 if \a str is not found. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} Example: @@ -4398,8 +4367,7 @@ qsizetype QString::lastIndexOf(QLatin1StringView str, qsizetype from, Qt::CaseSe /*! \overload lastIndexOf() - Returns the index position of the last occurrence of the character - \a ch, searching backward from position \a from. + \include qstring.qdocinc {qstring-last-index-of} {character} {ch} */ qsizetype QString::lastIndexOf(QChar ch, qsizetype from, Qt::CaseSensitivity cs) const { @@ -4417,14 +4385,13 @@ qsizetype QString::lastIndexOf(QChar ch, qsizetype from, Qt::CaseSensitivity cs) \since 5.14 \overload lastIndexOf() - Returns the index position of the last occurrence of the string view \a - str in this string, searching backward from index position \a - from. If \a from is -1, the search starts at the last - character; if \a from is -2, at the next to last character and so - on. Returns -1 if \a str is not found. + \include qstring.qdocinc {qstring-last-index-of} {string view} {str} - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc negative-index-start-search-from-end + + Returns -1 if \a str is not found. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \note When searching for a 0-length \a str, the match at the end of the data is excluded from the search by a negative \a from, even @@ -4444,8 +4411,7 @@ qsizetype QString::lastIndexOf(QChar ch, qsizetype from, Qt::CaseSensitivity cs) Returns the index position of the last occurrence of the string view \a str in this string. Returns -1 if \a str is not found. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa indexOf(), contains(), count() */ @@ -4593,8 +4559,7 @@ QString &QString::replace(const QRegularExpression &re, const QString &after) Returns the number of (potentially overlapping) occurrences of the string \a str in this string. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa contains(), indexOf() */ @@ -4609,8 +4574,7 @@ qsizetype QString::count(const QString &str, Qt::CaseSensitivity cs) const Returns the number of occurrences of character \a ch in the string. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa contains(), indexOf() */ @@ -4626,8 +4590,7 @@ qsizetype QString::count(QChar ch, Qt::CaseSensitivity cs) const Returns the number of (potentially overlapping) occurrences of the string view \a str in this string. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa contains(), indexOf() */ @@ -4641,8 +4604,7 @@ qsizetype QString::count(QStringView str, Qt::CaseSensitivity cs) const Returns \c true if this string contains an occurrence of the string \a str; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} Example: \snippet qstring/main.cpp 17 @@ -4674,8 +4636,7 @@ qsizetype QString::count(QStringView str, Qt::CaseSensitivity cs) const Returns \c true if this string contains an occurrence of the string view \a str; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa indexOf(), count() */ @@ -4706,9 +4667,11 @@ qsizetype QString::indexOf(const QRegularExpression &re, qsizetype from, QRegula Returns the index position of the last match of the regular expression \a re in the string, which starts before the index - position \a from. If \a from is -1, the search starts at the last - character; if \a from is -2, at the next to last character and so - on. Returns -1 if \a re didn't match anywhere. + position \a from. + + \include qstring.qdocinc negative-index-start-search-from-end + + Returns -1 if \a re didn't match anywhere. If the match is successful and \a rmatch is not \nullptr, it also writes the results of the match into the QRegularExpressionMatch object @@ -5177,8 +5140,7 @@ QString QString::mid(qsizetype position, qsizetype n) const Returns \c true if the string starts with \a s; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \snippet qstring/main.cpp 65 @@ -5220,8 +5182,7 @@ bool QString::startsWith(QChar c, Qt::CaseSensitivity cs) const Returns \c true if the string starts with the string view \a str; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (default), the search is case-sensitive; - otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa endsWith() */ @@ -5230,8 +5191,7 @@ bool QString::startsWith(QChar c, Qt::CaseSensitivity cs) const Returns \c true if the string ends with \a s; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \snippet qstring/main.cpp 20 @@ -5249,8 +5209,7 @@ bool QString::endsWith(const QString &s, Qt::CaseSensitivity cs) const Returns \c true if the string ends with the string view \a str; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa startsWith() */ @@ -6312,8 +6271,7 @@ QString& QString::fill(QChar ch, qsizetype size) to, or greater than zero if \a s1 is less than, equal to, or greater than \a s2. - If \a cs is Qt::CaseSensitive, the comparison is case sensitive; - otherwise the comparison is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} Case sensitive comparison is based exclusively on the numeric Unicode values of the characters and is very fast, but is not what @@ -9578,8 +9536,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size) Returns an integer that compares to zero as this Latin-1 string compares to the string-view \a str, Latin-1 string \a l1, or character \a ch, respectively. - If \a cs is Qt::CaseSensitive (the default), the comparison is case sensitive; - otherwise the comparison is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa operator==(), operator<(), operator>() */ @@ -9599,8 +9556,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size) Latin-1 string \a l1, or character \a ch, respectively; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive; - otherwise the search is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa endsWith() */ @@ -9619,8 +9575,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size) Latin-1 string \a l1, or character \a ch, respectively; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive; - otherwise the search is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa startsWith() */ @@ -9636,11 +9591,9 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size) Latin-1 string, searching forward from index position \a from. Returns -1 if \a str is not found. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} - If \a from is -1, the search starts at the last character; if it is - -2, at the next to last character and so on. + \include qstring.qdocinc negative-index-start-search-from-end \sa QString::indexOf() */ @@ -9655,8 +9608,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size) string-view \a str, Latin-1 string \a l1, or character \a ch; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (the default), the search is - case-sensitive; otherwise the search is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa indexOf(), QStringView::contains(), QStringView::indexOf(), QString::indexOf() @@ -9673,11 +9625,9 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size) string, searching backward from index position \a from. Returns -1 if \a str is not found. - If \a from is -1, the search starts at the last character; - if \a from is -2, at the next to last character and so on. + \include qstring.qdocinc negative-index-start-search-from-end - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \note When searching for a 0-length \a str or \a l1, the match at the end of the data is excluded from the search by a negative \a @@ -9701,8 +9651,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size) string-view \a str or Latin-1 string \a l1, respectively, in this Latin-1 string. Returns -1 if \a str is not found. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} */ /*! @@ -9721,8 +9670,7 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size) string-view \a str, Latin-1 string \a l1, or character \a ch, respectively, in this Latin-1 string. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa contains(), indexOf() */ @@ -10684,8 +10632,7 @@ qsizetype QtPrivate::count(QLatin1StringView haystack, QChar needle, Qt::CaseSen Returns \c true if \a haystack starts with \a needle, otherwise returns \c false. - If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive; - otherwise the search is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa QtPrivate::endsWith(), QString::endsWith(), QStringView::endsWith(), QLatin1StringView::endsWith() */ @@ -10725,8 +10672,7 @@ bool QtPrivate::startsWith(QLatin1StringView haystack, QLatin1StringView needle, Returns \c true if \a haystack ends with \a needle, otherwise returns \c false. - If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive; - otherwise the search is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa QtPrivate::startsWith(), QString::endsWith(), QStringView::endsWith(), QLatin1StringView::endsWith() */ diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp index 8f1aa3dfea..b9ea630249 100644 --- a/src/corelib/text/qstringview.cpp +++ b/src/corelib/text/qstringview.cpp @@ -310,9 +310,11 @@ QT_BEGIN_NAMESPACE /*! \fn const QChar *QStringView::data() const +//! [const-pointer-to-first-ch] Returns a const pointer to the first character in the string view. \note The character array represented by the return value is \e not null-terminated. +//! [const-pointer-to-first-ch] \sa begin(), end(), utf16() */ @@ -321,9 +323,7 @@ QT_BEGIN_NAMESPACE \fn const QChar *QStringView::constData() const \since 6.0 - Returns a const pointer to the first character in the string view. - - \note The character array represented by the return value is \e not null-terminated. + \include qstringview.cpp const-pointer-to-first-ch \sa data(), begin(), end(), utf16() */ @@ -331,12 +331,10 @@ QT_BEGIN_NAMESPACE /*! \fn const storage_type *QStringView::utf16() const - Returns a const pointer to the first character in the string view. + \include qstringview.cpp const-pointer-to-first-ch \c{storage_type} is \c{char16_t}. - \note The character array represented by the return value is \e not null-terminated. - \sa begin(), end(), data() */ @@ -536,8 +534,10 @@ QT_BEGIN_NAMESPACE This function is provided for STL compatibility. +//! [calling-on-empty-is-UB] \warning Calling this function on an empty string view constitutes undefined behavior. +//! [calling-on-empty-is-UB] \sa back(), first(), last() */ @@ -549,8 +549,7 @@ QT_BEGIN_NAMESPACE This function is provided for STL compatibility. - \warning Calling this function on an empty string view constitutes - undefined behavior. + \include qstringview.cpp calling-on-empty-is-UB \sa front(), first(), last() */ @@ -562,8 +561,7 @@ QT_BEGIN_NAMESPACE This function is provided for compatibility with other Qt containers. - \warning Calling this function on an empty string view constitutes - undefined behavior. + \include qstringview.cpp calling-on-empty-is-UB \sa front(), back(), last() */ @@ -575,8 +573,7 @@ QT_BEGIN_NAMESPACE This function is provided for compatibility with other Qt containers. - \warning Calling this function on an empty string view constitutes - undefined behavior. + \include qstringview.cpp calling-on-empty-is-UB \sa back(), front(), first() */ @@ -730,8 +727,7 @@ QT_BEGIN_NAMESPACE Returns an integer that compares to zero as this string view compares to the string view \a str. - If \a cs is Qt::CaseSensitive (the default), the comparison is case sensitive; - otherwise the comparison is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} \sa operator==(), operator<(), operator>() */ @@ -745,8 +741,7 @@ QT_BEGIN_NAMESPACE Returns an integer that compares to zero as this string view compares to the Latin-1 string \a l1, or character \a ch, respectively. - If \a cs is Qt::CaseSensitive (the default), the comparison is case sensitive; - otherwise the comparison is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} \sa operator==(), operator<(), operator>() */ @@ -789,8 +784,7 @@ QT_BEGIN_NAMESPACE Latin-1 string \a l1, or character \a ch, respectively; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive; - otherwise the search is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa endsWith() */ @@ -805,8 +799,7 @@ QT_BEGIN_NAMESPACE Latin-1 string \a l1, or character \a ch, respectively; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (the default), the search is case-sensitive; - otherwise the search is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa startsWith() */ @@ -821,11 +814,9 @@ QT_BEGIN_NAMESPACE Latin-1 string \a l1, or character \a ch, respectively, in this string view, searching forward from index position \a from. Returns -1 if \a str is not found. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} - If \a from is -1, the search starts at the last character; if it is - -2, at the next to last character and so on. + \include qstring.qdocinc negative-index-start-search-from-end \sa QString::indexOf() */ @@ -839,8 +830,7 @@ QT_BEGIN_NAMESPACE Returns \c true if this string view contains an occurrence of the string view \a str, Latin-1 string \a l1, or character \a ch; otherwise returns \c false. - If \a cs is Qt::CaseSensitive (the default), the search is - case-sensitive; otherwise the search is case-insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa indexOf() */ @@ -853,12 +843,13 @@ QT_BEGIN_NAMESPACE Returns the index position of the last occurrence of the string view \a str, Latin-1 string \a l1, or character \a ch, respectively, in this string view, - searching backward from index position \a from. If \a from is -1, - the search starts at the last character; if \a from is -2, at the next to last - character and so on. Returns -1 if \a str is not found. + searching backward from index position \a from. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc negative-index-start-search-from-end + + Returns -1 if \a str is not found. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \note When searching for a 0-length \a str or \a l1, the match at the end of the data is excluded from the search by a negative \a @@ -882,8 +873,7 @@ QT_BEGIN_NAMESPACE searching backward from the last character of this string view. Returns -1 if \a str is not found. - If \a cs is Qt::CaseSensitive (default), the search is case - sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa QString::lastIndexOf() */ @@ -918,9 +908,11 @@ QT_BEGIN_NAMESPACE Returns the index position of the last match of the regular expression \a re in the string view, which starts before the index - position \a from. If \a from is -1, the search starts at the last - character; if \a from is -2, at the next to last character and so - on. Returns -1 if \a re didn't match anywhere. + position \a from. + + \include qstring.qdocinc negative-index-start-search-from-end + + Returns -1 if \a re didn't match anywhere. If the match is successful and \a rmatch is not \nullptr, it also writes the results of the match into the QRegularExpressionMatch object @@ -1104,8 +1096,7 @@ QT_BEGIN_NAMESPACE Returns the number of occurrences of the character \a ch in the string view. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa QString::count(), contains(), indexOf() */ @@ -1119,8 +1110,7 @@ QT_BEGIN_NAMESPACE Returns the number of (potentially overlapping) occurrences of the string view \a str in this string view. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa QString::count(), contains(), indexOf() */ @@ -1134,8 +1124,7 @@ QT_BEGIN_NAMESPACE Returns the number of (potentially overlapping) occurrences of the Latin-1 string \a l1 in this string view. - If \a cs is Qt::CaseSensitive (default), the search is - case sensitive; otherwise the search is case insensitive. + \include qstring.qdocinc {search-comparison-case-sensitivity} {search} \sa QString::count(), contains(), indexOf() */