View source for cpp/container/mdspan

{{cpp/title|mdspan}}
{{cpp/container/mdspan/navbar}}
{{dcl begin}}
{{dcl header|mdspan}}
{{dcl|since=c++23|1=
template<
    class T,
    class Extents,
    class LayoutPolicy = std::layout_right,
    class AccessorPolicy = std::default_accessor<T>
> class mdspan;
}}
{{dcl end}}

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

Each specialization {{tt|MDS}} of {{tt|mdspan}} models {{lconcept|copyable}} and satisfies:
:* {{c|std::is_nothrow_move_constructible_v<MDS>}} is {{c|true}},
:* {{c|std::is_nothrow_move_assignable_v<MDS>}} is {{c|true}}, and
:* {{c|std::is_nothrow_swappable_v<MDS>}} is {{c|true}}.
A specialization of {{tt|mdspan}} is a {{named req|TriviallyCopyable}} type if its {{tt|accessor_type}}, {{tt|mapping_type}} and {{tt|data_handle_type}} are {{named req|TriviallyCopyable}} types.

===Template parameters===
{{par begin}}
{{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|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. Must satisfy the constraint that {{c|std::is_same_v<T, typename AccessorPolicy::element_type>}} is {{c|true}}.}}
{{par end}}

{{todo|add the requirement of layout policy and accessor policy.}}

===Member types===
{{dsc begin}}
{{dsc hitem|Member type|Definition}}
{{dsc|{{tt|extents_type}}|{{tt|Extents}}}}
{{dsc|{{tt|layout_type}}|{{tt|LayoutPolicy}}}}
{{dsc|{{tt|accessor_type}}|{{tt|AccessorPolicy}}}}
{{dsc|{{tt|mapping_type}}|{{tt|LayoutPolicy::mapping<Extents>}}}}
{{dsc|{{tt|element_type}}|{{tt|T}}}}
{{dsc|{{tt|value_type}}|{{c/core|std::remove_cv_t<T>}}}}
{{dsc|{{tt|index_type}}|{{tt|Extents::index_type}}}}
{{dsc|{{tt|size_type}}|{{tt|Extents::size_type}}}}
{{dsc|{{tt|rank_type}}|{{tt|Extents::rank_type}}}}
{{dsc|{{tt|data_handle_type}}|{{tt|AccessorPolicy::data_handle_type}}}}
{{dsc|{{tt|reference}}|{{tt|AccessorPolicy::reference}}}}
{{dsc end}}

===Data members===
{{dsc begin}}
{{dsc hitem|Member object|Definition}}
{{dsc expos mem obj|acc_|private=yes|The accessor of type {{tt|accessor_type}}}}
{{dsc expos mem obj|map_|private=yes|The layout mapping of type {{tt|mapping_type}}}}
{{dsc expos mem obj|ptr_|private=yes|The underlying data handle of type {{tt|data_handle_type}}}}
{{dsc end}}

===Member functions===
{{dsc begin}}
{{dsc inc|cpp/container/mdspan/dsc constructor}}
{{dsc inc|cpp/container/mdspan/dsc operator{{=}}}}

{{dsc h2|Element access}}
{{dsc inc|cpp/container/mdspan/dsc operator_at}}

{{dsc h2|Observers}}
{{dsc inc|cpp/container/mdspan/dsc size}}
{{dsc inc|cpp/container/mdspan/dsc empty}}
{{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 data_handle}}
{{dsc inc|cpp/container/mdspan/dsc mapping}}
{{dsc inc|cpp/container/mdspan/dsc accessor}}

{{dsc inc|cpp/container/mdspan/dsc is_unique}}
{{dsc inc|cpp/container/mdspan/dsc is_exhaustive}}
{{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_exhaustive}}
{{dsc inc|cpp/container/mdspan/dsc is_always_strided}}
{{dsc end}}

===Non-member functions===
{{dsc begin}}
{{dsc inc|cpp/container/mdspan/dsc swap}}
{{dsc end}}

===Helper types and templates===
{{dsc begin}}
{{dsc inc|cpp/container/mdspan/dsc extents}}
{{dsc inc|cpp/container/mdspan/dsc dextents}}
{{dsc inc|cpp/container/mdspan/dsc layout_right}}
{{dsc inc|cpp/container/mdspan/dsc layout_left}}
{{dsc inc|cpp/container/mdspan/dsc layout_stride}}
{{dsc inc|cpp/container/mdspan/dsc default_accessor}}
{{dsc end}}

==={{rl|deduction guides|Deduction guides}}{{mark|c++23}}===

===Notes===
{{feature test macro|__cpp_lib_mdspan|std=C++23|value=202207L|{{tt|std::mdspan}}}}

===Example===
{{example
|Can be previewed at https://godbolt.org/z/PK7bccGr3.
|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===
{{dsc begin}}
{{dsc inc|cpp/container/dsc span}}
{{dsc inc|cpp/numeric/dsc valarray}}
{{dsc end}}

{{langlinks|de|es|ja|ru|zh}}