caution

Note, this article is not finished! You can help by editing this doc page.

Span class reference

Overview

Simplified

template< class T, /* ... */ >
class span;

Detailed

template<
    class T,
    std::size_t Extent = std::dynamic_extent
> class span;

std::span is a view over a dynamic or static contiguous container.

Memory

important

This section requires improvement. You can help by editing this doc page.

Technical details

Technical details

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
  • a typical implementation may have only one member - a pointer to T

• dynamic extent, in which case:

  • the number of elements is not known at compile-time and can change at runtime
  • a typical implementation holds two members - a pointer to T and a size

Named requirements

std::span meets the requirements of:

• TriviallyCopyable (since C++23)
  • note

    Specializations of std::span are already trivially copyable types in all existing implementations, even before the formal requirement introduced in C++23.

Feature testing macros

important

This section requires improvement. You can help by editing this doc page.

std::span

Defined in

span

Template parameters

pub	T	Type of the elements.
pub	Extent	Number of elements in the container or std::dynamic_extent if dynamic.

Type names

pub	element_type	T
pub	value_type	std::remove_cv_t<T>
pub	size_type	Unsigned integer type (usually std::size_t)
pub	difference_type	Signed integer type (usually std::ptrdiff_t)
pub	pointer	T*
pub	const_pointer	const T*
pub	reference	T&
pub	const_reference	T const&
pub	iterator	Implementation-defined LegacyRandomAccessIterator, ConstexprIterator and contiguous_iterator to value_type.
pub	reverse_iterator	std::reverse_iterator<iterator>

Member functions

pub	(constructors)	Constructs a span.
pub	(destructor)	Destroys the span.
pub	operator=	Assigns values to the container.

Element access

pub	front	Returns the first element.
pub	back	Returns the last element.
pub	operator[]	Accesses a specified element.
pub	data	Returns a pointer to the first element of the underlying array.

Iterators

pub	begin	Returns an iterator/const_iterator to the beginning.
pub	end	Returns an iterator/const_iterator to the end.
pub	rbegin	Returns a reverse iterator/const_iterator to the beginning.
pub	rend	Returns a reverse iterator/const_iterator to the end.

Observers

pub	size	Returns the number of elements.
pub	size_bytes	Returns the maximum possible number of elements.
pub	empty	Returns true if the span is empty, otherwise false.

Subviews

pub	first	Clears the contents.
pub	last	Inserts elements.
pub	subspan	Removes elements.

Constants

static constexpr std::size_t extent = Extent;

Non-member functions

pub

as_bytes as_writable_bytes

Lexicographically compares the values in the span.

Non-member constants

pub

std::dynamic_extent

A constant of type std::size_t signifying that the span has dynamic extent.

Helper templates

since C++20

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.

since C++20

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

Click to expand

Deduction guides

// (1)
template <class It, class EndOrSize>
span(It, EndOrSize) -> span<std::remove_reference_t<std::iter_reference_t<It>>>;

(1) allows the element type to be deduced from the iterator-sentinel pair.

// (2)
template<class T, std::size_t N>
span(T (&)[N]) -> span<T, N>;

// (3)
template<class T, std::size_t N>
span(std::array<T, N>&) -> span<T, N>;

// (4)
template<class T, std::size_t N>
span(const std::array<T, N>&) -> span<const T, N>;

(2 - 4) allows the static extent to be deduced from built-in arrays and std::array

// (5)
template<class R>
span(R&&) -> span<std::remove_reference_t<std::ranges::range_reference_t<R>>>;

(5) allow the element type to be deduced from ranges.

Overload resolution

In order for any of the deduction guides to participate in overload resolution, the folllowing requirements must be met:

• for (1), It satisfies contiguous_iterator
• for (5), R satisfies contiguous_range

Examples

important

This section requires improvement. You can help by editing this doc page.