diff options
Diffstat (limited to 'src/corelib/text/qutf8stringview.qdoc')
-rw-r--r-- | src/corelib/text/qutf8stringview.qdoc | 242 |
1 files changed, 112 insertions, 130 deletions
diff --git a/src/corelib/text/qutf8stringview.qdoc b/src/corelib/text/qutf8stringview.qdoc index 031769440c..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 @@ -77,7 +61,7 @@ QUtf8StringView is a \e{Literal Type}. - \section Compatible Character Types + \section2 Compatible Character Types QUtf8StringView accepts strings over a variety of character types: @@ -86,16 +70,16 @@ \li \c char8_t (C++20 only) \endlist - \section Sizes and Sub-Strings + \section2 Sizes and Sub-Strings - All sizes and postions in QUtf8StringView functions are in + All sizes and positions in QUtf8StringView functions are in UTF-8 code points (that is, UTF-8 multibyte sequences count as two, three or four, depending on their length). QUtf8StringView does not an attempt to detect or prevent slicing right through UTF-8 multibyte sequences. This is similar to the situation with QStringView and surrogate pairs. - \section C++20, char8_t, and QUtf8StringView + \section2 C++20, char8_t, and QUtf8StringView In C++20, \c{u8""} string literals changed their type from \c{const char[]} to \c{const char8_t[]}. If Qt 6 could have depended @@ -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). @@ -325,35 +286,35 @@ \a string must remain valid for the lifetime of this string view object. - This constructor only participates in overload resolution if \a str + This constructor only participates in overload resolution if \a string is an actual array and if \c Char is a compatible character type. The compatible character types are: \c char8_t, \c char, \c{signed char} and \c{unsigned char}. - \sa fromArray + \sa fromArray() */ /*! - \fn template <typename StdBasicString> QUtf8StringView::QUtf8StringView(const StdBasicString &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 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 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> static QBasicUtf8StringView 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. @@ -587,69 +542,69 @@ */ /*! - \fn QUtf8StringView::mid(qsizetype start, qsizetype length) const + \fn QUtf8StringView::mid(qsizetype pos, qsizetype n) const - Returns the substring of length \a length starting at position - \a start in this object. + 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 start exceeds the - length of the string. If there are less than \a length code points - available in the string starting at \a start, or if - \a length is negative (default), the function returns all code points that - are available from \a start. + Returns an empty string view if \a n exceeds the + 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. \sa first(), last(), sliced(), chopped(), chop(), truncate() */ /*! - \fn QUtf8StringView::left(qsizetype length) const + \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 length starting at position + Returns the substring of length \a n 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 n is greater than or equal to size(), or less than zero. - \sa first(), last(), sliced(), startsWith(), chopped(), chop(), truncate() + \sa first(), last(), sliced(), chopped(), chop(), truncate() */ /*! - \fn QUtf8StringView::right(qsizetype length) const + \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 length starting at position - size() - \a length in this object. + Returns the substring of length \a n starting at position + size() - \a n in this object. - The entire string is returned if \a length 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(), endsWith(), chopped(), chop(), truncate() + \sa first(), last(), sliced(), chopped(), chop(), truncate() */ /*! \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(). - \sa last(), sliced(), startsWith(), chopped(), chop(), truncate() + \sa last(), sliced(), chopped(), chop(), truncate() */ /*! \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(). - \sa first(), sliced(), endsWith(), chopped(), chop(), truncate() + \sa first(), sliced(), chopped(), chop(), truncate() */ /*! @@ -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,56 +627,71 @@ 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() */ /*! - \fn QUtf8StringView::chopped(qsizetype length) const + \fn QUtf8StringView::chopped(qsizetype n) const - Returns the substring of length size() - \a length starting at the + Returns the substring of length size() - \a n starting at the beginning of this object. - Same as \c{first(size() - length)}. + Same as \c{first(size() - n)}. - \note The behavior is undefined when \a length < 0 or \a length > size(). + \note The behavior is undefined when \a n < 0 or \a n > size(). \sa sliced(), first(), last(), chop(), truncate() */ /*! - \fn QUtf8StringView::truncate(qsizetype length) + \fn QUtf8StringView::truncate(qsizetype n) - Truncates this string view to \a length code points. + Truncates this string view to \a n code points. - Same as \c{*this = first(length)}. + Same as \c{*this = first(n)}. - \note The behavior is undefined when \a length < 0 or \a length > size(). + \note The behavior is undefined when \a n < 0 or \a n > size(). \sa sliced(), first(), last(), chopped(), chop() */ /*! - \fn QUtf8StringView::chop(qsizetype length) + \fn QUtf8StringView::chop(qsizetype n) - Truncates this string view by \a length code points. + Truncates this string view by \a n code points. - Same as \c{*this = first(size() - length)}. + Same as \c{*this = first(size() - n)}. - \note The behavior is undefined when \a length < 0 or \a length > size(). + \note The behavior is undefined when \a n < 0 or \a n > size(). \sa sliced(), first(), last(), chopped(), truncate() */ /*! - \fn QUtf8StringView::trimmed() const + \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 - Strips leading and trailing whitespace and returns the result. + Returns \c true if this string contains valid UTF-8 encoded data, + or \c false otherwise. - Whitespace means any code point for which QChar::isSpace() returns - \c true. This includes the ASCII characters '\\t', '\\n', '\\v', - '\\f', '\\r', and ' '. + \since 6.3 */ /*! @@ -729,10 +701,20 @@ 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}. +*/ |