std::span(3) | C++ Standard Libary | std::span(3) |
NAME¶
std::span - std::span
Synopsis¶
Defined in header <span>
template<
class T, (since C++20)
std::size_t Extent = std::dynamic_extent
> class span;
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 std::span is a TriviallyCopyable type. (since
C++23)
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
Member types¶
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&
implementation-defined LegacyRandomAccessIterator,
iterator 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.
Member constant
static constexpr std::size_t extent = Extent;
Member functions¶
constructor constructs a span
(public member function)
operator= assigns a span
(public member function)
Iterators¶
begin returns an iterator to the beginning
(C++20) (public member function)
end returns an iterator to the end
(C++20) (public member function)
rbegin returns a reverse iterator to the beginning
(C++20) (public member function)
rend returns a reverse iterator to the end
(C++20) (public member function)
Element access¶
front access the first element
(C++20) (public member function)
back access the last element
(C++20) (public member function)
operator[] accesses an element of the sequence
(public member function)
data returns a pointer to the beginning of the sequence of elements
(public member function)
Observers¶
size returns the number of elements in the sequence
(public member function)
size_bytes returns the size of the sequence in bytes
(public member function)
empty checks if the sequence is empty
(public member function)
Subviews
first obtains a subspan consisting of the first N elements of the sequence
(public member function)
last obtains a subspan consisting of the last N elements of the sequence
(public member function)
subspan obtains a subspan
(public member function)
Non-member functions¶
as_bytes converts a span into a view of its underlying bytes
as_writable_bytes (function template)
(C++20)
Non-member constant
dynamic_extent a constant of type size_t signifying that the span has dynamic
extent
(C++20) (constant)
Helper templates
template<class T, std::size_t Extent>
inline constexpr bool ranges::enable_borrowed_range<std::span<T,
Extent>> = true;
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;
This specialization of ranges::enable_view makes span satisfy view.
Deduction guides
Notes¶
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: __cpp_lib_span
Example¶
The example uses std::span to implement some algorithms on contiguous ranges.
// Run this code
#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> [[nodiscard]]
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> [[nodiscard]]
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> [[nodiscard]]
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
Defect reports
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 they are as default_initializable is
not
extents were not view required
See also¶
initializer_list creates a temporary array in list-initialization
and then
(C++11) references it
(class template)
basic_string_view read-only string view
(C++17) (class template)
ranges::subrange combines an iterator-sentinel pair into a view
(C++20) (class template)
2022.07.31 | http://cppreference.com |