std::mdspan(3)

💖 NAME 💖

std::mdspan — and yeah, the name is literally std::mdspan, bestie. This is the std::mdspan(3) page from the C++ Standard Libary manual (the header really spells it “Libary” 😭 — iconic typo behavior).

✨ Synopsis ✨

Defined in header <mdspan>:

template<

    class T,
    class Extents,                                   (since C++23)
    class LayoutPolicy = std::layout_right,
    class AccessorPolicy = std::default_accessor<T>

> class mdspan;

std::mdspan is a view over a contiguous sequence of objects, and it reinterprets that sequence as a multidimensional array. Multidimensional-array main character energy, fr fr.

Every specialization MDS of mdspan models copyable and ticks these boxes:

• 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. No cap, that's the rule.

🌸 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 🎀

• 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 🦋

• 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 💅

• constructor — constructs an mdspan (public member function)
• operator= — assigns an mdspan (public member function)

🔥 Element access 🔥

• operator[] — accesses an element at the specified multidimensional index (public member function)

👀 Observers 👀

• size — returns the size of the multidimensional index space (public member function)
• empty — checks if the size of the index space is zero (public member function)
• stride — obtains the stride along the specified dimension (public member function)
• extents — obtains the extents object (public member function)
• data_handle — obtains the pointer to the underlying 1D sequence (public member function)
• mapping — obtains the mapping object (public member function)
• accessor — obtains the accessor policy object (public member function)
• is_unique — determines if this mdspan's mapping is unique (every combination of indices maps to a different underlying element) (public member function)
• is_exhaustive — determines if this mdspan's mapping is exhaustive (every underlying element can be accessed with some combination of indices) (public member function)
• is_strided — 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)
• is_always_unique [static] — determines if this mdspan's layout mapping is always unique (public static member function)
• is_always_exhaustive [static] — determines if this mdspan's layout mapping is always exhaustive (public static member function)
• is_always_strided [static] — determines if this mdspan's layout mapping is always strided (public static member function)

🌈 Non-member functions 🌈

• std::swap(std::mdspan) (C++23) — specializes the std::swap algorithm for mdspan (function template)

🌸 Subviews 🌸

• submdspan_extents (C++26) — creates new extents from the existing extents and slice specifiers (function template)
• submdspan (C++26) — returns a view of a subset of an existing mdspan (function template)

🎀 Helper types and templates 🎀

• extents (C++23) — a descriptor of a multidimensional index space of some rank (class template)
• dextents (C++23) — convenience alias template for an all-dynamic std::extents (alias template)
• layout_right (C++23) — row-major multidimensional array layout mapping policy; rightmost extent has stride 1 (class)
• layout_left (C++23) — column-major multidimensional array layout mapping policy; leftmost extent has stride 1 (class)
• layout_stride (C++23) — a layout mapping policy with user-defined strides (class)
• default_accessor (C++23) — a type for indexed access to elements of mdspan (class template)

🦋 Subviews helpers 🦋

• full_extent / full_extent_t (C++26) — a slice specifier tag describing full range of indices in the specified extent (tag)
• strided_slice (C++26) — a slice specifier representing a set of regularly spaced indices as indicated by an offset, an extent, and a stride (class template)
• submdspan_mapping_result (C++26) — a return type of the overloads of submdspan_mapping (class template)

✨ Deduction guides ✨

No extra notes on this page for the deduction guides — just the section heading sitting there with main character energy. 💅

⭐ Notes ⭐

Feature-test macros, bestie:

• __cpp_lib_mdspan — 202207L — (C++23) — std::mdspan
• __cpp_lib_submdspan — 202306L — (C++26) — std::submdspan

🍓 Example 🍓

You can preview this on Compiler Explorer. The page has the little // Run this code marker, then this exact code:

// 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 💜

• span (C++20) — a non-owning view over a contiguous sequence of objects (class template)
• valarray — numeric arrays, array masks and array slices (class template)

💀 Category 💀

• Todo with reason

---

That's the whole page, bestie. Source/version and date: http://cppreference.com, 2024.06.10, std::mdspan(3). Go be a multidimensional icon! 🫶✨