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)