Difference between revisions of "cpp/container/span"
m (→Example: use 'contiguous ranges' instead, which is more appropriate) |
m (elaborates span implementation details) |
||
Line 13: | Line 13: | ||
The class template {{tt|span}} describes an object that can refer to a contiguous sequence of objects with the first element of the sequence at position zero. A {{tt|span}} can either have a ''static'' extent, in which case the number of elements in the sequence is known and encoded in the type, or a ''dynamic'' extent. | The class template {{tt|span}} describes an object that can refer to a contiguous sequence of objects with the first element of the sequence at position zero. A {{tt|span}} can either have a ''static'' extent, in which case the number of elements in the sequence is known and encoded in the type, or a ''dynamic'' extent. | ||
− | + | If a {{tt|span}} has ''dynamic'' extent a typical implementation holds two members: a pointer to {{tt|T}} and a size. | |
+ | A {{tt|span}} with ''static'' extent may have only one member: a pointer to {{tt|T}}. | ||
===Template parameters=== | ===Template parameters=== |
Revision as of 08:30, 5 July 2020
Defined in header <span>
|
||
template< class T, |
(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 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
.
Contents |
Template parameters
T | - | element type; must be a complete 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&
|
iterator
|
implementation-defined LegacyRandomAccessIterator, ConstexprIterator, and LegacyContiguousIterator 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
constructs a span (public member function) | |
assigns 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) | |
Observers | |
(C++20) |
returns the number of elements in the sequence (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
(C++20) |
converts a span into a view of its underlying bytes (function template) |
Non-member constant
(C++20) |
a constant of type std::size_t signifying that the span has dynamic extent (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 std::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>> = |
||
This specialization of std::ranges::enable_view makes span
of zero or dynamic extent satisfy view
. Spans of nonzero static extent are not default_initializable
and therefore not views.
Deduction guides
Example
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> [[nodiscard]] constexpr bool starts_with(std::span<T,N> data, std::span<T,M> prefix) { return data.size() >= prefix.size() && std::equal(data.begin(), data.end(), prefix.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(); } 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) { 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}) && 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