Free function, doc and basic example

3 files changed, 40 insertions, 21 deletions

diff --git a/src/Collapse/doc/intro_edge_collapse.h b/src/Collapse/doc/intro_edge_collapse.h
index 2b272a9e..81edd79f 100644
--- a/src/Collapse/doc/intro_edge_collapse.h
+++ b/src/Collapse/doc/intro_edge_collapse.h
@@ -76,9 +76,9 @@ namespace collapse {
  * 
  * \subsection edgecollapseexample Basic edge collapse
  * 
- * This example builds the `Flag_complex_edge_collapser` from a proximity graph represented as a list of
- * `Flag_complex_edge_collapser::Filtered_edge`.
- * Then it collapses edges and displays a new list of `Flag_complex_edge_collapser::Filtered_edge` (with less edges)
+ * This example calls `Gudhi::collapse::flag_complex_collapse_edges()` from a proximity graph represented as a list of
+ * `Filtered_edge`.
+ * Then it collapses edges and displays a new list of `Filtered_edge` (with less edges)
  * that will preserve the persistence homology computation.
  * 
  * \include Collapse/edge_collapse_basic_example.cpp
diff --git a/src/Collapse/example/edge_collapse_basic_example.cpp b/src/Collapse/example/edge_collapse_basic_example.cpp
index 69ce329e..1b3dc1b5 100644
--- a/src/Collapse/example/edge_collapse_basic_example.cpp
+++ b/src/Collapse/example/edge_collapse_basic_example.cpp
@@ -2,13 +2,13 @@
 
 #include <iostream>
 #include <vector>
+#include <tuple>
 
 int main() {
   // Type definitions
   using Filtration_value = float;
   using Vertex_handle = short;
-  using Flag_complex_edge_collapser = Gudhi::collapse::Flag_complex_edge_collapser<Vertex_handle, Filtration_value>;
-  using Filtered_edge = Flag_complex_edge_collapser::Filtered_edge;
+  using Filtered_edge = std::tuple<Vertex_handle, Vertex_handle, Filtration_value>;
   using Filtered_edge_list = std::vector<Filtered_edge>;
 
   //  1   2
@@ -25,16 +25,9 @@ int main() {
                               {0, 2, 2.},
                               {1, 3, 2.}};
 
-  Flag_complex_edge_collapser edge_collapser(graph);
+  auto remaining_edges = Gudhi::collapse::flag_complex_collapse_edges(graph);
 
-  Filtered_edge_list remaining_edges;
-  // Retrieve collapse edges from the output iterator
-  edge_collapser.process_edges(
-    [&remaining_edges](Vertex_handle u, Vertex_handle v, Filtration_value filtration) {
-        remaining_edges.emplace_back(u, v, filtration);
-      });
-
-  for (Filtered_edge filtered_edge_from_collapse : remaining_edges) {
+  for (auto filtered_edge_from_collapse : remaining_edges) {
     std::cout << "fn[" << std::get<0>(filtered_edge_from_collapse) << ", " << std::get<1>(filtered_edge_from_collapse)
               << "] = " << std::get<2>(filtered_edge_from_collapse) << std::endl;
   }
diff --git a/src/Collapse/include/gudhi/Flag_complex_edge_collapser.h b/src/Collapse/include/gudhi/Flag_complex_edge_collapser.h
index 9cd57d7e..981ec88d 100644
--- a/src/Collapse/include/gudhi/Flag_complex_edge_collapser.h
+++ b/src/Collapse/include/gudhi/Flag_complex_edge_collapser.h
@@ -12,11 +12,9 @@
 #ifndef FLAG_COMPLEX_EDGE_COLLAPSER_H_
 #define FLAG_COMPLEX_EDGE_COLLAPSER_H_
 
-#include <gudhi/graph_simplicial_complex.h>
 #include <gudhi/Debug_utils.h>
 
 #include <boost/functional/hash.hpp>
-#include <boost/graph/adjacency_list.hpp>
 #include <boost/iterator/iterator_facade.hpp>
 
 #include <Eigen/Sparse>
@@ -39,12 +37,11 @@ namespace Gudhi {
 
 namespace collapse {
 
-/**
+/** \private
+ * 
  * \class Flag_complex_edge_collapser
  * \brief Flag complex sparse matrix data structure.
  *
- * \ingroup collapse
- *
  * \details
  * This class stores a <a target="_blank" href="https://en.wikipedia.org/wiki/Clique_complex">Flag complex</a>
  * in an <a target="_blank" href="https://eigen.tuxfamily.org/dox/group__TutorialSparse.html">Eigen sparse matrix</a>.
@@ -296,7 +293,7 @@ class Flag_complex_edge_collapser {
    * `Flag_complex_edge_collapser::Filtered_edge`.
    */
   template<typename FilteredEdgeRange>
-  Flag_complex_edge_collapser(FilteredEdgeRange edges)
+  Flag_complex_edge_collapser(const FilteredEdgeRange& edges)
   : f_edge_vector_(std::begin(edges), std::end(edges)) { }
 
   /** \brief Performs edge collapse in a increasing sequence of the filtration value.
@@ -310,7 +307,7 @@ class Flag_complex_edge_collapser {
     // Sort edges
     auto sort_by_filtration = [](const Filtered_edge& edge_a, const Filtered_edge& edge_b) -> bool
     {
-      return (get<2>(edge_a) < get<2>(edge_b)); 
+      return (std::get<2>(edge_a) < std::get<2>(edge_b)); 
     };
 
 #ifdef GUDHI_USE_TBB
@@ -342,6 +339,35 @@ class Flag_complex_edge_collapser {
 
 };
 
+/** \brief Constructs a Flag complex from edges as an input, collapse edges and returns remaining edges.
+ *
+ * \fn auto Gudhi::collapse::flag_complex_collapse_edges(FilteredEdgeRange const& edges)
+ *
+ * \tparam FilteredEdgeRange furnishes `std::begin` and `std::end` methods and returns an iterator on a
+ * FilteredEdge of type `std::tuple<Vertex_handle, Vertex_handle, Filtration_value>`
+ *
+ * \ingroup edge_collapse
+ * 
+ */
+template<class FilteredEdgeRange> auto flag_complex_collapse_edges(const FilteredEdgeRange& edges) {
+  auto first_edge_itr = std::begin(edges);
+  auto first_vertex = std::get<0>(*first_edge_itr);
+  auto first_filt = std::get<2>(*first_edge_itr);
+  using Vertex_handle = decltype(first_vertex);
+  using Filtration_value = decltype(first_filt);
+  using Edge_collapser = Flag_complex_edge_collapser<Vertex_handle, Filtration_value>;
+  std::vector<typename Edge_collapser::Filtered_edge> remaining_edges;
+  if (first_edge_itr != std::end(edges)) {
+    Edge_collapser edge_collapser(edges);
+    edge_collapser.process_edges(
+      [&remaining_edges](Vertex_handle u, Vertex_handle v, Filtration_value filtration) {
+          // insert the edge
+          remaining_edges.emplace_back(u, v, filtration);
+        });
+  }
+  return remaining_edges;
+}
+
 }  // namespace collapse
 
 }  // namespace Gudhi