template<classT,std::size_tExtent=std::dynamic_extent>classspan;(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.
For a spans, pointers, iterators, and references to elements of s are invalidated when an operation invalidates a pointer in the range [s.data(), s.data()+s.size()).
Template parameters
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 Nested types
Type Definition element_typeTvalue_typestd::remove_cv_t<T>size_type
difference_type
pointerT*const_pointerconstT*referenceT&const_referenceconstT&iterator
implementation-defined
,
, and
whose value_type is value_typeconst_iterator(since C++23)std::const_iterator<iterator>reverse_iteratorstd::reverse_iterator<iterator>const_reverse_iterator(since C++23)std::const_iterator<reverse_iterator>
iterator is a mutable iterator if T is not const-qualified.
All requirements on the iterator types of a
apply to the iterator type of span as well.
Data members
Member Description 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 is dynamic )the number of elements
(exposition-only member object*)Member functions
constructs a span
(public member function)
assigns a span
(public member function)
(destructor)
(implicitly declared)
destructs a span
(public member function) Iterators
(C++23)
returns an iterator to the beginning
(public member function)
(C++23)
returns an iterator to the end
(public member function)
(C++23)
returns a reverse iterator to the beginning
(public member function)
(C++23)
returns a reverse iterator to the end
(public member function)
Element access
access the first element
(public member function)
access the last element
(public member function)
(C++26)
access specified element with bounds checking
(public member function)
access specified element
(public member function)
direct access to the underlying contiguous storage
(public member function)
Observers
returns the number of elements
(public member function)
returns the size of the sequence in bytes
(public member function)
checks if the sequence is empty
(public member function)
Subviews
obtains a subspan consisting of the first N elements of the sequence
(public member function)
obtains a subspan consisting of the last N elements of the sequence
(public member function)
obtains a subspan
(public member function)
Non-member functions
Helper constant
Helper templates
template<classT,std::size_tExtent>constexprboolranges::enable_borrowed_range<std::span<T,Extent>>=true;(since C++20)This specialization of
makes span satisfy
.
template<classT,std::size_tExtent>constexprboolranges::enable_view<std::span<T,Extent>>=true;(since C++20)This specialization of
makes span satisfy
.
Notes
Specializations of std::span are already trivially copyable types in all existing implementations, even before the formal requirement introduced in C++23.
macro ValueStdFeature
(C++20)std::span
(C++26)std::span::atExample
The example uses std::span to implement some algorithms on contiguous ranges.
Run this code
#include<algorithm>#include<cstddef>#include<iostream>#include<span>template<classT,std::size_tN>[[nodiscard]]constexprautoslide(std::span<T,N>s,std::size_toffset,std::size_twidth){returns.subspan(offset,offset+width<=s.size()?width:0U);}template<classT,std::size_tN,std::size_tM>constexprboolstarts_with(std::span<T,N>data,std::span<T,M>prefix){returndata.size()>=prefix.size()&&std::equal(prefix.begin(),prefix.end(),data.begin());}template<classT,std::size_tN,std::size_tM>constexprboolends_with(std::span<T,N>data,std::span<T,M>suffix){returndata.size()>=suffix.size()&&std::equal(data.end()-suffix.size(),data.end(),suffix.end()-suffix.size());}template<classT,std::size_tN,std::size_tM>constexprboolcontains(std::span<T,N>span,std::span<T,M>sub){returnstd::ranges::search(span,sub).begin()!=span.end();}voidprintln(constauto&seq){for(constauto&elem:seq)std::cout<<elem<<' ';std::cout<<'\n';}intmain(){constexprinta[]{0,1,2,3,4,5,6,7,8};constexprintb[]{8,7,6};constexprstaticstd::size_twidth{6};for(std::size_toffset{};;++offset)if(autos=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 5 1 2 3 4 5 6 2 3 4 5 6 7 3 4 5 6 7 8 Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++20 it was unclear when the pointers, iterators, and
references to elements of span are invalidated made clear
C++20 the declaration of span's destructor was unnecessary removed the declaration
C++20 a span of non-zero static extents was not a viewany span is a viewSee also