Merge pull request #46 from purpleprotocol/feature/42/insert-edge-cycle-check

Added Graph::add_edge_check_cycle() method

Author: octavonce

.travis.yml

@@ -15,7 +15,7 @@ git:
   depth: 10
 
 before_script:
-  - chmod +x benches-compare.sh
+  - if [ "$TRAVIS_RUST_VERSION" == "nightly" ]; then chmod +x benches-compare.sh; fi
 
 script:
   - cargo build --verbose --all --features "dot"
@@ -28,4 +28,4 @@ script:
     fi
 
 after_script:
-  - ./benches-compare.sh
+  - if [ "$TRAVIS_RUST_VERSION" == "nightly" ]; ./benches-compare.sh; fi

benches/benchmark.rs

@@ -1073,6 +1073,44 @@ fn bench_others(c: &mut Criterion) {
             }
         })
     });
+    c.bench_function("add_edge_cycle_check_10", |b| {
+        let mut graph: Graph<usize> = Graph::new();
+        b.iter(|| {
+            let mut v1 = graph.add_vertex(0);
+
+            for i in 1..=10 {
+                let v2 = graph.add_vertex(i);
+                graph.add_edge_check_cycle(&v1, &v2);
+                v1 = v2.clone();
+            }
+        })
+    });
+
+    c.bench_function("add_edge_cycle_check_100", |b| {
+        let mut graph: Graph<usize> = Graph::new();
+        b.iter(|| {
+            let mut v1 = graph.add_vertex(0);
+
+            for i in 1..=100 {
+                let v2 = graph.add_vertex(i);
+                graph.add_edge_check_cycle(&v1, &v2);
+                v1 = v2.clone();
+            }
+        })
+    });
+    #[cfg(feature = "sbench")]
+    c.bench_function("add_edge_cycle_check_m", |b| {
+        let mut graph: Graph<usize> = Graph::new();
+        b.iter(|| {
+            let mut v1 = graph.add_vertex(0);
+
+            for i in 1..=10_000_000 {
+                let v2 = graph.add_vertex(i);
+                graph.add_edge_check_cycle(&v1, &v2);
+                v1 = v2.clone();
+            }
+        })
+    });
     c.bench_function("add_vertex_10", |b| {
         let mut graph: Graph<usize> = Graph::new();
         b.iter(|| {

src/graph.rs

@@ -47,6 +47,10 @@ pub enum GraphErr {
     /// The given weight is invalid
     InvalidWeight,
 
+    /// The operation cannot be performed as it will
+    /// create a cycle in the graph.
+    CycleError,
+
     #[cfg(feature = "dot")]
     /// Could not render .dot file
     CouldNotRender,
@@ -292,7 +296,41 @@ impl<T> Graph<T> {
             return Ok(());
         }
 
-        self.do_add_edge(a, b, 0.0)
+        self.do_add_edge(a, b, 0.0, false)
+    }
+
+    /// Attempts to place a new edge in the graph, checking if the specified
+    /// edge will create a cycle in the graph. If it does, this operation will fail.
+    /// 
+    /// Note that this operation has a bigger performance hit than `Graph::add_edge()`.
+    /// 
+    /// /// ## Example
+    /// ```rust
+    /// use graphlib::{Graph, GraphErr, VertexId};
+    ///
+    /// let mut graph: Graph<usize> = Graph::new();
+    ///
+    /// // Id of vertex that is not place in the graph
+    /// let id = VertexId::random();
+    ///
+    /// let v1 = graph.add_vertex(1);
+    /// let v2 = graph.add_vertex(2);
+    ///
+    /// // Adding an edge is idempotent
+    /// graph.add_edge_check_cycle(&v1, &v2);
+    /// graph.add_edge_check_cycle(&v1, &v2);
+    /// graph.add_edge_check_cycle(&v1, &v2);
+    ///
+    /// // Fails on adding an edge which creates
+    /// // a cycle in the graph.
+    /// assert_eq!(graph.add_edge_check_cycle(&v2, &v1), Err(GraphErr::CycleError));
+    /// ```
+    pub fn add_edge_check_cycle(&mut self, a: &VertexId, b: &VertexId) -> Result<(), GraphErr> {
+        if self.has_edge(a, b) {
+            return Ok(());
+        }
+
+        self.do_add_edge(a, b, 0.0, true)
     }
 
     /// Attempts to place a new edge in the graph.
@@ -330,7 +368,7 @@ impl<T> Graph<T> {
             return Err(GraphErr::InvalidWeight);
         }
 
-        self.do_add_edge(a, b, weight)
+        self.do_add_edge(a, b, weight, false)
     }
 
     /// Returns the weight of the specified edge
@@ -1284,7 +1322,7 @@ impl<T> Graph<T> {
 
     #[cfg(feature = "dot")]
     /// Creates a file with the dot representation of the graph.
-    /// This method requires the `dot` feature.
+    /// This method requires the `dot` crate feature.
     ///
     /// ## Example
     /// ```rust
@@ -1332,6 +1370,8 @@ impl<T> Graph<T> {
 
     #[cfg(feature = "dot")]
     /// Labels the vertex with the given id. Returns the old label if successful.
+    /// 
+    /// This method requires the `dot` crate feature.
     ///
     /// ## Example
     /// ```rust
@@ -1365,6 +1405,8 @@ impl<T> Graph<T> {
 
     #[cfg(feature = "dot")]
     /// Retrieves the label of the vertex with the given id.
+    /// 
+    /// This method requires the `dot` crate feature.
     ///
     /// This function will return a default label if no label is set. Returns
     /// `None` if there is no vertex associated with the given id in the graph.
@@ -1399,6 +1441,8 @@ impl<T> Graph<T> {
 
     #[cfg(feature = "dot")]
     /// Maps each label that is placed on a vertex to a new label.
+    /// 
+    /// This method requires the `dot` crate feature.
     ///
     /// ```rust
     /// use std::collections::HashMap;
@@ -1454,7 +1498,7 @@ impl<T> Graph<T> {
         }
     }
 
-    fn do_add_edge(&mut self, a: &VertexId, b: &VertexId, weight: f32) -> Result<(), GraphErr> {
+    fn do_add_edge(&mut self, a: &VertexId, b: &VertexId, weight: f32, check_cycle: bool) -> Result<(), GraphErr> {
         let id_ptr1 = if self.vertices.get(a).is_some() {
             *a
         } else {
@@ -1497,10 +1541,33 @@ impl<T> Graph<T> {
         }
 
         // Remove outbound vertex from roots
-        self.roots.remove(&b);
+        let was_root = self.roots.remove(&b);
 
         // Remove inbound vertex from tips
-        self.tips.remove(&a);
+        let was_tip = self.tips.remove(&a);
+
+        let mut is_cyclic = false;
+
+        if check_cycle {
+            let mut dfs = Dfs::new(&self);
+            is_cyclic = dfs.is_cyclic();
+        }
+
+        // Roll-back changes if cycle check succeeds
+        if is_cyclic {
+            // Remove from edge table
+            self.remove_edge(a, b);
+
+            if was_root {
+                self.roots.insert(b.clone());
+            }
+
+            if was_tip {
+                self.tips.insert(a.clone());
+            }
+
+            return Err(GraphErr::CycleError);
+        }
 
         Ok(())
     }
@@ -1698,4 +1765,33 @@ mod tests {
             }
         }
     }
+
+    #[test]
+    fn test_add_edge_cycle_check() {
+        let mut graph: Graph<usize> = Graph::new();
+    
+        // Id of vertex that is not place in the graph
+        let id = VertexId::random();
+    
+        let v1 = graph.add_vertex(1);
+        let v2 = graph.add_vertex(2);
+    
+        // Adding an edge is idempotent
+        graph.add_edge_check_cycle(&v1, &v2).unwrap();
+        graph.add_edge_check_cycle(&v1, &v2).unwrap();
+        graph.add_edge_check_cycle(&v1, &v2).unwrap();
+
+        let mut graph2 = graph.clone();
+    
+        // Fails on adding an edge which creates
+        // a cycle in the graph.
+        assert_eq!(graph2.add_edge_check_cycle(&v2, &v1), Err(GraphErr::CycleError));
+
+        // Check that the graph state has rolled back
+        assert_eq!(graph.edges, graph2.edges);
+        assert_eq!(graph.roots, graph2.roots);
+        assert_eq!(graph.tips, graph2.tips);
+        assert_eq!(graph.inbound_table, graph2.inbound_table);
+        assert_eq!(graph.outbound_table, graph2.outbound_table);
+    }
 }