Scroll to navigation

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.


For a span s, 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()).


Every specialization of std::span is a TriviallyCopyable type. (since C++23)


A typical implementation holds a pointer to T, if the extent is dynamic, the
implementation also holds a 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

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
const_iterator (since C++23) std::const_iterator<iterator>
reverse_iterator std::reverse_iterator<iterator>
const_reverse_iterator (since std::const_iterator<reverse_iterator>
C++23)


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; (since C++20)

Member functions


constructor constructs a span
(public member function)
operator= assigns a span
(public member function)
destructor destructs a span
(implicitly declared) (public member function)

Iterators


begin returns an iterator to the beginning
cbegin (public member function)
(C++23)
end returns an iterator to the end
cend (public member function)
(C++23)
rbegin returns a reverse iterator to the beginning
crbegin (public member function)
(C++23)
rend returns a reverse iterator to the end
crend (public member function)
(C++23)

Element access


front access the first element
(public member function)
back access the last element
(public member function)
at access specified element with bounds checking
(C++26) (public member function)
operator[] access specified element
(public member function)
data direct access to the underlying contiguous storage
(public member function)

Observers


size returns the number of elements
(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
obtains a subspan consisting of the first N elements of the
first sequence
(public member function)
obtains a subspan consisting of the last N elements of the
last 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 std::size_t signifying that the span has dynamic
(C++20) extent
(constant)


Helper templates


template< class T, std::size_t Extent >
inline constexpr bool ranges::enable_borrowed_range<std::span<T, (since C++20)
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>> = (since C++20)
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 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) Constructing std::span from a
std::initializer_list

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>
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::ranges::search(span, sub).begin() != span.end();
}


void println(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};
constexpr static std::size_t width{6};


for (std::size_t offset{}; ; ++offset)
if (auto s = slide(std::span{a}, offset, width); !s.empty())
println(s);
else
break;


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
it was unclear when the pointers,
LWG 3203 C++20 iterators, and made clear
references to elements of span are
invalidated
LWG 3903 C++20 the declaration of span's destructor was removed the declaration
unnucessary
P2325R3 C++20 a span of non-zero static extents was any span is a view
not a view

See also


mdspan a multi-dimensional non-owning array view
(C++23) (class template)
ranges::subrange combines an iterator-sentinel pair into a view
(C++20) (class template)
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)

2024.06.10 http://cppreference.com