diff options
Diffstat (limited to 'src/corelib/text/qstringview.cpp')
| -rw-r--r-- | src/corelib/text/qstringview.cpp | 219 |
1 files changed, 136 insertions, 83 deletions
diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp index c13b51b493..29b83ffe8f 100644 --- a/src/corelib/text/qstringview.cpp +++ b/src/corelib/text/qstringview.cpp @@ -32,7 +32,7 @@ QT_BEGIN_NAMESPACE When used as an interface type, QStringView allows a single function to accept a wide variety of UTF-16 string data sources. One function accepting QStringView thus replaces three function overloads (taking QString and - \c{(const QChar*, int)}), while at the same time enabling even more string data + \c{(const QChar*, qsizetype)}), while at the same time enabling even more string data sources to be passed to the function, such as \c{u"Hello World"}, a \c char16_t string literal. @@ -179,7 +179,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn template <typename Char> QStringView::QStringView(const Char *str, qsizetype len) + \fn template <typename Char, QStringView::if_compatible_char<Char> = true> QStringView::QStringView(const Char *str, qsizetype len) Constructs a string view on \a str with length \a len. @@ -195,7 +195,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn template <typename Char> QStringView::QStringView(const Char *first, const Char *last) + \fn template <typename Char, QStringView::if_compatible_char<Char> = true> QStringView::QStringView(const Char *first, const Char *last) Constructs a string view on \a first with length (\a last - \a first). @@ -262,26 +262,26 @@ QT_BEGIN_NAMESPACE */ /*! - \fn template <typename Container, if_compatible_container<Container>> QStringView::QStringView(const Container &str) + \fn template <typename Container, QStringView::if_compatible_container<Container>> QStringView::QStringView(const Container &str) - Constructs a string view on \a str. The length is taken from \c{str.size()}. + Constructs a string view on \a str. The length is taken from \c{std::size(str)}. - \c{str.data()} must remain valid for the lifetime of this string view object. + \c{std::data(str)} must remain valid for the lifetime of this string view object. - This constructor only participates in overload resolution if \c StdBasicString is an - instantiation of \c std::basic_string with a compatible character type. The + This constructor only participates in overload resolution if \c Container is a + container with a compatible character type as \c{value_type}. The compatible character types are: \c QChar, \c ushort, \c char16_t and (on platforms, such as Windows, where it is a 16-bit type) \c wchar_t. - The string view will be empty if and only if \c{str.empty()}. It is unspecified - whether this constructor can result in a null string view (\c{str.data()} would + The string view will be empty if and only if \c{std::size(str) == 0}. It is unspecified + whether this constructor can result in a null string view (\c{std::data(str)} would have to return \nullptr for this). \sa isNull(), isEmpty() */ /*! - \fn template <typename Char, size_t Size> static QStringView QStringView::fromArray(const Char (&string)[Size]) noexcept + \fn template <typename Char, size_t Size, QStringView::if_compatible_char<Char> = true> static QStringView QStringView::fromArray(const Char (&string)[Size]) noexcept Constructs a string view on the full character string literal \a string, including any trailing \c{Char(0)}. If you don't want the @@ -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() */ @@ -473,7 +471,7 @@ QT_BEGIN_NAMESPACE /*! \fn qsizetype QStringView::size() const - Returns the size of this string view, in UTF-16 code points (that is, + Returns the size of this string view, in UTF-16 code units (that is, surrogate pairs count as two for the purposes of this function, the same as in QString). @@ -481,7 +479,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn int QStringView::length() const + \fn QStringView::length() const Same as size(). @@ -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() */ @@ -657,8 +654,10 @@ QT_BEGIN_NAMESPACE Returns a string view that points to \a n characters of this string view, starting at position \a pos. +//! [UB-sliced-index-length] \note The behavior is undefined when \a pos < 0, \a n < 0, or \a pos + \a n > size(). +//! [UB-sliced-index-length] \sa first(), last(), chopped(), chop(), truncate() */ @@ -671,7 +670,9 @@ QT_BEGIN_NAMESPACE Returns a string view starting at position \a pos in this object, and extending to its end. +//! [UB-sliced-index-only] \note The behavior is undefined when \a pos < 0 or \a pos > size(). +//! [UB-sliced-index-only] \sa first(), last(), chopped(), chop(), truncate() */ @@ -727,11 +728,24 @@ QT_BEGIN_NAMESPACE \fn int QStringView::compare(QStringView str, Qt::CaseSensitivity cs) const \since 5.12 - Returns an integer that compares to zero as this string view compares to the - string view \a str. + Compares this string view with string view \a str and returns a negative integer if + this string view is less than \a str, a positive integer if it is greater than + \a str, and zero if they are equal. + + \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison} + + \sa operator==(), operator<(), operator>() +*/ + +/*! + \fn int QStringView::compare(QUtf8StringView str, Qt::CaseSensitivity cs) const + \since 6.5 + + Compares this string view with QUtf8StringView \a str and returns a negative integer if + this string view is less than \a str, a positive integer if it is greater than + \a str, and zero if they are equal. - 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>() */ @@ -742,22 +756,22 @@ QT_BEGIN_NAMESPACE \fn int QStringView::compare(QChar ch, Qt::CaseSensitivity cs) const \since 5.15 - Returns an integer that compares to zero as this string view compares to the - Latin-1 string \a l1, or character \a ch, respectively. + Compares this string view to the Latin-1 string view \a l1, or the character \a ch. + Returns a negative integer if this string view is less than \a l1 or \a ch, + a positive integer if it is greater than \a l1 or \a ch, and zero if they are equal. - 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>() */ /*! - \fn QStringView::operator==(QStringView lhs, QStringView rhs) - \fn QStringView::operator!=(QStringView lhs, QStringView rhs) - \fn QStringView::operator< (QStringView lhs, QStringView rhs) - \fn QStringView::operator<=(QStringView lhs, QStringView rhs) - \fn QStringView::operator> (QStringView lhs, QStringView rhs) - \fn QStringView::operator>=(QStringView lhs, QStringView rhs) + \fn QStringView::operator==(const QStringView &lhs, const QStringView &rhs) + \fn QStringView::operator!=(const QStringView &lhs, const QStringView &rhs) + \fn QStringView::operator< (const QStringView &lhs, const QStringView &rhs) + \fn QStringView::operator<=(const QStringView &lhs, const QStringView &rhs) + \fn QStringView::operator> (const QStringView &lhs, const QStringView &rhs) + \fn QStringView::operator>=(const QStringView &lhs, const QStringView &rhs) Operators for comparing \a lhs to \a rhs. @@ -779,18 +793,24 @@ QT_BEGIN_NAMESPACE \sa {Comparing Strings} */ +/* +//! [utf16-or-latin1-or-ch] +the UTF-16 string viewed by \a str, the Latin-1 string viewed by \a l1, +or the character \a ch +//! [utf16-or-latin1-or-ch] +*/ + /*! \fn bool QStringView::startsWith(QStringView str, Qt::CaseSensitivity cs) const \fn bool QStringView::startsWith(QLatin1StringView l1, Qt::CaseSensitivity cs) const \fn bool QStringView::startsWith(QChar ch) const \fn bool QStringView::startsWith(QChar ch, Qt::CaseSensitivity cs) const - Returns \c true if this string view starts with string view \a str, - Latin-1 string \a l1, or character \a ch, respectively; - otherwise returns \c false. + Returns \c true if this string view starts with + \include qstringview.cpp utf16-or-latin1-or-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() */ @@ -801,12 +821,11 @@ QT_BEGIN_NAMESPACE \fn bool QStringView::endsWith(QChar ch) const \fn bool QStringView::endsWith(QChar ch, Qt::CaseSensitivity cs) const - Returns \c true if this string view ends with string view \a str, - Latin-1 string \a l1, or character \a ch, respectively; - otherwise returns \c false. + Returns \c true if this string view ends with + \include qstringview.cpp utf16-or-latin1-or-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() */ @@ -817,15 +836,14 @@ QT_BEGIN_NAMESPACE \fn qsizetype QStringView::indexOf(QChar c, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const \since 5.14 - Returns the index position of the first occurrence of the string view \a str, - 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. + Returns the index position of the first occurrence of + \include qstringview.cpp utf16-or-latin1-or-ch + respectively, in this string view, searching forward from index position + \a from. Returns -1 if \a str, \a l1 or \a ch is not found, respectively. - 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() */ @@ -836,11 +854,11 @@ QT_BEGIN_NAMESPACE \fn bool QStringView::contains(QChar c, Qt::CaseSensitivity cs) const \since 5.14 - 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. + Returns \c true if this string view contains an occurrence of + \include qstringview.cpp utf16-or-latin1-or-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 indexOf() */ @@ -851,14 +869,16 @@ QT_BEGIN_NAMESPACE \fn qsizetype QStringView::lastIndexOf(QChar c, qsizetype from, Qt::CaseSensitivity cs) const \since 5.14 - 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. + Returns the index position of the last occurrence of + \include qstringview.cpp utf16-or-latin1-or-ch + respectively, in this string view, searching backward from index + position \a from. + + \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. + Returns -1 if \a str, \a l1 or \a c is not found, respectively. + + \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 @@ -877,13 +897,12 @@ QT_BEGIN_NAMESPACE \since 6.2 \overload lastIndexOf() - Returns the index position of the last occurrence of the string view \a str - or Latin-1 string \a l1, respectively, in this string view, - searching backward from the last character of this string view. - Returns -1 if \a str is not found. + Returns the index position of the last occurrence of the UTF-16 string viewed + by \a str or the Latin-1 string viewed by \a l1 respectively, in this string + view searching backward from the last character of this string view. Returns + -1 if \a str or \a l1 is not found, respectively. - 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 +937,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 @@ -1076,6 +1097,32 @@ QT_BEGIN_NAMESPACE */ /*! + \fn bool QStringView::isLower() const + \since 6.7 + Returns \c true if this view is identical to its lowercase folding. + + Note that this does \e not mean that the string view does not contain + uppercase letters (some uppercase letters do not have a lowercase + folding; they are left unchanged by toString().toLower()). + For more information, refer to the Unicode standard, section 3.13. + + \sa QChar::toLower(), isUpper() +*/ + +/*! + \fn bool QStringView::isUpper() const + \since 6.7 + Returns \c true if this view is identical to its uppercase folding. + + Note that this does \e not mean that the the string view does not contain + lowercase letters (some lowercase letters do not have a uppercase + folding; they are left unchanged by toString().toUpper()). + For more information, refer to the Unicode standard, section 3.13. + + \sa QChar::toUpper(), isLower() +*/ + +/*! \fn QStringView::toWCharArray(wchar_t *array) const \since 5.14 @@ -1104,8 +1151,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 +1165,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() */ @@ -1132,10 +1177,9 @@ QT_BEGIN_NAMESPACE \overload count() Returns the number of (potentially overlapping) occurrences of the - Latin-1 string \a l1 in this string view. + Latin-1 string viewed by \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() */ @@ -1400,4 +1444,13 @@ QT_BEGIN_NAMESPACE \sa QStringTokenizer, qTokenize() */ +/*! + \fn QStringView::operator std::u16string_view() const + \since 6.7 + + Converts this QStringView object to a \c{std::u16string_view} object. + The returned view will have the same data pointer and length of + this view. +*/ + QT_END_NAMESPACE |