depth_first_search: Return visitor by value

doc/depth_first_search.html

@@ -28,10 +28,10 @@ <H1><A NAME="sec:depth-first-search"></A><img src="figs/python.gif" alt="(Python
 
 <i>// non-named parameter version</i>
 template &lt;class Graph, class <a href="DFSVisitor.html">DFSVisitor</a>, class ColorMap&gt;
-void depth_first_search(const Graph&amp; g, DFSVisitor vis, ColorMap color)
+DFSVisitor depth_first_search(const Graph&amp; g, DFSVisitor vis, ColorMap color)
 
 template &lt;class Graph, class <a href="DFSVisitor.html">DFSVisitor</a>, class ColorMap&gt;
-void depth_first_search(const Graph&amp; g, DFSVisitor vis, ColorMap color,
+DFSVisitor depth_first_search(const Graph&amp; g, DFSVisitor vis, ColorMap color,
                         typename graph_traits&lt;Graph&gt;::vertex_descriptor start)
 
 </PRE>

doc/depth_first_visit.html

@@ -24,15 +24,15 @@ <H2><A NAME="sec:dfs"></A>
 <P>
 <PRE>
 template &lt;class <a href="./IncidenceGraph.html">IncidenceGraph</a>, class <a href="./DFSVisitor.html">DFSVisitor</a>, class ColorMap&gt;
-void depth_first_visit(IncidenceGraph& g,
+DFSVisitor depth_first_visit(IncidenceGraph& g,
   typename graph_traits&lt;IncidenceGraph&gt;::vertex_descriptor s,
-  DFSVisitor&amp; vis, ColorMap color)
+  DFSVisitor vis, ColorMap color)
 
 template &lt;class <a href="./IncidenceGraph.html">IncidenceGraph</a>, class <a href="./DFSVisitor.html">DFSVisitor</a>, class ColorMap,
           class TerminatorFunc&gt;
-void depth_first_visit(IncidenceGraph& g,
+DFSVisitor depth_first_visit(IncidenceGraph& g,
   typename graph_traits&lt;IncidenceGraph&gt;::vertex_descriptor s,
-  DFSVisitor&amp; vis, ColorMap color, TerminatorFunc func = TerminatorFunc())
+  DFSVisitor vis, ColorMap color, TerminatorFunc func = TerminatorFunc())
 </PRE>
 
 <P>

include/boost/graph/depth_first_search.hpp

@@ -263,7 +263,7 @@ namespace detail
 } // namespace detail
 
 template < class VertexListGraph, class DFSVisitor, class ColorMap >
-void depth_first_search(const VertexListGraph& g, DFSVisitor vis,
+DFSVisitor depth_first_search(const VertexListGraph& g, DFSVisitor vis,
     ColorMap color,
     typename graph_traits< VertexListGraph >::vertex_descriptor start_vertex)
 {
@@ -298,18 +298,19 @@ void depth_first_search(const VertexListGraph& g, DFSVisitor vis,
                 g, u, vis, color, detail::nontruth2());
         }
     }
+    return vis;
 }
 
 template < class VertexListGraph, class DFSVisitor, class ColorMap >
-void depth_first_search(
+DFSVisitor depth_first_search(
     const VertexListGraph& g, DFSVisitor vis, ColorMap color)
 {
     typedef typename boost::graph_traits< VertexListGraph >::vertex_iterator vi;
     std::pair< vi, vi > verts = vertices(g);
     if (verts.first == verts.second)
-        return;
+        return vis;
 
-    depth_first_search(g, vis, color, detail::get_default_starting_vertex(g));
+    return depth_first_search(g, vis, color, detail::get_default_starting_vertex(g));
 }
 
 template < class Visitors = null_visitor > class dfs_visitor
@@ -409,22 +410,24 @@ namespace graph
 BOOST_GRAPH_MAKE_OLD_STYLE_PARAMETER_FUNCTION(depth_first_search, 1)
 
 template < class IncidenceGraph, class DFSVisitor, class ColorMap >
-void depth_first_visit(const IncidenceGraph& g,
+DFSVisitor depth_first_visit(const IncidenceGraph& g,
     typename graph_traits< IncidenceGraph >::vertex_descriptor u,
     DFSVisitor vis, ColorMap color)
 {
     vis.start_vertex(u, g);
     detail::depth_first_visit_impl(g, u, vis, color, detail::nontruth2());
+    return vis;
 }
 
 template < class IncidenceGraph, class DFSVisitor, class ColorMap,
     class TerminatorFunc >
-void depth_first_visit(const IncidenceGraph& g,
+DFSVisitor depth_first_visit(const IncidenceGraph& g,
     typename graph_traits< IncidenceGraph >::vertex_descriptor u,
     DFSVisitor vis, ColorMap color, TerminatorFunc func = TerminatorFunc())
 {
     vis.start_vertex(u, g);
     detail::depth_first_visit_impl(g, u, vis, color, func);
+    return vis;
 }
 } // namespace boost
 

test/Jamfile.v2

@@ -44,6 +44,7 @@ alias graph_test_regular :
     [ run csr_graph_test.cpp : : : : : <variant>release ]
     [ run dag_longest_paths.cpp ]
     [ run dfs.cpp ]
+    [ run dfv_test.cpp ]
     [ run undirected_dfs.cpp ]
     [ compile dfs_cc.cpp ]
     [ compile dijkstra_cc.cpp ]

test/dfv_test.cpp

@@ -0,0 +1,96 @@
+//=======================================================================
+// Copyright 2022 Ralf Kohrt
+
+// Distributed under the Boost Software License, Version 1.0. (See
+// accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+//=======================================================================
+#include <boost/graph/adjacency_list.hpp>
+#include <boost/graph/depth_first_search.hpp>
+#include <boost/core/lightweight_test.hpp>
+
+using namespace boost;
+
+// Set up the vertex names
+enum vertex_id_t { u, v, w, x, y, z, N };
+
+
+struct counting_dfs_visitor
+{
+  template<typename Vertex, typename Graph>
+  void initialize_vertex(Vertex v, const Graph& g)
+  {
+    ++vertex_events;
+  }
+
+  template<typename Vertex, typename Graph>
+  void start_vertex(Vertex v, const Graph& g)
+  {
+    ++vertex_events;
+  }
+
+  template<typename Vertex, typename Graph>
+  void discover_vertex(Vertex v, const Graph& g)
+  {
+    ++vertex_events;
+  }
+
+  template<typename Edge, typename Graph>
+  void examine_edge(Edge e, const Graph& g)
+  {
+    ++seen_edges;
+  }
+
+  template<typename Edge, typename Graph>
+  void tree_edge(Edge e, const Graph& g)
+  {}
+
+  template<typename Edge, typename Graph>
+  void back_edge(Edge e, const Graph& g)
+  {}
+
+  template<typename Edge, typename Graph>
+  void forward_or_cross_edge(Edge e, const Graph& g)
+  {}
+
+  template<typename Vertex, typename Graph>
+  void finish_vertex(Vertex v, const Graph& g)
+  {
+    ++vertex_events;
+  }
+
+  size_t vertex_events = 0;
+  size_t seen_edges = 0;
+
+};
+
+void
+test_dfv_returns_copied_visitor()
+{
+  typedef adjacency_list<listS,
+                         vecS,
+                         undirectedS,
+                         // Vertex properties
+                         property<vertex_color_t, default_color_type> >
+    Graph;
+  typedef typename boost::property_map< Graph, boost::vertex_color_t >::type
+    ColorMap;
+
+  // Specify the edges in the graph
+  typedef std::pair<int, int> E;
+  E edge_array[] = { E(u, v), E(u, w), E(u, x), E(x, v), E(y, x),
+                     E(v, y), E(w, y), E(w, z), E(z, z) };
+  Graph g(edge_array, edge_array + sizeof(edge_array) / sizeof(E), N);
+
+  ColorMap color = get(boost::vertex_color, g);
+  counting_dfs_visitor visitor_copy = depth_first_visit(g, vertex(u, g), counting_dfs_visitor(), color);
+  BOOST_TEST(visitor_copy.vertex_events == 6u*2u + 1u); // discover_vertex + finish_vertex for each vertex and once start_vertex
+  BOOST_TEST(visitor_copy.seen_edges == 2u*9u);
+}
+
+int
+main(int argc, char* argv[])
+{
+  test_dfv_returns_copied_visitor();
+  return boost::report_errors();
+}