[ENH] Augment coiteration algorithm to handle hashed level during conjunctive merge

include/xsparse/level_capabilities/co_iteration.hpp

@@ -7,7 +7,27 @@
 #include <stdexcept>
 
 namespace xsparse::level_capabilities
-{
+{   
+/*
+    The class template for Coiteration of level formats.
+
+    Uses a generic function object F to compare elements 
+    from different sequences at the same position and returns a tuple of the 
+    minimum index and the corresponding elements from each sequence.
+
+    Parameters
+    ----------
+    F : class
+        A function object that is used to compare two elements from different ranges.
+    IK : class
+        The type of the first element of each range.
+    PK : class
+        The type of the second element of each range.
+    Levels : Tuple of class
+        A tuple of level formats, where each level is itself a tuple of elements to be iterated.
+    Is : Tuple of class
+        A tuple of indices that is used to keep track of the current position in each level.
+    */ 
     template <class F, class IK, class PK, class Levels, class Is>
     class Coiterate;
 

test/source/coiteration_test.cpp

@@ -3,10 +3,13 @@
 #include <tuple>
 #include <vector>
 #include <functional>
+#include <set>
+#include <unordered_map>
 
 #include <xsparse/levels/compressed.hpp>
 #include <xsparse/levels/dense.hpp>
 #include <xsparse/levels/singleton.hpp>
+#include <xsparse/levels/hashed.hpp>
 #include <xsparse/version.h>
 
 #include <xsparse/util/container_traits.hpp>
@@ -193,3 +196,74 @@ TEST_CASE("Coiteration-Singleton-Singleton-Dense-Dense")
     }
     CHECK(fn(std::tuple(it1 == end1, it2 == end2, it3 == end3, it4 == end4)) == true);
 }
+
+TEST_CASE("Coiteration-Dense-Hashed-ConjunctiveMerge")
+{
+    constexpr uint8_t ZERO = 0;
+
+    std::unordered_map<uintptr_t, uintptr_t> const umap1{ { 0, 1 }, { 2, 0 }, { 1, 2 } };
+    std::vector<std::unordered_map<uintptr_t, uintptr_t>> const crd0{ umap1 };
+
+    // initialize the two levels to be coiterated
+    xsparse::levels::dense<std::tuple<>, uintptr_t, uintptr_t> s1{ 5 };
+    xsparse::levels::hashed<
+        std::tuple<>,
+        uintptr_t,
+        uintptr_t,
+        xsparse::util::container_traits<std::vector, std::set, std::unordered_map>,
+        xsparse::level_properties<false, false, false, false, false>>
+        h { 5, crd0 };
+
+    // define a conjunctive function
+    auto fn = [](std::tuple<bool, bool> t) constexpr
+    {
+        return (std::get<0>(t) && std::get<1>(t));
+    };
+
+    xsparse::level_capabilities::Coiterate<std::function<bool(std::tuple<bool, bool>)>,
+                                           uintptr_t,
+                                           uintptr_t,
+                                           std::tuple<decltype(s1), decltype(h)>,
+                                           std::tuple<>>
+        coiter(fn, s1, h);
+
+    auto it_helper1 = s1.iter_helper(std::make_tuple(), ZERO);
+    auto it1 = it_helper1.begin();
+    auto it_helper2 = h.iter_helper(ZERO);
+    auto it2 = it_helper2.begin();
+
+    auto end1 = it_helper1.end();
+    auto end2 = it_helper2.end();
+
+    // when co-iterating over levels that are unordered (i.e. hashed), then we use locate to check
+    // if the index exists in the hashed level. If not, then we skip it.
+    for (auto const [ik, pk_tuple] : coiter.coiter_helper(std::make_tuple(), ZERO))
+    {
+        // get the index and pointer from the levels involved in co-iteration
+        auto [i1, p1] = *it1;
+        auto [i2, p2] = *it2;
+
+        // should only iterate over the ordered level
+        uintptr_t l = i1;
+        CHECK(ik == l);
+
+        // check that neither level has reached the end
+        if (it1 != end1)
+        {
+            CHECK(ik == l);
+
+            if (i1 == l && h.locate(p1, i1) != std::nullopt)
+            {
+                CHECK(p1 == std::get<0>(pk_tuple).value());
+                CHECK(p2 == std::get<1>(pk_tuple).value());
+            }
+
+            // increment through the dense level always
+            ++it1;
+        }
+    }
+
+    // check that the constexpr function representing the coiteration is conjunctive
+    CHECK(fn(std::tuple(it1 == end1, it2 == end2)) == true);
+    CHECK(fn(std::tuple(it1 == end1, it2 != end2)) == false);
+}