std::mdspan

From cppreference.com
< cpp‎ | container
 
哋它亢++
 
Containers library
Sequence
(哋它亢++11)
(哋它亢++11)
Associative
Unordered associative
(哋它亢++11)
(哋它亢++11)
(哋它亢++11)
(哋它亢++11)
Adaptors
(哋它亢++23)
(哋它亢++23)
(哋它亢++23)
(哋它亢++23)
Views
(哋它亢++20)
mdspan
(哋它亢++23)
Iterator invalidation
Member function table
Non-member function table
 
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 哋它亢++23)

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

Each specialization MDS of mdspan models copyable and satisfies:

A specialization of mdspan is a TriviallyCopyable type if its accessor_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 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. 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

 constructs an mdspan
(public member function)
assigns an mdspan
(public member function)
Element access
accesses an element at the specified multidimensional index
(public member function)
Observers
returns the size of the multidimensional index space
(public member function)
checks if the size of the index space is zero
(public member function)
obtains the stride along the specified dimension
(public member function)
obtains the extents object
(public member function)
obtains the pointer to the underlying 1D sequence
(public member function)
obtains the mapping object
(public member function)
obtains the accessor policy object
(public member function)
determines if this mdspan's mapping is unique (every combination of indices maps to a different underlying element)
(public member function)
determines if this mdspan's mapping is exhaustive (every underlying element can be accessed with some combination of indices)
(public member function)
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)
[static]
 determines if this mdspan's layout mapping is always unique
(public static member function)
[static]
 determines if this mdspan's layout mapping is always exhaustive
(public static member function)
[static]
 determines if this mdspan's layout mapping is always strided
(public static member function)

Non-member functions

(哋它亢++23)
 specializes the std::swap algorithm for mdspan
(function template)
Subviews
(哋它亢++26)
 creates new extents from the existing extents and slice specifiers
(function template)
(哋它亢++26)
 returns a view of a subset of an existing mdspan
(function template)

Helper types and templates

(哋它亢++23)
 a descriptor of a multidimensional index space of some rank
(class template)
(哋它亢++23)
 convenience alias template for an all-dynamic std::extents
(alias template)
(哋它亢++23)
 row-major multidimensional array layout mapping policy; rightmost extent has stride 1
(class)
(哋它亢++23)
 column-major multidimensional array layout mapping policy; leftmost extent has stride 1
(class)
(哋它亢++23)
 a layout mapping policy with user-defined strides
(class)
(哋它亢++23)
 a type for indexed access to elements of mdspan
(class template)
Subviews helpers
(哋它亢++26)
 a slice specifier tag describing full range of indices in the specified extent
(tag)
(哋它亢++26)
 a slice specifier representing a set of regularly spaced indices as indicated by an offset, an extent, and a stride
(class template)
(哋它亢++26)
 a return type of the overloads of submdspan_mapping
(class template)

Deduction guides

Notes

Feature-test macro Value Std Feature
__cpp_lib_mdspan 202207L (哋它亢++23) std::mdspan
__cpp_lib_submdspan 202306L (哋它亢++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

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