diff options
Diffstat (limited to 'src/corelib/text/qbytearrayview.qdoc')
| -rw-r--r-- | src/corelib/text/qbytearrayview.qdoc | 455 |
1 files changed, 406 insertions, 49 deletions
diff --git a/src/corelib/text/qbytearrayview.qdoc b/src/corelib/text/qbytearrayview.qdoc index 91048c5dad..eb890917eb 100644 --- a/src/corelib/text/qbytearrayview.qdoc +++ b/src/corelib/text/qbytearrayview.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** 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) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \class QByteArrayView @@ -38,6 +14,15 @@ \reentrant + \compares strong + \compareswith strong QByteArray {const char *} + \endcompareswith + \compareswith strong QString QStringView QUtf8StringView QLatin1StringView \ + QChar char16_t + When comparing with string and Unicode character types, the content is + interpreted as UTF-8. + \endcompareswith + A QByteArrayView references a contiguous portion of raw bytes it does not own. It acts as an interface type to all kinds of byte-array-like data, without the need to construct a QByteArray first. @@ -80,6 +65,12 @@ If in doubt, obtain a strong reference to the data by calling toByteArray() to convert the QByteArrayView into a QByteArray. + The methods supported by QByteArrayView reflect those of \l QByteArray. In + particular, to the limited degree that it ascribes semantics (such as + character case, spacing, digits of numbers) to the character data viewed, it + uses the C locale and ASCII encoding. See \l {C locale and ASCII functions} + for details and the limitations on these methods. + \section1 Compatible Byte Types QByteArrayView can be constructed on any container of bytes, where the byte type @@ -202,7 +193,7 @@ */ /*! - \fn template <typename Byte> QByteArrayView::QByteArrayView(const Byte *data, qsizetype len) + \fn template <typename Byte, QByteArrayView::if_compatible_byte<Byte> = true> QByteArrayView::QByteArrayView(const Byte *data, qsizetype len) Constructs a byte array view on \a data with length \a len. @@ -220,7 +211,7 @@ */ /*! - \fn template <typename Byte> QByteArrayView::QByteArrayView(const Byte *first, const Byte *last) + \fn template <typename Byte, QByteArrayView::if_compatible_byte<Byte> = true> QByteArrayView::QByteArrayView(const Byte *first, const Byte *last) Constructs a byte array view on \a first with length (\a last - \a first). @@ -288,7 +279,7 @@ */ /*! - \fn template <typename Container> QByteArrayView::QByteArrayView(const Container &c) + \fn template <typename Container, QByteArrayView::if_compatible_container<Container> = true> QByteArrayView::QByteArrayView(const Container &c) Constructs a byte array view on the array-like container \a c. The length and data are set via \c{std::size(c)} and \c{std::data(c)} respectively. @@ -296,7 +287,7 @@ The container's data must remain valid for the lifetime of this byte array view object. This constructor participates in overload resolution if \a c is any contiguous - container container with elements of a compatible byte type. + container with elements of a compatible byte type. \sa {Compatible Byte Types} */ @@ -323,16 +314,12 @@ The return value will be a null QByteArray if and only if this byte array view is null. - - \warning QByteArrayView can store data with more than 2\sup{31} bytes while - QByteArray cannot. Calling this function on a byte array view for which size() - returns a value greater than \c{INT_MAX / 2} constitutes undefined behavior. */ /*! \fn const char *QByteArrayView::data() const - Returns a const \c char pointer to the first byte in the byte array. + Returns a const \c char pointer to the first byte in the byte array view. \note The character array represented by the return value is \e not guaranteed to be null-terminated. The returned pointer is only safe to use for accessing @@ -344,7 +331,7 @@ /*! \fn const char *QByteArrayView::constData() const - Returns a const \c char pointer to the first byte in the byte array. + Returns a const \c char pointer to the first byte in the byte array view. \note The character array represented by the return value is \e not guaranteed to be null-terminated. The returned pointer is only safe to use for accessing @@ -353,11 +340,43 @@ \sa data(), begin(), end() */ +/*! //! friend + \fn int QByteArrayView::operator==(const QByteArrayView &lhs, const QByteArrayView &rhs) + \fn int QByteArrayView::operator!=(const QByteArrayView &lhs, const QByteArrayView &rhs) + \fn int QByteArrayView::operator< (const QByteArrayView &lhs, const QByteArrayView &rhs) + \fn int QByteArrayView::operator<=(const QByteArrayView &lhs, const QByteArrayView &rhs) + \fn int QByteArrayView::operator> (const QByteArrayView &lhs, const QByteArrayView &rhs) + \fn int QByteArrayView::operator>=(const QByteArrayView &lhs, const QByteArrayView &rhs) + + Comparison operators for QByteArrayView. +*/ + +/*! + \fn int QByteArrayView::compare(QByteArrayView bv, Qt::CaseSensitivity cs = Qt::CaseSensitive) const + \since 6.2 + + Returns an integer less than, equal to, or greater than zero depending on + whether this QByteArrayView sorts before, at the same position as, or after + the QByteArrayView \a bv. The comparison is performed according to case + sensitivity \a cs. + + \sa operator==() +*/ + +/*! + \fn QByteArrayView::isValidUtf8() const + + Returns \c true if this byte array view contains valid UTF-8 encoded data, + or \c false otherwise. + + \since 6.3 +*/ + /*! \fn QByteArrayView::const_iterator QByteArrayView::begin() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the - first byte in the byte array. + first byte in the byte array view. This function is provided for STL compatibility. @@ -378,7 +397,7 @@ \fn QByteArrayView::const_iterator QByteArrayView::end() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing - just after the last byte in the byte array. + just after the last byte in the byte array view. This function is provided for STL compatibility. @@ -398,7 +417,7 @@ \fn QByteArrayView::const_reverse_iterator QByteArrayView::rbegin() const Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing - to the first byte in the byte array, in reverse order. + to the first byte in the byte array view, in reverse order. This function is provided for STL compatibility. @@ -419,7 +438,7 @@ \fn QByteArrayView::const_reverse_iterator QByteArrayView::rend() const Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past - the last byte in the byte array, in reverse order. + the last byte in the byte array view, in reverse order. This function is provided for STL compatibility. @@ -471,7 +490,7 @@ */ /*! - \fn int QByteArrayView::length() const + \fn QByteArrayView::length() const Same as size(). @@ -501,7 +520,7 @@ /*! \fn char QByteArrayView::front() const - Returns the first byte in the byte array. + Returns the first byte in the byte array view. This function is provided for STL compatibility. @@ -514,7 +533,7 @@ /*! \fn char QByteArrayView::back() const - Returns the last byte in the byte array. + Returns the last byte in the byte array view. This function is provided for STL compatibility. @@ -552,8 +571,10 @@ Returns a byte array view that points to \a n bytes of this byte array 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() */ @@ -564,7 +585,9 @@ Returns a byte array 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() */ @@ -608,6 +631,309 @@ */ /*! + \fn QByteArrayView QByteArrayView::mid(qsizetype start, qsizetype length) const + \since 6.5 + + \deprecated Use sliced() instead in new code. + + Returns the subarray of length \a length starting at position + \a start in this object. + + Returns an empty byte array view if \a start exceeds the + length of the byte array view. If there are less than \a length characters + available in the byte array view starting at \a start, or if + \a length is negative (default), the function returns all characters that + are available from \a start. + + \sa first(), last(), sliced(), chopped(), chop(), truncate() +*/ + +/*! + \fn QByteArrayView QByteArrayView::left(qsizetype length) const + \since 6.5 + + \deprecated Use first() instead in new code. + + Returns the subarray of length \a length starting at position + 0 in this object. + + The entire byte array 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() +*/ + +/*! + \fn QByteArrayView QByteArrayView::right(qsizetype length) const + \since 6.5 + + \deprecated Use last() instead in new code. + + Returns the subarray of length \a length starting at position + size() - \a length in this object. + + The entire byte array 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() +*/ + +/*! + \fn QByteArrayView QByteArrayView::trimmed() const noexcept + \since 6.3 + + Returns a copy of this byte array view with spacing characters + removed from the start and end. + + The spacing characters are those for which the standard C++ \c isspace() + function returns \c true in the C locale; these are the ASCII characters + tabulation '\\t', line feed '\\n', carriage return '\\r', vertical + tabulation '\\v', form feed '\\f', and space ' '. + + \sa QChar::SpecialCharacter, {QByteArray#Spacing Characters}{Spacing Characters} +*/ + +/*! + \fn qlonglong QByteArrayView::toLongLong(bool *ok, int base) const + \since 6.3 + + Returns this byte array view converted to a \c {long long} using base \a + base, which is ten by default. Bases 0 and 2 through 36 are supported, using + letters for digits beyond 9; A is ten, B is eleven and so on. + + If \a base is 0, the base is determined automatically using the following + rules: if the byte array view begins with "0x", the rest of it is read as + hexadecimal (base 16); otherwise, if it begins with "0", the rest of it is + read as octal (base 8); otherwise it is read as decimal. + + 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. + + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. +*/ + +/*! + \fn qulonglong QByteArrayView::toULongLong(bool *ok, int base) const + \since 6.3 + + Returns this byte array view converted to an \c {unsigned long long} using + base \a base, which is ten by default. Bases 0 and 2 through 36 are + supported, using letters for digits beyond 9; A is ten, B is eleven and so + on. + + If \a base is 0, the base is determined automatically using the following + rules: if the byte array view begins with "0x", the rest of it is read as + hexadecimal (base 16); otherwise, if it begins with "0", the rest of it is + read as octal (base 8); otherwise it is read as decimal. + + 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. + + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. +*/ + +/*! + \fn int QByteArrayView::toInt(bool *ok, int base) const + \since 6.3 + + Returns this byte array view converted to an \c int using base \a base, + which is ten by default. Bases 0 and 2 through 36 are supported, using + letters for digits beyond 9; A is ten, B is eleven and so on. + + If \a base is 0, the base is determined automatically using the following + rules: if the byte array view begins with "0x", the rest of it is read as + hexadecimal (base 16); otherwise, if it begins with "0", the rest of it is + read as octal (base 8); otherwise it is read as decimal. + + 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. + + \snippet code/src_corelib_text_qbytearrayview.cpp 2 + + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. +*/ + +/*! + \fn uint QByteArrayView::toUInt(bool *ok, int base) const + \since 6.3 + + Returns this byte array view converted to an \c {unsigned int} using base \a + base, which is ten by default. Bases 0 and 2 through 36 are supported, using + letters for digits beyond 9; A is ten, B is eleven and so on. + + If \a base is 0, the base is determined automatically using the following + rules: if the byte array view begins with "0x", the rest of it is read as + hexadecimal (base 16); otherwise, if it begins with "0", the rest of it is + read as octal (base 8); otherwise it is read as decimal. + + 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. + + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. +*/ + +/*! + \fn long QByteArrayView::toLong(bool *ok, int base) const + \since 6.3 + + Returns this byte array view converted to a \c long int using base \a base, + which is ten by default. Bases 0 and 2 through 36 are supported, using + letters for digits beyond 9; A is ten, B is eleven and so on. + + If \a base is 0, the base is determined automatically using the following + rules: if the byte array view begins with "0x", the rest of it is read as + hexadecimal (base 16); otherwise, if it begins with "0", the rest of it is + read as octal (base 8); otherwise it is read as decimal. + + 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. + + \snippet code/src_corelib_text_qbytearrayview.cpp 3 + + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. +*/ + +/*! + \fn ulong QByteArrayView::toULong(bool *ok, int base) const + \since 6.3 + + Returns this byte array view converted to an \c {unsigned long int} using + base \a base, which is ten by default. Bases 0 and 2 through 36 are + supported, using letters for digits beyond 9; A is ten, B is eleven and so + on. + + If \a base is 0, the base is determined automatically using the following + rules: if the byte array view begins with "0x", the rest of it is read as + hexadecimal (base 16); otherwise, if it begins with "0", the rest of it is + read as octal (base 8); otherwise it is read as decimal. + + 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. + + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. +*/ + +/*! + \fn short QByteArrayView::toShort(bool *ok, int base) const + \since 6.3 + + Returns this byte array view converted to a \c short using base \a base, + which is ten by default. Bases 0 and 2 through 36 are supported, using + letters for digits beyond 9; A is ten, B is eleven and so on. + + If \a base is 0, the base is determined automatically using the following + rules: if the byte array view begins with "0x", the rest of it is read as + hexadecimal (base 16); otherwise, if it begins with "0", the rest of it is + read as octal (base 8); otherwise it is read as decimal. + + 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. + + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. +*/ + +/*! + \fn ushort QByteArrayView::toUShort(bool *ok, int base) const + \since 6.3 + + Returns this byte array view converted to an \c {unsigned short} using base + \a base, which is ten by default. Bases 0 and 2 through 36 are supported, + using letters for digits beyond 9; A is ten, B is eleven and so on. + + If \a base is 0, the base is determined automatically using the following + rules: if the byte array view begins with "0x", the rest of it is read as + hexadecimal (base 16); otherwise, if it begins with "0", the rest of it is + read as octal (base 8); otherwise it is read as decimal. + + 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. + + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. +*/ + +/*! + \fn double QByteArrayView::toDouble(bool *ok) const + \since 6.3 + + Returns this byte array 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). + + 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. + + \warning The QByteArrayView content may only contain valid numerical + characters which includes the plus/minus sign, the character e used in + scientific notation, and the decimal point. Including the unit or additional + characters leads to a conversion error. + + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. + + This function ignores leading and trailing spacing characters. +*/ + +/*! + \fn float QByteArrayView::toFloat(bool *ok) const + \since 6.3 + + Returns this byte array 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). + + 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. + + \snippet code/src_corelib_text_qbytearrayview.cpp 4 + + \warning The QByteArrayView content may only contain valid numerical + characters which includes the plus/minus sign, the character e used in + scientific notation, and the decimal point. Including the unit or additional + characters leads to a conversion error. + + \note The conversion of the number is performed in the default C locale, + regardless of the user's locale. Use QLocale to perform locale-aware + conversions between numbers and strings. + + This function ignores leading and trailing whitespace. +*/ + +/*! \fn bool QByteArrayView::startsWith(QByteArrayView bv) const \fn bool QByteArrayView::startsWith(char ch) const @@ -636,8 +962,7 @@ respectively, in this byte array view, searching forward from index position \a from.Returns -1 if no match is found. - If \a from is -1, the search starts at the last character; if it is - -2, at the next to last character and so on. + \include qstring.qdocinc negative-index-start-search-from-end \sa lastIndexOf(), contains() */ @@ -654,14 +979,37 @@ */ /*! - \fn qsizetype QByteArrayView::lastIndexOf(QByteArrayView bv, qsizetype from = -1) const + \fn qsizetype QByteArrayView::lastIndexOf(QByteArrayView bv, qsizetype from) const \fn qsizetype QByteArrayView::lastIndexOf(char ch, qsizetype from = -1) const Returns the index position of either the start of the last occurrence of the sequence of bytes viewed by \a bv or the last occurrence of byte \a ch, - respectively, in this byte array view, searching forward from index position - \a from. If \a from is -1 (the default), the search starts from the end of the - byte array view. Returns -1 if no match is found. + respectively, in this byte array view, searching backward from index position + \a from. + + \include qstring.qdocinc negative-index-start-search-from-end + + Returns -1 if no match is found. + + \note When searching for a 0-length \a bv, the match at the end of + 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 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 indexOf(), contains() +*/ + +/*! + \fn qsizetype QByteArrayView::lastIndexOf(QByteArrayView bv) const + \since 6.2 + \overload + + Returns the index position of the start of the last + occurrence of the sequence of bytes viewed by \a bv in this byte + array view, searching backward from the end of this byte array + view. Returns -1 if no match is found. \sa indexOf(), contains() */ @@ -697,3 +1045,12 @@ \sa QByteArray::isNull(), QByteArrayView */ + +/*! + \fn QByteArrayView::operator std::string_view() const + \since 6.7 + + Converts this QByteArrayView object to a \c{std::string_view} object. + The returned view will have the same data pointer and length of + this view. +*/ |