{"id":8208,"date":"2023-09-11T18:26:22","date_gmt":"2023-09-11T18:26:22","guid":{"rendered":"https:\/\/www.modernescpp.com\/?p=8208"},"modified":"2023-09-13T18:41:12","modified_gmt":"2023-09-13T18:41:12","slug":"c23-a-multidimensional-view","status":"publish","type":"post","link":"https:\/\/www.modernescpp.com\/index.php\/c23-a-multidimensional-view\/","title":{"rendered":"C++23: A Multidimensional View"},"content":{"rendered":"\n

A std::mdspan<\/code> is a non-owning multidimensional view of a contiguous sequence of objects. The contiguous sequence of objects can be a plain C-array, a pointer with a size, a std::array<\/code>, a std::vector<\/code>, or a std::string<\/code>.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Often, this multidimensional view is called a multidimensional array.<\/p>\n\n\n\n

The number of dimensions and the size of each dimension determine the shape of the multidimensional array. The number of dimensions is called rank, and the size of each dimension extension. The size of the std::mdspan<\/code> is the product of all dimensions that are not 0. You can access the elements of a std::mdspan<\/code> using the multidimensional index operator []<\/code>.<\/p>\n\n\n\n

Each dimension of a std::mdspan<\/code> can have a static <\/em>or dynamic extent<\/em>. static extent<\/em> means that its length is specified at compile time; dynamic extent<\/em> means that its length is specified at run time.<\/p>\n\n\n\n

Here is its definition:<\/p>\n\n\n\n

template<\/span><<\/span>\n    class<\/span> T<\/span>,\n    class<\/span> Extents<\/span>,\n    class<\/span> LayoutPolicy<\/span> =<\/span> std::<\/span>layout_right,\n    class<\/span> AccessorPolicy<\/span> =<\/span> std::<\/span>default_accessor<<\/span>T><\/span>\n><\/span> class<\/span> mdspan<\/span>;\n<\/pre><\/div>\n\n\n\n
    \n
  •  T<\/code>: the contiguous sequence of objects<\/li>\n\n\n\n
  • Extents<\/code>: specifies the number of dimensions as their size; each dimension can have a static extent<\/em> or a dynamic extent<\/em><\/li>\n\n\n\n
  • LayoutPolicy<\/code>: specifies the layout policy to access the underlying memory<\/li>\n\n\n\n
  • AccessorPolicy<\/code>: specifies how the underlying elements are referenced<\/li>\n<\/ul>\n\n\n\n
    Thanks to class template argument deduction (CTAG) in C++17, the compiler can often automatically deduce the template arguments from the types of initializers:<\/p>\n\n\n\n
    \/\/ mdspan.cpp<\/span>\n\n#include <mdspan><\/span>\n#include <iostream><\/span>\n#include <vector><\/span>\n\nint<\/span> main<\/span>() {\n    \n    std::<\/span>vector myVec{1<\/span>, 2<\/span>, 3<\/span>, 4<\/span>, 5<\/span>, 6<\/span>, 7<\/span>, 8<\/span>};          \/\/ (1)<\/span>\n\n    std::<\/span>mdspan m{myVec.data(), 2<\/span>, 4<\/span>};                  \/\/ (2)<\/span>\n    std::<\/span>cout <<<\/span> "m.rank(): "<\/span> <<<\/span> m.rank() <<<\/span> '\\n'<\/span>;      \/\/ (4)<\/span>\n\n    for<\/span> (std::<\/span>size_t<\/span> i =<\/span> 0<\/span>; i <<\/span> m.extent(0<\/span>); ++<\/span>i) {     \/\/ (6)<\/span>\n        for<\/span> (std::<\/span>size_t<\/span> j =<\/span> 0<\/span>; j <<\/span> m.extent(1<\/span>); ++<\/span>j) { \/\/ (7)<\/span>\n            std::<\/span>cout <<<\/span> m[i, j] <<<\/span> ' '<\/span>;                \/\/ (8)<\/span>\n        }\n        std::<\/span>cout <<<\/span> '\\n'<\/span>;\n    }\n\n    std::<\/span>cout <<<\/span> '\\n'<\/span>;\n\n    std::<\/span>mdspan m2{myVec.data(), 4<\/span>, 2<\/span>};                 \/\/ (3)<\/span>\n    std::<\/span>cout <<<\/span> "m2.rank(): "<\/span> <<<\/span> m2.rank() <<<\/span> '\\n'<\/span>;    \/\/ (5)<\/span>\n\n    for<\/span> (std::<\/span>size_t<\/span> i =<\/span> 0<\/span>; i <<\/span> m2.extent(0<\/span>); ++<\/span>i) {\n        for<\/span> (std::<\/span>size_t<\/span> j =<\/span> 0<\/span>; j <<\/span> m2.extent(1<\/span>); ++<\/span>j) {\n        std::<\/span>cout <<<\/span> m2[i, j] <<<\/span> ' '<\/span>;  \n    }\n    std::<\/span>cout <<<\/span> '\\n'<\/span>;\n  }\n\n}\n<\/pre><\/div>\n\n\n\n
    I apply class template argument deduction three times in this example. Line (1) uses it for a std::vector<\/code>, and lines (2) and (3) for a std::mdspan<\/code>. The first 2-dimensional array m <\/code>has a shape of (2, 4), the second one m2 <\/code>a shape of (4, 2). Lines (4) and (5) display the ranks of both std::mdspan<\/code>. Thanks to the extent of each dimension (lines 6 and 7) and the index operator in line (8), it is straightforward to iterate through multidimensional arrays.<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    If your multidimensional array should have a static extent<\/em>, you have to specify the template arguments.<\/p>\n\n\n\n
    \/\/ staticDynamicExtent.cpp<\/span>\n\n#include <mdspan><\/span>\n#include <iostream><\/span>\n#include <string><\/span>\n#include <vector><\/span>\n#include <tuple><\/span>\n\nint<\/span> main<\/span>() {\n    \n    std::<\/span>vector myVec{1<\/span>, 2<\/span>, 3<\/span>, 4<\/span>, 5<\/span>, 6<\/span>, 7<\/span>, 8<\/span>};\n\n    std::<\/span>mdspan<<\/span>int<\/span>, std::<\/span>extents<<\/span>std::<\/span>size_t<\/span>, 2<\/span>, 4<\/span>>><\/span> m{myVec.data()}; \/\/ (1)<\/span>\n    std::<\/span>cout <<<\/span> "m.rank(): "<\/span> <<<\/span> m.rank() <<<\/span> '\\n'<\/span>;\n\n    for<\/span> (std::<\/span>size_t<\/span> i =<\/span> 0<\/span>; i <<\/span> m.extent(0<\/span>); ++<\/span>i) {\n        for<\/span> (std::<\/span>size_t<\/span> j =<\/span> 0<\/span>; j <<\/span> m.extent(1<\/span>); ++<\/span>j) {\n            std::<\/span>cout <<<\/span> m[i, j] <<<\/span> ' '<\/span>;  \n        }\n        std::<\/span>cout <<<\/span> '\\n'<\/span>;\n    }\n\n    std::<\/span>cout <<<\/span> '\\n'<\/span>;\n\n    std::<\/span>mdspan<<\/span>int<\/span>, std::<\/span>extents<<\/span>std::<\/span>size_t<\/span>, std::<\/span>dynamic_extent, \n                std::<\/span>dynamic_extent>><\/span> m2{myVec.data(), 4<\/span>, 2<\/span>};          \/\/ (2)<\/span>\n    std::<\/span>cout <<<\/span> "m2.rank(): "<\/span> <<<\/span> m2.rank() <<<\/span> '\\n'<\/span>;\n\n    for<\/span> (std::<\/span>size_t<\/span> i =<\/span> 0<\/span>; i <<\/span> m2.extent(0<\/span>); ++<\/span>i) {\n        for<\/span> (std::<\/span>size_t<\/span> j =<\/span> 0<\/span>; j <<\/span> m2.extent(1<\/span>); ++<\/span>j) {\n        std::<\/span>cout <<<\/span> m2[i, j] <<<\/span> ' '<\/span>;  \n    }\n    std::<\/span>cout <<<\/span> '\\n'<\/span>;\n  }\n\n   std::<\/span>cout <<<\/span> '\\n'<\/span>;\n\n}\n<\/pre><\/div>\n\n\n\n
    The program staticDynamicExtent.cpp <\/code>is based on the previous program mdspan.cpp, and produces the same output. The difference is that the std::mdspan m<\/code> (line 1) has a static extent<\/em>. For completeness, std::mdspan m2<\/code> (line 2) has a dynamic extent<\/em>. Consequentially, the shape of m <\/code>is specified with template arguments, but the shape m2 <\/code>is with function arguments.<\/p>\n\n\n\n
    Layout Policy<\/h2>\n\n\n\n
    A std::mdspan<\/code> allows you to specify the layout policy to access the underlying memory. By default, std::layout_right <\/code>(C, C++, or Python style) is used, but you can also specify std::layout_left<\/code> (Fortran or MATLAB style). The following graphic exemplifies in which sequence the elements of the std::mdspan<\/code> are accessed.<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    Traversing two std::mdspan<\/code> with the layout policy std::layout_right<\/code> and std::layout_left<\/code> shows the difference.<\/p>\n\n\n\n
    \/\/ mdspanLayout.cpp<\/span>\n\n#include <mdspan><\/span>\n#include <iostream><\/span>\n#include <vector><\/span>\n\nint<\/span> main<\/span>() {\n    \n    std::<\/span>vector myVec{1<\/span>, 2<\/span>, 3<\/span>, 4<\/span>, 5<\/span>, 6<\/span>, 7<\/span>, 8<\/span>};\n\n    std::<\/span>mdspan<<\/span>int<\/span>, std::<\/span>extents<<\/span>std::<\/span>size_t<\/span>,      \/\/ (1)<\/span>\n         std::<\/span>dynamic_extent, std::<\/span>dynamic_extent><\/span>, \n         std::<\/span>layout_right><\/span> m{myVec.data(), 4<\/span>, 2<\/span>};\n    std::<\/span>cout <<<\/span> "m.rank(): "<\/span> <<<\/span> m.rank() <<<\/span> '\\n'<\/span>;\n\n    for<\/span> (std::<\/span>size_t<\/span> i =<\/span> 0<\/span>; i <<\/span> m.extent(0<\/span>); ++<\/span>i) {\n        for<\/span> (std::<\/span>size_t<\/span> j =<\/span> 0<\/span>; j <<\/span> m.extent(1<\/span>); ++<\/span>j) {\n            std::<\/span>cout <<<\/span> m[i, j] <<<\/span> ' '<\/span>;  \n        }\n        std::<\/span>cout <<<\/span> '\\n'<\/span>;\n    }\n\n    std::<\/span>cout <<<\/span> '\\n'<\/span>;\n\n    std::<\/span>mdspan<<\/span>int<\/span>, std::<\/span>extents<<\/span>std::<\/span>size_t<\/span>,     \/\/ (2)<\/span>\n         std::<\/span>dynamic_extent, std::<\/span>dynamic_extent><\/span>, \n         std::<\/span>layout_left><\/span> m2{myVec.data(), 4<\/span>, 2<\/span>};\n    std::<\/span>cout <<<\/span> "m2.rank(): "<\/span> <<<\/span> m2.rank() <<<\/span> '\\n'<\/span>;\n\n    for<\/span> (std::<\/span>size_t<\/span> i =<\/span> 0<\/span>; i <<\/span> m2.extent(0<\/span>); ++<\/span>i) {\n        for<\/span> (std::<\/span>size_t<\/span> j =<\/span> 0<\/span>; j <<\/span> m2.extent(1<\/span>); ++<\/span>j) {\n        std::<\/span>cout <<<\/span> m2[i, j] <<<\/span> ' '<\/span>;  \n    }\n    std::<\/span>cout <<<\/span> '\\n'<\/span>;\n  }\n\n}\n<\/pre><\/div>\n\n\n\n
    The std::mdspan m<\/code> uses std::layout_right<\/code> (line 1), the other std::mdspan std::layout_left<\/code> (line 2). Thanks to class template argument deduction, the constructor call of std::mdspan<\/code> (line 2) needs no explicit template arguments and is equivalent to the expression std::mdspan m2{myVec.data(), 4, <\/code>2}.<\/p>\n\n\n\n
    The output of the program shows the two different layout strategies:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    The following table presents an overview of std::mdspan<\/code>‘s interface.<\/p>\n\n\n\n
    Functions of a std::mdspan md<\/code><\/strong><\/td>Description<\/strong><\/td><\/tr>
    md[ind]<\/code><\/td>Access the ind<\/code>-th element.<\/td><\/tr>
    md.size<\/code><\/td>Returns the size of the multidimensional array.<\/td><\/tr>
    md.rank<\/code><\/td>Returns the dimension of the multidimensional array.<\/td><\/tr>
    md.extents(i)<\/code><\/td>Returns the size of the i<\/code>-th dimension.<\/td><\/tr>
    md.data_handle<\/code><\/td>Returns a pointer to the contiguous sequence of elements.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    What’s Next? <\/h2>\n\n\n\n
    C++20 does not provide concrete coroutines, but C++20 provides a framework for implementing coroutines. This changes with C++23. std::generator<\/code> is the first concrete coroutine.<\/p>\n","protected":false},"excerpt":{"rendered":"
    A std::mdspan is a non-owning multidimensional view of a contiguous sequence of objects. The contiguous sequence of objects can be a plain C-array, a pointer with a size, a std::array, a std::vector, or a std::string. Often, this multidimensional view is called a multidimensional array. The number of dimensions and the size of each dimension determine […]<\/p>\n","protected":false},"author":21,"featured_media":8210,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[378],"tags":[],"class_list":["post-8208","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-c-23"],"_links":{"self":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/8208","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/comments?post=8208"}],"version-history":[{"count":15,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/8208\/revisions"}],"predecessor-version":[{"id":9994,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/8208\/revisions\/9994"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/media\/8210"}],"wp:attachment":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/media?parent=8208"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/categories?post=8208"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/tags?post=8208"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}