diff options
author | Andrei Golubev <andrei.golubev@qt.io> | 2020-08-31 11:38:53 +0200 |
---|---|---|
committer | Andrei Golubev <andrei.golubev@qt.io> | 2020-09-18 10:02:04 +0200 |
commit | 8716413afcb4718352a93d90adb6f38491ad236e (patch) | |
tree | de8fc5955c0a3e934fb878fa389bae181d99fb85 /src | |
parent | 465ddfc870c3aa2c9afeb2255d173bf6da294c9a (diff) |
Update QByteArray documentation relevant to prepend optimization
[ChangeLog][QtCore][QByteArray] QByteArray is a prepend optimized
container similar to QList.
Task-number: QTBUG-84320
Change-Id: I45ed1cb75414930f5998be58bfcfe343b1790331
Reviewed-by: MÃ¥rten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Diffstat (limited to 'src')
-rw-r--r-- | src/corelib/text/qbytearray.cpp | 46 |
1 files changed, 39 insertions, 7 deletions
diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp index 04df7a5eb8..1c40bba377 100644 --- a/src/corelib/text/qbytearray.cpp +++ b/src/corelib/text/qbytearray.cpp @@ -930,6 +930,11 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes) Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first byte in the byte-array. +//! [iterator-invalidation-func-desc] + \warning The returned iterator is invalidated on detachment or when the + QByteArray is modified. +//! [iterator-invalidation-func-desc] + \sa constBegin(), end() */ @@ -944,6 +949,8 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes) Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first byte in the byte-array. + \include qbytearray.cpp iterator-invalidation-func-desc + \sa begin(), cend() */ @@ -952,6 +959,8 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes) Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first byte in the byte-array. + \include qbytearray.cpp iterator-invalidation-func-desc + \sa begin(), constEnd() */ @@ -960,6 +969,8 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes) Returns an \l{STL-style iterators}{STL-style iterator} pointing just after the last byte in the byte-array. + \include qbytearray.cpp iterator-invalidation-func-desc + \sa begin(), constEnd() */ @@ -974,6 +985,8 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes) Returns a const \l{STL-style iterators}{STL-style iterator} pointing just after the last byte in the byte-array. + \include qbytearray.cpp iterator-invalidation-func-desc + \sa cbegin(), end() */ @@ -982,6 +995,8 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes) Returns a const \l{STL-style iterators}{STL-style iterator} pointing just after the last byte in the byte-array. + \include qbytearray.cpp iterator-invalidation-func-desc + \sa constBegin(), end() */ @@ -991,6 +1006,8 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes) Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to the first byte in the byte-array, in reverse order. + \include qbytearray.cpp iterator-invalidation-func-desc + \sa begin(), crbegin(), rend() */ @@ -1005,6 +1022,8 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes) Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first byte in the byte-array, in reverse order. + \include qbytearray.cpp iterator-invalidation-func-desc + \sa begin(), rbegin(), rend() */ @@ -1014,6 +1033,8 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes) Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past the last byte in the byte-array, in reverse order. + \include qbytearray.cpp iterator-invalidation-func-desc + \sa end(), crend(), rbegin() */ @@ -1028,6 +1049,8 @@ QByteArray qUncompress(const uchar* data, qsizetype nbytes) Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to one past the last byte in the byte-array, in reverse order. + \include qbytearray.cpp iterator-invalidation-func-desc + \sa end(), rend(), rbegin() */ @@ -1215,6 +1238,10 @@ QByteArray &QByteArray::operator=(const char *str) \note a statically allocated byte array will report a capacity of 0, even if it's not empty. + \note The free space position in the allocated memory block is undefined. In + other words, one should not assume that the free memory is always located + after the initialized elements. + \sa reserve(), squeeze() */ @@ -1252,8 +1279,12 @@ QByteArray &QByteArray::operator=(const char *str) Returns a pointer to the data stored in the byte array. The pointer can be used to access the bytes that compose the array. - The data is '\\0'-terminated. The pointer remains valid as long - as the array isn't reallocated or destroyed. + The data is '\\0'-terminated. + +//! [pointer-invalidation-desc] + The pointer remains valid as long as no detach happens and the QByteArray + is not modified. +//! [pointer-invalidation-desc] This operator is mostly useful to pass a byte array to a function that accepts a \c{const char *}. @@ -1288,9 +1319,10 @@ QByteArray &QByteArray::operator=(const char *str) Example: \snippet code/src_corelib_text_qbytearray.cpp 8 - The pointer remains valid as long as the byte array isn't - reallocated or destroyed. For read-only access, constData() is - faster because it never causes a \l{deep copy} to occur. + \include qbytearray.cpp pointer-invalidation-desc + + For read-only access, constData() is faster because it never + causes a \l{deep copy} to occur. This function is mostly useful to pass a byte array to a function that accepts a \c{const char *}. @@ -1322,8 +1354,8 @@ QByteArray &QByteArray::operator=(const char *str) Returns a pointer to the data stored in the byte array. The pointer can be used to access the bytes that compose the array. The data is '\\0'-terminated unless the QByteArray object was created from raw data. - The pointer remains valid as long as the byte array isn't reallocated or - destroyed. + + \include qbytearray.cpp pointer-invalidation-desc This function is mostly useful to pass a byte array to a function that accepts a \c{const char *}. |