Package com.jgalgo.graph

Interface GraphBuilder

  • public interface GraphBuilder
    A builder for graphs.

    The builder is used to construct non-empty graphs. Differing from GraphFactory which create new empty graphs, the builder is used to add vertices and edges before actually creating the graph. This capability is required to create immutable graphs, but can also be used to build mutable graph and may gain a performance boost compared to creating an empty graph and adding the same vertices and edges.

    Author:
    Barak Ugav
    See Also:
    newUndirected(), newDirected(), IndexGraphBuilder, GraphFactory

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      int addEdge​(int source, int target)
      Add a new edge to the graph.
      void addEdge​(int source, int target, int edge)
      Add a new edge to the graph, with user-chosen identifier.
      default <E,​WeightsT extends Weights<E>>
      WeightsT      		 addEdgesWeights​(Object key, Class<? super E> type)
      Add a new weights container associated with the edges of the built graph.
      <E,​WeightsT extends Weights<E>>
      WeightsT      		 addEdgesWeights​(Object key, Class<? super E> type, E defVal)
      Add a new weights container associated with the edges of the built graph with default value.
      int addVertex()
      Add a new vertex to the graph.
      void addVertex​(int vertex)
      Add a new vertex to the graph, with user-chosen identifier.
      default <V,​WeightsT extends Weights<V>>
      WeightsT      		 addVerticesWeights​(Object key, Class<? super V> type)
      Add a new weights container associated with the vertices of the built graph.
      <V,​WeightsT extends Weights<V>>
      WeightsT      		 addVerticesWeights​(Object key, Class<? super V> type, V defVal)
      Add a new weights container associated with the vertices of built graph with default value.
      Graph build()
      Build a new immutable graph with the builder vertices and edges.
      Graph buildMutable()
      Build a new mutable graph with the builder vertices and edges.
      void clear()
      Clear the builder by removing all vertices and edges added to it.
      IntSet edges()
      Get the set of edges that were added to the graph.
      void expectedEdgesNum​(int edgesNum)
      Hint about the number of edges expected to be added to the builder.
      void expectedVerticesNum​(int verticesNum)
      Hint about the number of vertices expected to be added to the builder.
      <E,​WeightsT extends Weights<E>>
      WeightsT      		 getEdgesWeights​(Object key)
      Get the edges weights of some key.
      Set<Object> getEdgesWeightsKeys()
      Get the keys of all the associated edges weights.
      <V,​WeightsT extends Weights<V>>
      WeightsT      		 getVerticesWeights​(Object key)
      Get the vertices weights of some key.
      Set<Object> getVerticesWeightsKeys()
      Get the keys of all the associated vertices weights.
      static GraphBuilder newDirected()
      Create a new builder that builds directed graphs.
      static GraphBuilder newFrom​(Graph g)
      Create a new builder initialized with an existing graph vertices and edges, without copying the weights.
      static GraphBuilder newFrom​(Graph g, boolean copyWeights)
      Create a new builder initialized with an existing graph vertices and edges, with/without copying the weights.
      static GraphBuilder newUndirected()
      Create a new builder that builds undirected graphs.
      IntSet vertices()
      Get the set of vertices that were added to the graph.

    • Method Detail

      • vertices

        IntSet vertices()
        Get the set of vertices that were added to the graph.
        Returns:
        the graph vertices

      • edges

        IntSet edges()
        Get the set of edges that were added to the graph.
        Returns:
        the graph edges

      • addVertex

        int addVertex()
        Add a new vertex to the graph.

        The builder will choose identifier not used for any existing vertex, and will return it. It is also possible to add a new vertex and choose its identifier by using addVertex(int). Only one of addVertex() and addVertex(int) can be used during the construction of a graph.

        Returns:
        the new vertex identifier

      • addVertex

        void addVertex​(int vertex)
        Add a new vertex to the graph, with user-chosen identifier.

        This function is similar to addVertex(), but let the user to choose the the identifier of the new vertex. Only one of addVertex() and addVertex(int) can be used during the construction of a graph.

        Parameters:
        vertex - the new vertex identifier

      • addEdge

        int addEdge​(int source,
            int target)
        Add a new edge to the graph.

        The builder will choose identifier not used for any existing edge, and will return it. It is also possible to add a new edge and choose its identifier by using addEdge(int, int, int). Only one of addEdge(int, int) and addEdge(int, int, int) can be used during the construction of a graph.

        Parameters:
        source - the source vertex of the new edge
        target - the target vertex of the new edge
        Returns:
        the new edge identifier

      • addEdge

        void addEdge​(int source,
             int target,
             int edge)
        Add a new edge to the graph, with user-chosen identifier.

        This function is similar to addEdge(int, int), but let the user to choose the identifier of the new edge. Only one of addEdge(int, int) and addEdge(int, int, int) can be used during the construction of a graph.

        Parameters:
        source - the source vertex of the new edge
        target - the target vertex of the new edge
        edge - the identifier of the new edge

      • expectedVerticesNum

        void expectedVerticesNum​(int verticesNum)
        Hint about the number of vertices expected to be added to the builder.

        This method does not affect the built graph, only the builder itself.

        Parameters:
        verticesNum - the expected number of vertices to be added to the builder

      • expectedEdgesNum

        void expectedEdgesNum​(int edgesNum)
        Hint about the number of edges expected to be added to the builder.

        This method does not affect the built graph, only the builder itself.

        Parameters:
        edgesNum - the expected number of edges to be added to the builder

      • getVerticesWeights

        <V,​WeightsT extends Weights<V>> WeightsT getVerticesWeights​(Object key)
        Get the vertices weights of some key.

        See Weights for a complete documentation of the weights containers.

        Type Parameters:
        V - The weight data type
        WeightsT - the weights container, used to avoid casts of containers of primitive types
        Parameters:
        key - some key of the weights, could be anything
        Returns:
        vertices weights of the key, or null if no container found with the specified key

      • addVerticesWeights

        default <V,​WeightsT extends Weights<V>> WeightsT addVerticesWeights​(Object key,
                                                                          Class<? super V> type)
        Add a new weights container associated with the vertices of the built graph.

        See Weights for a complete documentation of the weights containers.

        Type Parameters:
        V - The weight data type
        WeightsT - the weights container, used to avoid casts of containers of primitive types
        Parameters:
        key - some key of the weights, could be anything
        type - the type of the weights, used for primitive types weights
        Returns:
        a new weights container
        Throws:
        IllegalArgumentException - if a vertices weights container with the same key already exists in the graph

      • addVerticesWeights

        <V,​WeightsT extends Weights<V>> WeightsT addVerticesWeights​(Object key,
                                                                  Class<? super V> type,
                                                                  V defVal)
        Add a new weights container associated with the vertices of built graph with default value.

        See Weights for a complete documentation of the weights containers.

        Type Parameters:
        V - The weight data type
        WeightsT - the weights container, used to avoid casts of containers of primitive types
        Parameters:
        key - some key of the weights, could be anything
        type - the type of the weights, used for primitive types weights
        defVal - default value use for the weights container
        Returns:
        a new weights container
        Throws:
        IllegalArgumentException - if a vertices weights container with the same key already exists in the graph

      • getVerticesWeightsKeys

        Set<Object> getVerticesWeightsKeys()
        Get the keys of all the associated vertices weights.

        See Weights for a complete documentation of the weights containers.

        Returns:
        the keys of all the associated vertices weights

      • getEdgesWeights

        <E,​WeightsT extends Weights<E>> WeightsT getEdgesWeights​(Object key)
        Get the edges weights of some key.

        See Weights for a complete documentation of the weights containers.

        Type Parameters:
        E - The weight data type
        WeightsT - the weights container, used to avoid casts of containers of primitive types
        Parameters:
        key - some key of the weights, could be anything
        Returns:
        edges weights of the key, or null if no container found with the specified key

      • addEdgesWeights

        default <E,​WeightsT extends Weights<E>> WeightsT addEdgesWeights​(Object key,
                                                                       Class<? super E> type)
        Add a new weights container associated with the edges of the built graph.

        See Weights for a complete documentation of the weights containers.

        Type Parameters:
        E - The weight data type
        WeightsT - the weights container, used to avoid casts of containers of primitive types
        Parameters:
        key - some key of the weights, could be anything
        type - the type of the weights, used for primitive types weights
        Returns:
        a new weights container
        Throws:
        IllegalArgumentException - if a edges weights container with the same key already exists in the graph

      • addEdgesWeights

        <E,​WeightsT extends Weights<E>> WeightsT addEdgesWeights​(Object key,
                                                               Class<? super E> type,
                                                               E defVal)
        Add a new weights container associated with the edges of the built graph with default value.

        See Weights for a complete documentation of the weights containers.

        Type Parameters:
        E - The weight data type
        WeightsT - the weights container, used to avoid casts of containers of primitive types
        Parameters:
        key - some key of the weights, could be anything
        type - the type of the weights, used for primitive types weights
        defVal - default value use for the weights container
        Returns:
        a new weights container
        Throws:
        IllegalArgumentException - if a edges weights container with the same key already exists in the graph

      • getEdgesWeightsKeys

        Set<Object> getEdgesWeightsKeys()
        Get the keys of all the associated edges weights.

        See Weights for a complete documentation of the weights containers.

        Returns:
        the keys of all the associated edges weights

      • clear

        void clear()
        Clear the builder by removing all vertices and edges added to it.

      • build

        Graph build()
        Build a new immutable graph with the builder vertices and edges.
        Returns:
        a new immutable graph with the vertices and edges that were added to the builder.

      • buildMutable

        Graph buildMutable()
        Build a new mutable graph with the builder vertices and edges.
        Returns:
        a new mutable graph with the vertices and edges that were added to the builder.

      • newUndirected

        static GraphBuilder newUndirected()
        Create a new builder that builds undirected graphs.
        Returns:
        a new empty builder for undirected graphs

      • newDirected

        static GraphBuilder newDirected()
        Create a new builder that builds directed graphs.
        Returns:
        a new empty builder for directed graphs

      • newFrom

        static GraphBuilder newFrom​(Graph g)
        Create a new builder initialized with an existing graph vertices and edges, without copying the weights.

        If the given graph is directed, the new builder will build directed graphs, and similarly for undirected graphs.

        Parameters:
        g - a graph
        Returns:
        a builder initialized with the given graph vertices and edges, without the original graph vertices/edges weights.

      • newFrom

        static GraphBuilder newFrom​(Graph g,
                            boolean copyWeights)
        Create a new builder initialized with an existing graph vertices and edges, with/without copying the weights.

        If the given graph is directed, the new builder will build directed graphs, and similarly for undirected graphs.

        Parameters:
        g - a graph
        copyWeights - if true, the weights of the vertices and edges will be copied to the new graph
        Returns:
        a builder initialized with the given graph vertices and edges, with/without the original graph vertices/edges weights.