diff options
Diffstat (limited to 'src/corelib/text/qbytearrayview.qdoc')
| -rw-r--r-- | src/corelib/text/qbytearrayview.qdoc | 139 |
1 files changed, 94 insertions, 45 deletions
diff --git a/src/corelib/text/qbytearrayview.qdoc b/src/corelib/text/qbytearrayview.qdoc index 96bb1ccb56..eb890917eb 100644 --- a/src/corelib/text/qbytearrayview.qdoc +++ b/src/corelib/text/qbytearrayview.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2021 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,10 +314,6 @@ 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. */ /*! @@ -354,12 +341,12 @@ */ /*! //! friend - \fn int QByteArrayView::operator==(QByteArrayView lhs, QByteArrayView rhs) - \fn int QByteArrayView::operator!=(QByteArrayView lhs, QByteArrayView rhs) - \fn int QByteArrayView::operator< (QByteArrayView lhs, QByteArrayView rhs) - \fn int QByteArrayView::operator<=(QByteArrayView lhs, QByteArrayView rhs) - \fn int QByteArrayView::operator> (QByteArrayView lhs, QByteArrayView rhs) - \fn int QByteArrayView::operator>=(QByteArrayView lhs, 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) + \fn int QByteArrayView::operator>=(const QByteArrayView &lhs, const QByteArrayView &rhs) Comparison operators for QByteArrayView. */ @@ -503,7 +490,7 @@ */ /*! - \fn int QByteArrayView::length() const + \fn QByteArrayView::length() const Same as size(). @@ -584,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() */ @@ -596,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() */ @@ -640,6 +631,54 @@ */ /*! + \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 @@ -923,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() */ @@ -947,8 +985,10 @@ 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 backward from index position - \a from. If \a from is -1, the search starts at the last character; - if \a from is -2, at the next to last character and so on. + \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 @@ -1005,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. +*/ |