home | help 
std::span(3)		       C++ Standard Libary		    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 contigu-
     ous 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 ab-
     stract 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  LegacyRandomAcces-
     sIterator,
	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 iter-
     ator 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  ele-
     ments of the
	first		      sequence
			      (public member function)
			      obtains  a  subspan  consisting of the last N ele-
     ments 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	retroac-
     tively 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)

http://cppreference.com 	   2024.06.10			    std::span(3)
home | help