ah-mdspan.H File Reference

Non-owning multidimensional array view (Aleph::mdspan). More...

#include <array>
#include <cstddef>
#include <type_traits>
#include <utility>
#include <ah-cpp-compat.H>
#include <ah-errors.H>

Include dependency graph for ah-mdspan.H:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	Aleph::extents< IndexType, Exts >
	Shape (per-axis sizes) of an mdspan, mixing compile-time and run-time extents. More...
struct	Aleph::layout_right
	Row-major layout: the last axis varies fastest (C convention). More...
class	Aleph::layout_right::mapping< Extents >
	Mapping from row-major multi-indices to linear offsets. More...
struct	Aleph::layout_left
	Column-major layout: the first axis varies fastest (Fortran convention). More...
class	Aleph::layout_left::mapping< Extents >
	Mapping from column-major multi-indices to linear offsets. More...
struct	Aleph::default_accessor< ElementType >
	Trivial accessor policy: access(p, i) is just p[i]. More...
class	Aleph::mdspan< T, Extents, LayoutPolicy, AccessorPolicy >
	Non-owning view of a contiguous buffer as a multidimensional grid. More...

Namespaces
namespace	Aleph
	Main namespace for Aleph-w library functions.

Typedefs
template<class IndexType , size_t Rank>
using	Aleph::dextents = typename decltype(mdspan_detail::dextents_of< IndexType >(std::make_index_sequence< Rank >{}))::type
	extents<IndexType, ...> with all Rank axes dynamic — the common case.

Variables
constexpr size_t	Aleph::dynamic_extent = static_cast<size_t>(-1)
	Sentinel marking an axis whose extent is only known at run time.

Detailed Description

Non-owning multidimensional array view (Aleph::mdspan).

Aleph::mdspan<T, Extents, Layout, Accessor> is a lightweight, non-owning "view" over a contiguous buffer the caller already owns (a T*, Aleph::Array<T>::data(), std::vector<T>::data(), a CA::Dense_Cell_Storage<T,N>::view(), ...), exposing it as a multidimensional grid indexable via operator()(i, j, ...). It never allocates, copies, or owns anything — it is a pointer plus a shape.

Aleph::mdspan's element access is exclusively operator()(i, j, ...) plus a bounds-checked .at(i, j, ...) — not std::mdspan's own operator[](i, j, ...) (a C++23 language feature, multi-argument subscript, which cannot be backported to C++20; Aleph's baseline is C++20, GCC 11+/Clang 14+). This surface is identical regardless of the toolchain:

• When the toolchain provides C++23's <mdspan> (ALEPH_HAS_STD_MDSPAN, see ah-cpp-compat.H), Aleph::mdspan<T, Extents, Layout, Accessor> is a thin wrapper around a std::mdspan (still zero-copy — the wrapper only holds the std::mdspan by value, itself just a pointer/mapping/accessor triple) that forwards everything except element access, and implements operator()/.at() on top of the real std::mdspan::operator[]. Aleph::extents, Aleph::dextents, Aleph::layout_right, Aleph::layout_left and Aleph::default_accessor remain plain aliases of their std:: counterparts — only the class with the element-access surface needs wrapping.
• Otherwise this header provides a native C++20 implementation covering the same surface (construction, extents()/extent(r)/ rank()/size(), operator(), .at(), data_handle(), layout_right/layout_left). It is not a bit-for-bit reimplementation of the standard: in particular, the polyfill's extents<IndexType, Exts...> stores every extent at runtime rather than folding compile-time (static_extent) values out of the object's storage — a deliberate simplification that costs nothing for the fully-dynamic dextents case this library actually uses (e.g. CA::Dense_Cell_Storage), and only forgoes a size optimization for mixed static/dynamic extents, which Aleph does not currently need.

Why a view, not a container

mdspan never allocates. It is the multidimensional-shape counterpart of std::span: wrap an existing buffer to get readable m(i, j) indexing and shape introspection, with zero copies and zero overhead beyond the index-to-offset arithmetic itself.

Bounds checking

operator() matches std::mdspan's contract: out-of-range indices are undefined behavior (this is a zero-overhead view, not a checked container). Use .at(i, j, ...) for a bounds-checked access that throws std::out_of_range via ah_out_of_range_error_if, matching the get_curr()/get_curr_ne()-style checked/unchecked pairing used elsewhere in Aleph.

Example

std::vector<double> buf(6, 0.0);
Aleph::mdspan<double, Aleph::dextents<size_t, 2>> m(buf.data(), 2, 3);
m(0, 0) = 1.0; m(1, 2) = 5.0;
for (size_t i = 0; i < m.extent(0); ++i)
  for (size_t j = 0; j < m.extent(1); ++j)
    std::cout << m(i, j) << (j + 1 == m.extent(1) ? '\n' : ' ');

See also

CA::Dense_Cell_Storage::view() in tpl_ca_storage.H for the cellular-automata lattice application.

Examples/mdspan_matrix_view_example.cc for the matrix-view case.

Author

Leandro Rabindranath Leon

Definition in file ah-mdspan.H.