add Topo::with_initials API (petgraph#585)

* add Topo::with_initials API

* filter nodes with incoming edges for Topo::with_initials API

* Clear up the docs

---------

Co-authored-by: Agustín Borgna <[email protected]>

Author: Lucian-4a25

src/visit/traversal.rs

@@ -344,6 +344,23 @@ where
         topo
     }
 
+    /// Create a new `Topo` with initial nodes.
+    ///
+    /// Nodes with incoming edges are ignored.
+    pub fn with_initials<G, I>(graph: G, initials: I) -> Self
+    where
+        G: IntoNeighborsDirected + Visitable<NodeId = N, Map = VM>,
+        I: IntoIterator<Item = N>,
+    {
+        Topo {
+            tovisit: initials
+                .into_iter()
+                .filter(|&n| graph.neighbors_directed(n, Incoming).next().is_none())
+                .collect(),
+            ordered: graph.visit_map(),
+        }
+    }
+
     fn extend_with_initials<G>(&mut self, g: G)
     where
         G: IntoNodeIdentifiers + IntoNeighborsDirected<NodeId = N>,

tests/graph.rs

@@ -1536,6 +1536,30 @@ fn toposort_generic() {
     println!("{:?}", gr);
     assert_is_topo_order(&gr, &order);
 
+    {
+        order.clear();
+        let init_nodes = gr.node_identifiers().filter(|n| {
+            gr.neighbors_directed(n.clone(), Direction::Incoming)
+                .next()
+                .is_none()
+        });
+        let mut topo = Topo::with_initials(&gr, init_nodes);
+        while let Some(nx) = topo.next(&gr) {
+            order.push(nx);
+        }
+        assert_is_topo_order(&gr, &order);
+    }
+
+    {
+        // test `with_initials` API using nodes with incoming edges
+        order.clear();
+        let mut topo = Topo::with_initials(&gr, gr.node_identifiers());
+        while let Some(nx) = topo.next(&gr) {
+            order.push(nx);
+        }
+        assert_is_topo_order(&gr, &order);
+    }
+
     {
         order.clear();
         let mut topo = Topo::new(&gr);

tests/quickcheck.rs

@@ -727,6 +727,35 @@ fn full_topo_generic() {
                 return false;
             }
         }
+
+        {
+            order.clear();
+            let init_nodes = gr.node_identifiers().filter(|n| {
+                gr.neighbors_directed(n.clone(), Direction::Incoming)
+                    .next()
+                    .is_none()
+            });
+            let mut topo = Topo::with_initials(&gr, init_nodes);
+            while let Some(nx) = topo.next(&gr) {
+                order.push(nx);
+            }
+            if !is_topo_order(&gr, &order) {
+                println!("{:?}", gr);
+                return false;
+            }
+        }
+
+        {
+            order.clear();
+            let mut topo = Topo::with_initials(&gr, gr.node_identifiers());
+            while let Some(nx) = topo.next(&gr) {
+                order.push(nx);
+            }
+            if !is_topo_order(&gr, &order) {
+                println!("{:?}", gr);
+                return false;
+            }
+        }
         true
     }
     quickcheck::quickcheck(prop_generic as fn(_) -> bool);