QSpan Class | Qt Core | Qt 6.11.0
Description: A non-owning container over contiguous data.

- Qt 6.11
- Qt Core
- C++ Classes
- QSpan
- Qt 6.11.0 Reference Documentation

# 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

## Related Non-Members

`(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`.
- (since Qt 6.9) `QSpan<const T>` doesn't detach Qt containers, `std::span` does.
- 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

### `[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::const_reverse_iterator

An alias for `std::reverse_iterator<const_iterator>`.

See also const_iterator, reverse_iterator, 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.

### `[alias]` QSpan::reverse_iterator

An alias for `std::reverse_iterator<iterator>`. Includes the `const`, if any.

See also iterator, const_reverse_iterator, and Const and Mutable Spans.

### `[alias]` QSpan::size_type

An alias for qsizetype. This differs from `std::span`.

This alias is provided for compatbility with the STL.

### `[alias]` QSpan::value_type

An alias for `T`. Excludes the `const`, if any.

This alias is provided for compatbility with the STL.

See also element_type and Const and Mutable Spans.

## Member Function Documentation

### `[default]` QSpan::QSpan()

Default constructor.

This constructor is only present if `E` is either zero (0) or `std::dynamic_extent`. In other words: only fixed-zero-sized or variable-sized spans are default-constructible.

See also extent and Variable-Size and Fixed-Size Spans.

### `[constexpr noexcept]` template < typename S, size_t N, QSpan<T, E>::if_qualification_conversion<S> = true > QSpan::QSpan(QSpan<S, N> other)

### `[constexpr noexcept]` template < typename S, size_t N, QSpan<T, E>::if_qualification_conversion<S> = true > QSpan::QSpan(std::span<S, N> other)

Constructs a QSpan referencing the data in the supplied span other.

#### Constraints

Participates in overload resolution only if

- either `N` or extent are `std::dynamic_extent` or extent `==` `N`
- and either `S` or `const S` are the same as `T`.

### `[constexpr]` template <typename Range, QSpan<T, E>::if_compatible_range<Range> = true> QSpan::QSpan(Range &&r)

Constructs a QSpan referencing the data in the supplied range r.

#### Constraints

Participates in overload resolution only if `Range` is a compatible range.

### `[constexpr noexcept]` template <size_t N> QSpan::QSpan(q20::type_identity_t<T> (&)[N] arr)

### `[constexpr noexcept]` template < typename S, size_t N, QSpan<T, E>::if_qualification_conversion<S> = true > QSpan::QSpan(std::array<S, N> &arr)

### `[constexpr noexcept]` template < typename S, size_t N, QSpan<T, E>::if_qualification_conversion<S> = true > QSpan::QSpan(const std::array<S, N> &arr)

Constructs a QSpan referencing the data in the supplied array arr.

Note: `q20::type_identity_t` is a C++17 backport of C++20's `std::type_identity_t`.

#### Constraints

Participates in overload resolution only if

- either `N` or extent are `std::dynamic_extent` or otherwise extent `==` `N`
- and either `S` or `const S` are the same as `T`.

### `[constexpr]` QSpan::QSpan(std::initializer_list<QSpan<T, E>::value_type> il)

Constructs a QSpan referencing the data in the supplied initializer list il.

Note: This constructor is `noexcept` only if `E` is `std::dynamic_extent`.

Note: If `E` is not `std::dynamic_extent` and the size of il is not `E`, the behavior is undefined.

#### Constraints

Participates in overload resolution only if `T` is `const`-qualified.

See also Const and Mutable Spans.

### `[constexpr]` template <typename It, QSpan<T, E>::if_compatible_iterator<It> = true> QSpan::QSpan(It first, It last)

Constructs a QSpan referencing the data starting at first and having length (last - first).

`[first, last)` must be a valid range.

#### Constraints

Participates in overload resolution only if `It` is a compatible iterator.

### `[constexpr]` template <typename It, QSpan<T, E>::if_compatible_iterator<It> = true> QSpan::QSpan(It first, qsizetype count)

Constructs a QSpan referencing the data starting at first and having length count.

`[first, count)` must be a valid range.

#### Constraints

Participates in overload resolution only if `It` is a compatible iterator.

### `[default]` QSpan::QSpan(const QSpan<T, E> &other)

### `[default]` QSpan::QSpan(QSpan<T, E> &&other)

### `[default]` QSpan<T, E> &QSpan::operator=(const QSpan<T, E> &other)

### `[default]` QSpan<T, E> &QSpan::operator=(QSpan<T, E> &&other)

### `[default]` QSpan::~QSpan()

These Special Member Functions are implicitly-defined.

Note: Moves are equivalent to copies. Only data() and size() are copied from span to span, not the referenced data.

### `[constexpr]` auto QSpan::back() const

Returns a reference to the last element in the span.

The span must not be empty, otherwise the behavior is undefined.

See also operator[](), front(), size(), empty(), and Const and Mutable Spans.

### `[constexpr noexcept]` auto QSpan::begin() const

Returns an interator pointing at the beginning of the span.

Because QSpan iterators are just pointers, this is the same as calling data().

See also end(), cbegin(), rbegin(), crbegin(), data(), and Const and Mutable Spans.

### `[constexpr noexcept]` auto QSpan::cbegin() const

Returns a const_iterator pointing to the beginning of the span.

This will return a read-only iterator even if `T` is not `const`:

     QSpan<int> span = ~~~;
     *span.begin() = 42; // OK
     *span.cbegin() = 42; // ERROR: cannot assign through a const_iterator

See also cend(), begin(), crbegin(), rbegin(), data(), and Const and Mutable Spans.

### `[constexpr noexcept]` auto QSpan::cend() const

Returns a const_iterator pointing to one past the end of the span.

See also cbegin(), end(), crend(), rend(), data(), size(), and Const and Mutable Spans.

### `[constexpr, since 6.9]` void QSpan::chop(QSpan<T, E>::size_type n)

Same as `*this = chopped(`n`)`.

This function is only available on variable-sized spans.

This function was introduced in Qt 6.9.

See also chopped().

### `[constexpr, since 6.9]` auto QSpan::chopped(QSpan<T, E>::size_type n) const

Returns a variable-sized span of size size() - n referencing the first size() - n elements of this span.

Same as `first(size() - n)`.

n must be non-negative.

This span must hold at least n elements (`E` >= n and size() >= n), otherwise the behavior is undefined.

This function was introduced in Qt 6.9.

See also subspan(), first(QSpan<T,E>::size_type), last(QSpan<T,E>::size_type), and chop().

### `[constexpr noexcept]` auto QSpan::crbegin() const

Returns a const_reverse_iterator pointing to the beginning of the reversed span.

See also crend(), rbegin(), cbegin(), begin(), and Const and Mutable Spans.

### `[constexpr noexcept]` auto QSpan::crend() const

Returns a const_reverse_iterator pointing to one past the end of the reversed span.

See also crbegin(), rend(), cend(), end(), and Const and Mutable Spans.

### `[constexpr noexcept]` auto QSpan::data() const

Returns a pointer to the beginning of the span.

The same as calling begin().

See also begin(), front(), and Const and Mutable Spans.

### `[constexpr noexcept]` auto QSpan::empty() const

### `[constexpr noexcept]` auto QSpan::isEmpty() const

Returns whether the span is empty, that is, whether `size() == 0`.

These functions do the same thing: empty() is provided for STL compatibility and isEmpty() is provided for Qt compatibility.

See also size() and size_bytes().

### `[constexpr noexcept]` auto QSpan::end() const

Returns an iterator pointing to one past the end of the span.

Because QSpan iterators are just pointers, this it the same as calling `data() + size()`.

See also begin(), cend(), rend(), crend(), data(), size(), and Const and Mutable Spans.

### `[constexpr noexcept(...)]` template <std::size_t Count> auto QSpan::first() const

Returns a fixed-sized span of size `Count` referencing the first `Count` elements of `*this`.

The span must hold at least `Count` elements (`E` >= `Count` and size() >= `Count`), otherwise the behavior is undefined.

Note: This function is noexcept when `subspan_always_succeeds_v<Count>` is `true`.

See also first(QSpan<T,E>::size_type), last(), and subspan().

### `[constexpr]` auto QSpan::first(QSpan<T, E>::size_type n) const

Returns a variable-sized span of size n referencing the first n elements of `*this`.

n must be non-negative.

The span must hold at least n elements (`E` >= n and size() >= n), otherwise the behavior is undefined.

See also first<N>(), last(QSpan<T,E>::size_type), subspan(QSpan<T,E>::size_type), subspan(QSpan<T,E>::size_type, QSpan<T,E>::size_type), sliced(), and chopped().

### `[constexpr]` auto QSpan::front() const

Returns a reference to the first element in the span.

The span must not be empty, otherwise the behavior is undefined.

See also operator[](), back(), size(), empty(), and Const and Mutable Spans.

### `[constexpr noexcept(...)]` template <std::size_t Count> auto QSpan::last() const

Returns a fixed-sized span of size `Count` referencing the last `Count` elements of `*this`.

The span must hold at least `Count` elements (`E` >= `Count` and size() >= `Count`), otherwise the behavior is undefined.

Note: This function is noexcept when `subspan_always_succeeds_v<Count>` is `true`.

See also last(QSpan<T,E>::size_type), first(), and subspan().

### `[constexpr]` auto QSpan::last(QSpan<T, E>::size_type n) const

Returns a variable-sized span of size n referencing the last n elements of `*this`.

n must be non-negative.

The span must hold at least n elements (`E` >= n and size() >= n), otherwise the behavior is undefined.

See also last(), first(QSpan<T,E>::size_type), subspan(QSpan<T,E>::size_type), subspan(QSpan<T,E>::size_type, QSpan<T,E>::size_type), sliced(), and chopped().

### `[constexpr noexcept]` auto QSpan::rbegin() const

Returns a reverse_iterator pointing to the beginning of the reversed span.

See also rend(), crbegin(), begin(), cbegin(), and Const and Mutable Spans.

### `[constexpr noexcept]` auto QSpan::rend() const

Returns a reverse_iterator pointing to one past the end of the reversed span.

See also rbegin(), crend(), end(), cend(), and Const and Mutable Spans.

### `[constexpr noexcept]` auto QSpan::size() const

Returns the size of the span, that is, the number of elements it references.

See also size_bytes(), empty(), and isEmpty().

### `[constexpr noexcept]` auto QSpan::size_bytes() const

Returns the size of the span in bytes, that is, the number of elements multiplied by `sizeof(T)`.

See also size(), empty(), and isEmpty().

### `[constexpr, since 6.9]` void QSpan::slice(QSpan<T, E>::size_type pos)

Same as `*this = sliced(`pos`)`.

This function is only available on variable-sized spans.

This function was introduced in Qt 6.9.

See also sliced().

### `[constexpr, since 6.9]` void QSpan::slice(QSpan<T, E>::size_type pos, QSpan<T, E>::size_type n)

Same as `*this = sliced(`pos`,`n`)`.

This function is only available on variable-sized spans.

This function was introduced in Qt 6.9.

See also sliced().

### `[constexpr noexcept(...)]` template <std::size_t Offset, std::size_t Count> auto QSpan::subspan() const

Returns a span of size `Count` referencing the `Count` elements of this span starting at `Offset`.

If `*this` is a variable-sized span, the return type is a variable-sized span, otherwise it is a fixed-sized span.

This span must hold at least `Offset + Count` elements (`E` >= `Offset + Count` and size() >= `Offset + Count`), otherwise the behavior is undefined.

Note: This function is noexcept when `subspan_always_succeeds_v<Offset + Count>` is `true`.

See also subspan(QSpan<T,E>::size_type, QSpan<T,E>::size_type), first(), last(), and Variable-Size and Fixed-Size Spans.

### `[constexpr noexcept(...)]` template <std::size_t Offset> auto QSpan::subspan() const

Returns a span of size `E - Offset` referencing the remainder of this span after dropping the first `Offset` elements.

If `*this` is a variable-sized span, the return type is a variable-sized span, otherwise it is a fixed-sized span.

This span must hold at least `Offset` elements (`E` >= `Offset` and size() >= `Offset`), otherwise the behavior is undefined.

Note: This function is noexcept when `subspan_always_succeeds_v<Offset>` is `true`.

See also subspan(QSpan<T,E>::size_type), subspan(), first(), last(), and Variable-Size and Fixed-Size Spans.

### `[constexpr]` auto QSpan::subspan(QSpan<T, E>::size_type pos) const

### `[constexpr]` auto QSpan::sliced(QSpan<T, E>::size_type pos) const

Returns a variable-sized span of size `size() - pos` referencing the remainder of this span after dropping the first pos elements.

pos must be non-negative.

This span must hold at least pos elements (`E` >= pos and size() >= pos), otherwise the behavior is undefined.

These functions do the same thing: subspan() is provided for STL compatibility and sliced() is provided for Qt compatibility.

See also subspan(), first(QSpan<T,E>::size_type), last(QSpan<T,E>::size_type), chopped(), and slice().

### `[constexpr]` auto QSpan::subspan(QSpan<T, E>::size_type pos, QSpan<T, E>::size_type n) const

### `[constexpr]` auto QSpan::sliced(QSpan<T, E>::size_type pos, QSpan<T, E>::size_type n) const

Returns a variable-sized span of size n referencing the n elements of this span starting at pos.

Both pos and n must be non-negative.

This span must hold at least `pos + n` elements (`E` >= `pos + n` and size() >= `pos + n`), otherwise the behavior is undefined.

These functions do the same thing: subspan() is provided for STL compatibility and sliced() is provided for Qt compatibility.

See also subspan(), first(QSpan<T,E>::size_type), last(QSpan<T,E>::size_type), chopped(), and slice().

### `[constexpr]` QSpan<T, E>::reference QSpan::operator[](QSpan<T, E>::size_type idx) const

Returns a reference to the element at index idx in the span.

The index must be in range, that is, idx >= 0 and idx < size(), otherwise the behavior is undefined.

See also front(), back(), size(), empty(), and Const and Mutable Spans.

## Member Variable Documentation

### const std::size_t 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().

## Related Non-Members

### `[noexcept, since 6.8]` auto as_bytes(QSpan<T, E> s)

Returns s as a `QSpan<const std::byte, E'>` whose size() is equal to `s.size_bytes()`.

If `E` is `std::dynamic_extent` then so is `E'`. Otherwise, `E' = E * sizeof(T)`.

Note: `q20::dynamic_extent` is a C++17 backport of C++20's `std::dynamic_extent`.

This function was introduced in Qt 6.8.

See also as_writable_bytes(), size_bytes(), and Const and Mutable Spans.

### `[noexcept, since 6.8]` auto as_writable_bytes(QSpan<T, E> s)

Returns s as a `QSpan<std::byte, E'>` whose size() is equal to `s.size_bytes()`.

If `E` is `std::dynamic_extent` then so is `E'`. Otherwise, `E' = E * sizeof(T)`.

Note: `q20::dynamic_extent` is a C++17 backport of C++20's `std::dynamic_extent`.

#### Constraints

Participates in overload resolution only if `!std::is_const_v<T>`.

This function was introduced in Qt 6.8.

See also as_bytes(), size_bytes(), and Const and Mutable Spans.