//! 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;
}