home | help 
std::mdspan(3)		       C++ Standard Libary		  std::mdspan(3)

NAME
     std::mdspan - std::mdspan

Synopsis
	Defined in header <mdspan>
	template<

	    class T,
	    class Extents,				     (since C++23)
	    class LayoutPolicy = std::layout_right,
	    class AccessorPolicy = std::default_accessor<T>

	> class mdspan;

	std::mdspan  is  a view into a contiguous sequence of objects that rein-
     terprets it as
	a multidimensional array.

	Each specialization MDS of mdspan models copyable and satisfies:

	  * std::is_nothrow_move_constructible_v<MDS> is true,
	  * std::is_nothrow_move_assignable_v<MDS> is true, and
	  * std::is_nothrow_swappable_v<MDS> is true.

	A specialization of mdspan is a TriviallyCopyable  type  if  its  acces-
     sor_type,
	mapping_type and data_handle_type are TriviallyCopyable types.

Template parameters
	T	       - element type; a complete object type that is neither an
     abstract
			 class type nor an array type.
	Extents 	- specifies number of dimensions, their sizes, and which
     are known at
			 compile time. Must be a specialization of std::extents.
	LayoutPolicy   - specifies how to convert multidimensional index to  un-
     derlying 1D
			 index	(column-major  3D array, symmetric triangular 2D
     matrix, etc).
			 specifies how to convert underlying 1D index to a  ref-
     erence to T.
	AccessorPolicy	-  Must  satisfy  the  constraint that std::is_same_v<T,
     typename
			 AccessorPolicy::element_type> is true.

	 This section is incomplete
	 Reason: add the requirement of layout policy and accessor policy.

Member types
	Member type	 Definition
	extents_type	 Extents
	layout_type	 LayoutPolicy
	accessor_type	 AccessorPolicy
	mapping_type	 LayoutPolicy::mapping<Extents>
	element_type	 T
	value_type	 std::remove_cv_t<T>
	index_type	 Extents::index_type
	size_type	 Extents::size_type
	rank_type	 Extents::rank_type
	data_handle_type AccessorPolicy::data_handle_type
	reference	 AccessorPolicy::reference

Member objects
	Member name    Definition
	acc_ (private) The accessor of type accessor_type
		       (exposition-only member object*)
	map_ (private) The layout mapping of type mapping_type
		       (exposition-only member object*)
	ptr_ (private) The underlying data handle of type data_handle_type
		       (exposition-only member object*)

Member functions
	constructor	     constructs an mdspan
			     (public member function)
	operator=	     assigns an mdspan
			     (public member function)

Element access
	operator[]	     accesses an element at  the  specified  multidimen-
     sional index
			     (public member function)

Observers
	size		      returns  the  size  of  the multidimensional index
     space
			     (public member function)
	empty		     checks if the size of the index space is zero
			     (public member function)
	stride		     obtains the stride along the specified dimension
			     (public member function)
	extents 	     obtains the extents object
			     (public member function)
	data_handle	     obtains the pointer to the underlying 1D sequence
			     (public member function)
	mapping 	     obtains the mapping object
			     (public member function)
	accessor	     obtains the accessor policy object
			     (public member function)
			     determines  if  this  mdspan's  mapping  is  unique
     (every
	is_unique	     combination of indices maps to a different underly-
     ing element)
			     (public member function)
			     determines  if  this mdspan's mapping is exhaustive
     (every
	is_exhaustive	     underlying element can be accessed with some combi-
     nation of
			     indices)
			     (public member function)
			     determines if this mdspan's mapping is strided  (in
     each
	is_strided	      dimension,  incrementing	an  index jumps over the
     same number of
			     underlying elements every time)
			     (public member function)
	is_always_unique     determines if this mdspan's layout mapping  is  al-
     ways unique
	[static]	     (public static member function)
	is_always_exhaustive  determines  if this mdspan's layout mapping is al-
     ways exhaustive
	[static]	     (public static member function)
	is_always_strided    determines if this mdspan's layout mapping  is  al-
     ways strided
	[static]	     (public static member function)

Non-member functions
	std::swap(std::mdspan) specializes the std::swap algorithm for mdspan
	(C++23) 	       (function template)
	      Subviews
	submdspan_extents      creates new extents from the existing extents and
     slice
	(C++26) 	       specifiers
			       (function template)
	submdspan	       returns a view of a subset of an existing mdspan
	(C++26) 	       (function template)

	Helper types and templates

	extents 		  a descriptor of a multidimensional index space
     of some rank
	(C++23) 		 (class template)
	dextents		 convenience alias template for  an  all-dynamic
     std::extents
	(C++23) 		 (alias template)
	layout_right		 row-major multidimensional array layout mapping
     policy;
	(C++23) 		 rightmost extent has stride 1
				 (class)
	layout_left		 column-major multidimensional array layout map-
     ping policy;
	(C++23) 		 leftmost extent has stride 1
				 (class)
	layout_stride		  a  layout  mapping  policy  with  user-defined
     strides
	(C++23) 		 (class)
	default_accessor	 a type for indexed access to elements of mdspan
	(C++23) 		 (class template)
	      Subviews helpers
	full_extent		 a slice specifier tag describing full range  of
     indices in
	full_extent_t		 the specified extent
	(C++26) 		 (tag)
	strided_slice		  a  slice specifier representing a set of regu-
     larly spaced
	(C++26) 		 indices as indicated by an offset,  an  extent,
     and a stride
				 (class template)
	submdspan_mapping_result   a  return  type  of	the  overloads	of  sub-
     mdspan_mapping
	(C++26) 		 (class template)

	Deduction guides

Notes
	Feature-test macro   Value    Std      Feature
	__cpp_lib_mdspan    202207L (C++23) std::mdspan
	__cpp_lib_submdspan 202306L (C++26) std::submdspan

Example
	Can be previewed on Compiler Explorer.

     // Run this code

      #include <cstddef>
      #include <mdspan>
      #include <print>
      #include <vector>

      int main()
      {
	  std::vector v{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12};

	  // View data as contiguous memory representing 2 rows of 6 ints each
	  auto ms2 = std::mdspan(v.data(), 2, 6);
	  // View the same data as a 3D array 2 x 3 x 2
	  auto ms3 = std::mdspan(v.data(), 2, 3, 2);

	  // Write data using 2D view
	  for (std::size_t i = 0; i != ms2.extent(0); i++)
	      for (std::size_t j = 0; j != ms2.extent(1); j++)
		  ms2[i, j] = i * 1000 + j;

	  // Read back using 3D view
	  for (std::size_t i = 0; i != ms3.extent(0); i++)
	  {
	      std::println("slice @ i = {}", i);
	      for (std::size_t j = 0; j != ms3.extent(1); j++)
	      {
		  for (std::size_t k = 0; k != ms3.extent(2); k++)
		      std::print("{} ", ms3[i, j, k]);
		  std::println("");
	      }
	  }
      }

Output:
      slice @ i = 0
      0 1
      2 3
      4 5
      slice @ i = 1
      1000 1001
      1002 1003
      1004 1005

See also
	span	 a non-owning view over a contiguous sequence of objects
	(C++20)  (class template)
	valarray numeric arrays, array masks and array slices
		 (class template)

Category:
	  * Todo with reason

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