summaryrefslogtreecommitdiffstats
path: root/src/corelib/text/qutf8stringview.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'src/corelib/text/qutf8stringview.qdoc')
-rw-r--r--src/corelib/text/qutf8stringview.qdoc176
1 files changed, 84 insertions, 92 deletions
diff --git a/src/corelib/text/qutf8stringview.qdoc b/src/corelib/text/qutf8stringview.qdoc
index 8ff208ff23..b433e5b995 100644
--- a/src/corelib/text/qutf8stringview.qdoc
+++ b/src/corelib/text/qutf8stringview.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com>
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** 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 Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2020 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 GFDL-1.3-no-invariants-only
/*!
\class QUtf8StringView
@@ -35,6 +11,14 @@
\ingroup tools
\ingroup string-processing
+ \compares strong
+ \compareswith strong char16_t QChar {const char16_t *} QString QStringView \
+ QLatin1StringView
+ \endcompareswith
+ \compareswith strong {const char *} QByteArray QByteArrayView
+ The contents of byte arrays is interpreted as utf-8.
+ \endcompareswith
+
A QUtf8StringView references a contiguous portion of a UTF-8
string it does not own. It acts as an interface type to all kinds
of UTF-8 string, without the need to construct a QString or
@@ -116,42 +100,14 @@
The second, in namespace \c{q_has_char8_t}, has a value_type of
\c{const char8_t} and is only available when compiling in C++20 mode.
- In C++17 mode, \c{q_no_char8_t} is an inline namespace, in C++20 it's
- \c{q_has_char8_t}. This means that the name "QUtf8StringView" (without
- explicit namespace) will denote different types in C++17 and C++20 modes.
+ \c{q_no_char8_t} is an inline namespace regardless of C++ edition, to avoid
+ accidental binary incompatibilities. To use the \c{char8_t} version, you
+ need to name it explicitly with \c{q_has_char8_t::QUtf8StringView}.
Internally, both are instantiations of the same template class,
QBasicUtf8StringView. Please do not use the template class's name in your
source code.
- All Qt APIs use \c{q_no_char8_t::QUtf8StringView} due to binary compatibility,
- but these APIs accept \c{q_has_char8_t::QUtf8StringView} as well, since the
- latter implicitly converts into the former, and vice versa.
-
- In your own code, please use only \c QUtf8StringView and/or
- \c{q_no_char8_t::QUtf8StringView}:
-
- \list
- \li If you only target C++20, then use "QUtf8StringView". It will be an alias
- for \c{q_has_char8_t::QUtf8StringView} and you'll never look back.
- \li If you only target C++17, then use "QUtf8StringView". It will be an alias
- for \c{q_no_char8_t::QUtf8StringView} and for the time being, you're ok.
- \li If you target both C++17 and C++20, then you have a choice to make:
- \list
- \li If you don't mind the source-incompatibility of return values of
- QUtf8StringView::data() etc changing when compiling under C++17 or C++20,
- use "QUtf8StringView". You will need to write your code in such a way that
- it adapts to the differences in the QUtf8StringView API in different C++
- versions.
- \li If you don't want to deal with the above source-incompatibilities, or if
- you need to maintain binary compatibility between C++20 and C++17 builds,
- use "q_no_char8_t::QUtf8StringView" explicitly. Be aware that the
- \c{q_no_char8_t} version will disappear in Qt 7.
- \endlist
- \endlist
-
- Taken together: Just use QUtf8StringView unless you know what you're doing.
-
\sa QAnyStringView, QUtf8StringView, QString
*/
@@ -256,6 +212,11 @@
*/
/*!
+ \fn QUtf8StringView::QUtf8StringView(const storage_type *d, qsizetype n)
+ \internal
+*/
+
+/*!
\fn QUtf8StringView::QUtf8StringView(std::nullptr_t)
Constructs a null string view.
@@ -264,7 +225,7 @@
*/
/*!
- \fn template <typename Char> QUtf8StringView::QUtf8StringView(const Char *str, qsizetype len)
+ \fn template <typename Char, QUtf8StringView::if_compatible_char<Char> = true> QUtf8StringView::QUtf8StringView(const Char *str, qsizetype len)
Constructs a string view on \a str with length \a len.
@@ -280,7 +241,7 @@
*/
/*!
- \fn template <typename Char> QUtf8StringView::QUtf8StringView(const Char *first, const Char *last)
+ \fn template <typename Char, QUtf8StringView::if_compatible_char<Char> = true> QUtf8StringView::QUtf8StringView(const Char *first, const Char *last)
Constructs a string view on \a first with length (\a last - \a first).
@@ -334,26 +295,26 @@
*/
/*!
- \fn template <typename Container, if_compatible_container<Container>> QUtf8StringView::QUtf8StringView(const Container &str)
+ \fn template <typename Container, QUtf8StringView::if_compatible_container<Container>> QUtf8StringView::QUtf8StringView(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 Container 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 char8_t, \c char, \c{signed char} and
\c{unsigned char}.
- 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, if_compatible_char<Char>> QUtf8StringView::fromArray(const Char (&string)[Size])
+ \fn template <typename Char, size_t Size, QUtf8StringView::if_compatible_char<Char>> QUtf8StringView::fromArray(const Char (&string)[Size])
Constructs a string view on the full character string literal \a string,
including any trailing \c{Char(0)}. If you don't want the
@@ -381,7 +342,7 @@
/*!
\fn QUtf8StringView::data() const
- Returns a const pointer to the first code point in the string.
+ Returns a const pointer to the first code point in the string view.
\note The character array represented by the return value is \e not null-terminated.
@@ -391,7 +352,7 @@
/*!
\fn QUtf8StringView::utf8() const
- Returns a const pointer to the first code point in the string.
+ Returns a const pointer to the first code point in the string view.
The result is returned as a \c{const char8_t*}, so this function is only available when
compiling in C++20 mode.
@@ -405,7 +366,7 @@
\fn QUtf8StringView::const_iterator QUtf8StringView::begin() const
Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first code point in
- the string.
+ the string view.
This function is provided for STL compatibility.
@@ -446,7 +407,7 @@
\fn QUtf8StringView::const_reverse_iterator QUtf8StringView::rbegin() const
Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
- code point in the string, in reverse order.
+ code point in the string view, in reverse order.
This function is provided for STL compatibility.
@@ -467,7 +428,7 @@
\fn QUtf8StringView::const_reverse_iterator QUtf8StringView::rend() const
Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past
- the last code point in the string, in reverse order.
+ the last code point in the string view, in reverse order.
This function is provided for STL compatibility.
@@ -525,18 +486,12 @@
*/
/*!
- \fn int QUtf8StringView::length() const
- \obsolete
- Use size() and port callers to qsizetype.
+ \fn QUtf8StringView::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 QUtf8StringView can represent strings with more than 2\sup{31} code points.
- 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()
*/
@@ -563,7 +518,7 @@
/*!
\fn QUtf8StringView::front() const
- Returns the first code point in the string. Same as first().
+ Returns the first code point in the string view. Same as first().
This function is provided for STL compatibility.
@@ -576,7 +531,7 @@
/*!
\fn QUtf8StringView::back() const
- Returns the last code point in the string. Same as last().
+ Returns the last code point in the string view. Same as last().
This function is provided for STL compatibility.
@@ -592,11 +547,11 @@
Returns the substring of length \a n starting at position
\a pos in this object.
- \obsolete Use sliced() instead in new code.
+ \deprecated Use sliced() instead in new code.
Returns an empty string view if \a n exceeds the
- length of the string. If there are less than \a n code points
- available in the string starting at \a pos, or if
+ length of the string view. If there are less than \a n code points
+ available in the string view starting at \a pos, or if
\a n is negative (default), the function returns all code points that
are available from \a pos.
@@ -606,12 +561,12 @@
/*!
\fn QUtf8StringView::left(qsizetype n) const
- \obsolete Use first() instead in new code.
+ \deprecated Use first() instead in new code.
Returns the substring of length \a n starting at position
0 in this object.
- The entire string is returned if \a n is greater than or equal
+ The entire string view is returned if \a n is greater than or equal
to size(), or less than zero.
\sa first(), last(), sliced(), chopped(), chop(), truncate()
@@ -620,12 +575,12 @@
/*!
\fn QUtf8StringView::right(qsizetype n) const
- \obsolete Use last() instead in new code.
+ \deprecated Use last() instead in new code.
Returns the substring of length \a n starting at position
size() - \a n in this object.
- The entire string is returned if \a n is greater than or equal
+ The entire string view is returned if \a n is greater than or equal
to size(), or less than zero.
\sa first(), last(), sliced(), chopped(), chop(), truncate()
@@ -635,7 +590,7 @@
\fn QUtf8StringView::first(qsizetype n) const
Returns a string view that contains the first \a n code points
- of this string.
+ of this string view.
\note The behavior is undefined when \a n < 0 or \a n > size().
@@ -645,7 +600,7 @@
/*!
\fn QUtf8StringView::last(qsizetype n) const
- Returns a string view that contains the last \a n code points of this string.
+ Returns a string view that contains the last \a n code points of this string view.
\note The behavior is undefined when \a n < 0 or \a n > size().
@@ -658,8 +613,10 @@
Returns a string view containing \a n code points 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()
*/
@@ -670,7 +627,9 @@
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()
*/
@@ -713,16 +672,49 @@
*/
/*!
+ \fn int QUtf8StringView::compare(QLatin1StringView str, Qt::CaseSensitivity cs) const
+ \fn int QUtf8StringView::compare(QUtf8StringView str, Qt::CaseSensitivity cs) const
+ \fn int QUtf8StringView::compare(QStringView str, Qt::CaseSensitivity cs) const
+ \since 6.5
+
+ Compares this string view with \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}
+*/
+
+
+/*!
+ \fn QUtf8StringView::isValidUtf8() const
+
+ Returns \c true if this string contains valid UTF-8 encoded data,
+ or \c false otherwise.
+
+ \since 6.3
+*/
+
+/*!
\fn template <typename QStringLike> qToUtf8StringViewIgnoringNull(const QStringLike &s);
\relates QUtf8StringView
\internal
Convert \a s to a QUtf8StringView ignoring \c{s.isNull()}.
- Returns a string-view that references \a{s}'s data, but is never null.
+ Returns a string view that references \a{s}'s data, but is never null.
This is a faster way to convert a QByteArray to a QUtf8StringView,
if null QByteArrays can legitimately be treated as empty ones.
\sa QByteArray::isNull(), QUtf8StringView
*/
+
+
+/*! \fn QUtf8StringView::operator std::basic_string_view<storage_type>() const
+ \since 6.7
+
+ Converts this QUtf8StringView object to a
+ \c{std::basic_string_view} object. The returned view will have the
+ same data pointer and length of this view. The character type of
+ the returned view will be \c{storage_type}.
+*/