QSpan Class
template <typename T, int E> class QSpanA non-owning container over contiguous data. More...
Header: | #include <QSpan> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
qmake: | QT += core |
Since: | Qt 6.7 |
Note: All functions in this class are reentrant.
Public Types
const_iterator | |
const_pointer | |
const_reference | |
difference_type | |
element_type | |
iterator | |
pointer | |
reference |
Static Public Members
const int | extent |
Detailed Description
A QSpan references a contiguous portion of another contiguous container. It acts as an interface type for all kinds of contiguous containers, without the need to construct an owning container such as QList or std::vector first.
The data referenced by a QSpan may be represented as an array (or array-compatible data-structure such as QList, std::vector, QVarLengthArray, etc.). QSpan itself merely stores a pointer to the data, so users must ensure that QSpan objects do not outlive the data they reference.
Unlike views such as QStringView, QLatin1StringView and QUtf8StringView, referenced data can be modified through a QSpan object. To prevent this, construct a QSpan over a const T
(see Const and Mutable Spans):
int numbers[] = {0, 1, 2}; QSpan<int> span = numbers; span[0] = 42; // numbers == {42, 1, 2}; QSpan<const int> cspan = numbers; cspan[0] = 0; // ERROR: cspan[0] is read-only
Variable-Size and Fixed-Size Spans
A QSpan can be fixed-size or variable-sized.
A variable-sized span is formed by omitting the second template argument (or setting it to std::dynamic_extent
, which is, however, only available in C++20 builds), as seen in the example above.
A fixed-size span is formed by passing a number as the second template argument:
int numbers[] = {0, 1, 2}; QSpan<int, 3> span = numbers; QSpan<const int, 3> = numbers; // also OK
As the name suggests, a fixed-size span's size() is fixed at compile-time whereas the size() of a variable-sized span is determined only at run-time.
A fixed-size span is not default-constructible (unless its extent is zero (0)). A variable-sized span is default-constructible and will have data() == nullptr
and size() == 0
.
A fixed-size span can be implicitly converted into a variable-sized one. The opposite direction (variable-length into fixed-length) has the precondition that both span's sizes must match.
Const and Mutable Spans
Unlike with owning containers, const
is shallow in QSpan: you can still modify the data through a const QSpan (but not through a QSpan<const T>
), and begin() and end() are not overloaded on const
/non-const
. There are cbegin() and cend(), though, that return const_iterators which prevent modification of the data even though T
is not const:
int numbers[] = {0, 1, 2}; const QSpan<int> span = numbers; span.front() = 42; // OK, numbers[0] == 42 now *span.begin() = 31; // OK, numbers[0] == 31 now *span.cbegin() = -1; // ERROR: cannot assign through a const_iterator
Other Properties
QSpan should be passed by value, not by reference-to-const:
void consume(QSpan<const int> data); // OK void consume(const QSpan<const int> &data); // works, but is non-idiomatic and less efficient
QSpan<T,N>
is a Literal Type, regardless of whether T
is a Literal Type or not.
QSpan vs. std::span
QSpan is closely modelled after std::span, but has a few differences which we'll discuss here. Since they both implicitly convert into each other, you're free to choose whichever one you like best in your own code.
- QSpan is using the signed qsizetype as
size_type
whereasstd::span
usessize_t
. - (since Qt 6.9)
QSpan<const T>
doesn't detach Qt containers,std::span
does. - All QSpan constructors are implicit; many
std::span
ones areexplicit
. - QSpan can be constructed from rvalue owning containers,
std::span
can not.
The last two are required for source-compatibility when functions that took owning containers are converted to take QSpan instead, which is a vitally-important use-case in Qt. The use of qsizetype is for consistency with the rest of Qt containers. QSpan template arguments still use size_t to avoid introducing unnecessary error conditions (negative sizes).
Compatible Iterators
QSpan can be constructed from an iterator and size or from an iterator pair, provided the iterators are compatible ones. Eventually, this should mean C++20 std::contiguous_iterator
and std::sentinel_for
, but while Qt still supports C++17, only raw pointers are considered contiguous iterators.
Compatible Ranges
QSpan can also be constructed from a compatible range. A range is compatible if it has compatible iterators.
See also QList, QStringView, QLatin1StringView, and QUtf8StringView.
Member Type Documentation
[alias]
QSpan::const_iterator
An alias for const T*
and const_pointer
, respectively.
See also const_pointer, iterator, const_reverse_iterator, and Const and Mutable Spans.
[alias]
QSpan::const_pointer
An alias for const T*
and const element_type*
, respectively.
This alias is provided for compatbility with the STL.
See also element_type, pointer, const_reference, const_iterator, and Const and Mutable Spans.
[alias]
QSpan::const_reference
An alias for const T&
and const element_type&
, respectively.
This alias is provided for compatbility with the STL.
See also element_type, reference, const_pointer, and Const and Mutable Spans.
[alias]
QSpan::difference_type
An alias for qptrdiff. This differs from std::span
.
This alias is provided for compatbility with the STL.
[alias]
QSpan::element_type
An alias for T
. Includes the const
, if any.
This alias is provided for compatbility with the STL.
See also value_type, pointer, and Const and Mutable Spans.
[alias]
QSpan::iterator
An alias for T*
and pointer
, respectively. Includes the const
, if any.
See also pointer, const_iterator, reverse_iterator, and Const and Mutable Spans.
[alias]
QSpan::pointer
An alias for T*
and element_type*
, respectively. Includes the const
, if any.
This alias is provided for compatbility with the STL.
See also element_type, const_pointer, reference, iterator, and Const and Mutable Spans.
[alias]
QSpan::reference
An alias for T&
and element_type&
, respectively. Includes the const
, if any.
This alias is provided for compatbility with the STL.
See also element_type, const_reference, pointer, and Const and Mutable Spans.
Member Variable Documentation
const int QSpan::extent
The second template argument of QSpan<T, E>
, that is, E
. This is std::dynamic_extent
for variable-sized spans.
Note: While all other sizes and indexes in QSpan use qsizetype, this variable, like E
, is actually of type size_t
, for compatibility with std::span
and std::dynamic_extent
.
See also size().