Skip to main content
caution

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

Span class reference

Overview

template< class T, /* ... */ >
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 inspan

Template parameters

pubT

Type of the elements.

pubExtent

Number of elements in the container or std::dynamic_extent if dynamic.

Type names

pubelement_typeT
pubvalue_typestd::remove_cv_t<T>
pubsize_typeUnsigned integer type (usually std::size_t)
pubdifference_typeSigned integer type (usually std::ptrdiff_t)
pubpointerT*
pubconst_pointerconst T*
pubreferenceT&
pubconst_referenceT const&
pubiterator

Implementation-defined LegacyRandomAccessIterator, ConstexprIterator and contiguous_iterator to value_type.

pubreverse_iteratorstd::reverse_iterator<iterator>

Member functions

pub(constructors)

Constructs a span.

pub(destructor)

Destroys the span.

puboperator=

Assigns values to the container.

Element access

pubfront

Returns the first element.

pubback

Returns the last element.

puboperator[]

Accesses a specified element.

pubdata

Returns a pointer to the first element of the underlying array.

Iterators

pubbegin

Returns an iterator/const_iterator to the beginning.

pubend

Returns an iterator/const_iterator to the end.

pubrbegin

Returns a reverse iterator/const_iterator to the beginning.

pubrend

Returns a reverse iterator/const_iterator to the end.

Observers

pubsize

Returns the number of elements.

pubsize_bytes

Returns the maximum possible number of elements.

pubempty

Returns true if the span is empty, otherwise false.

Subviews

pubfirst

Clears the contents.

publast

Inserts elements.

pubsubspan

Removes elements.

Constants

static constexpr std::size_t extent = Extent;

Non-member functions

pubas_bytes
as_writable_bytes

Lexicographically compares the values in the span.

Non-member constants

pubstd::dynamic_extent

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

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 (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:

Examples

important

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

This article originates from this CppReference page. It was likely altered for improvements or editors' preference. Click "Edit this page" to see all changes made to this document.
Hover to see the original license.
caution

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

Span class reference

Overview

template< class T, /* ... */ >
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 inspan

Template parameters

pubT

Type of the elements.

pubExtent

Number of elements in the container or std::dynamic_extent if dynamic.

Type names

pubelement_typeT
pubvalue_typestd::remove_cv_t<T>
pubsize_typeUnsigned integer type (usually std::size_t)
pubdifference_typeSigned integer type (usually std::ptrdiff_t)
pubpointerT*
pubconst_pointerconst T*
pubreferenceT&
pubconst_referenceT const&
pubiterator

Implementation-defined LegacyRandomAccessIterator, ConstexprIterator and contiguous_iterator to value_type.

pubreverse_iteratorstd::reverse_iterator<iterator>

Member functions

pub(constructors)

Constructs a span.

pub(destructor)

Destroys the span.

puboperator=

Assigns values to the container.

Element access

pubfront

Returns the first element.

pubback

Returns the last element.

puboperator[]

Accesses a specified element.

pubdata

Returns a pointer to the first element of the underlying array.

Iterators

pubbegin

Returns an iterator/const_iterator to the beginning.

pubend

Returns an iterator/const_iterator to the end.

pubrbegin

Returns a reverse iterator/const_iterator to the beginning.

pubrend

Returns a reverse iterator/const_iterator to the end.

Observers

pubsize

Returns the number of elements.

pubsize_bytes

Returns the maximum possible number of elements.

pubempty

Returns true if the span is empty, otherwise false.

Subviews

pubfirst

Clears the contents.

publast

Inserts elements.

pubsubspan

Removes elements.

Constants

static constexpr std::size_t extent = Extent;

Non-member functions

pubas_bytes
as_writable_bytes

Lexicographically compares the values in the span.

Non-member constants

pubstd::dynamic_extent

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

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 (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:

Examples

important

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

This article originates from this CppReference page. It was likely altered for improvements or editors' preference. Click "Edit this page" to see all changes made to this document.
Hover to see the original license.