Namespaces
Variants
    Actions

      std::span

      From cppreference.com
      < cpp‎ | container
       
      C++
       
      Containers library
       
      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.

      For a spans, 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)

      Contents

      [edit]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

      [edit]Nested types

      Type Definition
      element_typeT
      value_typestd::remove_cv_t<T>
      size_typestd::size_t
      difference_typestd::ptrdiff_t
      pointerT*
      const_pointerconst T*
      referenceT&
      const_referenceconst T&
      iterator[1] implementation-defined LegacyRandomAccessIterator, ConstexprIterator, and contiguous_iterator whose value_type is value_type
      const_iterator(since C++23)std::const_iterator<iterator>
      reverse_iteratorstd::reverse_iterator<iterator>
      const_reverse_iterator(since C++23)std::const_iterator<reverse_iterator>
      1. ↑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.

      [edit]Data members

      Member Description
      constexprstd::size_t extent
      [static]
      		Extent
      (public static member constant)
      pointerdata_ a pointer to the underlying sequence
      (exposition-only member object*)
      size_typesize_
      (present only if the extent is dynamic )      		 the number of elements
      (exposition-only member object*)

      [edit]Member functions

      		 constructs a span
      (public member function)[edit]
      		 assigns a span
      (public member function)[edit]
      (destructor)
      (implicitly declared)
      		 destructs a span
      (public member function)
      Iterators
      (C++23)
      		 returns an iterator to the beginning
      (public member function)[edit]
      (C++23)
      		 returns an iterator to the end
      (public member function)[edit]
      (C++23)
      		 returns a reverse iterator to the beginning
      (public member function)[edit]
      (C++23)
      		 returns a reverse iterator to the end
      (public member function)[edit]
      Element access
      		access the first element
      (public member function)[edit]
      		 access the last element
      (public member function)[edit]
      (C++26)
      		 access specified element with bounds checking
      (public member function)[edit]
      		 access specified element
      (public member function)[edit]
      		 direct access to the underlying contiguous storage
      (public member function)[edit]
      Observers
      		returns the number of elements
      (public member function)[edit]
      		 returns the size of the sequence in bytes
      (public member function)[edit]
      		 checks if the sequence is empty
      (public member function)[edit]
      Subviews
      		obtains a subspan consisting of the first N elements of the sequence
      (public member function)[edit]
      		 obtains a subspan consisting of the last N elements of the sequence
      (public member function)[edit]
      		 obtains a subspan
      (public member function)[edit]

      [edit]Non-member functions

      (C++20)
      		 converts a span into a view of its underlying bytes
      (function template)[edit]

      [edit]Helper constant

      (C++20)
      		 a constant of type std::size_t signifying that the span has dynamic extent
      (constant)[edit]

      [edit]Helper templates

      template<class T, std::size_t Extent >
      constexprboolranges::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 >
      constexprboolranges::enable_view<std::span<T, Extent>>=true;
      		(since C++20)

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

      [edit]Deduction guides

      [edit]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 ValueStdFeature
      __cpp_lib_span202002L(C++20)std::span
      202311L(C++26)std::span::at
      __cpp_lib_span_initializer_list202311L(C++26)Constructing std::span from a std::initializer_list

      [edit]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]]constexprauto 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>constexprbool 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>constexprbool 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>constexprbool contains(std::span<T, N> span, std::span<T, M> sub){return std::ranges::search(span, sub).begin()!= span.end();}   void println(constauto& seq){for(constauto& elem : seq)std::cout<< elem <<' ';std::cout<<'\n';}   int main(){constexprint a[]{0, 1, 2, 3, 4, 5, 6, 7, 8};constexprint b[]{8, 7, 6};constexprstaticstd::size_t width{6};   for(std::size_t offset{};;++offset)if(auto s = slide(std::span{a}, offset, width);!s.empty()) println(s);elsebreak;   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

      [edit]Defect reports

      The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

      DR Applied to Behavior as published Correct behavior
      LWG 3203C++20 it was unclear when the pointers, iterators, and
      references to elements of span are invalidated       		made clear
      LWG 3903C++20 the declaration of span's destructor was unnecessary removed the declaration
      P2325R3C++20 a span of non-zero static extents was not a viewany span is a view

      [edit]See also

      (C++23)
      		 a multi-dimensional non-owning array view
      (class template)[edit]
      (C++20)
      		 combines an iterator-sentinel pair into a view
      (class template)[edit]
      (C++11)
      		 references a temporary array created in list-initialization
      (class template)[edit]
      (C++17)
      		 read-only string view
      (class template)[edit]
      Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/container/span&oldid=182285"
      close