Package com.jgalgo.graph

Interface IndexGraphBuilder

  • public interface IndexGraphBuilder
    A builder for Index graphs.

    The builder is used to construct non-empty index graphs. Differing from IndexGraphFactory 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(), GraphBuilder, IndexGraphFactory

    • 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.

        As the built graph is an Index graph, the vertices must be 0,1,2,...,verticesNum-1 and user-chosen IDs are not supported. A new vertex will be assigned ID of value vertices().size().

        Returns:
        the identifier of the new vertex

      • addEdge

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

        As the built graph is an Index graph, the edges must be 0,1,2,...,edgesNum-1. A new edge will be assigned ID of value edges().size().

        It is possible to construct a graph by inserting the edges in a different order than their indices (IDs), by using addEdge(int, int, int) in which the ID of the inserted edge is specified along with the source and target vertices. If this method is used, the set of edges will be validated when a new graph is created, and it must be equal 0,1,2,...,edgesNum-1. 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 identifier of the new edge

      • 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. As the built graph is an Index graph, the edges must be 0,1,2,...,edgesNum-1. This constraint is validated when the graph is actually created by the builder.

        Instead of this method, addEdge(int, int) can be used, letting the builder 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

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

      • buildMutable

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

      • reIndexAndBuild

        IndexGraphBuilder.ReIndexedGraph reIndexAndBuild​(boolean reIndexVertices,
                                                 boolean reIndexEdges)
        Re-Index the vertices/edges and build a new immutable graph with the new indexing.

        Re-indexing is the operation of assigning new indices to the vertices/edges. By re-indexing the vertices/edges, the performance of accessing/iterating over the graph vertices/edges may increase, for example if a more cache friendly indexing exists.

        Note that this method is not required to re-index the vertices (edges) if reIndexVertices (reIndexEdges) is true, it is simply allowed to. Whether or not a re-indexing was performed can be checked via the IndexGraphBuilder.ReIndexedGraph return value.

        Parameters:
        reIndexVertices - if true, the implementation is allowed to (note that it is not required) to re-index the vertices of the graph. If false, the original vertices identifiers are used. Whether or not re-indexing was performed can be checked via IndexGraphBuilder.ReIndexedGraph.verticesReIndexing().
        reIndexEdges - if true, the implementation is allowed to (note that it is not required) to re-index the edges of the graph. If false, the original edges identifiers are used. Whether or not re-indexing was performed can be checked via IndexGraphBuilder.ReIndexedGraph.edgesReIndexing().
        Returns:
        the re-indexed immutable graph, along with the re-indexing mapping to the original indices

      • reIndexAndBuildMutable

        IndexGraphBuilder.ReIndexedGraph reIndexAndBuildMutable​(boolean reIndexVertices,
                                                        boolean reIndexEdges)
        Re-Index the vertices/edges and build a new mutable graph with the new indexing.

        Re-indexing is the operation of assigning new indices to the vertices/edges. By re-indexing the vertices/edges, the performance of accessing/iterating over the graph vertices/edges may increase, for example if a more cache friendly indexing exists.

        Note that this method is not required to re-index the vertices (edges) if reIndexVertices (reIndexEdges) is true, it is simply allowed to. Whether or not a re-indexing was performed can be checked via the IndexGraphBuilder.ReIndexedGraph return value.

        Parameters:
        reIndexVertices - if true, the implementation is allowed to (note that it is not required) to re-index the vertices of the graph. If false, the original vertices identifiers are used. Whether or not re-indexing was performed can be checked via IndexGraphBuilder.ReIndexedGraph.verticesReIndexing().
        reIndexEdges - if true, the implementation is allowed to (note that it is not required) to re-index the edges of the graph. If false, the original edges identifiers are used. Whether or not re-indexing was performed can be checked via IndexGraphBuilder.ReIndexedGraph.edgesReIndexing().
        Returns:
        the re-indexed mutable graph, along with the re-indexing mapping to the original indices

      • newUndirected

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

      • newDirected

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

      • newFrom

        static IndexGraphBuilder newFrom​(IndexGraph 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 IndexGraphBuilder newFrom​(IndexGraph 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.