std::mdspan
From cppreference.com
C++
Feature test macros (C++20)
Concepts library (C++20)
Metaprogramming library (C++11)
Ranges library (C++20)
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Containers library
(C++17)
(C++11)
(C++26)
(C++26)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++23)
(C++23)
(C++23)
(C++23)
(C++20)
mdspan
(C++23)
Tables
std::mdspan
(C++26)
(C++26)
(C++26)
(C++26)
(C++26)
(C++26)
(C++26)
(C++26)
(C++26)
Defined in header
<mdspan>
template<
(since C++23)
class T,
class Extents,
class LayoutPolicy = std::layout_right,
class AccessorPolicy = std::default_accessor <T>
std::mdspan is a multidimensional array view that maps a multidimensional index to an element of the array. The mapping and element access policies are configurable, and the underlying array need not be contiguous or even exist in memory at all.
Each specialization MDS of mdspan models copyable and satisfies:
- std::is_nothrow_move_constructible_v <MDS> is true,
- std::is_nothrow_move_assignable_v <MDS> is true, and
- std::is_nothrow_swappable_v <MDS> is true.
A specialization of mdspan is a TriviallyCopyable type if its accessor_type, mapping_type and data_handle_type are TriviallyCopyable types.
Contents
[edit] 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.
[edit] Member types
Member
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
[edit] Data members
Member
Description
accessor_type acc_ (private)
the accessor(exposition-only member object*)
mapping_type map_ (private)
the layout mapping(exposition-only member object*)
data_handle_type ptr_ (private)
the underlying data handle(exposition-only member object*)
[edit] Member functions
Element access
Observers
[static]
mdspan at a given rank index (public static 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]
(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]
(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]
(public member function) [edit]
[static]
(public static member function) [edit]
[static]
(public static member function) [edit]
[static]
(public static member function) [edit]
[edit] Non-member functions
Subviews
(C++26)
(function template) [edit]
[edit] Helper types and templates
Layout mapping policies
(C++23)
1 (class) [edit]
(C++23)
1 (class) [edit]
(C++26)
(class template) [edit]
(C++26)
(class template) [edit]
Subviews helpers
(C++26)
(class template) [edit]
[edit] Deduction guides
[edit] 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
| |
__cpp_lib_aligned_accessor |
202411L |
(C++26) | std::aligned_accessor |
[edit] 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