Namespaces
Variants
Views
Actions

std::mdspan

From cppreference.com
< cpp‎ | container
Revision as of 09:23, 18 October 2024 by D41D8CD98F (Talk | contribs)

 
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 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.

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). Must satisfy the requirements of LayoutMappingPolicy.
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. Must satisfy the requirements of AccessorPolicy.

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) [edit]
assigns an mdspan
(public member function) [edit]
Element access
accesses an element at the specified multidimensional index
(public member function) [edit]
Observers
[static]
 returns the rank of a mdspan
(public static member function) [edit]
[static]
 returns the dynamic rank of a mdspan
(public static member function) [edit]
[static]
 returns the static extent size of a mdspan at a given rank index
(public static member function) [edit]
returns the extent of a mdspan at a given rank index
(public member function) [edit]
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]
Subviews
(C++26)
 returns a view of a subset of an existing mdspan
(function template) [edit]
(C++26)
 creates new extents from the existing extents and slice specifiers
(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)
 a type for indexed access to elements of mdspan
(class template) [edit]
Layout mapping policies
(C++23)
 column-major multidimensional array layout mapping policy; leftmost extent has stride 1
(class) [edit]
(C++23)
 row-major multidimensional array layout mapping policy; rightmost extent has stride 1
(class) [edit]
(C++23)
 a layout mapping policy with user-defined strides
(class) [edit]
(C++26)
 column-major layout mapping policy with padding stride that can be greater than or equal to the leftmost extent
(class template) [edit]
(C++26)
 row-major layout mapping policy with padding stride that can be greater than or equal to the rightmost extent
(class template) [edit]
Subviews helpers
(C++26)
 a slice specifier tag describing full range of indices in the specified extent
(tag)[edit]
(C++26)
 a slice specifier representing a set of regularly spaced indices as indicated by an offset, an extent, and a stride
(class template) [edit]
(C++26)
 a return type of the overloads of submdspan_mapping
(class template) [edit]

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
202403L (C++26) std::mdspan padded layouts

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

(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=177124"