std::span<T,Extent>::span

From cppreference.com
< cpp‎ | container‎ | span
 
C++
 
Containers library
 
std::span
 
constexpr span() noexcept;
 (1) (since C++20)
template< class It >

explicit(extent != std::dynamic_extent)

constexpr span( It first, size_type count );
 (2) (since C++20)
template< class It, class End >

explicit(extent != std::dynamic_extent)

constexpr span( It first, End last );
 (3) (since C++20)
template< std::size_t N >
constexpr span( std::type_identity_t<element_type> (&arr)[N] ) noexcept;
 (4) (since C++20)
template< class U, std::size_t N >
constexpr span( std::array<U, N>& arr ) noexcept;
 (5) (since C++20)
template< class U, std::size_t N >
constexpr span( const std::array<U, N>& arr ) noexcept;
 (6) (since C++20)
template< class R >

explicit(extent != std::dynamic_extent)

constexpr span( R&& range );
 (7) (since C++20)
explicit(extent != std::dynamic_extent)
constexpr span( std::initializer_list<value_type> il ) noexcept;
 (8) (since C++26)
template< class U, std::size_t N >

explicit(extent != std::dynamic_extent && N == std::dynamic_extent)

constexpr span( const std::span<U, N>& source ) noexcept;
 (9) (since C++20)
constexpr span( const span& other ) noexcept = default;
 (10) (since C++20)

Constructs a span.

1) Constructs an empty span whose data() == nullptr and size() == 0.
  • This overload participates in overload resolution only if extent == 0 || extent == std::dynamic_extent.
2) Constructs a span that is a view over the range [first, first + count); the resulting span has data() == std::to_address(first) and size() == count.
  • The behavior is undefined if [first, first + count) is not a valid range, if It does not actually model contiguous_iterator, or if extent != std::dynamic_extent && count != extent.
  • This overload participates in overload resolution only if
3) Constructs a span that is a view over the range [first, last); the resulting span has data() == std::to_address(first) and size() == last-first.
  • The behavior is undefined if [first, last) is not a valid range, if It does not actually model contiguous_iterator, if End does not actually model sized_sentinel_for for It, or if extent != std::dynamic_extent && last-first != extent.
  • This overload participates in overload resolution only if
4-6) Constructs a span that is a view over the array arr; the resulting span has size() == N and data() == std::data(arr).
  • These overloads participate in overload resolution only if extent == std::dynamic_extent || N == extent is true and the conversion from std::remove_pointer_t<decltype(data(arr))> to element_type is at most a qualification conversion.
7) Constructs a span that is a view over the range range; the resulting span has size() == std::ranges::size(range) and data() == std::ranges::data(range).
  • The behavior is undefined if R does not actually model contiguous_range and sized_range or if R does not model borrowed_range while element_type is non-const or both extent != dynamic_extent and std::ranges::size(range) != extent are true.
  • This overload participates in overload resolution only if
8) Constructs a span that is a view over the initializer list il; the resulting span has size() == il.size() and data() == il.begin().
  • The behavior is undefined if both extent != dynamic_extent and il.size() != extent are true.
  • This overload participates in overload resolution only if std::is_const_v<element_type> is true.
9) Converting constructor from another span source; the resulting span has size() == source.size() and data() == source.data().
  • The behavior is undefined if both extent != dynamic_extent and source.size() != extent are true.
  • This overload participates in overload resolution only if at least one of extent == std::dynamic_extent, N == std::dynamic_extent and N == extent is true and the conversion from U to element_type is at most a qualification conversion.
10) Defaulted copy constructor copies the size and data pointer; the resulting span has size() == other.size() and data() == other.data().

Parameters

first - iterator to the first element of the sequence
count - number of elements in the sequence
last - iterator past the last element of the sequence or another sentinel
arr - array to construct a view for
range - range to construct a view for
source - another span to convert from
other - another span to copy from

Exceptions

2) Throws nothing.
3) Throws what and when last - first throws.
7) Throws what and when std::ranges::size(r) and std::ranges::data(r) throw.

Notes

Feature-test macro Value Std Feature
__cpp_lib_span_initializer_list 202311L (C++26) Constructing std::span from a std::initializer_list, (8)

Example

Run this code
#include <array>
#include <iostream>
#include <span>
#include <vector>
 
void print_span(std::span<const int> s)
{
    for (int n : s)
        std::cout << n << ' ';
    std::cout << '\n';
}
 
int main()
{
    int c[]{1, 2, 3};
    print_span(c); // constructs from array
 
    std::array a{4, 5, 6};
    print_span(a); // constructs from std::array
 
    std::vector v{7, 8, 9};
    print_span(v); // constructs from std::vector
 
#if __cpp_lib_span_initializer_list
    print_span({0, 1, 2}); // constructs from initializer_list
#else
    print_span({{0, 1, 2}}); // ditto, a workaround
#endif
}

Output: 

1 2 3 
4 5 6
7 8 9
0 1 2

See also

 direct access to the underlying contiguous storage
(public member function)
returns the number of elements
(public member function)
assigns a span
(public member function)
(C++17)(C++20)
 returns the size of a container or array
(function template)
(C++17)
 obtains the pointer to the underlying array
(function template)
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/container/span/span&oldid=167798"