(C++17) | ||||
| Sequence | ||||
(C++11) | ||||
(C++26) | ||||
(C++26) | ||||
(C++11) | ||||
| Associative | ||||
| Unordered associative | ||||
(C++11) | ||||
(C++11) | ||||
(C++11) | ||||
(C++11) | ||||
| Adaptors | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
| Views | ||||
span (C++20) | ||||
(C++23) | ||||
| Tables | ||||
| Iterator invalidation | ||||
| Member function table | ||||
| Non-member function table |
| Member functions | ||||
| Element access | ||||
(C++26) | ||||
| Iterators | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
| Observers | ||||
| Subviews | ||||
| Non-member functions | ||||
| Non-member constant | ||||
| Deduction guides |
Defined in header <span> | ||
template< class T, | (since C++20) | |
The class templatespan describes an object that can refer to a contiguous sequence of objects with the first element of the sequence at position zero. Aspan can either have astatic extent, in which case the number of elements in the sequence is known at compile-time and encoded in the type, or adynamic extent.
For aspans, pointers, iterators, and references to elements ofs are invalidated when an operation invalidates a pointer in the range[s.data(), s.data()+ s.size()).
Every specialization of | (since C++23) |
Contents |
| T | - | element type; must be a complete object type that is not an abstract class type |
| Extent | - | the number of elements in the sequence, orstd::dynamic_extent if dynamic |
| 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[1] | implementation-definedLegacyRandomAccessIterator,ConstexprIterator, andcontiguous_iterator whosevalue_type isvalue_type |
const_iterator(since C++23) | std::const_iterator<iterator> |
reverse_iterator | std::reverse_iterator<iterator> |
const_reverse_iterator(since C++23) | std::const_iterator<reverse_iterator> |
iterator is a mutable iterator ifT is not const-qualified.All requirements on the iterator types of aContainer apply to theiterator type ofspan as well.
| Member | Description |
constexprstd::size_t extent [static] | Extent (public static member constant) |
pointerdata_ | a pointer to the underlying sequence (exposition-only member object*) |
size_typesize_(present only if the extent isdynamic ) | the number of elements (exposition-only member object*) |
constructs aspan(public member function)[edit] | |
assigns aspan(public member function)[edit] | |
(destructor) (implicitly declared) | destructs aspan(public member function) |
Iterators | |
(C++23) | returns an iterator to the beginning (public member function)[edit] |
(C++23) | returns an iterator to the end (public member function)[edit] |
(C++23) | returns a reverse iterator to the beginning (public member function)[edit] |
(C++23) | returns a reverse iterator to the end (public member function)[edit] |
Element access | |
| access the first element (public member function)[edit] | |
| access the last element (public member function)[edit] | |
(C++26) | access specified element with bounds checking (public member function)[edit] |
| access specified element (public member function)[edit] | |
| direct access to the underlying contiguous storage (public member function)[edit] | |
Observers | |
| returns the number of elements (public member function)[edit] | |
| returns the size of the sequence in bytes (public member function)[edit] | |
| checks if the sequence is empty (public member function)[edit] | |
Subviews | |
obtains a subspan consisting of the firstN elements of the sequence(public member function)[edit] | |
obtains a subspan consisting of the lastN elements of the sequence(public member function)[edit] | |
| obtains a subspan (public member function)[edit] | |
(C++20) | converts aspan into a view of its underlying bytes(function template)[edit] |
(C++20) | a constant of typestd::size_t signifying that thespan has dynamic extent(constant)[edit] |
template<class T,std::size_t Extent> constexprboolranges::enable_borrowed_range<std::span<T, Extent>>=true; | (since C++20) | |
This specialization ofranges::enable_borrowed_range makesspan satisfyborrowed_range.
template<class T,std::size_t Extent> constexprboolranges::enable_view<std::span<T, Extent>>=true; | (since C++20) | |
This specialization ofranges::enable_view makesspan satisfyview.
Specializations ofstd::span are already trivially copyable types in all existing implementations, even before the formal requirement introduced in C++23.
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_span | 202002L | (C++20) | std::span |
202311L | (C++26) | std::span::at | |
__cpp_lib_span_initializer_list | 202311L | (C++26) | Constructingstd::span from astd::initializer_list |
The example usesstd::span to implement some algorithms on contiguous ranges.
#include <algorithm>#include <cstddef>#include <iostream>#include <span> template<class T,std::size_t N>[[nodiscard]]constexprauto 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>constexprbool 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>constexprbool 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>constexprbool contains(std::span<T, N> span, std::span<T, M> sub){return std::ranges::search(span, sub).begin()!= span.end();} void println(constauto& seq){for(constauto& elem: seq)std::cout<< elem<<' ';std::cout<<'\n';} int main(){constexprint a[]{0,1,2,3,4,5,6,7,8};constexprint b[]{8,7,6};constexprstaticstd::size_t width{6}; for(std::size_t offset{};;++offset)if(auto s= slide(std::span{a}, offset, width);!s.empty()) println(s);elsebreak; static_assert(""&& starts_with(std::span{a}, std::span{a,4})&& starts_with(std::span{a+1,4}, std::span{a+1,3})&&!starts_with(std::span{a}, std::span{b})&&!starts_with(std::span{a,8}, std::span{a+1,3})&& ends_with(std::span{a}, std::span{a+6,3})&&!ends_with(std::span{a}, std::span{a+6,2})&& contains(std::span{a}, std::span{a+1,4})&&!contains(std::span{a,8}, std::span{a,9}));}
Output:
0 1 2 3 4 51 2 3 4 5 62 3 4 5 6 73 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 |
|---|---|---|---|
| LWG 3203 | C++20 | it was unclear when the pointers, iterators, and references to elements of span are invalidated | made clear |
| LWG 3903 | C++20 | the declaration ofspan's destructor was unnecessary | removed the declaration |
| P2325R3 | C++20 | aspan of non-zero static extents was not aview | anyspan is aview |
(C++23) | a multi-dimensional non-owning array view (class template)[edit] |
(C++20) | combines an iterator-sentinel pair into aview(class template)[edit] |
(C++11) | references a temporary array created inlist-initialization (class template)[edit] |
(C++17) | read-only string view (class template)[edit] |
