flat_matrix alignment: span -> subrange

Author: SpectraL519

include/gl/types/flat_jagged_vector.hpp

@@ -13,6 +13,8 @@
 #include <stdexcept>
 #include <vector>
 
+// TODO: use std::ranges::subrange instead of std::span
+
 namespace gl {
 
 /// @brief A flattened 2D vector (jagged array) providing efficient storage for variable-length segments.

include/gl/types/flat_matrix.hpp

@@ -35,20 +35,22 @@ class flat_matrix {
     using value_type = T;
     /// @brief Unsigned integral type used for sizes and indices
     using size_type = std::size_t;
+    /// @brief The underlying contiguous storage container
+    using container_type = std::vector<value_type>;
     /// @brief Reference to an element
-    using reference = value_type&;
+    using reference = typename container_type::reference;
     /// @brief Const reference to an element
-    using const_reference = const value_type&;
-    /// @brief Span type representing a non-owning uniform row of elements
-    using row_type = std::span<value_type>;
-    /// @brief Const span type representing a non-owning uniform const row of elements
-    using const_row_type = std::span<const value_type>;
+    using const_reference = typename container_type::const_reference;
+    /// @brief Subrange type representing a non-owning uniform row of elements
+    using row_type = std::ranges::subrange<typename container_type::iterator>;
+    /// @brief Const subrange type representing a non-owning uniform const row of elements
+    using const_row_type = std::ranges::subrange<typename container_type::const_iterator>;
 
     // --- iterators ---
 
     /// @brief Random access iterator over the rows of the `flat_matrix`.
     ///
-    /// This iterator dereferences to a `row_type` (span of elements representing a single matrix row),
+    /// This iterator dereferences to a `row_type` (subrange of elements representing a single matrix row),
     /// allowing efficient iteration and random access. It calculates the memory offsets mathematically
     /// based on the column dimension.
     ///
@@ -57,44 +59,48 @@ class flat_matrix {
     /// @warning Invalidated when the `flat_matrix` structural dimensions are modified or memory is reallocated.
     template <bool Const>
     class row_iterator {
-        using data_ptr_type = std::conditional_t<Const, const T*, T*>;
+        using data_iter_type = std::conditional_t<
+            Const,
+            typename container_type::const_iterator,
+            typename container_type::iterator>;
 
     public:
         /// @brief Satisfies random access iterator concept
         using iterator_concept = std::random_access_iterator_tag;
         /// @brief Legacy iterator category (random access)
         using iterator_category = std::random_access_iterator_tag;
-        /// @brief Type of row this iterator dereferences to (span or const span)
+        /// @brief Type of row this iterator dereferences to (subrange or const subrange)
         using value_type = std::conditional_t<Const, const_row_type, row_type>;
         /// @brief Signed integral difference type
         using difference_type = std::ptrdiff_t;
         /// @brief Pointer type (void because iterators dereference to spans)
         using pointer = void;
-        /// @brief Reference type (span of elements)
+        /// @brief Reference type (subrange of elements)
         using reference = value_type;
 
         /// @brief Default constructor creates a null iterator
         row_iterator() = default;
 
         /// @brief Constructs an iterator pointing to a specific row.
-        /// @param data_ptr Pointer to the underlying flat element data
+        /// @param data_iter Iterator to the underlying flat element data
         /// @param n_cols The number of columns in the matrix
         /// @param row_idx The index of the row this iterator currently points to
-        row_iterator(data_ptr_type data_ptr, size_type n_cols, size_type row_idx) noexcept
-        : _data_ptr(data_ptr), _row_size(n_cols), _row_idx(row_idx) {}
+        row_iterator(data_iter_type data_iter, size_type n_cols, size_type row_idx) noexcept
+        : _data_iter(data_iter), _row_size(n_cols), _row_idx(row_idx) {}
 
         /// @brief Implicit conversion from mutable to const iterator
         /// @return A const iterator pointing to the same row
         operator row_iterator<true>() const noexcept
         requires(not Const)
         {
-            return row_iterator<true>(this->_data_ptr, this->_row_size, this->_row_idx);
+            return row_iterator<true>(this->_data_iter, this->_row_size, this->_row_idx);
         }
 
         /// @brief Dereferences the iterator to the current row.
-        /// @return A span representing the row at the current position
+        /// @return A subrange representing the row at the current position
         [[nodiscard]] reference operator*() const noexcept {
-            return reference(this->_data_ptr + this->_row_idx * this->_row_size, this->_row_size);
+            const auto row_beg = this->_data_iter + this->_row_idx * this->_row_size;
+            return reference(row_beg, row_beg + this->_row_size);
         }
 
         /// @brief Random access to a row at an offset from the current position.
@@ -206,7 +212,7 @@ class flat_matrix {
         }
 
     private:
-        data_ptr_type _data_ptr{nullptr};
+        data_iter_type _data_iter;
         size_type _row_size{0uz};
         size_type _row_idx{0uz};
     };
@@ -439,7 +445,7 @@ class flat_matrix {
             return;
         }
 
-        std::vector<value_type> new_data(new_rows * new_cols, value);
+        container_type new_data(new_rows * new_cols, value);
         const auto min_rows = std::min(this->_n_rows, new_rows);
         const auto min_cols = std::min(this->_n_cols, new_cols);
 
@@ -474,20 +480,22 @@ class flat_matrix {
 
     /// @brief Returns the row at the given index without bounds checking.
     /// @param r The index of the row to access
-    /// @return A span representing the row at index r
+    /// @return A subrange representing the row at index r
     /// @pre `r < n_rows()`; otherwise Undefined Behavior
     /// @warning No bounds checking is performed for performance.
     [[nodiscard]] row_type operator[](size_type r) {
-        return row_type(this->_data.data() + r * this->_n_cols, this->_n_cols);
+        const auto row_beg = this->_data.begin() + r * this->_n_cols;
+        return row_type(row_beg, row_beg + this->_n_cols);
     }
 
     /// @brief Returns a const row at the given index without bounds checking.
     /// @param r The index of the row to access
-    /// @return A const span representing the row at index r
+    /// @return A const subrange representing the row at index r
     /// @pre `r < n_rows()`; otherwise Undefined Behavior
     /// @warning No bounds checking is performed.
     [[nodiscard]] const_row_type operator[](size_type r) const {
-        return const_row_type(this->_data.data() + r * this->_n_cols, this->_n_cols);
+        const auto row_beg = this->_data.begin() + r * this->_n_cols;
+        return const_row_type(row_beg, row_beg + this->_n_cols);
     }
 
     /// @brief Returns a reference to an element without bounds checking.
@@ -512,7 +520,7 @@ class flat_matrix {
 
     /// @brief Returns the row at the given index with bounds checking.
     /// @param r The index of the row
-    /// @return A span representing the row at index r
+    /// @return A subrange representing the row at index r
     /// @exception std::out_of_range If `r >= n_rows()`
     [[nodiscard]] row_type at(size_type r) {
         this->_check_row(r);
@@ -521,7 +529,7 @@ class flat_matrix {
 
     /// @brief Returns a const row at the given index with bounds checking.
     /// @param r The index of the row
-    /// @return A const span representing the row at index r
+    /// @return A const subrange representing the row at index r
     /// @exception std::out_of_range If `r >= n_rows()`
     [[nodiscard]] const_row_type at(size_type r) const {
         this->_check_row(r);
@@ -551,60 +559,60 @@ class flat_matrix {
     }
 
     /// @brief Returns the first row without bounds checking.
-    /// @return A span representing the first row
+    /// @return A subrange representing the first row
     /// @pre Matrix must not be empty; otherwise Undefined Behavior
     /// @warning No bounds checking is performed.
     [[nodiscard]] row_type front() noexcept {
         return (*this)[0uz];
     }
 
     /// @brief Returns a const reference to the first row without bounds checking.
-    /// @return A const span representing the first row
+    /// @return A const subrange representing the first row
     /// @pre Matrix must not be empty; otherwise Undefined Behavior
     /// @warning No bounds checking is performed.
     [[nodiscard]] const_row_type front() const noexcept {
         return (*this)[0uz];
     }
 
     /// @brief Returns the last row without bounds checking.
-    /// @return A span representing the last row
+    /// @return A subrange representing the last row
     /// @pre Matrix must not be empty; otherwise Undefined Behavior
     /// @warning No bounds checking is performed.
     [[nodiscard]] row_type back() noexcept {
         return (*this)[this->_n_rows - 1uz];
     }
 
     /// @brief Returns a const reference to the last row without bounds checking.
-    /// @return A const span representing the last row
+    /// @return A const subrange representing the last row
     /// @pre Matrix must not be empty; otherwise Undefined Behavior
     /// @warning No bounds checking is performed.
     [[nodiscard]] const_row_type back() const noexcept {
         return (*this)[this->_n_rows - 1uz];
     }
 
     /// @brief Explicitly named alias for `front()` yielding the first row.
-    /// @return A span representing the first row
+    /// @return A subrange representing the first row
     /// @pre Matrix must not be empty; otherwise Undefined Behavior
     [[nodiscard]] row_type front_row() noexcept {
         return this->front();
     }
 
     /// @brief Explicitly named alias for `front()` yielding the first const row.
-    /// @return A const span representing the first row
+    /// @return A const subrange representing the first row
     /// @pre Matrix must not be empty; otherwise Undefined Behavior
     [[nodiscard]] const_row_type front_row() const noexcept {
         return this->front();
     }
 
     /// @brief Explicitly named alias for `back()` yielding the last row.
-    /// @return A span representing the last row
+    /// @return A subrange representing the last row
     /// @pre Matrix must not be empty; otherwise Undefined Behavior
     [[nodiscard]] row_type back_row() noexcept {
         return this->back();
     }
 
     /// @brief Explicitly named alias for `back()` yielding the last const row.
-    /// @return A const span representing the last row
+    /// @return A const subrange representing the last row
     /// @pre Matrix must not be empty; otherwise Undefined Behavior
     [[nodiscard]] const_row_type back_row() const noexcept {
         return this->back();
@@ -644,15 +652,15 @@ class flat_matrix {
 
     /// @brief Semantically symmetric alias for `at(r)` returning a bounds-checked row.
     /// @param r The row index
-    /// @return A span representing the row
+    /// @return A subrange representing the row
     /// @exception std::out_of_range If `r >= n_rows()`
     [[nodiscard]] row_type row(size_type r) {
         return this->at(r);
     }
 
     /// @brief Semantically symmetric alias for `at(r)` returning a bounds-checked const row.
     /// @param r The row index
-    /// @return A const span representing the row
+    /// @return A const subrange representing the row
     /// @exception std::out_of_range If `r >= n_rows()`
     [[nodiscard]] const_row_type row(size_type r) const {
         return this->at(r);
@@ -712,41 +720,46 @@ class flat_matrix {
         return this->_data.size();
     }
 
-    /// @brief Returns a span over all element data in flattened 1D form.
-    /// @return A span of all elements in the underlying `_data` array.
+    /// @brief Returns a subrange of all element data in flattened 1D form.
+    /// @return A subrange of all elements in the underlying `_data` array.
     [[nodiscard]] row_type data_view() noexcept {
         return row_type(this->_data);
     }
 
-    /// @brief Returns a const span over all element data in flattened 1D form.
-    /// @return A const span of all elements in the underlying `_data` array.
+    /// @brief Returns a const subrange of all element data in flattened 1D form.
+    /// @return A const subrange of all elements in the underlying `_data` array.
     [[nodiscard]] const_row_type data_view() const noexcept {
         return const_row_type(this->_data);
     }
 
     /// @brief Returns a reference to the underlying flat data container.
     /// @return A mutable reference to the underlying `_data` array.
     /// @warning Modifying this vector directly can fatally corrupt the matrix structure. Use for advanced operations only.
-    [[nodiscard]] std::vector<value_type>& data_storage() noexcept {
+    [[nodiscard]] container_type& data_storage() noexcept {
         return this->_data;
     }
 
     /// @brief Returns a const reference to the underlying flat data container.
     /// @return A const reference to the underlying `_data` array.
-    [[nodiscard]] const std::vector<value_type>& data_storage() const noexcept {
+    [[nodiscard]] const container_type& data_storage() const noexcept {
         return this->_data;
     }
 
     /// @brief Returns a raw pointer to the underlying flat data array.
     /// @return A raw pointer to the first element in the `_data` array.
-    /// @warning No bounds checking is performed.
-    [[nodiscard]] value_type* data_ptr() noexcept {
+    /// @warning Not available for boolean matrices.
+    [[nodiscard]] value_type* data_ptr() noexcept
+    requires(not std::same_as<value_type, bool>)
+    {
         return this->_data.data();
     }
 
     /// @brief Returns a const raw pointer to the underlying flat data array.
     /// @return A const raw pointer to the first element in the `_data` array.
-    [[nodiscard]] const value_type* data_ptr() const noexcept {
+    /// @warning Not available for boolean matrices.
+    [[nodiscard]] const value_type* data_ptr() const noexcept
+    requires(not std::same_as<value_type, bool>)
+    {
         return this->_data.data();
     }
 
@@ -1009,7 +1022,7 @@ class flat_matrix {
                 this->_n_rows = col_size;
 
             // pre-allocate new vector to guarantee O(RxC) structural shift, avoiding cubic complexity with multiple inserts
-            std::vector<value_type> new_data;
+            container_type new_data;
             new_data.reserve(this->_n_rows * (this->_n_cols + 1uz));
 
             auto r_it = std::ranges::begin(r);
@@ -1038,7 +1051,7 @@ class flat_matrix {
         else {
             // create a temporary sized range and recursively call the method to leverage the sized range logic,
             // ensuring strong exception guarantee for unsized input
-            this->insert_col(pos, std::ranges::to<std::vector<value_type>>(std::forward<R>(r)));
+            this->insert_col(pos, std::ranges::to<container_type>(std::forward<R>(r)));
         }
     }
 
@@ -1074,7 +1087,7 @@ class flat_matrix {
             ));
         }
 
-        std::vector<value_type> new_data;
+        container_type new_data;
         new_data.reserve(this->_n_rows * (this->_n_cols + 1uz));
 
         for (size_type r_idx = 0uz; r_idx < this->_n_rows; ++r_idx) {
@@ -1123,7 +1136,7 @@ class flat_matrix {
             return;
         }
 
-        std::vector<value_type> new_data;
+        container_type new_data;
         new_data.reserve(this->_n_rows * (this->_n_cols - 1uz));
 
         for (size_type r_idx = 0uz; r_idx < this->_n_rows; ++r_idx) {
@@ -1151,28 +1164,28 @@ class flat_matrix {
     /// @return Iterator to the first row
     /// @note Iterator invalidated by structural modifications
     [[nodiscard]] iterator begin() noexcept {
-        return iterator(this->_data.data(), this->_n_cols, 0uz);
+        return iterator(this->_data.begin(), this->_n_cols, 0uz);
     }
 
     /// @brief Returns a mutable iterator past the last row (end sentinel).
     /// @return Iterator one position past the last row
     /// @note Iterator invalidated by structural modifications
     [[nodiscard]] iterator end() noexcept {
-        return iterator(this->_data.data(), this->_n_cols, this->_n_rows);
+        return iterator(this->_data.begin(), this->_n_cols, this->_n_rows);
     }
 
     /// @brief Returns a const iterator to the first row.
     /// @return Const iterator to the first row
     /// @note Iterator invalidated by structural modifications
     [[nodiscard]] const_iterator begin() const noexcept {
-        return const_iterator(this->_data.data(), this->_n_cols, 0uz);
+        return const_iterator(this->_data.begin(), this->_n_cols, 0uz);
     }
 
     /// @brief Returns a const iterator past the last row (end sentinel).
     /// @return Const iterator one position past the last row
     /// @note Iterator invalidated by structural modifications
     [[nodiscard]] const_iterator end() const noexcept {
-        return const_iterator(this->_data.data(), this->_n_cols, this->_n_rows);
+        return const_iterator(this->_data.begin(), this->_n_cols, this->_n_rows);
     }
 
     /// @brief Returns a const iterator to the first row (explicit const form).
@@ -1289,7 +1302,7 @@ class flat_matrix {
 
     size_type _n_rows{0uz};
     size_type _n_cols{0uz};
-    std::vector<value_type> _data;
+    container_type _data;
 };
 
 } // namespace gl