1 files changed, 53 insertions, 0 deletions
diff --git a/graph/src/builder.rs b/graph/src/builder.rs
new file mode 100644
index 0000000..ce85cce
--- /dev/null
+++ b/graph/src/builder.rs
@@ -0,0 +1,53 @@
+//! This file defines the expected behaviours of a builder of graphs.
+
+use crate::{error::Error, Graph};
+
+/// A builder is actually just a graph that can be altered in more
+/// ways than an extension graph can.  It should not have any methods
+/// from the Graph trait, though, as we shall convert a builder to a
+/// normal final graph before using it.
+pub trait Builder: Default {
+    /// Some graphs are labelled.  This type should be the type of the
+    /// labels.
+    type Label;
+
+    /// The type of the result graph.
+    type Result: Graph;
+
+    /// Construct an empty builder with the capacity to hold a given
+    /// number of nodes.
+    ///
+    /// Implementations may ignore this method, where the default
+    /// implementation just calls `Default::default`.
+    #[inline]
+    fn with_capacity(_size: usize) -> Self {
+        Self::default()
+    }
+
+    /// Add a vertex without children.
+    fn add_vertex(&mut self) -> usize;
+
+    /// Add an edge from the source to the target.
+    fn add_edge(&mut self, source: usize, target: usize, label: Self::Label) -> Result<(), Error>;
+
+    /// Remove an edge from the source to the target.
+    ///
+    /// Since some graphs are labelled, the users are allowed to pass
+    /// a predicate to determine if an edge from the source to the
+    /// target should be removed.
+    fn remove_edge<F>(&mut self, source: usize, target: usize, predicate: F) -> Result<(), Error>
+    where
+        F: Fn(Self::Label) -> bool;
+
+    /// Convert the builder into a graph.
+    ///
+    /// This is the purpose of having a builder.
+    fn build(self) -> Self::Result;
+
+    /// Convert the builder into a graph using a reference.
+    ///
+    /// This is similar to [`build`][Builder::build], but takes an
+    /// immutable reference of the builder, so that the builder can
+    /// still be used later on.
+    fn build_ref(&self) -> Self::Result;
+}