QSpan Class

template <typename T, std::size_t E = std::size_t(-1)> class QSpan

A 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

List of all members, including inherited members

Note: All functions in this class are reentrant.

Public Types

	const_iterator
	const_pointer
	const_reference
	const_reverse_iterator
	difference_type
	element_type
	iterator
	pointer
	reference
	reverse_iterator
	size_type
	value_type

Public Functions

	QSpan()
	QSpan(QSpan<S, N> other)
	QSpan(Range &&r)
	QSpan(const std::array<S, N> &arr)
	QSpan(q20::type_identity_t<T> (&)[N] arr)
	QSpan(std::array<S, N> &arr)
	QSpan(std::initializer_list<QSpan<T, E>::value_type> il)
	QSpan(std::span<S, N> other)
	QSpan(It first, It last)
	QSpan(It first, qsizetype count)
	QSpan(const QSpan<T, E> &other)
	QSpan(QSpan<T, E> &&other)
	~QSpan()
auto	back() const
auto	begin() const
auto	cbegin() const
auto	cend() const
`(since 6.9)` void	chop(QSpan<T, E>::size_type n)
`(since 6.9)` auto	chopped(QSpan<T, E>::size_type n) const
auto	crbegin() const
auto	crend() const
auto	data() const
auto	empty() const
auto	end() const
auto	first() const
auto	first(QSpan<T, E>::size_type n) const
auto	front() const
auto	isEmpty() const
auto	last() const
auto	last(QSpan<T, E>::size_type n) const
auto	rbegin() const
auto	rend() const
auto	size() const
auto	size_bytes() const
`(since 6.9)` void	slice(QSpan<T, E>::size_type pos)
`(since 6.9)` void	slice(QSpan<T, E>::size_type pos, QSpan<T, E>::size_type n)
auto	sliced(QSpan<T, E>::size_type pos) const
auto	sliced(QSpan<T, E>::size_type pos, QSpan<T, E>::size_type n) const
auto	subspan() const
auto	subspan() const
auto	subspan(QSpan<T, E>::size_type pos) const
auto	subspan(QSpan<T, E>::size_type pos, QSpan<T, E>::size_type n) const
QSpan<T, E> &	operator=(QSpan<T, E> &&other)
QSpan<T, E> &	operator=(const QSpan<T, E> &other)
QSpan<T, E>::reference	operator[](QSpan<T, E>::size_type idx) const

Static Public Members

const std::size_t extent

`(since 6.8)` auto	as_bytes(QSpan<T, E> s)
`(since 6.8)` auto	as_writable_bytes(QSpan<T, E> s)

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 whereas std::span uses size_t.
All QSpan constructors are implicit; many std::span ones are explicit.
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