Defined in header <span> | ||
---|---|---|
template< class T, std::size_t Extent = std::dynamic_extent > class span; | (since C++20) |
The class template span
describes an object that can refer to a contiguous sequence of objects with the first element of the sequence at position zero. A span
can either have a static extent, in which case the number of elements in the sequence is known at compile-time and encoded in the type, or a dynamic extent.
If a span
has dynamic extent, a typical implementation holds two members: a pointer to T
and a size. A span
with static extent may have only one member: a pointer to T
.
Every specialization of | (since C++23) |
T | - | element type; must be a complete object type that is not an abstract class type |
Extent | - | the number of elements in the sequence, or std::dynamic_extent if dynamic |
Member type | Definition |
---|---|
element_type | T |
value_type | std::remove_cv_t<T> |
size_type | std::size_t |
difference_type | std::ptrdiff_t |
pointer | T* |
const_pointer | const T* |
reference | T& |
const_reference | const T& |
iterator | implementation-defined LegacyRandomAccessIterator, ConstexprIterator, and contiguous_iterator whose value_type is value_type |
reverse_iterator | std::reverse_iterator<iterator> |
Note: iterator
is a mutable iterator if T
is not const-qualified.
All requirements on the iterator types of a Container apply to the iterator
type of span
as well.
static constexpr std::size_t extent = Extent; | (since C++20) |
(C++20) | constructs a span (public member function) |
(C++20) | assigns a span (public member function) |
Iterators |
|
(C++20) | returns an iterator to the beginning (public member function) |
(C++20) | returns an iterator to the end (public member function) |
(C++20) | returns a reverse iterator to the beginning (public member function) |
(C++20) | returns a reverse iterator to the end (public member function) |
Element access |
|
(C++20) | access the first element (public member function) |
(C++20) | access the last element (public member function) |
(C++20) | accesses an element of the sequence (public member function) |
(C++20) | returns a pointer to the beginning of the sequence of elements (public member function) |
Observers |
|
(C++20) | returns the number of elements in the sequence (public member function) |
(C++20) | returns the size of the sequence in bytes (public member function) |
(C++20) | checks if the sequence is empty (public member function) |
Subviews |
|
(C++20) | obtains a subspan consisting of the first N elements of the sequence (public member function) |
(C++20) | obtains a subspan consisting of the last N elements of the sequence (public member function) |
(C++20) | obtains a subspan (public member function) |
(C++20) | converts a span into a view of its underlying bytes (function template) |
(C++20) | a constant of type size_t signifying that the span has dynamic extent (constant) |
template< class T, std::size_t Extent > inline constexpr bool ranges::enable_borrowed_range<std::span<T, Extent>> = true; | (since C++20) |
This specialization of ranges::enable_borrowed_range
makes span
satisfy borrowed_range
.
template< class T, std::size_t Extent > inline constexpr bool ranges::enable_view<std::span<T, Extent>> = true; | (since C++20) |
This specialization of ranges::enable_view
makes span
satisfy view
.
Specializations of std::span
are already trivially copyable types in all existing implementations, even before the formal requirement introduced in C++23.
Feature-test macro | Value | Std | Comment |
---|---|---|---|
__cpp_lib_span | 202002L | (C++20) |
std::span |
The example uses std::span
to implement some algorithms on contiguous ranges.
#include <algorithm> #include <cstddef> #include <iostream> #include <span> template<class T, std::size_t N> [[nodiscard]] constexpr auto slide(std::span<T,N> s, std::size_t offset, std::size_t width) { return s.subspan(offset, offset + width <= s.size() ? width : 0U); } template<class T, std::size_t N, std::size_t M> constexpr bool starts_with(std::span<T,N> data, std::span<T,M> prefix) { return data.size() >= prefix.size() && std::equal(prefix.begin(), prefix.end(), data.begin()); } template<class T, std::size_t N, std::size_t M> constexpr bool ends_with(std::span<T,N> data, std::span<T,M> suffix) { return data.size() >= suffix.size() && std::equal(data.end() - suffix.size(), data.end(), suffix.end() - suffix.size()); } template<class T, std::size_t N, std::size_t M> constexpr bool contains(std::span<T,N> span, std::span<T,M> sub) { return std::search(span.begin(), span.end(), sub.begin(), sub.end()) != span.end(); // return std::ranges::search(span, sub).begin() != span.end(); } void print(const auto& seq) { for (const auto& elem : seq) std::cout << elem << ' '; std::cout << '\n'; } int main() { constexpr int a[] {0, 1, 2, 3, 4, 5, 6, 7, 8}; constexpr int b[] {8, 7, 6}; for (std::size_t offset{}; ; ++offset) { static constexpr std::size_t width{6}; auto s = slide(std::span{a}, offset, width); if (s.empty()) break; print(s); } static_assert( starts_with(std::span{a}, std::span{a, 4}) and starts_with(std::span{a + 1, 4}, std::span{a + 1, 3}) and ! starts_with(std::span{a}, std::span{b}) and ! starts_with(std::span{a, 8}, std::span{a + 1, 3}) and ends_with(std::span{a}, std::span{a + 6, 3}) and ! ends_with(std::span{a}, std::span{a + 6, 2}) and contains(std::span{a}, std::span{a + 1, 4}) and ! contains(std::span{a, 8}, std::span{a, 9}) ); }
Output:
0 1 2 3 4 5 1 2 3 4 5 6 2 3 4 5 6 7 3 4 5 6 7 8
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
P2325R3 | C++20 | span of non-zero static extents were not view | they are as default_initializable is not required |
(C++11) | creates a temporary array in list-initialization and then references it (class template) |
(C++17) | read-only string view (class template) |
(C++23) | a multi-dimensional non-owning array view (class template) |
(C++20) | combines an iterator-sentinel pair into a view (class template) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/container/span