Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/container/mdspan"

From cppreference.com
< cpp‎ | container
m (adding data member of the typical implementation(as in the synopsis), for the convenience of exposition)
m (fmt. The order of sections in this page is optimal, IMO: Template parameters => Member types => Data members ... Maybe it worth to apply this order to views too)
Line 3: Line 3:
 
{{dcl begin}}
 
{{dcl begin}}
 
{{dcl header|mdspan}}
 
{{dcl header|mdspan}}
−
{{dcl | since=c++23 |1=
+
{{dcl|since=c++23|1=
 
template<
 
template<
 
     class T,
 
     class T,
Line 10: Line 10:
 
     class AccessorPolicy = std::default_accessor<T>
 
     class AccessorPolicy = std::default_accessor<T>
 
> class mdspan;
 
> class mdspan;
−
}}  
+
}}
 
{{dcl end}}
 
{{dcl end}}
  
Line 17: Line 17:
 
===Template parameters===
 
===Template parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | T | element type; a complete object type that is neither an abstract class type nor an array type,}}
+
{{par|T|element type; a complete object type that is neither an abstract class type nor an array type,}}
−
{{par | Extents | specifies number of dimensions, their sizes, and which are known at compile time. Must be a specialization of {{lc|std::extents}}}}
+
{{par|Extents|specifies number of dimensions, their sizes, and which are known at compile time. Must be a specialization of {{lc|std::extents}}}}
−
{{par | LayoutPolicy | specifies how to convert multidimensional index to underlying 1D index (column-major 3D array, symmetric triangular 2D matrix, etc) }}
+
{{par|LayoutPolicy|specifies how to convert multidimensional index to underlying 1D index (column-major 3D array, symmetric triangular 2D matrix, etc)}}
−
{{par | AccessorPolicy | specifies how to convert underlying 1D index to a reference to T }}
+
{{par|AccessorPolicy|specifies how to convert underlying 1D index to a reference to T}}
 
{{par end}}
 
{{par end}}
  
 
===Member types===
 
===Member types===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc hitem | Member type | Definition}}
+
{{dsc hitem|Member type|Definition}}
−
{{dsc | {{tt|extents_type}} | {{tt|Extents}} }}
+
{{dsc|{{tt|extents_type}}|{{tt|Extents}}}}
−
{{dsc | {{tt|layout_type}} | {{tt|LayoutPolicy}} }}
+
{{dsc|{{tt|layout_type}}|{{tt|LayoutPolicy}}}}
−
{{dsc | {{tt|accessor_type}} | {{tt|AccessorPolicy}} }}
+
{{dsc|{{tt|accessor_type}}|{{tt|AccessorPolicy}}}}
−
{{dsc | {{tt|mapping_type}} | {{tt|LayoutPolicy::mapping<Extents>}} }}
+
{{dsc|{{tt|mapping_type}}|{{tt|LayoutPolicy::mapping<Extents>}}}}
−
{{dsc | {{tt|element_type}} | {{tt|T}} }}
+
{{dsc|{{tt|element_type}}|{{tt|T}}}}
−
{{dsc | {{tt|value_type}} | {{tt|std::remove_cv_t<T>}} }}
+
{{dsc|{{tt|value_type}}|{{tt|std::remove_cv_t<T>}}}}
−
{{dsc | {{tt|index_type}} | {{tt|Extents::index_type}} }}
+
{{dsc|{{tt|index_type}}|{{tt|Extents::index_type}}}}
−
{{dsc | {{tt|size_type}} | {{tt|Extents::size_type}} }}
+
{{dsc|{{tt|size_type}}|{{tt|Extents::size_type}}}}
−
{{dsc | {{tt|rank_type}} | {{tt|Extents::rank_type}} }}
+
{{dsc|{{tt|rank_type}}|{{tt|Extents::rank_type}}}}
−
{{dsc | {{tt|data_handle_type}} | {{tt|AccessorPolicy::data_handle_type}} }}
+
{{dsc|{{tt|data_handle_type}}|{{tt|AccessorPolicy::data_handle_type}}}}
−
{{dsc | {{tt|reference}} | {{tt|AccessorPolicy::reference}} }}
+
{{dsc|{{tt|reference}}|{{tt|AccessorPolicy::reference}}}}
 
{{dsc end}}
 
{{dsc end}}
  
Line 42: Line 42:
 
Typical implementations of {{tt|mdspan}} hold only three non-static data member:
 
Typical implementations of {{tt|mdspan}} hold only three non-static data member:
  
−
* an accessor of type {{tt|accessor_type}} (shown here as {{tt|''acc_'' }} for exposition only).
+
* An accessor of type {{tt|accessor_type}} (shown here as {{tti|acc_}} for exposition only).
−
* a layout mapping of type {{tt|mappint_type}} (shown here as {{tt|''map_''}} for exposition only).
+
* A layout mapping of type {{tt|mappint_type}} (shown here as {{tti|map_}} for exposition only).
−
* a underlying data handle of type {{tt|data_handle_type}} (shown here as {{tt|''ptr_''}} for exposition only).  
+
* A underlying data handle of type {{tt|data_handle_type}} (shown here as {{tti|ptr_}} for exposition only).
  
 
===Member functions===
 
===Member functions===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/container/mdspan/dsc constructor}}
+
{{dsc inc|cpp/container/mdspan/dsc constructor}}
−
{{dsc inc | cpp/container/mdspan/dsc operator{{=}}}}
+
{{dsc inc|cpp/container/mdspan/dsc operator{{=}}}}
  
−
{{dsc h2 | Element access}}
+
{{dsc h2|Element access}}
−
{{dsc inc | cpp/container/mdspan/dsc operator_at}}
+
{{dsc inc|cpp/container/mdspan/dsc operator_at}}
  
−
{{dsc h2 | Observers}}
+
{{dsc h2|Observers}}
−
{{dsc inc | cpp/container/mdspan/dsc size}}
+
{{dsc inc|cpp/container/mdspan/dsc size}}
−
{{dsc inc | cpp/container/mdspan/dsc empty}}
+
{{dsc inc|cpp/container/mdspan/dsc empty}}
−
{{dsc inc | cpp/container/mdspan/dsc stride}}
+
{{dsc inc|cpp/container/mdspan/dsc stride}}
−
{{dsc inc | cpp/container/mdspan/dsc extents_mfun}} <!-- dsc extents is for std::extents -->
+
{{dsc inc|cpp/container/mdspan/dsc extents_mfun}} <!-- dsc extents is for std::extents -->
−
{{dsc inc | cpp/container/mdspan/dsc data_handle}}
+
{{dsc inc|cpp/container/mdspan/dsc data_handle}}
−
{{dsc inc | cpp/container/mdspan/dsc mapping}}
+
{{dsc inc|cpp/container/mdspan/dsc mapping}}
−
{{dsc inc | cpp/container/mdspan/dsc accessor}}
+
{{dsc inc|cpp/container/mdspan/dsc accessor}}
  
−
{{dsc inc | cpp/container/mdspan/dsc is_unique}}
+
{{dsc inc|cpp/container/mdspan/dsc is_unique}}
−
{{dsc inc | cpp/container/mdspan/dsc is_exhaustive}}
+
{{dsc inc|cpp/container/mdspan/dsc is_exhaustive}}
−
{{dsc inc | cpp/container/mdspan/dsc is_strided}}
+
{{dsc inc|cpp/container/mdspan/dsc is_strided}}
−
{{dsc inc | cpp/container/mdspan/dsc is_always_unique}}
+
{{dsc inc|cpp/container/mdspan/dsc is_always_unique}}
−
{{dsc inc | cpp/container/mdspan/dsc is_always_exhaustive}}
+
{{dsc inc|cpp/container/mdspan/dsc is_always_exhaustive}}
−
{{dsc inc | cpp/container/mdspan/dsc is_always_strided}}
+
{{dsc inc|cpp/container/mdspan/dsc is_always_strided}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Non-member functions===
 
===Non-member functions===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/container/mdspan/dsc swap}}
+
{{dsc inc|cpp/container/mdspan/dsc swap}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Helper types and templates===
 
===Helper types and templates===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/container/mdspan/dsc extents}}
+
{{dsc inc|cpp/container/mdspan/dsc extents}}
−
{{dsc inc | cpp/container/mdspan/dsc dextents}}
+
{{dsc inc|cpp/container/mdspan/dsc dextents}}
−
{{dsc inc | cpp/container/mdspan/dsc layout_right}}
+
{{dsc inc|cpp/container/mdspan/dsc layout_right}}
−
{{dsc inc | cpp/container/mdspan/dsc layout_left}}
+
{{dsc inc|cpp/container/mdspan/dsc layout_left}}
−
{{dsc inc | cpp/container/mdspan/dsc layout_stride}}
+
{{dsc inc|cpp/container/mdspan/dsc layout_stride}}
 
{{dsc end}}
 
{{dsc end}}
  
Line 93: Line 93:
 
===Example===
 
===Example===
 
{{example
 
{{example
−
| can be previewed at https://godbolt.org/z/PK7bccGr3
+
|can be previewed at https://godbolt.org/z/PK7bccGr3
−
| code=
+
|code=
−
#include <vector>
+
 
#include <mdspan>
 
#include <mdspan>
 
#include <print>
 
#include <print>
 +
#include <vector>
  
 
int main()
 
int main()
 
{
 
{
−
  std::vector v = {1,2,3,4,5,6,7,8,9,10,11,12};
+
    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
+
    // View data as contiguous memory representing 2 rows of 6 ints each
−
  auto ms2 = std::mdspan(v.data(), 2, 6);
+
    auto ms2 = std::mdspan(v.data(), 2, 6);
−
  // View the same data as a 3D array 2 x 3 x 2
+
    // View the same data as a 3D array 2 x 3 x 2
−
  auto ms3 = std::mdspan(v.data(), 2, 3, 2);
+
    auto ms3 = std::mdspan(v.data(), 2, 3, 2);
  
−
  // write data using 2D view
+
    // write data using 2D view
−
  for(size_t i=0; i != ms2.extent(0); i++)
+
    for (size_t i = 0; i != ms2.extent(0); i++)
−
    for(size_t j=0; j != ms2.extent(1); j++)
+
        for (size_t j = 0; j != ms2.extent(1); j++)
−
      ms2[i, j] = i*1000 + j;
+
            ms2[i, j] = i * 1000 + j;
  
−
  // read back using 3D view
+
    // read back using 3D view
−
  for(size_t i=0; i != ms3.extent(0); i++)
+
    for (size_t i = 0; i != ms3.extent(0); i++)
−
  {
+
−
    std::println("slice @ i = {}", i);
+
−
    for(size_t j=0; j != ms3.extent(1); j++)
+
 
     {
 
     {
−
      for(size_t k=0; k != ms3.extent(2); k++)
+
        std::println("slice @ i = {}", i);
−
        std::print("{} ", ms3[i, j, k]);
+
        for (size_t j = 0; j != ms3.extent(1); j++)
−
      std::println("");
+
        {
 +
            for (size_t k = 0; k != ms3.extent(2); k++)
 +
                std::print("{} ", ms3[i, j, k]);
 +
            std::println("");
 +
        }
 
     }
 
     }
−
  }
 
 
}
 
}
−
| output=
+
|output=
 
slice @ i = 0
 
slice @ i = 0
−
0 1  
+
0 1
−
2 3  
+
2 3
−
4 5  
+
4 5
 
slice @ i = 1
 
slice @ i = 1
−
1000 1001  
+
1000 1001
−
1002 1003  
+
1002 1003
−
1004 1005  
+
1004 1005
 
}}
 
}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/container/dsc span}}
+
{{dsc inc|cpp/container/dsc span}}
−
{{dsc inc | cpp/numeric/dsc valarray}}
+
{{dsc inc|cpp/numeric/dsc valarray}}
 
{{dsc end}}
 
{{dsc end}}
  
 
{{langlinks|de|es|ja|ru|zh}}
 
{{langlinks|de|es|ja|ru|zh}}

Revision as of 13:45, 23 May 2023

 
C++
 
Containers library
 
std::mdspan
 
Defined in header <mdspan>
template<

    class T,
    class Extents,
    class LayoutPolicy = std::layout_right,
    class AccessorPolicy = std::default_accessor<T>

> class mdspan;
 (since C++23)

std::mdspan is a non-owning view into a contiguous sequence of objects that reinterprets it as a multidimensional array.

Contents

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 underlying 1D index (column-major 3D array, symmetric triangular 2D matrix, etc)
AccessorPolicy - specifies how to convert underlying 1D index to a reference to T

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

Data members

Typical implementations of mdspan hold only three non-static data member:

  • An accessor of type accessor_type (shown here as acc_ for exposition only).
  • A layout mapping of type mappint_type (shown here as map_ for exposition only).
  • A underlying data handle of type data_handle_type (shown here as ptr_ for exposition only).

Member functions

 constructs an mdspan
(public member function) [edit]
assigns an mdspan
(public member function) [edit]
Element access
accesses an element at the specified multidimensional index
(public member function) [edit]
Observers
returns the size of the multidimensional index space
(public member function) [edit]
checks if the size of the index space is zero
(public member function) [edit]
obtains the stride along the specified dimension
(public member function) [edit]
obtains the extents object
(public member function) [edit]
obtains the pointer to the underlying 1D sequence
(public member function) [edit]
obtains the mapping object
(public member function) [edit]
obtains the accessor policy object
(public member function) [edit]
determines if this mdspan's mapping is unique (every combination of indices maps to a different underlying element)
(public member function) [edit]
determines if this mdspan's mapping is exhaustive (every underlying element can be accessed with some combination of indices)
(public member function) [edit]
determines if this mdspan's mapping is strided (in each dimension, incrementing an index jumps over the same number of underlying elements every time)
(public member function) [edit]
[static]
 determines if this mdspan's layout mapping is always unique
(public static member function) [edit]
[static]
 determines if this mdspan's layout mapping is always exhaustive
(public static member function) [edit]
[static]
 determines if this mdspan's layout mapping is always strided
(public static member function) [edit]

Non-member functions

(C++23)
 specializes the std::swap algorithm for mdspan
(function template) [edit]

Helper types and templates

(C++23)
 a descriptor of a multidimensional index space of some rank
(class template) [edit]
(C++23)(C++26)
 convenience alias template for an all-dynamic std::extents
(alias template)[edit]
(C++23)
 row-major multidimensional array layout mapping policy; rightmost extent has stride 1
(class) [edit]
(C++23)
 column-major multidimensional array layout mapping policy; leftmost extent has stride 1
(class) [edit]
(C++23)
 a layout mapping policy with user-defined strides
(class) [edit]

Deduction guides

Notes

Feature-test macro Value Std Feature
__cpp_lib_mdspan 202207L (C++23) std::mdspan

Example

can be previewed at https://godbolt.org/z/PK7bccGr3

Run this code
#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 (size_t i = 0; i != ms2.extent(0); i++)
        for (size_t j = 0; j != ms2.extent(1); j++)
            ms2[i, j] = i * 1000 + j;
 
    // read back using 3D view
    for (size_t i = 0; i != ms3.extent(0); i++)
    {
        std::println("slice @ i = {}", i);
        for (size_t j = 0; j != ms3.extent(1); j++)
        {
            for (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

(C++20)
 a non-owning view over a contiguous sequence of objects
(class template) [edit]
numeric arrays, array masks and array slices
(class template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/container/mdspan&oldid=152041"