C++ Library - <mdspan>

---

---

The <mdspan> header in C++ is used for working with multidimensional views of data. It provides an efficient way to access multidimensional arrays or contiguous blocks of memory with flexible mapping layouts.

This header is part of the containers library and also optimized for performing critical applications, can be used with different data layouts such as (row-major, column-major order).

Including <mdspan> Header

To include the <mdspan> header in your C++ program, you can use the following syntax.

#include <mdspan>

Functions of <mdspan> Header

Below is list of all functions from <mdspan> header.

S.No	Functions & Description
1	operator [] This function accesses an element at the specified multidimensional index.
2	size This function returns the size of the multidimensional index space.
3	empty This function checks if the size of the index space is zero.
4	stride This function obtains the stride along the specified dimension.
5	extents This function obtains the extents object.
6	data_handle This function obtains the pointer to the underlying 1D sequence.
7	mapping This function obtains the mapping object that defines how multidimensional indices map to the 1D data.
8	accessor This function returns the accessor policy object, which manages access to the underlying element.

Accessing Elements

In the following example we are going to use, operator[] it allows matrix[1][2] accesses the element at the first row and second column.

#include <mdspan>
#include <iostream>
int main() {
    std::array<int, 9> data = {1, 2, 3, 4, 5, 6, 7, 8, 9};
    std::mdspan<int, std::extents<3, 3>> matrix(data.data());
    std::cout << "Element at [1][2]: " << matrix[1][2] << std::endl; 
    return 0;
}

Output

If we run the above code it will generate the following output

6

Property Checks

The property checks are member functions that provide information about how the multidimensional mapping of the object behaves.

S.No	Functions & Description
1	is_unique This function determines if this mdspan's mapping is unique.
2	is_exhaustive This function determines if this mdspan's mapping is exhaustive.
3	is_strided This 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).

Property Checking

In the following example we are going to use, is_unique() function to check if each multidimensional index in the mdspan maps to a distinct element in the 1D data array.

#include <mdspan>
#include <iostream>
int main() {
    std::array<int, 9> data = {1, 2, 3, 4, 5, 6, 7, 8, 9};
    std::mdspan<int, std::extents<3, 3>> matrix(data.data());
    if (matrix.is_unique()) {
        std::cout << "Mapping is unique." << std::endl;
    } else {
        std::cout << "Mapping is not unique." << std::endl;
    }
    return 0;
}

Output

If we run the above code it will generate the following output

Mapping is unique.

Static Functions

The static functions provides compile-time properties of mdspan and its mapping layout.

S.No	Functions & Description
1	is_always_unique This static function determines if this mdspan's layout mapping is always unique.
2	is_always_exhaustive This static function determines if this mdspan's layout mapping is always exhaustive.
3	is_always_strided This static function determines if this mdspan's layout mapping is always strided.

Checking Compile-Time Property

In the following example we are going to use, is_always_exhaustive to check if the layout mapping always covers the entire extents of the mdspan in a contiguous manner at compile-time.

#include <mdspan>
#include <iostream>
int main() {
    if (std::mdspan<int, std::extents<3, 3>>::is_always_exhaustive()) {
        std::cout << "Mapping is always exhaustive." << std::endl;
    } else {
        std::cout << "Mapping is not always exhaustive." << std::endl;
    }
    return 0;
}

Output

If we run the above code it will generate the following output

Mapping is always exhaustive.