summaryrefslogtreecommitdiffstats
path: root/src/corelib/text/qstringview.cpp
diff options
context:
space:
mode:
Diffstat (limited to 'src/corelib/text/qstringview.cpp')
-rw-r--r--src/corelib/text/qstringview.cpp631
1 files changed, 413 insertions, 218 deletions
diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp
index a36a98fca4..29b83ffe8f 100644
--- a/src/corelib/text/qstringview.cpp
+++ b/src/corelib/text/qstringview.cpp
@@ -1,45 +1,7 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com>
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the QtCore module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2017 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com>
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
#include "qstringview.h"
-#include "qstring.h"
-#include "qlocale_p.h"
QT_BEGIN_NAMESPACE
@@ -69,8 +31,8 @@ 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, QStringRef, and
- \c{(const QChar*, int)}), while at the same time enabling even more string data
+ thus replaces three function overloads (taking QString and
+ \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.
@@ -87,11 +49,11 @@ QT_BEGIN_NAMESPACE
QChar constructor by itself.
\li \e QString: if you store an unmodified copy of the string and thus would
like to take advantage of QString's implicit sharing.
- \li QLatin1String: if you can implement the function without converting the
- QLatin1String to UTF-16 first; users expect a function overloaded on
- QLatin1String to perform strictly less memory allocations than the
+ \li QLatin1StringView: if you can implement the function without converting the
+ QLatin1StringView to UTF-16 first; users expect a function overloaded on
+ QLatin1StringView to perform strictly less memory allocations than the
semantically equivalent call of the QStringView version, involving
- construction of a QString from the QLatin1String.
+ construction of a QString from the QLatin1StringView.
\endlist
QStringView can also be used as the return value of a function. If you call a
@@ -105,7 +67,7 @@ QT_BEGIN_NAMESPACE
allowed in \c constexpr functions). You can use an indexed loop and/or utf16() in
\c constexpr contexts instead.
- \sa QString, QStringRef
+ \sa QString
*/
/*!
@@ -130,11 +92,6 @@ QT_BEGIN_NAMESPACE
\typedef QStringView::size_type
Alias for qsizetype. Provided for compatibility with the STL.
-
- Unlike other Qt classes, QStringView uses qsizetype as its \c size_type, to allow
- accepting data from \c{std::basic_string} without truncation. The Qt API functions,
- for example length(), return \c int, while the STL-compatible functions, for example
- size(), return \c size_type.
*/
/*!
@@ -222,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.
@@ -238,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).
@@ -278,11 +235,9 @@ QT_BEGIN_NAMESPACE
\fn template <typename Char, size_t N> QStringView::QStringView(const Char (&string)[N])
Constructs a string view on the character string literal \a string.
- The length is set to \c{N-1}, excluding the trailing \{Char(0)}.
- If you need the full array, use the constructor from pointer and
- size instead:
-
- \snippet code/src_corelib_text_qstringview.cpp 2
+ The view covers the array until the first \c{Char(0)} is encountered,
+ or \c N, whichever comes first.
+ If you need the full array, use fromArray() instead.
\a string must remain valid for the lifetime of this string view
object.
@@ -292,20 +247,12 @@ QT_BEGIN_NAMESPACE
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.
-*/
-
-/*!
- \fn QStringView::QStringView(const QString &str)
-
- Constructs a string view on \a str.
-
- \c{str.data()} must remain valid for the lifetime of this string view object.
- The string view will be null if and only if \c{str.isNull()}.
+ \sa fromArray
*/
/*!
- \fn QStringView::QStringView(const QStringRef &str)
+ \fn QStringView::QStringView(const QString &str)
Constructs a string view on \a str.
@@ -315,42 +262,59 @@ QT_BEGIN_NAMESPACE
*/
/*!
- \fn template <typename StdBasicString> QStringView::QStringView(const StdBasicString &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, 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
+ null-terminator included in the view then you can chop() it off
+ when you are certain it is at the end. Alternatively you can use
+ the constructor overload taking an array literal which will create
+ a view up to, but not including, the first null-terminator in the data.
+
+ \a string must remain valid for the lifetime of this string view
+ object.
+
+ This function will work with any array literal if \c Char is a
+ compatible character 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.
+*/
+
+/*!
\fn QString QStringView::toString() const
Returns a deep copy of this string view's data as a QString.
The return value will be the null QString if and only if this string view is null.
-
- \warning QStringView can store strings with more than 2\sup{30} characters
- while QString cannot. Calling this function on a string view for which size()
- returns a value greater than \c{INT_MAX / 2} constitutes undefined behavior.
*/
/*!
\fn const QChar *QStringView::data() const
- Returns a const pointer to the first character in the string.
+//! [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()
*/
@@ -359,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.
-
- \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()
*/
@@ -369,12 +331,10 @@ QT_BEGIN_NAMESPACE
/*!
\fn const storage_type *QStringView::utf16() const
- Returns a const pointer to the first character in the string.
+ \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()
*/
@@ -382,11 +342,11 @@ QT_BEGIN_NAMESPACE
\fn QStringView::const_iterator QStringView::begin() const
Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first character in
- the string.
+ the string view.
This function is provided for STL compatibility.
- \sa end(), cbegin(), rbegin(), data()
+ \sa end(), constBegin(), cbegin(), rbegin(), data()
*/
/*!
@@ -396,7 +356,16 @@ QT_BEGIN_NAMESPACE
This function is provided for STL compatibility.
- \sa cend(), begin(), crbegin(), data()
+ \sa cend(), begin(), constBegin(), crbegin(), data()
+*/
+
+/*!
+ \fn QStringView::const_iterator QStringView::constBegin() const
+ \since 6.1
+
+ Same as begin().
+
+ \sa constEnd(), begin(), cbegin(), crbegin(), data()
*/
/*!
@@ -407,7 +376,7 @@ QT_BEGIN_NAMESPACE
This function is provided for STL compatibility.
- \sa begin(), cend(), rend()
+ \sa begin(), constEnd(), cend(), rend()
*/
/*! \fn QStringView::const_iterator QStringView::cend() const
@@ -416,14 +385,22 @@ QT_BEGIN_NAMESPACE
This function is provided for STL compatibility.
- \sa cbegin(), end(), crend()
+ \sa cbegin(), end(), constEnd(), crend()
+*/
+
+/*! \fn QStringView::const_iterator QStringView::constEnd() const
+ \since 6.1
+
+ Same as end().
+
+ \sa constBegin(), end(), cend(), crend()
*/
/*!
\fn QStringView::const_reverse_iterator QStringView::rbegin() const
Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
- character in the string, in reverse order.
+ character in the string view, in reverse order.
This function is provided for STL compatibility.
@@ -444,7 +421,7 @@ QT_BEGIN_NAMESPACE
\fn QStringView::const_reverse_iterator QStringView::rend() const
Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past
- the last character in the string, in reverse order.
+ the last character in the string view, in reverse order.
This function is provided for STL compatibility.
@@ -494,24 +471,20 @@ 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 and QStringRef).
+ as in QString).
\sa empty(), isEmpty(), isNull(), length()
*/
/*!
- \fn int QStringView::length() const
+ \fn QStringView::length() const
- Same as size(), except returns the result as an \c int.
+ Same as size().
This function is provided for compatibility with other Qt containers.
- \warning QStringView can represent strings with more than 2\sup{31} characters.
- Calling this function on a string view for which size() returns a value greater
- than \c{INT_MAX} constitutes undefined behavior.
-
\sa empty(), isEmpty(), isNull(), size()
*/
@@ -537,7 +510,7 @@ QT_BEGIN_NAMESPACE
/*!
\fn template <typename...Args> QString QStringView::arg(Args &&...args) const
- \fn template <typename...Args> QString QLatin1String::arg(Args &&...args) const
+ \fn template <typename...Args> QString QLatin1StringView::arg(Args &&...args) const
\fn template <typename...Args> QString QString::arg(Args &&...args) const
\since 5.14
@@ -547,7 +520,7 @@ QT_BEGIN_NAMESPACE
second of the \a args the \c{%N} with the next-lowest \c{N} etc.
\c Args can consist of anything that implicitly converts to QString,
- QStringView or QLatin1String.
+ QStringView or QLatin1StringView.
In addition, the following types are also supported: QChar, QLatin1Char.
@@ -557,12 +530,14 @@ QT_BEGIN_NAMESPACE
/*!
\fn QChar QStringView::front() const
- Returns the first character in the string. Same as first().
+ Returns the first character in the string view. Same as first().
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()
*/
@@ -570,12 +545,11 @@ QT_BEGIN_NAMESPACE
/*!
\fn QChar QStringView::back() const
- Returns the last character in the string. Same as last().
+ Returns the last character in the string view. Same as last().
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()
*/
@@ -583,12 +557,11 @@ QT_BEGIN_NAMESPACE
/*!
\fn QChar QStringView::first() const
- Returns the first character in the string. Same as front().
+ Returns the first character in the string view. Same as front().
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()
*/
@@ -596,12 +569,11 @@ QT_BEGIN_NAMESPACE
/*!
\fn QChar QStringView::last() const
- Returns the last character in the string. Same as back().
+ Returns the last character in the string view. Same as back().
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()
*/
@@ -612,11 +584,11 @@ QT_BEGIN_NAMESPACE
Returns the substring of length \a length starting at position
\a start in this object.
- \obsolete Use sliced() instead in new code.
+ \deprecated Use sliced() instead in new code.
Returns an empty string view if \a start exceeds the
- length of the string. If there are less than \a length characters
- available in the string starting at \a start, or if
+ length of the string view. If there are less than \a length characters
+ available in the string view starting at \a start, or if
\a length is negative (default), the function returns all characters that
are available from \a start.
@@ -626,12 +598,12 @@ QT_BEGIN_NAMESPACE
/*!
\fn QStringView QStringView::left(qsizetype length) const
- \obsolete Use first() instead in new code.
+ \deprecated Use first() instead in new code.
Returns the substring of length \a length starting at position
0 in this object.
- The entire string is returned if \a length is greater than or equal
+ The entire string view is returned if \a length is greater than or equal
to size(), or less than zero.
\sa first(), last(), sliced(), startsWith(), chopped(), chop(), truncate()
@@ -640,12 +612,12 @@ QT_BEGIN_NAMESPACE
/*!
\fn QStringView QStringView::right(qsizetype length) const
- \obsolete Use last() instead in new code.
+ \deprecated Use last() instead in new code.
Returns the substring of length \a length starting at position
size() - \a length in this object.
- The entire string is returned if \a length is greater than or equal
+ The entire string view is returned if \a length is greater than or equal
to size(), or less than zero.
\sa first(), last(), sliced(), endsWith(), chopped(), chop(), truncate()
@@ -656,33 +628,36 @@ QT_BEGIN_NAMESPACE
\since 6.0
Returns a string view that points to the first \a n characters
- of this string.
+ of this string view.
\note The behavior is undefined when \a n < 0 or \a n > size().
- \sa last(), subString(), startsWith(), chopped(), chop(), truncate()
+ \sa last(), sliced(), startsWith(), chopped(), chop(), truncate()
*/
/*!
\fn QStringView QStringView::last(qsizetype n) const
\since 6.0
- Returns a string view that points to the last \a n characters of this string.
+ Returns a string view that points to the last \a n characters of this string
+ view.
\note The behavior is undefined when \a n < 0 or \a n > size().
- \sa first(), subString(), endsWith(), chopped(), chop(), truncate()
+ \sa first(), sliced(), endsWith(), chopped(), chop(), truncate()
*/
/*!
\fn QStringView QStringView::sliced(qsizetype pos, qsizetype n) const
\since 6.0
- Returns a string view that points to \a n characters of this string,
+ 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()
*/
@@ -695,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()
*/
@@ -751,115 +728,286 @@ 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>()
*/
/*!
- \fn int QStringView::compare(QLatin1String l1, Qt::CaseSensitivity cs) const
+ \fn int QStringView::compare(QLatin1StringView l1, Qt::CaseSensitivity cs) const
\fn int QStringView::compare(QChar ch) const
\fn int QStringView::compare(QChar ch, Qt::CaseSensitivity cs) const
- \since 5.14
+ \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==(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.
+
+ \sa compare()
+*/
+
+/*!
+ \fn int QStringView::localeAwareCompare(QStringView other) const
+ \since 6.4
+
+ Compares this string view with the \a other string view and returns
+ an integer less than, equal to, or greater than zero if this string
+ view is less than, equal to, or greater than the \a other string view.
+
+ The comparison is performed in a locale- and also platform-dependent
+ manner. Use this function to present sorted lists of strings to the
+ user.
+
+ \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(QLatin1String l1, 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()
*/
/*!
\fn bool QStringView::endsWith(QStringView str, Qt::CaseSensitivity cs) const
- \fn bool QStringView::endsWith(QLatin1String l1, Qt::CaseSensitivity cs) const
+ \fn bool QStringView::endsWith(QLatin1StringView l1, Qt::CaseSensitivity cs) const
\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()
*/
/*!
\fn qsizetype QStringView::indexOf(QStringView str, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
- \fn qsizetype QStringView::indexOf(QLatin1String l1, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
+ \fn qsizetype QStringView::indexOf(QLatin1StringView l1, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
\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()
*/
/*!
\fn bool QStringView::contains(QStringView str, Qt::CaseSensitivity cs) const
- \fn bool QStringView::contains(QLatin1String l1, Qt::CaseSensitivity cs) const
+ \fn bool QStringView::contains(QLatin1StringView l1, Qt::CaseSensitivity cs) const
\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()
*/
/*!
\fn qsizetype QStringView::lastIndexOf(QStringView str, qsizetype from, Qt::CaseSensitivity cs) const
- \fn qsizetype QStringView::lastIndexOf(QLatin1String l1, qsizetype from, Qt::CaseSensitivity cs) const
+ \fn qsizetype QStringView::lastIndexOf(QLatin1StringView l1, qsizetype from, Qt::CaseSensitivity cs) const
\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 (default),
- 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
+
+ Returns -1 if \a str, \a l1 or \a c 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}
+
+ \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
+ from, even though \c{-1} is normally thought of as searching from
+ the end of the string view: the match at the end is \e after the
+ last character, so it is excluded. To include such a final empty
+ match, either give a positive value for \a from or omit the \a from
+ parameter entirely.
\sa QString::lastIndexOf()
*/
/*!
+ \fn qsizetype QStringView::lastIndexOf(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
+ \fn qsizetype QStringView::lastIndexOf(QLatin1StringView l1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
+ \since 6.2
+ \overload lastIndexOf()
+
+ 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.
+
+ \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
+
+ \sa QString::lastIndexOf()
+*/
+
+/*!
+ \fn QStringView::lastIndexOf(QChar c, Qt::CaseSensitivity cs) const
+ \since 6.3
+ \overload lastIndexOf()
+*/
+
+#if QT_CONFIG(regularexpression)
+/*!
+ \fn qsizetype QStringView::indexOf(const QRegularExpression &re, qsizetype from, QRegularExpressionMatch *rmatch) const
+ \since 6.1
+
+ Returns the index position of the first match of the regular
+ expression \a re in the string view, searching forward from index
+ position \a from. 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
+ pointed to by \a rmatch.
+
+ \note Due to how the regular expression matching algorithm works,
+ this function will actually match repeatedly from the beginning of
+ the string view until the position \a from is reached.
+*/
+
+/*!
+ \fn qsizetype QStringView::lastIndexOf(const QRegularExpression &re, qsizetype from, QRegularExpressionMatch *rmatch) const
+ \since 6.1
+
+ 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.
+
+ \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
+ pointed to by \a rmatch.
+
+ \note Due to how the regular expression matching algorithm works,
+ this function will actually match repeatedly from the beginning of
+ the string view until the position \a from is reached.
+
+ \note When searching for a regular expression \a re that may match
+ 0 characters, the match at the end of the data is excluded from the
+ search by a negative \a from, even though \c{-1} is normally
+ thought of as searching from the end of the string view: the match
+ at the end is \e after the last character, so it is excluded. To
+ include such a final empty match, either give a positive value for
+ \a from or omit the \a from parameter entirely.
+*/
+
+/*!
+ \fn qsizetype QStringView::lastIndexOf(const QRegularExpression &re, QRegularExpressionMatch *rmatch = nullptr) const
+ \since 6.2
+
+ Returns the index position of the last match of the regular
+ expression \a re in the string view. 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
+ pointed to by \a rmatch.
+
+ \note Due to how the regular expression matching algorithm works,
+ this function will actually match repeatedly from the beginning of
+ the string view until the end of the string view is reached.
+*/
+
+/*!
+ \fn bool QStringView::contains(const QRegularExpression &re, QRegularExpressionMatch *rmatch) const
+ \since 6.1
+
+ Returns \c true if the regular expression \a re matches somewhere in this
+ string view; otherwise returns \c false.
+
+ If the match is successful and \a rmatch is not \nullptr, it also
+ writes the results of the match into the QRegularExpressionMatch object
+ pointed to by \a rmatch.
+
+ \sa QRegularExpression::match()
+*/
+
+/*!
+ \fn qsizetype QStringView::count(const QRegularExpression &re) const
+ \since 6.1
+
+ Returns the number of times the regular expression \a re matches
+ in the string view.
+
+ For historical reasons, this function counts overlapping matches.
+ This behavior is different from simply iterating over the matches
+ in the string view using QRegularExpressionMatchIterator.
+
+ \sa QRegularExpression::globalMatch()
+
+*/
+#endif // QT_CONFIG(regularexpression)
+
+/*!
\fn QByteArray QStringView::toLatin1() const
Returns a Latin-1 representation of the string as a QByteArray.
@@ -886,7 +1034,7 @@ QT_BEGIN_NAMESPACE
/*!
\fn QByteArray QStringView::toUtf8() const
- Returns a UTF-8 representation of the string as a QByteArray.
+ Returns a UTF-8 representation of the string view as a QByteArray.
UTF-8 is a Unicode codec and can represent all characters in a Unicode
string like QString.
@@ -897,11 +1045,11 @@ QT_BEGIN_NAMESPACE
/*!
\fn QList<uint> QStringView::toUcs4() const
- Returns a UCS-4/UTF-32 representation of the string as a QList<uint>.
+ Returns a UCS-4/UTF-32 representation of the string view as a QList<uint>.
UCS-4 is a Unicode codec and therefore it is lossless. All characters from
- this string will be encoded in UCS-4. Any invalid sequence of code units in
- this string is replaced by the Unicode replacement character
+ this string view will be encoded in UCS-4. Any invalid sequence of code units in
+ this string view is replaced by the Unicode replacement character
(QChar::ReplacementCharacter, which corresponds to \c{U+FFFD}).
The returned list is not 0-terminated.
@@ -916,19 +1064,19 @@ QT_BEGIN_NAMESPACE
Convert \a s to a QStringView ignoring \c{s.isNull()}.
- Returns a string-view that references \a{s}' data, but is never null.
+ Returns a string view that references \a{s}' data, but is never null.
- This is a faster way to convert a QString or QStringRef to a QStringView,
+ This is a faster way to convert a QString to a QStringView,
if null QStrings can legitimately be treated as empty ones.
- \sa QString::isNull(), QStringRef::isNull(), QStringView
+ \sa QString::isNull(), QStringView
*/
/*!
\fn bool QStringView::isRightToLeft() const
\since 5.11
- Returns \c true if the string is read right to left.
+ Returns \c true if the string view is read right to left.
\sa QString::isRightToLeft()
*/
@@ -937,7 +1085,7 @@ QT_BEGIN_NAMESPACE
\fn bool QStringView::isValidUtf16() const
\since 5.15
- Returns \c true if the string contains valid UTF-16 encoded data,
+ Returns \c true if the string view contains valid UTF-16 encoded data,
or \c false otherwise.
Note that this function does not perform any special validation of the
@@ -949,14 +1097,40 @@ 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
- Transcribes this string into the given \a array.
+ Transcribes this string view into the given \a array.
The caller is responsible for ensuring \a array is large enough to hold the
- \c wchar_t encoding of this string (allocating the array with the same length
- as the string is always sufficient). The array is encoded in UTF-16 on
+ \c wchar_t encoding of this string view (allocating the array with the same length
+ as the string view is always sufficient). The array is encoded in UTF-16 on
platforms where \c wchar_t is 2 bytes wide (e.g. Windows); otherwise (Unix
systems), \c wchar_t is assumed to be 4 bytes wide and the data is written
in UCS-4.
@@ -975,10 +1149,9 @@ QT_BEGIN_NAMESPACE
\overload count()
Returns the number of occurrences of the character \a ch in the
- string reference.
+ 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()
*/
@@ -990,10 +1163,23 @@ QT_BEGIN_NAMESPACE
\overload count()
Returns the number of (potentially overlapping) occurrences of the
- string reference \a str in this string reference.
+ 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()
+*/
+
+/*!
+ \fn qsizetype QStringView::count(QLatin1StringView l1, Qt::CaseSensitivity cs) const noexcept
+
+ \since 6.4
+ \overload count()
+
+ Returns the number of (potentially overlapping) occurrences of the
+ Latin-1 string viewed by \a l1 in this string view.
+
+ \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
\sa QString::count(), contains(), indexOf()
*/
@@ -1001,15 +1187,15 @@ QT_BEGIN_NAMESPACE
/*!
\fn qint64 QStringView::toLongLong(bool *ok, int base) const
- Returns the string converted to a \c{long long} using base \a
+ Returns the string view converted to a \c{long long} using base \a
base, which is 10 by default and must be between 2 and 36, or 0.
Returns 0 if the conversion fails.
If \a ok is not \nullptr, failure is reported by setting *\a{ok}
to \c false, and success by setting *\a{ok} to \c true.
- If \a base is 0, the C language convention is used: If the string
- begins with "0x", base 16 is used; if the string begins with "0",
+ If \a base is 0, the C language convention is used: if the string view
+ begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
base 8 is used; otherwise, base 10 is used.
The string conversion will always happen in the 'C' locale. For locale
@@ -1023,15 +1209,15 @@ QT_BEGIN_NAMESPACE
/*!
\fn quint64 QStringView::toULongLong(bool *ok, int base) const
- Returns the string converted to an \c{unsigned long long} using base \a
+ Returns the string view converted to an \c{unsigned long long} using base \a
base, which is 10 by default and must be between 2 and 36, or 0.
Returns 0 if the conversion fails.
If \a ok is not \nullptr, failure is reported by setting *\a{ok}
to \c false, and success by setting *\a{ok} to \c true.
- If \a base is 0, the C language convention is used: If the string
- begins with "0x", base 16 is used; if the string begins with "0",
+ If \a base is 0, the C language convention is used: if the string view
+ begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
base 8 is used; otherwise, base 10 is used.
The string conversion will always happen in the 'C' locale. For locale
@@ -1045,15 +1231,15 @@ QT_BEGIN_NAMESPACE
/*!
\fn long QStringView::toLong(bool *ok, int base) const
- Returns the string converted to a \c long using base \a
+ Returns the string view converted to a \c long using base \a
base, which is 10 by default and must be between 2 and 36, or 0.
Returns 0 if the conversion fails.
If \a ok is not \nullptr, failure is reported by setting *\a{ok}
to \c false, and success by setting *\a{ok} to \c true.
- If \a base is 0, the C language convention is used: If the string
- begins with "0x", base 16 is used; if the string begins with "0",
+ If \a base is 0, the C language convention is used: if the string view
+ begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
base 8 is used; otherwise, base 10 is used.
The string conversion will always happen in the 'C' locale. For locale
@@ -1067,15 +1253,15 @@ QT_BEGIN_NAMESPACE
/*!
\fn ulong QStringView::toULong(bool *ok, int base) const
- Returns the string converted to an \c{unsigned long} using base \a
+ Returns the string view converted to an \c{unsigned long} using base \a
base, which is 10 by default and must be between 2 and 36, or 0.
Returns 0 if the conversion fails.
If \a ok is not \nullptr, failure is reported by setting *\a{ok}
to \c false, and success by setting *\a{ok} to \c true.
- If \a base is 0, the C language convention is used: If the string
- begins with "0x", base 16 is used; if the string begins with "0",
+ If \a base is 0, the C language convention is used: if the string view
+ begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
base 8 is used; otherwise, base 10 is used.
The string conversion will always happen in the 'C' locale. For locale
@@ -1089,15 +1275,15 @@ QT_BEGIN_NAMESPACE
/*!
\fn int QStringView::toInt(bool *ok, int base) const
- Returns the string converted to an \c int using base \a
+ Returns the string view converted to an \c int using base \a
base, which is 10 by default and must be between 2 and 36, or 0.
Returns 0 if the conversion fails.
If \a ok is not \nullptr, failure is reported by setting *\a{ok}
to \c false, and success by setting *\a{ok} to \c true.
- If \a base is 0, the C language convention is used: If the string
- begins with "0x", base 16 is used; if the string begins with "0",
+ If \a base is 0, the C language convention is used: if the string view
+ begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
base 8 is used; otherwise, base 10 is used.
The string conversion will always happen in the 'C' locale. For locale
@@ -1111,15 +1297,15 @@ QT_BEGIN_NAMESPACE
/*!
\fn uint QStringView::toUInt(bool *ok, int base) const
- Returns the string converted to an \c{unsigned int} using base \a
+ Returns the string view converted to an \c{unsigned int} using base \a
base, which is 10 by default and must be between 2 and 36, or 0.
Returns 0 if the conversion fails.
If \a ok is not \nullptr, failure is reported by setting *\a{ok}
to \c false, and success by setting *\a{ok} to \c true.
- If \a base is 0, the C language convention is used: If the string
- begins with "0x", base 16 is used; if the string begins with "0",
+ If \a base is 0, the C language convention is used: if the string view
+ begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
base 8 is used; otherwise, base 10 is used.
The string conversion will always happen in the 'C' locale. For locale
@@ -1133,15 +1319,15 @@ QT_BEGIN_NAMESPACE
/*!
\fn short QStringView::toShort(bool *ok, int base) const
- Returns the string converted to a \c short using base \a
+ Returns the string view converted to a \c short using base \a
base, which is 10 by default and must be between 2 and 36, or 0.
Returns 0 if the conversion fails.
If \a ok is not \nullptr, failure is reported by setting *\a{ok}
to \c false, and success by setting *\a{ok} to \c true.
- If \a base is 0, the C language convention is used: If the string
- begins with "0x", base 16 is used; if the string begins with "0",
+ If \a base is 0, the C language convention is used: if the string view
+ begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
base 8 is used; otherwise, base 10 is used.
The string conversion will always happen in the 'C' locale. For locale
@@ -1155,15 +1341,15 @@ QT_BEGIN_NAMESPACE
/*!
\fn ushort QStringView::toUShort(bool *ok, int base) const
- Returns the string converted to an \c{unsigned short} using base \a
+ Returns the string view converted to an \c{unsigned short} using base \a
base, which is 10 by default and must be between 2 and 36, or 0.
Returns 0 if the conversion fails.
If \a ok is not \nullptr, failure is reported by setting *\a{ok}
to \c false, and success by setting *\a{ok} to \c true.
- If \a base is 0, the C language convention is used: If the string
- begins with "0x", base 16 is used; if the string begins with "0",
+ If \a base is 0, the C language convention is used: if the string view
+ begins with "0x", base 16 is used; otherwise, if the string view begins with "0",
base 8 is used; otherwise, base 10 is used.
The string conversion will always happen in the 'C' locale. For locale
@@ -1177,7 +1363,7 @@ QT_BEGIN_NAMESPACE
/*!
\fn double QStringView::toDouble(bool *ok) const
- Returns the string converted to a \c double value.
+ Returns the string view converted to a \c double value.
Returns an infinity if the conversion overflows or 0.0 if the
conversion fails for other reasons (e.g. underflow).
@@ -1200,7 +1386,7 @@ QT_BEGIN_NAMESPACE
/*!
\fn float QStringView::toFloat(bool *ok) const
- Returns the string converted to a \c float value.
+ Returns the string view converted to a \c float value.
Returns an infinity if the conversion overflows or 0.0 if the
conversion fails for other reasons (e.g. underflow).
@@ -1218,11 +1404,11 @@ QT_BEGIN_NAMESPACE
/*!
- \fn QStringView::tokenize(Needle &&sep, Flags...flags) const
- \fn QLatin1String::tokenize(Needle &&sep, Flags...flags) const
- \fn QString::tokenize(Needle &&sep, Flags...flags) const &
- \fn QString::tokenize(Needle &&sep, Flags...flags) const &&
- \fn QString::tokenize(Needle &&sep, Flags...flags) &&
+ \fn template <typename Needle, typename...Flags> auto QStringView::tokenize(Needle &&sep, Flags...flags) const
+ \fn template <typename Needle, typename...Flags> auto QLatin1StringView::tokenize(Needle &&sep, Flags...flags) const
+ \fn template <typename Needle, typename...Flags> auto QString::tokenize(Needle &&sep, Flags...flags) const &
+ \fn template <typename Needle, typename...Flags> auto QString::tokenize(Needle &&sep, Flags...flags) const &&
+ \fn template <typename Needle, typename...Flags> auto QString::tokenize(Needle &&sep, Flags...flags) &&
Splits the string into substring views wherever \a sep occurs, and
returns a lazy sequence of those strings.
@@ -1258,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