add: support for std::mdspan.

1uc · 1uc · commit 1d916bea20cb · 2025-11-18T10:59:00.000+01:00
Supports layout_{left,right,stride} and both accessors, i.e.
default_accessor and aligned_accessor. The padded layouts
should also work, but since they're not implemented in any
released version of (any of) the standard library, we're not testing
them (yet).

Copies are avoided for row-major layouts (layout_right) and for
one dimensional column-major layouts.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -194,6 +194,53 @@ jobs:
       working-directory: ${{github.workspace}}/build/src/examples
       run: $GITHUB_WORKSPACE/.github/run_examples.sh
 
+  # Job testing clang with C++23, libc++ and MDSPAN
+  # ================================================
+  Linux_Clang_CXX23_MDSPAN:
+    runs-on: ubuntu-24.04
+    env:
+      CC: clang-21
+      CXX: clang++-21
+
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        submodules: true
+
+    - name: "Add LLVM repository"
+      run: |
+        wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/llvm-snapshot.gpg
+        echo "deb [signed-by=/usr/share/keyrings/llvm-snapshot.gpg] http://apt.llvm.org/noble/ llvm-toolchain-noble-21 main" | sudo tee /etc/apt/sources.list.d/llvm.list
+
+    - name: "Install libraries"
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get -qq install clang-21 libc++-21-dev libc++abi-21-dev libhdf5-dev libsz2 ninja-build
+
+    - name: Build
+      run: |
+        CMAKE_OPTIONS=(
+          -GNinja
+          -DCMAKE_CXX_STANDARD=23
+          -DHIGHFIVE_USE_LIBCXX:BOOL=ON
+          -DHIGHFIVE_TEST_MDSPAN:BOOL=ON
+        )
+        source $GITHUB_WORKSPACE/.github/build.sh
+
+    - name: Test
+      working-directory: ${{github.workspace}}/build
+      run: |
+        ctest -j2 --output-on-failure -C $BUILD_TYPE
+
+    - name: Test No HDF5 Diagnositics
+      working-directory: ${{github.workspace}}/build
+      run: |
+        ! ctest --verbose -C $BUILD_TYPE | grep HDF5-DIAG
+
+    - name: Examples
+      working-directory: ${{github.workspace}}/build/src/examples
+      run: $GITHUB_WORKSPACE/.github/run_examples.sh
+
   # Job running unit-test with sanitizers
   # =====================================
   Linux_Sanitizers:
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -58,11 +58,19 @@ else()
   set(HIGHFIVE_TEST_SPAN_DEFAULT Off)
 endif()
 
+if (CMAKE_CXX_STANDARD GREATER_EQUAL 23)
+  include(CheckIncludeFileCXX)
+  CHECK_INCLUDE_FILE_CXX(mdspan HIGHFIVE_TEST_MDSPAN_DEFAULT)
+else()
+  set(HIGHFIVE_TEST_MDSPAN_DEFAULT Off)
+endif()
+
 option(HIGHFIVE_UNIT_TESTS "Compile unit-tests" ${HIGHFIVE_EXTRAS_DEFAULT})
 option(HIGHFIVE_EXAMPLES "Compile examples" ${HIGHFIVE_EXTRAS_DEFAULT})
 option(HIGHFIVE_BUILD_DOCS "Build documentation" ${HIGHFIVE_EXTRAS_DEFAULT})
 
 option(HIGHFIVE_TEST_SPAN "Enable testing std::span, requires C++20" ${HIGHFIVE_TEST_SPAN_DEFAULT})
+option(HIGHFIVE_TEST_MDSPAN "Enable testing std::mdspan, requires C++23 and libc++" ${HIGHFIVE_TEST_MDSPAN_DEFAULT})
 option(HIGHFIVE_TEST_BOOST "Enable testing Boost features" OFF)
 option(HIGHFIVE_TEST_BOOST_SPAN "Additionally, enable testing `boost::span`" OFF)
 option(HIGHFIVE_TEST_EIGEN "Enable testing Eigen" OFF)
@@ -92,6 +100,10 @@ if(CMAKE_CXX_STANDARD EQUAL 98 OR CMAKE_CXX_STANDARD LESS ${HIGHFIVE_CXX_STANDAR
   message(FATAL_ERROR "HighFive needs to be compiled with at least C++${HIGHFIVE_CXX_STANDARD_DEFAULT}")
 endif()
 
+if(HIGHFIVE_TEST_MDSPAN AND CMAKE_CXX_STANDARD LESS 23)
+  message(FATAL_ERROR "HIGHFIVE_TEST_MDSPAN requires C++23 or newer, but CMAKE_CXX_STANDARD is ${CMAKE_CXX_STANDARD}")
+endif()
+
 add_compile_definitions(HIGHFIVE_CXX_STD=${CMAKE_CXX_STANDARD})
 
 # HighFive
diff --git a/cmake/HighFiveOptionalDependencies.cmake b/cmake/HighFiveOptionalDependencies.cmake
@@ -52,6 +52,13 @@ if(NOT TARGET HighFiveSpanDependency)
   endif()
 endif()
 
+if(NOT TARGET HighFiveMdspanDependency)
+  add_library(HighFiveMdspanDependency INTERFACE)
+  if(HIGHFIVE_TEST_MDSPAN)
+    target_compile_definitions(HighFiveMdspanDependency INTERFACE HIGHFIVE_TEST_MDSPAN=1)
+  endif()
+endif()
+
 if(NOT TARGET HighFiveOptionalDependencies)
   add_library(HighFiveOptionalDependencies INTERFACE)
   target_link_libraries(HighFiveOptionalDependencies INTERFACE
@@ -60,5 +67,6 @@ if(NOT TARGET HighFiveOptionalDependencies)
     HighFiveXTensorDependency
     HighFiveOpenCVDependency
     HighFiveSpanDependency
+    HighFiveMdspanDependency
   )
 endif()
diff --git a/include/highfive/mdspan.hpp b/include/highfive/mdspan.hpp
@@ -0,0 +1,170 @@
+#pragma once
+
+#include "bits/H5Inspector_decl.hpp"
+#include "H5Exception.hpp"
+
+#include <mdspan>
+#include <vector>
+#include <array>
+#include <sstream>
+#include <utility>
+#include <type_traits>
+
+namespace HighFive {
+namespace details {
+
+// Specialization for std::mdspan
+template <class ElementType, class Extents, class LayoutPolicy, class AccessorPolicy>
+struct inspector<std::mdspan<ElementType, Extents, LayoutPolicy, AccessorPolicy>> {
+    using type = std::mdspan<ElementType, Extents, LayoutPolicy, AccessorPolicy>;
+    using value_type = typename type::element_type;
+    using base_type = typename inspector<value_type>::base_type;
+    using hdf5_type = base_type;
+    using extents_type = typename type::extents_type;
+    using accessor_type = typename type::accessor_type;
+
+    static constexpr size_t ndim = type::rank();
+    static constexpr size_t min_ndim = ndim + inspector<value_type>::min_ndim;
+    static constexpr size_t max_ndim = ndim + inspector<value_type>::max_ndim;
+
+    static constexpr bool is_trivially_copyable =
+        std::is_trivially_copyable<value_type>::value &&
+        inspector<value_type>::is_trivially_nestable &&
+        (std::is_same_v<std::default_accessor<value_type>, accessor_type>
+#ifdef __cpp_lib_aligned_accessor
+         || std::is_same_v<std::aligned_accessor<value_type>, accessor_type>
+#endif
+         ) &&
+        (std::is_same_v<typename type::layout_type, std::layout_right> ||
+         (std::is_same_v<typename type::layout_type, std::layout_left> && ndim == 1));
+    static constexpr bool is_trivially_nestable = false;
+
+  private:
+    using index_type = typename extents_type::index_type;
+
+    // Helper to access the first element (at index 0 in all dimensions)
+    static auto get_first_element(const type& val) {
+        std::array<index_type, ndim> indices{};
+        return val[indices];
+    }
+
+  public:
+    static size_t getRank(const type& val) {
+        if (val.empty()) {
+            return min_ndim;
+        }
+        return ndim + inspector<value_type>::getRank(get_first_element(val));
+    }
+
+    static std::vector<size_t> getDimensions(const type& val) {
+        std::vector<size_t> sizes;
+        sizes.reserve(ndim);
+        for (size_t r = 0; r < ndim; ++r) {
+            sizes.push_back(val.extent(r));
+        }
+        if (!val.empty()) {
+            auto s = inspector<value_type>::getDimensions(get_first_element(val));
+            sizes.insert(sizes.end(), s.begin(), s.end());
+        }
+        return sizes;
+    }
+
+    static void prepare(type& val, const std::vector<size_t>& dims) {
+        if (dims.size() < ndim) {
+            std::ostringstream os;
+            os << "Impossible to pair DataSet with " << dims.size()
+               << " dimensions into an mdspan with rank " << ndim << ".";
+            throw DataSpaceException(os.str());
+        }
+
+        // Check that dimensions match
+        for (size_t r = 0; r < ndim; ++r) {
+            if (dims[r] != val.extent(r)) {
+                std::ostringstream os;
+                os << "Mismatching dimensions for mdspan: expected " << val.extent(r)
+                   << " for dimension " << r << ", but got " << dims[r] << ".";
+                throw DataSpaceException(os.str());
+            }
+        }
+    }
+
+    static hdf5_type* data(type& val) {
+        if (!is_trivially_copyable) {
+            throw DataSetException("Invalid use of `inspector<std::mdspan<...>>::data`.");
+        }
+
+        if (val.empty()) {
+            return nullptr;
+        }
+
+        return inspector<value_type>::data(*val.data_handle());
+    }
+
+    static const hdf5_type* data(const type& val) {
+        if (!is_trivially_copyable) {
+            throw DataSetException("Invalid use of `inspector<std::mdspan<...>>::data`.");
+        }
+
+        if (val.empty()) {
+            return nullptr;
+        }
+
+        return inspector<value_type>::data(*val.data_handle());
+    }
+
+    static void serialize(const type& val, const std::vector<size_t>& dims, hdf5_type* m) {
+        auto subdims = std::vector<size_t>(dims.begin() + ndim, dims.end());
+        auto subsize = compute_total_size(subdims);
+
+        std::array<index_type, ndim> indices{};
+        auto iterate = [&](auto& self, size_t dim) -> void {
+            if (dim == ndim) {
+                // Base case: serialize element
+                inspector<value_type>::serialize(val[indices], subdims, m);
+                m += subsize;
+            } else {
+                // Recursive case: iterate over current dimension
+                const auto n = static_cast<index_type>(val.extent(dim));
+                for (indices[dim] = 0; indices[dim] < n; ++indices[dim]) {
+                    self(self, dim + 1);
+                }
+            }
+        };
+
+        iterate(iterate, 0);
+    }
+
+    static void unserialize(const hdf5_type* vec_align,
+                            const std::vector<size_t>& dims,
+                            type& val) {
+        if (dims.size() < ndim) {
+            std::ostringstream os;
+            os << "Impossible to pair DataSet with " << dims.size()
+               << " dimensions into an mdspan with rank " << ndim << ".";
+            throw DataSpaceException(os.str());
+        }
+
+        auto subdims = std::vector<size_t>(dims.begin() + ndim, dims.end());
+        auto subsize = compute_total_size(subdims);
+
+        std::array<index_type, ndim> indices{};
+        auto iterate = [&](auto& self, size_t dim) -> void {
+            if (dim == ndim) {
+                // Base case: unserialize element
+                inspector<value_type>::unserialize(vec_align, subdims, val[indices]);
+                vec_align += subsize;
+            } else {
+                // Recursive case: iterate over current dimension
+                const auto n = static_cast<index_type>(dims[dim]);
+                for (indices[dim] = 0; indices[dim] < n; ++indices[dim]) {
+                    self(self, dim + 1);
+                }
+            }
+        };
+
+        iterate(iterate, 0);
+    }
+};
+
+}  // namespace details
+}  // namespace HighFive
diff --git a/src/examples/CMakeLists.txt b/src/examples/CMakeLists.txt
@@ -23,6 +23,10 @@ set(span_examples
   ${CMAKE_CURRENT_SOURCE_DIR}/read_write_std_span.cpp
 )
 
+set(mdspan_examples
+  ${CMAKE_CURRENT_SOURCE_DIR}/read_write_std_mdspan.cpp
+)
+
 set(easy_examples
   ${CMAKE_CURRENT_SOURCE_DIR}/easy_attribute.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/easy_dumpoptions.cpp
@@ -85,6 +89,12 @@ if(HIGHFIVE_TEST_SPAN)
   endforeach()
 endif()
 
+if(HIGHFIVE_TEST_MDSPAN)
+  foreach(example_source ${mdspan_examples})
+    compile_example(${example_source} HighFiveFlags)
+  endforeach()
+endif()
+
 if(HIGHFIVE_TEST_BOOST)
   foreach(example_source ${boost_examples})
     compile_example(${example_source} HighFiveFlags HighFiveBoostDependency)
diff --git a/src/examples/read_write_std_mdspan.cpp b/src/examples/read_write_std_mdspan.cpp
@@ -0,0 +1,78 @@
+/*
+ *  Copyright (c), 2025, HighFive Developers
+ *
+ *  Distributed under the Boost Software License, Version 1.0.
+ *    (See accompanying file LICENSE_1_0.txt or copy at
+ *          http://www.boost.org/LICENSE_1_0.txt)
+ *
+ */
+
+// This example demonstrates using `std::mdspan`. An `std::mdspan` is a
+// multi-dimensional view over contiguous memory, similar to `std::span` but
+// for multi-dimensional arrays.
+
+#include <string>
+#include <vector>
+#include <mdspan>
+#include <cassert>
+
+#include <highfive/highfive.hpp>
+
+#include <highfive/mdspan.hpp>
+
+int main(void) {
+    using namespace HighFive;
+
+    std::string file_name = "read_write_mdspan.h5";
+    std::string dataset_name = "array";
+
+    // Assume we have multi-dimensional data stored contiguously, e.g. in a
+    // vector.
+    constexpr size_t rows = 3;
+    constexpr size_t cols = 4;
+    std::vector<double> values_row_major(rows * cols);
+
+    // Fill the data
+    for (size_t i = 0; i < rows; ++i) {
+        for (size_t j = 0; j < cols; ++j) {
+            values_row_major[i * cols + j] = double(i * cols + j);
+        }
+    }
+
+    // Create a 2D mdspan view over the contiguous memory.
+    auto view_row_major = std::mdspan(values_row_major.data(), std::extents{rows, cols});
+
+    {
+        File file(file_name, File::Truncate);
+        auto dataset = file.createDataSet(dataset_name, view_row_major);
+    }
+
+    // Let's read from file.
+    {
+        File file(file_name, File::ReadOnly);
+        auto dataset = file.getDataSet(dataset_name);
+
+        // Assume that memory was allocated by some means, e.g.:
+        auto dims = dataset.getDimensions();
+        auto values_col_major = std::vector<double>(dataset.getElementCount());
+
+        // Create a column-major mdspan view over the preallocated memory.
+        auto m = std::layout_left::mapping{std::extents{dims[0], dims[1]}};
+        auto view_col_major = std::mdspan(values_col_major.data(), m);
+
+        // ... now we can read into the preallocated memory:
+        dataset.read(view_col_major);
+
+        // Check that the data was read correctly.
+        for (size_t i = 0; i < rows; ++i) {
+            for (size_t j = 0; j < cols; ++j) {
+                if (view_col_major[i, j] != view_row_major[i, j]) {
+                    std::cerr << "Error: data was not read correctly." << std::endl;
+                    return 1;
+                }
+            }
+        }
+    }
+
+    return 0;
+}
diff --git a/tests/unit/CMakeLists.txt b/tests/unit/CMakeLists.txt
@@ -75,6 +75,10 @@ foreach(PUBLIC_HEADER ${public_headers})
       continue()
     endif()
 
+    if(PUBLIC_HEADER STREQUAL "highfive/mdspan.hpp" AND NOT HIGHFIVE_TEST_MDSPAN)
+      continue()
+    endif()
+
     get_filename_component(CLASS_NAME ${PUBLIC_HEADER} NAME_WE)
     configure_file(tests_import_public_headers.cpp "tests_${CLASS_NAME}.cpp" @ONLY)
     add_executable("tests_include_${CLASS_NAME}" "${CMAKE_CURRENT_BINARY_DIR}/tests_${CLASS_NAME}.cpp")
diff --git a/tests/unit/data_generator.hpp b/tests/unit/data_generator.hpp
diff --git a/tests/unit/supported_types.hpp b/tests/unit/supported_types.hpp
