std::span

Defined in header `<span>`
template< class T, std::size_t Extent = std::dynamic_extent > class span;		(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.

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&
`iterator`	implementation-defined LegacyRandomAccessIterator, ConstexprIterator, and `contiguous_iterator` whose `value_type` is `value_type`
`const_iterator`(C++23)	std::const_iterator<iterator>
`reverse_iterator`	std::reverse_iterator<iterator>
`const_reverse_iterator`(C++23)	std::const_iterator<reverse_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;		(since C++20)

Member functions

(constructor) (C++20)	constructs a `span` (public member function)
operator= (C++20)	assigns a `span` (public member function)
Iterators
begin cbegin (C++20)(C++23)	returns an iterator to the beginning (public member function)
end cend (C++20)(C++23)	returns an iterator to the end (public member function)
rbegin crbegin (C++20)(C++23)	returns a reverse iterator to the beginning (public member function)
rend crend (C++20)(C++23)	returns a reverse iterator to the end (public member function)
Element access
front (C++20)	access the first element (public member function)
back (C++20)	access the last element (public member function)
operator[] (C++20)	accesses an element of the sequence (public member function)
data (C++20)	returns a pointer to the beginning of the sequence of elements (public member function)
Observers
size (C++20)	returns the number of elements in the sequence (public member function)
size_bytes (C++20)	returns the size of the sequence in bytes (public member function)
empty (C++20)	checks if the sequence is empty (public member function)
Subviews
first (C++20)	obtains a subspan consisting of the first N elements of the sequence (public member function)
last (C++20)	obtains a subspan consisting of the last N elements of the sequence (public member function)
subspan (C++20)	obtains a subspan (public member function)

Non-member functions

as_bytesas_writable_bytes

(C++20)

converts a span into a view of its underlying bytes
(function template)

Non-member constant

dynamic_extent

(C++20)

a constant of type 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;		(since C++20)

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

This specialization of ranges::enable_view makes span satisfy view.

Deduction guides(C++20)

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	Comment
`__cpp_lib_span`	202002L	(C++20)	`std::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>
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::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 extents were not `view`	they are as `default_initializable` is not required

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Technical specifications
Symbols index
External libraries

Sequence
array (C++11)
vector
vector<bool>
deque
forward_list (C++11)
list
Associative
set
multiset
map
multimap
Unordered associative
unordered_set (C++11)
unordered_multiset (C++11)
unordered_map (C++11)
unordered_multimap (C++11)
Adaptors
stack
queue
priority_queue
flat_set (C++23)
flat_multiset (C++23)
flat_map (C++23)
flat_multimap (C++23)
Views
span (C++20)
mdspan (C++23)
Iterator invalidation
Member function table
Non-member function table

Member functions
span::span (C++20)
span::operator= (C++20)
Element access
span::front (C++20)
span::back (C++20)
span::operator[] (C++20)
span::data (C++20)
Iterators
span::beginspan::cbegin (C++20)(C++23)
span::endspan::cend (C++20)(C++23)
span::rbeginspan::crbegin (C++20)(C++23)
span::rendspan::crend (C++20)(C++23)
Observers
span::empty (C++20)
span::size (C++20)
span::size_bytes (C++20)
Subviews
span::first (C++20)
span::last (C++20)
span::subspan (C++20)
Non-member functions
as_bytesas_writable_bytes (C++20)(C++20)
Non-member constant
dynamic_extent (C++20)
Deduction guides(C++20)

initializer_list (C++11)	creates a temporary array in list-initialization and then references it (class template)
basic_string_view (C++17)	read-only string view (class template)
mdspan (C++23)	a multi-dimensional non-owning array view (class template)
ranges::subrange (C++20)	combines an iterator-sentinel pair into a `view` (class template)

std::span

Template parameters

Member types

Member constant

Member functions

Iterators

Element access

Observers

Subviews