Rework operator[]

This uses C++23's mutlidimensional subscript operator to improve the
indexing, and introduces non-contiguous slices.

Author: elius1

CMakeLists.txt

@@ -104,6 +104,7 @@ set(
     -Wno-c++98-compat-pedantic
     -Wno-missing-braces
     -Wno-padded
+    -Wno-unsafe-buffer-usage
 )
 
 set(
@@ -123,7 +124,7 @@ target_include_directories(
     vt-ndarray
     INTERFACE ${CMAKE_CURRENT_LIST_DIR}/include
 )
-target_compile_features(vt-ndarray INTERFACE cxx_std_17)
+target_compile_features(vt-ndarray INTERFACE cxx_std_23)
 
 add_library(vt::ndarray ALIAS vt-ndarray)
 
@@ -137,6 +138,7 @@ if(VT_ENABLE_TESTING)
         "${CMAKE_CURRENT_LIST_DIR}/test/vt/ndarray/allocator_test.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/test/vt/ndarray/container_test.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/test/vt/ndarray/foreach_benchmark.cpp"
+        "${CMAKE_CURRENT_LIST_DIR}/test/vt/ndarray/index_test.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/test/vt/ndarray/matrix_mul_benchmark.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/test/vt/ndarray/test_main.cpp"
         "${CMAKE_CURRENT_LIST_DIR}/test/vt/ndarray/view_test.cpp"

README.md

@@ -8,7 +8,7 @@ N-dimensional array library for C++, developed and maintained by [VORtech](https
 Getting started
 ---------------
 
-This is a header-only library. To use it, simply add all files under `include` to your include directories. The library uses C++17 features and assumes a C++17 compliant compiler. Compatibility with the following compilers is tested:
+This is a header-only library. To use it, simply add all files under `include` to your include directories. The library uses C++23 features and assumes a C++23 compliant compiler. Compatibility with the following compilers is tested:
 
 - GCC 14.2
 - Clang 18.1
@@ -27,8 +27,8 @@ int main() {
         1, 5, 9
     }};
 
-    assert(A[0][0] == 3); assert(A[0][1] == 1); assert(A[0][2] == 4);
-    assert(A[1][0] == 1); assert(A[1][1] == 5); assert(A[1][2] == 9);
+    assert(A[0, 0] == 3); assert(A[0, 1] == 1); assert(A[0, 2] == 4);
+    assert(A[1, 0] == 1); assert(A[1, 1] == 5); assert(A[1, 2] == 9);
 }
 ```
 
@@ -42,9 +42,9 @@ static void diag(vt::ndview<int, 2> A, vt::ndview<const int, 1> d) {
     const size_t n = d.shape(0);
     for (size_t i = 0; i < n; ++i) {
         for (size_t j = 0; j < n; ++j) {
-            A[i][j] = 0;
+            A[i, j] = 0;
         }
-        A[i][i] = d[i];
+        A[i, i] = d[i];
     }
 }
 

doc/vt/ndarray/container/index-operator.md

@@ -3,29 +3,39 @@ vt::ndarray::operator[]
 
 ```c++
 // (1)
-decltype(auto) operator[](std::size_t idx) noexcept;
+template<indexer... Index>
+decltype(auto) operator[](
+    Index... idx
+) noexcept requires((sizeof...(Index) <= N));
 // (2)
-decltype(auto) operator[](std::size_t idx) const noexcept;
+template<indexer... Index>
+decltype(auto) operator[](
+    Index... idx
+) const noexcept requires((sizeof...(Index) <= N));
 ```
 
-Accesses the view or element at the specified index. The behavior is undefined if `idx >= shape[0]`.
+Accesses the view, slice or element at the specified indices or index ranges. The behavior is undefined if any indices are outside the bounds of the array.
 
-1. Will return a mutable view or reference.
-2. Will return a const view or reference.
+1. Will return a mutable view, slice or reference.
+2. Will return a const view, slice or reference.
+
+If `sizeof...(Index) < N`, the result is similar to the arguments being padded with occurrences of [r()](../index-range/r.md#top) until `N` arguments are reached.
 
 Parameters
 ----------
 
 |||
-------- | --------------------------------------
-**idx** | index of the view or element to access
+------- | -----------------------------------------
+**idx** | parameter-pack of indices or index ranges
 
 Return value
 ------------
 
-If `N > 1`, returns a view of dimension `N - 1` into the sub-array at the specified index.
+If all arguments in the parameter-pack are convertible to `std::size_t`, returns a reference to the element at the specified indices.
+
+Else, if the parameter-pack specifies a contiguous slice, returns a [ndview](../view/readme.md#top) of the slice.
 
-If `N = 1`, returns a reference to the element at the specified index.
+Else, if the parameter-pack specifies a non-contiguous slice, returns a [ndslice](../slice/readme.md#top).
 
 Example
 -------
@@ -35,18 +45,25 @@ Example
 #include <cassert>
 
 int main() {
+    using vt::r;
+
     const vt::ndarray<int, 2> A{{ 2, 3 }, {
         3, 1, 4,
         1, 5, 9
     }};
 
-    // Elements can be accessed by chaining calls to operator[]
-    assert(A[1][1] == 5);
+    // Elements can be accessed by specifying only indices
+    assert(A[1, 1] == 5);
+
+    // A contiguous slice will result in a vt::ndview
+    vt::ndview<const int, 1> A_0j = A[0, r()];
+    assert(A_0j[0] == 3);
+    assert(A_0j[1] == 1);
+    assert(A_0j[2] == 4);
 
-    // A single call to operator[] will return a view into a sub-array
-    vt::ndview<const int, 1> A_0 = A[0];
-    assert(A_0[0] == 3);
-    assert(A_0[1] == 1);
-    assert(A_0[2] == 4);
+    // A non-contiguous slice will result in a vt::ndslice
+    vt::ndslice<const int, 1> A_i2 = A[r(), 2];
+    assert(A_i2[0] == 4);
+    assert(A_i2[1] == 9);
 }
 ```

doc/vt/ndarray/container/readme.md

@@ -113,7 +113,7 @@ int main() {
     std::cout << a << '\n';
 
     // The index-operator can be used to access elements:
-    std::cout << a[0][2][3] << '\n';
+    std::cout << a[0, 2, 3] << '\n';
 
     // The shape can be queried:
     std::cout << a.shape(0) << ',' << a.shape(1) << ',' a.shape(2) << '\n';

doc/vt/ndarray/container/reshape.md

@@ -54,9 +54,9 @@ int main() {
     assert(A[3] == 1);
 
     vt::ndview<const int, 2> B = A.reshape({ 2, 2 });
-    assert(B[0][0] == 3);
-    assert(B[0][1] == 1);
-    assert(B[1][0] == 4);
-    assert(B[1][1] == 1);
+    assert(B[0, 0] == 3);
+    assert(B[0, 1] == 1);
+    assert(B[1, 0] == 4);
+    assert(B[1, 1] == 1);
 }
 ```

doc/vt/ndarray/container/slice.md

@@ -52,9 +52,9 @@ int main() {
     // When slicing a 2D-array, rows outside of the slice will not be in the
     // obtained view
     vt::ndview<const int, 2> B = A.slice(1, 2);
-    assert(B[0][0] == 4);
-    assert(B[0][1] == 1);
-    assert(B[1][0] == 5);
-    assert(B[1][1] == 9);
+    assert(B[0, 0] == 4);
+    assert(B[0, 1] == 1);
+    assert(B[1, 0] == 5);
+    assert(B[1, 1] == 9);
 }
 ```

doc/vt/ndarray/index-range/r.md

@@ -0,0 +1,32 @@
+vt::r
+=====
+
+```c++
+// (1)
+constexpr index_range<0> r() noexcept;
+// (2)
+constexpr index_range<1> r(std::size_t start) noexcept;
+// (3)
+constexpr index_range<2> r(std::size_t start, std::size_t end) noexcept;
+```
+
+Convenience function for creating instances of `vt::index_range`.
+
+1. Creates an index range from the start of an array dimension to the end of an array dimension. (Similar to `:` in Python.)
+2. Creates an index range from a specified start to the end of an array dimension. (Similar to `start:` in Python.)
+3. Creates an index range from a specified start to a specified end. (Similar to `start:end` in Python.)
+
+The behavior is undefined if `start` or `end` are outside the bounds of the array that the resulting `vt::index_range` indexes into.
+
+Parameters
+----------
+
+|||
+--------- | -----------------------------------
+**start** | start index of the range
+**end**   | one past the end index of the range
+
+Return value
+------------
+
+The resulting `vt::index_range`.

doc/vt/ndarray/index-range/readme.md

@@ -0,0 +1,51 @@
+vt::index_range
+===============
+
+- Defined in header `<vt/ndarray/index.hpp>`
+- Defined in header `<vt/ndarray.hpp>`
+
+```c++
+template<std::size_t N>
+struct index_range;
+```
+
+Represents a range of indices, for creating a slice when indexing into an array. Either from the start of an array dimension to the end of an array dimension (`index_range<0>`), from a specified start to the end of an array dimension (`index_range<1>`), or from a specified start to a specified end (`index_range<2>`).
+
+Non-member functions
+--------------------
+
+|||
+------------- | --------------------------------------------------
+[r](r.md#top) | convenience function for creating an `index_range`
+
+Example
+-------
+
+```c++
+#include <vt/ndarray/container.hpp>
+#include <iostream>
+
+int main() {
+    // Use the vt::r convenience function to reduce clutter when creating
+    // instances of vt::index_range when performing a slicing operation.
+    using vt::r;
+
+    const vt::ndarray<int, 3> a{{ 2, 3, 4 }, {
+        3, 1, 4, 1,
+        5, 9, 2, 6,
+        5, 3, 5, 8,
+
+        9, 7, 9, 3,
+        2, 3, 8, 4,
+        6, 2, 6, 4
+    }};
+
+    std::cout << a[1, r(1), r(1, 3)] << '\n';
+}
+```
+
+Output:
+
+```
+[[3,8],[2,6]]
+```

doc/vt/ndarray/indexer/readme.md

@@ -0,0 +1,16 @@
+vt::indexer
+===========
+
+- Defined in header `<vt/ndarray/index.hpp>`
+- Defined in header `<vt/ndarray.hpp>`
+
+```c++
+template<typename T>
+concept indexer =
+    std::convertible_to<T, std::size_t>
+    || std::is_same_v<T, vt::index_range<0>>
+    || std::is_same_v<T, vt::index_range<1>>
+    || std::is_same_v<T, vt::index_range<2>>;
+```
+
+The concept `indexer<T>` specifies that `T` is an object type that can be used to index into a `vt::ndview`/`vt::ndslice`/`vt::ndarray`.

doc/vt/ndarray/readme.md

@@ -5,6 +5,9 @@ This reference documents the API of the vt-ndarray library. Follow the links bel
 
 - [ndarray](container/readme.md#top)
 - [ndview](view/readme.md#top)
+- [ndslice](slice/readme.md#top)
+- [index_range](index-range/readme.md#top)
+- [indexer](indexer/readme.md#top)
 - [ndarray_allocator](allocator/readme.md#top)
 
 Notes