C++ Guides

Three std::mdspan Traps: The Missing operator(), submdspan in C++26, and assert

A first mdspan program hits three traps in a row: the call spelling does not exist, the sub-view needs C++26, and assert breaks on a comma. The full view library lives in the companion guide; this tutorial assumes it and covers only the traps.

Written November 7, 2026 · Tested with GCC 14.2.0 · 6 min read

By the end of this guide
  • What this tutorial is
  • The compiler floor, briefly

What this tutorial is

This tutorial is a follow-up to the companion guide C++23 std::mdspan and Deducing This: A Matrix and Image View Library. That guide builds the full view library: row-major, column-major, and strided channel views, extents, observers, and the deducing-this wrapper. This tutorial assumes that library and does not repeat it. It covers the three things that trip people who write their first mdspan program after reading it: the access spelling that does not exist, the sub-view that needs C++26, and the assert that breaks on a comma.

The submdspan program below uses a 3-by-4 matrix, values 1 through 12 in row order. Its row sums are 10, 26, and 42. Those three numbers are the checksum for that program: a program that prints them read the matrix right.

The compiler floor, briefly

Full compiler results live in the companion guide's compiler matrix. Two facts matter here. First, GCC 14.2.0 also has no <mdspan> header. The header file is absent from the GCC 14.2.0 include tree, and the compile fails before any of the program's own code is read. The measured floor is GCC 16. Second, the two feature-test macros split by standard, and the split is what the submdspan trap turns on:

Under -std=c++23, __cpp_lib_mdspan is 202207 and __cpp_lib_submdspan is UNDEFINED. Under -std=c++26, the values are 202406 and 202603.

Trap 1: there is no operator()

Trap
The natural spelling for element access, carried over from every other multidimensional array type, is m(i, j). It does not compile. The minimal example is two lines, and both fail under GCC 16.2.0 in C++23 mode and in C++26 mode:
C++
#include <mdspan>
#include <vector>
#include <iostream>
int main() {
  std::vector<double> d{1, 2, 3, 4, 5, 6};
  std::mdspan<double, std::extents<std::size_t, 2, 3>> a(d.data());
  std::cout << "A op()=" << a(1, 2) << "\n";
  std::mdspan b(d.data(), 2, 3);
  std::cout << "B op()=" << b(1, 2) << "\n";
  return 0;
}
Output
mini.cpp:8:30: error: no match for call to ‘(std::mdspan<double, std::extents<long unsigned int, 2, 3> >) (int, int)’
    8 |   std::cout << "A op()=" << a(1, 2) << "\n";
      |                             ~^~~~~~
mini.cpp:11:30: error: no match for call to ‘(std::mdspan<double, std::extents<long unsigned int, 18446744073709551615, 18446744073709551615>, std::layout_right, std::default_accessor<double> >) (int, int)’
   11 |   std::cout << "B op()=" << b(1, 2) << "\n";
      |                             ~^~~~~~

The error is the same for the explicit-extents spelling and for the deduced spelling, and the same in C++26 mode: 2 error lines in each mode, both no match for call. The header explains why. In the libstdc++ 16 <mdspan> header, the text operator() occurs 11 times, and 5 of those are definitions, at lines 1583, 1761, 1976, 2620, and 2793. Every one of them belongs to a layout mapping class, where operator() converts indices to a flat offset. Class mdspan itself, at line 2938, exposes no operator() at all. Its element access is operator[], defined at lines 3069, 3089, and 3103, one overload for each index-passing form.

The cppreference page for std::mdspan agrees, and it is the primary to check before believing any other source on this point. Its member-function table lists operator[] as the element-access member and lists no operator(). Its example builds a view with std::mdspan(v.data(), 2, 6) and writes ms2[i, j]. The multidimensional subscript is C++23 syntax: the comma inside the brackets is the subscript operator, not the comma operator. The spelling to teach is m[i, j], in C++23 mode and in C++26 mode alike, and m(i, j) must never appear as working code.

The positive check is short. The same two views, read with brackets, compile and run under -std=c++23:

C++
#include <mdspan>
#include <vector>
#include <iostream>
int main() {
  std::vector<double> d{1, 2, 3, 4, 5, 6};
  std::mdspan<double, std::extents<std::size_t, 2, 3>> a(d.data());
  std::mdspan b(d.data(), 2, 3);
  const std::mdspan cb(d.data(), 2, 3);
  std::cout << "bracket-ok " << a[1, 2] << " " << b[1, 2] << " " << cb[0, 1] << "\n";
  return 0;
}
Output
bracket-ok 6 6 2

a[1, 2] is 6, the last element of the 2-by-3 view. b[1, 2] is the same element through the deduced view. cb[0, 1] is 2, read through a const view. A const mdspan still yields mutable references, because a view does not own its data and constness of the handle does not propagate to the elements.

Trap 2: submdspan is C++26, and it runs

Trap
C++23 ships mdspan without a sub-view operation. std::submdspan, which returns a view of a subset of an existing mdspan, is C++26. The macro table above already shows the split: __cpp_lib_submdspan is UNDEFINED under -std=c++23 and 202603 under -std=c++26 on GCC 16.2.0. The cppreference std::mdspan page marks submdspan (C++26) in its non-member function table, lists __cpp_lib_submdspan as 202306L, and marks at and the padded layouts (C++26) the same way. The library's own value, 202603, is newer than the paper value cppreference records; both are reported as observed, and the gate that matters is the compile, not the number. The companion guide showed only the C++23 failure and the hand-rolled replacement; this section is the C++26 run it deferred.

Under -std=c++23 the call is a compile error, re-executed at build time:

Output
error: 'submdspan' is not a member of 'std'; did you mean 'mdspan'?

Under -std=c++26 the same shape of program runs. Row views are the use case: one submdspan call per row, with std::full_extent keeping the whole row:

C++
// Same matrix, C++26 mode: adds std::submdspan row views.
#include <mdspan>
#include <vector>
#include <iostream>
#include <cassert>
int main() {
  std::vector<double> d{1,2,3,4, 5,6,7,8, 9,10,11,12};
  std::mdspan v(d.data(), 3, 4);
  double sums[3] = {};
  for (std::size_t r = 0; r < 3; ++r) {
    auto row = std::submdspan(v, r, std::full_extent);
    double s = 0;
    for (std::size_t c = 0; c < 4; ++c) s += row[c];
    sums[r] = s;
  }
  assert(sums[0] == 10 && sums[1] == 26 && sums[2] == 42);
  std::cout << "mdspan-submdspan-ok rowsums 10 26 42\n";
  return 0;
}
Output
mdspan-submdspan-ok rowsums 10 26 42

The row sums are the same 10, 26, and 42, which is the point: the sub-view reads the same buffer, and the sums prove it. Note the access spelling inside the loop is row[c], a single-index bracket on the one-dimensional row view. The C++23 replacement for a row view is the hand-rolled strided construction in the companion guide, with the pointer moved to the row origin; label it hand-rolled when you write it, because the offset arithmetic is yours to get wrong in exactly the ways submdspan gets right. When a C++26 library is available, prefer submdspan and delete the manual construction.

Trap 3: the assert trap

Trap
The last trap is not in the library. It is in the macro. A multi-argument subscript inside assert() breaks the macro, because the comma inside t[3, 2] splits the macro argument. This file must fail to compile, and it does:
C++
#include <mdspan>
#include <vector>
#include <cassert>
int main() {
  std::vector<double> d{1,2,3,4,5,6,7,8,9,10,11,12};
  std::mdspan<double, std::extents<std::size_t, 4, 3>,
              std::layout_stride> t(d.data(),
    std::layout_stride::mapping<std::extents<std::size_t, 4, 3>>{
      std::extents<std::size_t, 4, 3>{}, std::array<std::size_t, 2>{1, 4}});
  assert(t[3, 2] == 12 && t[0, 1] == 5);
  return 0;
}
Output
trap.cpp:12:39: error: macro ‘assert’ passed 3 arguments, but takes just 1
   12 |   assert(t[3, 2] == 12 && t[0, 1] == 5);
      |                                       ^

The macro sees three arguments: t[3, 2] == 12 && t[0, and 1] == 5. The fix is double parentheses around the whole expression:

C++
assert((t[3, 2] == 12 && t[0, 1] == 5));

The outer pair belongs to the macro call; the inner pair hides the commas from the preprocessor. That parenthesized form is the one that compiled in this run's probe batch: the matrix program used exactly this line and built with zero warnings. Any guide that teaches operator[] must show the parenthesized form or avoid assert for subscript checks. The same comma rule applies to any macro that takes one argument, not only assert.

Checklist

Three items, one per trap, in page order:

  1. Write m[i, j], never m(i, j). The call form does not exist in libstdc++ 16, in C++23 or in C++26.
  2. Use submdspan only at -std=c++26. Under C++23 it is a compile error; the C++23 replacement is a hand-rolled strided view, labeled as such.
  3. Parenthesize multi-argument subscripts inside assert(). The double-parenthesized form is the one that compiled in this run's probe batch; the bare form does not.

Frequently asked questions

My code uses m(i, j) from a tutorial. Is the tutorial wrong?

For this library, yes. The mdspan in libstdc++ 16 has no call operator: the member table lists operator[] only, and the minimal example above fails in both C++23 and C++26 modes. Change the spelling to brackets; nothing else in the program needs to move.

Why does the compiler error not suggest brackets?

Because no match for call reports what it tried: a call expression on a type with no call operator. The compiler cannot know you meant a subscript. The fix is in the spelling, and the error text is the same for the explicit-extents and the deduced view, which is why the minimal example shows both.

Can I use submdspan in C++23 mode?

No. The macro is undefined, the name is not a member of std, and the compile fails. The companion guide's hand-rolled strided view is the C++23 form. Move to -std=c++26 when your library has it, and prefer submdspan then.

Source

  • std::mdspan - cppreference: the class template; the member-function table lists operator[] as the element-access member and no operator(); the example writes ms2[i, j]; submdspan, at, and the padded layouts are marked (C++26); __cpp_lib_mdspan is 202207L and __cpp_lib_submdspan is 202306L.
  • C++23 - ISciNumPy: the MDSpan section states the multidimensional subscript item[1,2] and that sub-views are not yet included, likely for C++26; the Deducing This section shows the four-overload collapse and the CRTP pattern without a template.
  • C++23 std::mdspan and Deducing This: A Matrix and Image View Library: the companion guide on this site. It builds the full view library, proves deducing this on GCC 14, records the Clang with libstdc++ 16 header error, and shows the hand-rolled C++23 sub-view that this tutorial's submdspan section replaces at C++26.

Keep Exploring