Add lazy traversal edge views

Author: Mik1810

include/nxpp/graph.hpp

@@ -1546,6 +1546,14 @@ class Graph {
      * @throws std::runtime_error If @p start is not present in the graph.
      */
     [[nodiscard]] auto bfs_edges(const NodeID& start) const;
+    /**
+     * @brief Returns a lazy input range over breadth-first-search tree edges.
+     *
+     * @param start Node ID used as the BFS root.
+     * @return A non-owning input range yielding `(parent, child)` tree-edge pairs.
+     * @throws std::runtime_error If @p start is not present in the graph.
+     */
+    [[nodiscard]] auto bfs_edges_view(const NodeID& start) const;
     /**
      * @brief Materializes the breadth-first-search tree rooted at @p start.
      *
@@ -1607,6 +1615,14 @@ class Graph {
      * @throws std::runtime_error If @p start is not present in the graph.
      */
     [[nodiscard]] auto dfs_edges(const NodeID& start) const;
+    /**
+     * @brief Returns a lazy input range over depth-first-search tree edges.
+     *
+     * @param start Node ID used as the DFS root.
+     * @return A non-owning input range yielding `(parent, child)` tree-edge pairs.
+     * @throws std::runtime_error If @p start is not present in the graph.
+     */
+    [[nodiscard]] auto dfs_edges_view(const NodeID& start) const;
     /**
      * @brief Materializes the depth-first-search tree rooted at @p start.
      *

include/nxpp/traversal.hpp

@@ -11,12 +11,197 @@
 #include <boost/graph/breadth_first_search.hpp>
 #include <boost/graph/depth_first_search.hpp>
 
+#include <iterator>
+#include <memory>
+#include <optional>
+#include <queue>
+#include <vector>
+
 #include "graph.hpp"
 
 namespace nxpp {
 
 namespace detail {
 
+enum class traversal_order {
+    bfs,
+    dfs
+};
+
+template <typename GraphWrapper, traversal_order Order>
+class traversal_edges_view {
+public:
+    using NodeID = typename GraphWrapper::NodeType;
+    using value_type = std::pair<NodeID, NodeID>;
+
+    traversal_edges_view(const GraphWrapper& graph, const NodeID& start) : graph(&graph), start(start) {}
+
+    class iterator {
+    public:
+        using iterator_category = std::input_iterator_tag;
+        using value_type = traversal_edges_view::value_type;
+        using difference_type = std::ptrdiff_t;
+        using reference = const value_type&;
+
+        iterator() = default;
+
+        iterator(const GraphWrapper& graph, const NodeID& start)
+            : state(std::make_shared<traversal_state>(graph, start)) {
+            advance();
+        }
+
+        reference operator*() const {
+            return *state->current;
+        }
+
+        const value_type* operator->() const {
+            return &*state->current;
+        }
+
+        iterator& operator++() {
+            advance();
+            return *this;
+        }
+
+        void operator++(int) {
+            ++(*this);
+        }
+
+        friend bool operator==(const iterator& it, std::default_sentinel_t) {
+            return !it.state || it.state->done;
+        }
+
+        friend bool operator==(std::default_sentinel_t sentinel, const iterator& it) {
+            return it == sentinel;
+        }
+
+    private:
+        using GraphType = typename GraphWrapper::GraphType;
+        using VertexDesc = typename GraphWrapper::VertexDesc;
+        using OutEdgeIterator = typename boost::graph_traits<GraphType>::out_edge_iterator;
+
+        struct edge_cursor {
+            VertexDesc vertex;
+            OutEdgeIterator current;
+            OutEdgeIterator end;
+        };
+
+        struct traversal_state {
+            traversal_state(const GraphWrapper& graph, const NodeID& start)
+                : graph(&graph),
+                  colors(boost::num_vertices(graph.get_impl()), boost::white_color),
+                  current(std::nullopt),
+                  done(false) {
+                const auto start_vertex = graph.get_id_to_bgl_map().at(start);
+                colors[graph.get_vertex_index(start_vertex)] = boost::gray_color;
+                if constexpr (Order == traversal_order::bfs) {
+                    bfs_queue.push(start_vertex);
+                } else {
+                    push_dfs_vertex(start_vertex);
+                }
+            }
+
+            void push_dfs_vertex(VertexDesc vertex) {
+                auto [edge_it, edge_end] = boost::out_edges(vertex, graph->get_impl());
+                dfs_stack.push_back(edge_cursor{vertex, edge_it, edge_end});
+            }
+
+            const GraphWrapper* graph;
+            std::vector<boost::default_color_type> colors;
+            std::queue<VertexDesc> bfs_queue;
+            std::optional<edge_cursor> bfs_cursor;
+            std::vector<edge_cursor> dfs_stack;
+            std::optional<value_type> current;
+            bool done;
+        };
+
+        void advance() {
+            if (!state || state->done) {
+                return;
+            }
+
+            state->current.reset();
+            if constexpr (Order == traversal_order::bfs) {
+                advance_bfs();
+            } else {
+                advance_dfs();
+            }
+        }
+
+        void advance_bfs() {
+            while (!state->bfs_queue.empty()) {
+                if (!state->bfs_cursor.has_value()) {
+                    const auto vertex = state->bfs_queue.front();
+                    auto [edge_it, edge_end] = boost::out_edges(vertex, state->graph->get_impl());
+                    state->bfs_cursor = edge_cursor{vertex, edge_it, edge_end};
+                }
+
+                while (state->bfs_cursor->current != state->bfs_cursor->end) {
+                    const auto edge = *state->bfs_cursor->current;
+                    ++state->bfs_cursor->current;
+                    const auto child = boost::target(edge, state->graph->get_impl());
+                    const auto child_index = state->graph->get_vertex_index(child);
+                    if (state->colors[child_index] == boost::white_color) {
+                        state->colors[child_index] = boost::gray_color;
+                        state->bfs_queue.push(child);
+                        state->current = value_type{
+                            state->graph->get_node_id(state->bfs_cursor->vertex),
+                            state->graph->get_node_id(child)
+                        };
+                        return;
+                    }
+                }
+
+                state->colors[state->graph->get_vertex_index(state->bfs_cursor->vertex)] = boost::black_color;
+                state->bfs_queue.pop();
+                state->bfs_cursor.reset();
+            }
+
+            state->done = true;
+        }
+
+        void advance_dfs() {
+            while (!state->dfs_stack.empty()) {
+                auto& cursor = state->dfs_stack.back();
+                while (cursor.current != cursor.end) {
+                    const auto edge = *cursor.current;
+                    ++cursor.current;
+                    const auto child = boost::target(edge, state->graph->get_impl());
+                    const auto child_index = state->graph->get_vertex_index(child);
+                    if (state->colors[child_index] == boost::white_color) {
+                        state->colors[child_index] = boost::gray_color;
+                        state->current = value_type{
+                            state->graph->get_node_id(cursor.vertex),
+                            state->graph->get_node_id(child)
+                        };
+                        state->push_dfs_vertex(child);
+                        return;
+                    }
+                }
+
+                state->colors[state->graph->get_vertex_index(cursor.vertex)] = boost::black_color;
+                state->dfs_stack.pop_back();
+            }
+
+            state->done = true;
+        }
+
+        std::shared_ptr<traversal_state> state;
+    };
+
+    iterator begin() const {
+        return iterator(*graph, start);
+    }
+
+    std::default_sentinel_t end() const {
+        return {};
+    }
+
+private:
+    const GraphWrapper* graph;
+    NodeID start;
+};
+
 template <typename NodeID, typename EdgeWeight, bool Directed, typename EdgeRange>
 Graph<NodeID, EdgeWeight, Directed> build_tree_from_edges(const NodeID& root, const EdgeRange& edges) {
     Graph<NodeID, EdgeWeight, Directed> tree;
@@ -381,6 +566,15 @@ auto Graph<NodeID, EdgeWeight, Directed, Multi, Weighted, OutEdgeSelector, Verte
     return edges;
 }
 
+template <typename NodeID, typename EdgeWeight, bool Directed, bool Multi, bool Weighted, typename OutEdgeSelector, typename VertexSelector>
+auto Graph<NodeID, EdgeWeight, Directed, Multi, Weighted, OutEdgeSelector, VertexSelector>::bfs_edges_view(const NodeID& start) const {
+    if (!has_node(start)) {
+        throw std::runtime_error("Traversal failed: start node not found.");
+    }
+
+    return detail::traversal_edges_view<Graph, detail::traversal_order::bfs>(*this, start);
+}
+
 template <typename NodeID, typename EdgeWeight, bool Directed, bool Multi, bool Weighted, typename OutEdgeSelector, typename VertexSelector>
 auto Graph<NodeID, EdgeWeight, Directed, Multi, Weighted, OutEdgeSelector, VertexSelector>::bfs_tree(const NodeID& start) const {
     if (!has_node(start)) {
@@ -455,6 +649,15 @@ auto Graph<NodeID, EdgeWeight, Directed, Multi, Weighted, OutEdgeSelector, Verte
     return edges;
 }
 
+template <typename NodeID, typename EdgeWeight, bool Directed, bool Multi, bool Weighted, typename OutEdgeSelector, typename VertexSelector>
+auto Graph<NodeID, EdgeWeight, Directed, Multi, Weighted, OutEdgeSelector, VertexSelector>::dfs_edges_view(const NodeID& start) const {
+    if (!has_node(start)) {
+        throw std::runtime_error("Traversal failed: start node not found.");
+    }
+
+    return detail::traversal_edges_view<Graph, detail::traversal_order::dfs>(*this, start);
+}
+
 template <typename NodeID, typename EdgeWeight, bool Directed, bool Multi, bool Weighted, typename OutEdgeSelector, typename VertexSelector>
 auto Graph<NodeID, EdgeWeight, Directed, Multi, Weighted, OutEdgeSelector, VertexSelector>::dfs_tree(const NodeID& start) const {
     if (!has_node(start)) {

tests/test_edge_cases.cpp

@@ -3,6 +3,7 @@
 #include <iostream>
 #include <iterator>
 #include <limits>
+#include <ranges>
 #include <stdexcept>
 #include <string>
 #include <type_traits>
@@ -78,12 +79,77 @@ void test_missing_node_operations_throw() {
         [&] { (void)graph.bfs_edges("Milan"); },
         "Traversal failed: start node not found.",
         "bfs_edges() on a missing start node should report the standardized traversal error");
+    expect_runtime_error_message(
+        [&] { (void)graph.bfs_edges_view("Milan"); },
+        "Traversal failed: start node not found.",
+        "bfs_edges_view() on a missing start node should report the standardized traversal error");
+    expect_runtime_error_message(
+        [&] { (void)graph.dfs_edges_view("Milan"); },
+        "Traversal failed: start node not found.",
+        "dfs_edges_view() on a missing start node should report the standardized traversal error");
     expect_runtime_error_message(
         [&] { (void)graph.shortest_path("Rome", "Milan"); },
         "Shortest-path lookup failed: source or target node not found.",
         "shortest_path() with a missing target should report the standardized shortest-path lookup error");
 }
 
+void test_traversal_edge_views_match_eager_edges() {
+    nxpp::DiGraph graph;
+    graph.add_edge("A", "B");
+    graph.add_edge("A", "C");
+    graph.add_edge("B", "D");
+    graph.add_edge("C", "E");
+
+    auto bfs_view = graph.bfs_edges_view("A");
+    auto dfs_view = graph.dfs_edges_view("A");
+
+    static_assert(std::ranges::input_range<decltype(bfs_view)>);
+    static_assert(std::ranges::input_range<decltype(dfs_view)>);
+
+    std::vector<std::pair<std::string, std::string>> bfs_edges;
+    for (const auto& edge : bfs_view) {
+        bfs_edges.push_back(edge);
+    }
+
+    std::vector<std::pair<std::string, std::string>> dfs_edges;
+    for (const auto& edge : dfs_view) {
+        dfs_edges.push_back(edge);
+    }
+
+    expect(bfs_edges == graph.bfs_edges("A"), "bfs_edges_view should yield BFS tree edges in eager order");
+    expect(dfs_edges == graph.dfs_edges("A"), "dfs_edges_view should yield DFS tree edges in eager order");
+
+    std::vector<std::pair<std::string, std::string>> first_two_bfs;
+    for (const auto& edge : graph.bfs_edges_view("A") | std::views::take(2)) {
+        first_two_bfs.push_back(edge);
+    }
+
+    const auto eager_bfs = graph.bfs_edges("A");
+    expect(first_two_bfs.size() == 2, "bfs_edges_view should compose with std::views::take");
+    expect(first_two_bfs[0] == eager_bfs[0] && first_two_bfs[1] == eager_bfs[1],
+           "taken BFS view edges should match the eager prefix");
+
+    nxpp::Graph<> undirected_graph;
+    undirected_graph.add_edge("A", "B");
+    undirected_graph.add_edge("A", "C");
+    undirected_graph.add_edge("B", "D");
+
+    std::vector<std::pair<std::string, std::string>> undirected_bfs_edges;
+    for (const auto& edge : undirected_graph.bfs_edges_view("A")) {
+        undirected_bfs_edges.push_back(edge);
+    }
+
+    std::vector<std::pair<std::string, std::string>> undirected_dfs_edges;
+    for (const auto& edge : undirected_graph.dfs_edges_view("A")) {
+        undirected_dfs_edges.push_back(edge);
+    }
+
+    expect(undirected_bfs_edges == undirected_graph.bfs_edges("A"),
+           "undirected bfs_edges_view should yield tree edges in eager order");
+    expect(undirected_dfs_edges == undirected_graph.dfs_edges("A"),
+           "undirected dfs_edges_view should yield tree edges in eager order");
+}
+
 void test_disconnected_shortest_paths_preserve_unreachable_state() {
     nxpp::WeightedGraphStr graph;
     graph.add_edge("A", "B", 2.0);
@@ -438,6 +504,7 @@ int main() {
         {"empty graph reports empty collections", test_empty_graph_reports_empty_collections},
         {"singleton graph has no neighbors or traversal edges", test_singleton_graph_has_no_neighbors_or_traversal_edges},
         {"missing node operations throw", test_missing_node_operations_throw},
+        {"traversal edge views match eager edges", test_traversal_edge_views_match_eager_edges},
         {"disconnected shortest paths preserve unreachable state", test_disconnected_shortest_paths_preserve_unreachable_state},
         {"shortest path WeightMode options", test_shortest_path_weight_mode_options},
         {"2-SAT satisfiable and unsatisfiable formulas", test_two_sat_satisfiable_and_unsatisfiable_formulas},