1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs] QSpan: add section header for const/mutable spans

Browse Source 
... and link to it from function documentation blocks that differ
materially between the two.

Add another section to avoid non-const/mutable contents to fall into
the new section. This other section doesn't appear to require linking
from anywhere. Give it a \target nonetheless.

Change-Id: I11426f22f0cfd77ffcc55c545f5c2b7f48b5af52
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
(cherry picked from commit 70dc8d3103fade380caec96f7531432cd8e8adb6)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This commit is contained in:
Marc Mutz 2024-11-29 08:45:53 +01:00 committed by Qt Cherry-pick Bot
parent 6027eae74e
commit 003ced0799
1 changed files with 33 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
src/corelib/tools/qspan.qdoc
View File

@ -22,7 +22,7 @@
Unlike views such as QStringView, QLatin1StringView and QUtf8StringView, Unlike views such as QStringView, QLatin1StringView and QUtf8StringView,
referenced data can be modified through a QSpan object. To prevent this, referenced data can be modified through a QSpan object. To prevent this,
construct a QSpan over a \c{const T}: construct a QSpan over a \c{const T} (see \l{const-mutable-spans}):
\code \code
int numbers[] = {0, 1, 2}; int numbers[] = {0, 1, 2};
@ -59,6 +59,9 @@
The opposite direction (variable-length into fixed-length) has the The opposite direction (variable-length into fixed-length) has the
precondition that both span's sizes must match. precondition that both span's sizes must match.
\section2 Const and Mutable Spans
\target const-mutable-spans
Unlike with owning containers, \c{const} is \e{shallow} in QSpan: you can Unlike with owning containers, \c{const} is \e{shallow} in QSpan: you can
still modify the data through a const QSpan (but not through a still modify the data through a const QSpan (but not through a
\c{QSpan<const T>}), and begin() and end() are not overloaded on \c{QSpan<const T>}), and begin() and end() are not overloaded on
@ -73,6 +76,9 @@
*span.cbegin() = -1; // ERROR: cannot assign through a const_iterator *span.cbegin() = -1; // ERROR: cannot assign through a const_iterator
\endcode \endcode
\section2 Other Properties
\target other-span-properties
QSpan should be passed by value, not by reference-to-const: QSpan should be passed by value, not by reference-to-const:
\code \code
@ -135,7 +141,7 @@
This alias is provided for compatbility with the STL. This alias is provided for compatbility with the STL.
\sa value_type, pointer \sa value_type, pointer, {const-mutable-spans}
*/ */
/*! /*!
@ -145,7 +151,7 @@
This alias is provided for compatbility with the STL. This alias is provided for compatbility with the STL.
\sa element_type \sa element_type, {const-mutable-spans}
*/ */
/*! /*!
@ -171,7 +177,7 @@
This alias is provided for compatbility with the STL. This alias is provided for compatbility with the STL.
\sa element_type, const_pointer, reference, iterator \sa element_type, const_pointer, reference, iterator, {const-mutable-spans}
*/ */
/*! /*!
@ -181,7 +187,7 @@
This alias is provided for compatbility with the STL. This alias is provided for compatbility with the STL.
\sa element_type, pointer, const_reference, const_iterator \sa element_type, pointer, const_reference, const_iterator, {const-mutable-spans}
*/ */
/*! /*!
@ -191,7 +197,7 @@
This alias is provided for compatbility with the STL. This alias is provided for compatbility with the STL.
\sa element_type, const_reference, pointer \sa element_type, const_reference, pointer, {const-mutable-spans}
*/ */
/*! /*!
@ -201,7 +207,7 @@
This alias is provided for compatbility with the STL. This alias is provided for compatbility with the STL.
\sa element_type, reference, const_pointer \sa element_type, reference, const_pointer, {const-mutable-spans}
*/ */
/*! /*!
@ -209,7 +215,7 @@
An alias for \c{T*} and \c{pointer}, respectively. Includes the \c{const}, if any. An alias for \c{T*} and \c{pointer}, respectively. Includes the \c{const}, if any.
\sa pointer, const_iterator, reverse_iterator \sa pointer, const_iterator, reverse_iterator, {const-mutable-spans}
*/ */
/*! /*!
@ -217,7 +223,7 @@
An alias for \c{const T*} and \c{const_pointer}, respectively. An alias for \c{const T*} and \c{const_pointer}, respectively.
\sa const_pointer, iterator, const_reverse_iterator \sa const_pointer, iterator, const_reverse_iterator, {const-mutable-spans}
*/ */
/*! /*!
@ -225,7 +231,7 @@
An alias for \c{std::reverse_iterator<iterator>}. Includes the \c{const}, if any. An alias for \c{std::reverse_iterator<iterator>}. Includes the \c{const}, if any.
\sa iterator, const_reverse_iterator \sa iterator, const_reverse_iterator, {const-mutable-spans}
*/ */
/*! /*!
@ -233,7 +239,7 @@
An alias for \c{std::reverse_iterator<const_iterator>}. An alias for \c{std::reverse_iterator<const_iterator>}.
\sa const_iterator, reverse_iterator \sa const_iterator, reverse_iterator, {const-mutable-spans}
*/ */
/*! /*!
@ -351,6 +357,8 @@
\note This constructor is \c{noexcept} only if \c{E} is \c{std::dynamic_extent}. \note This constructor is \c{noexcept} only if \c{E} is \c{std::dynamic_extent}.
\note If \c{E} is not \c{std::dynamic_extent} and the size of \a il is not \c{E}, the behavior is undefined. \note If \c{E} is not \c{std::dynamic_extent} and the size of \a il is not \c{E}, the behavior is undefined.
\sa {const-mutable-spans}
*/ */
// //
@ -398,7 +406,7 @@
The index must be in range, that is, \a idx >= 0 and \a idx < size(), The index must be in range, that is, \a idx >= 0 and \a idx < size(),
otherwise the behavior is undefined. otherwise the behavior is undefined.
\sa front(), back(), size(), empty() \sa front(), back(), size(), empty(), {const-mutable-spans}
*/ */
/*! /*!
@ -408,7 +416,7 @@
The span must not be empty, otherwise the behavior is undefined. The span must not be empty, otherwise the behavior is undefined.
\sa operator[](), back(), size(), empty() \sa operator[](), back(), size(), empty(), {const-mutable-spans}
*/ */
/*! /*!
@ -418,7 +426,7 @@
The span must not be empty, otherwise the behavior is undefined. The span must not be empty, otherwise the behavior is undefined.
\sa operator[](), front(), size(), empty() \sa operator[](), front(), size(), empty(), {const-mutable-spans}
*/ */
/*! /*!
@ -428,7 +436,7 @@
The same as calling begin(). The same as calling begin().
\sa begin(), front() \sa begin(), front(), {const-mutable-spans}
*/ */
// //
@ -443,7 +451,7 @@
Because QSpan iterators are just pointers, this is the same as calling Because QSpan iterators are just pointers, this is the same as calling
data(). data().
\sa end(), cbegin(), rbegin(), crbegin(), data() \sa end(), cbegin(), rbegin(), crbegin(), data(), {const-mutable-spans}
*/ */
/*! /*!
@ -454,7 +462,7 @@
Because QSpan iterators are just pointers, this it the same as calling Because QSpan iterators are just pointers, this it the same as calling
\c{data() + size()}. \c{data() + size()}.
\sa begin(), cend(), rend(), crend(), data(), size() \sa begin(), cend(), rend(), crend(), data(), size(), {const-mutable-spans}
*/ */
/*! /*!
@ -469,7 +477,7 @@
*span.cbegin() = 42; // ERROR: cannot assign through a const_iterator *span.cbegin() = 42; // ERROR: cannot assign through a const_iterator
\endcode \endcode
\sa cend(), begin(), crbegin(), rbegin(), data() \sa cend(), begin(), crbegin(), rbegin(), data(), {const-mutable-spans}
*/ */
/*! /*!
@ -477,7 +485,7 @@
Returns a const_iterator pointing to one past the end of the span. Returns a const_iterator pointing to one past the end of the span.
\sa cbegin(), end(), crend(), rend(), data(), size() \sa cbegin(), end(), crend(), rend(), data(), size(), {const-mutable-spans}
*/ */
/*! /*!
@ -485,7 +493,7 @@
Returns a reverse_iterator pointing to the beginning of the reversed span. Returns a reverse_iterator pointing to the beginning of the reversed span.
\sa rend(), crbegin(), begin(), cbegin() \sa rend(), crbegin(), begin(), cbegin(), {const-mutable-spans}
*/ */
/*! /*!
@ -493,7 +501,7 @@
Returns a reverse_iterator pointing to one past the end of the reversed span. Returns a reverse_iterator pointing to one past the end of the reversed span.
\sa rbegin(), crend(), end(), cend() \sa rbegin(), crend(), end(), cend(), {const-mutable-spans}
*/ */
/*! /*!
@ -501,7 +509,7 @@
Returns a const_reverse_iterator pointing to the beginning of the reversed span. Returns a const_reverse_iterator pointing to the beginning of the reversed span.
\sa crend(), rbegin(), cbegin(), begin() \sa crend(), rbegin(), cbegin(), begin(), {const-mutable-spans}
*/ */
/*! /*!
@ -509,7 +517,7 @@
Returns a const_reverse_iterator pointing to one past the end of the reversed span. Returns a const_reverse_iterator pointing to one past the end of the reversed span.
\sa crbegin(), rend(), cend(), end() \sa crbegin(), rend(), cend(), end(), {const-mutable-spans}
*/ */
// //
@ -660,7 +668,7 @@
\note \c{q20::dynamic_extent} is a C++17 backport of C++20's \note \c{q20::dynamic_extent} is a C++17 backport of C++20's
\l{https://en.cppreference.com/w/cpp/container/span/dynamic_extent}{\c{std::dynamic_extent}}. \l{https://en.cppreference.com/w/cpp/container/span/dynamic_extent}{\c{std::dynamic_extent}}.
\sa as_writable_bytes(), size_bytes() \sa as_writable_bytes(), size_bytes(), {const-mutable-spans}
*/ */
/*! /*!
@ -679,5 +687,5 @@
\note \c{q20::dynamic_extent} is a C++17 backport of C++20's \note \c{q20::dynamic_extent} is a C++17 backport of C++20's
\l{https://en.cppreference.com/w/cpp/container/span/dynamic_extent}{\c{std::dynamic_extent}}. \l{https://en.cppreference.com/w/cpp/container/span/dynamic_extent}{\c{std::dynamic_extent}}.
\sa as_bytes(), size_bytes() \sa as_bytes(), size_bytes(), {const-mutable-spans}
*/ */