Interface IntGraphBuilder

All Superinterfaces:
GraphBuilder<Integer,Integer>
All Known Subinterfaces:
IndexGraphBuilder
public interface IntGraphBuilder extends GraphBuilder<Integer,Integer>
A builder for int graphs.

The builder is used to construct non-empty int graphs. Differing from IntGraphFactory 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.

To create a new builder, use one of the static methods undirected(), directed() or newInstance(boolean). For more options, create a new IntGraphFactory and use IntGraphFactory.newBuilder(), or use IntGraphFactory.newBuilderCopyOf(Graph) to create a builder initialized with an existing graph vertices and edges.

This interface is a specification of GraphBuilder for IntGraph.

Author:
Barak Ugav
See Also:

  • Method Details

    • vertices

      IntSet vertices()
      Description copied from interface: GraphBuilder
      Get the set of vertices that were added to the graph.
      Specified by:
      vertices in interface GraphBuilder<Integer,Integer>
      Returns:
      the graph vertices

    • edges

      IntSet edges()
      Description copied from interface: GraphBuilder
      Get the set of edges that were added to the graph.
      Specified by:
      edges in interface GraphBuilder<Integer,Integer>
      Returns:
      the graph edges

    • addVertex

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

      Vertices must be non negative integers.

      If there is a vertex builder, namely if vertexBuilder() does not return null, the method addVertexInt() can be used, which uses the vertex builder to create the new vertex object instead of requiring the user to provide it.

      Parameters:
      vertex - new vertex
      Throws:
      IllegalArgumentException - if vertex is already in the built graph, or if vertex is negative, as negative identifiers are not allowed

    • addVertex

      @Deprecated default void addVertex(Integer vertex)
      Deprecated.
      Please use addVertex(int) instead to avoid un/boxing.
      Add a new vertex to the built graph.

      A vertex can be any non null hashable object, namely it must implement the Object.hashCode() and Object.equals(Object) methods. Duplicate vertices are not allowed.

      If there is a vertex builder, namely if GraphBuilder.vertexBuilder() does not return null, the method GraphBuilder.addVertex() can be used, which uses the vertex builder to create the new vertex object instead of requiring the user to provide it.

      Specified by:
      addVertex in interface GraphBuilder<Integer,Integer>
      Parameters:
      vertex - new vertex
      Throws:
      IllegalArgumentException - if the given vertex is negative or any of reasons specified in GraphBuilder.addVertex(Object)

    • addVertexInt

      default int addVertexInt()
      Add a new vertex to the built graph, using the vertex builder.

      Unlike addVertex(int) in which the vertex is provided by the user, this method uses the vertex builder obtained by vertexBuilder() to create the new vertex and adds it to the graph.

      This method is equivalent to: 

       
 int vertex = vertexBuilder().build(vertices());
 addVertex(vertex);
 return vertex;
      Returns:
      the new vertex
      Throws:
      UnsupportedOperationException - if the builder does not have a vertex builder, namely if vertexBuilder() returns null

    • addVertex

      @Deprecated default Integer addVertex()
      Deprecated.
      Please use addVertexInt() instead to avoid un/boxing.
      Add a new vertex to the built graph, using the vertex builder.

      Unlike GraphBuilder.addVertex(Object) in which the vertex is provided by the user, this method uses the vertex builder obtained by GraphBuilder.vertexBuilder() to create the new vertex object and adds it to the graph.

      This method is equivalent to: 

       
 V vertex = vertexBuilder().build(vertices());
 addVertex(vertex);
 return vertex;
      Specified by:
      addVertex in interface GraphBuilder<Integer,Integer>
      Returns:
      the new vertex

    • addVertices

      void addVertices(Collection<? extends Integer> vertices)
      Add multiple vertices to the built graph.

      A vertex can be any non null hashable object, namely it must implement the Object.hashCode() and Object.equals(Object) methods. Duplicate vertices are not allowed.

      Prefer to pass IntCollection instead of Collection<Integer> as collection of vertices.

      Specified by:
      addVertices in interface GraphBuilder<Integer,Integer>
      Parameters:
      vertices - new vertices

    • addEdge

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

      If the built graph does not support self or parallel edges and the added edge is such edge, an exception will not be thrown. The edges are validated only when the graph is built, and an exception will be thrown only then.

      Edges must be non negative integers.

      If there is an edge builder, namely if edgeBuilder() does not return null, the method addEdge(int, int) can be used, which uses the edge builder to create the new edge object instead of requiring the user to provide it.

      Parameters:
      source - a source vertex
      target - a target vertex
      edge - a new edge identifier
      Throws:
      IllegalArgumentException - if edge is already in the graph or if it is negative, as negative identifiers are not allowed
      NoSuchVertexException - if source or target are not valid vertices identifiers

    • addEdge

      @Deprecated default void addEdge(Integer source, Integer target, Integer edge)
      Deprecated.
      Please use addEdge(int, int, int) instead to avoid un/boxing.
      Add a new edge to the built graph.

      If the built graph does not support self or parallel edges and the added edge is such edge, an exception will not be thrown. The edges are validated only when the graph is built, and an exception will be thrown only then.

      An edge can be any non null hashable object, namely it must implement the Object.hashCode() and Object.equals(Object) methods. Duplicate edges are not allowed.

      If there is an edge builder, namely if GraphBuilder.edgeBuilder() does not return null, the method GraphBuilder.addEdge(Object, Object) can be used, which uses the edge builder to create the new edge object instead of requiring the user to provide it.

      Specified by:
      addEdge in interface GraphBuilder<Integer,Integer>
      Parameters:
      source - a source vertex
      target - a target vertex
      edge - a new edge identifier

    • addEdge

      default int addEdge(int source, int target)
      Add a new edge to the built graph, using the edge builder.

      Unlike addEdge(int, int, int) in which the edge (identifier) is provided by the user, this method uses the edge builder obtained by edgeBuilder() to create the new edge object and adds it to the graph.

      If the graph does not support self or parallel edges and the added edge is such edge, an exception will not be thrown. The edges are validated only when the graph is built, and an exception will be thrown only then.

      This method is equivalent to: 

       
 int edge = edgeBuilder().build(edges());
 addEdge(source, target, edge);
 return edge;
      Parameters:
      source - a source vertex
      target - a target vertex
      Returns:
      the new edge
      Throws:
      UnsupportedOperationException - if the builder does not have an edge builder, namely if edgeBuilder() returns null
      NoSuchVertexException - if source or target are not valid vertices identifiers

    • addEdge

      @Deprecated default Integer addEdge(Integer source, Integer target)
      Deprecated.
      Please use addEdge(int, int) instead to avoid un/boxing.
      Add a new edge to the built graph, using the edge builder.

      Unlike GraphBuilder.addEdge(Object, Object, Object) in which the edge (identifier) is provided by the user, this method uses the edge builder obtained by GraphBuilder.edgeBuilder() to create the new edge object and adds it to the graph.

      If the built graph does not support self or parallel edges and the added edge is such edge, an exception will not be thrown. The edges are validated only when the graph is built, and an exception will be thrown only then.

      This method is equivalent to: 

       
 E edge = edgeBuilder().build(edges());
 addEdge(source, target, edge);
 return edge;
      Specified by:
      addEdge in interface GraphBuilder<Integer,Integer>
      Parameters:
      source - a source vertex
      target - a target vertex
      Returns:
      the new edge

    • addEdges

      void addEdges(EdgeSet<? extends Integer,? extends Integer> edges)
      Add multiple edges to the built graph.

      The EdgeSet passed to this method contains both the edges themselves (the identifiers) and their endpoints (sources and targets), see EdgeSet.iterator(), EdgeIter.source(), EdgeIter.target(). An EdgeSet can be obtained from one of the methods of a Graph, or using EdgeSet.of(Set, Graph).

      An edge can be any non null hashable object, namely it must implement the Object.hashCode() and Object.equals(Object) methods. Duplicate edges are not allowed.

      In the following snippet, a maximum cardinality matching is computed on a graph, and a new graph containing only the matching edges is created: 

       
 Graph<V, E> g = ...;
 Set<E> matching = MatchingAlgo.newInstance().computeMaximumMatching(g, null).edges();

 GraphBuilder<V,E> matchingGraphBuilder = GraphBuilder.undirected();
 matchingGraphBuilder.addVertices(g.vertices());
 matchingGraphBuilder.addEdges(EdgeSet.of(matching, g));
 Graph<V,E> matchingGraph = matchingGraphBuilder.build()

      Prefer to pass IEdgeSet instead of EdgeSet<Integer, Integer> as set of edges. See IEdgeSet.of(IntSet, IntGraph).

      Specified by:
      addEdges in interface GraphBuilder<Integer,Integer>
      Parameters:
      edges - the set of new edges, from which the edges identifiers as well as the endpoints (source and target) of each edge are accessible (see EdgeSet.iterator(), EdgeIter.source(), EdgeIter.target()).
      Throws:
      IllegalArgumentException - if any of the given edges are negative or any of reasons specified in GraphBuilder.addEdges(EdgeSet)

    • verticesWeights

      <T, WeightsT extends Weights<Integer, T>> WeightsT verticesWeights(String key)
      Get the vertices weights of some key.

      See Weights for a complete documentation of the weights containers.

      The return object is always some sub class of IWeights, such as IWeightsInt or IWeightsDouble.

      Specified by:
      verticesWeights in interface GraphBuilder<Integer,Integer>
      Type Parameters:
      T - The weight data type
      WeightsT - the weights container, used to avoid casts of containers of primitive types such as WeightsInt, WeightsDouble ect.
      Parameters:
      key - key of the weights
      Returns:
      vertices weights of the key, or null if no container found with the specified key

    • edgesWeights

      <T, WeightsT extends Weights<Integer, T>> WeightsT edgesWeights(String key)
      Get the edges weights of some key.

      See Weights for a complete documentation of the weights containers.

      The return object is always some sub class of IWeights, such as IWeightsInt or IWeightsDouble.

      Specified by:
      edgesWeights in interface GraphBuilder<Integer,Integer>
      Type Parameters:
      T - The weight data type
      WeightsT - the weights container, used to avoid casts of containers of primitive types such as WeightsInt, WeightsDouble ect.
      Parameters:
      key - key of the weights
      Returns:
      edges weights of the key, or null if no container found with the specified key

    • vertexBuilder

      IdBuilderInt vertexBuilder()
      Description copied from interface: GraphBuilder
      Get the vertex builder of this builder.

      The vertex builder is used to create new vertices during the execution of GraphBuilder.addVertex(), in which the vertex identifier is not provided by the user. No vertex builder necessarily exists, and this method may return a null value. In that case, GraphBuilder.addVertex() cannot be used, only GraphBuilder.addVertex(Object).

      Specified by:
      vertexBuilder in interface GraphBuilder<Integer,Integer>
      Returns:
      the vertex builder, or null if the there is no vertex builder

    • edgeBuilder

      IdBuilderInt edgeBuilder()
      Description copied from interface: GraphBuilder
      Get the edge builder of this builder.

      The edge builder is used to create new edges during the execution of GraphBuilder.addEdge(Object, Object), in which the edge identifier is not provided by the user. No edge builder necessarily exists, and this method may return a null value. In that case, GraphBuilder.addEdge(Object, Object) cannot be used, only GraphBuilder.addEdge(Object, Object, Object).

      Specified by:
      edgeBuilder in interface GraphBuilder<Integer,Integer>
      Returns:
      the edge builder, or null if the there is no edge builder

    • build

      IntGraph build()
      Description copied from interface: GraphBuilder
      Build a new immutable graph with the builder vertices and edges.

      Before the graph is built, the edges are validated. If the graph does not support self or parallel edges and such edges were added to the builder, an exception will be thrown.

      Specified by:
      build in interface GraphBuilder<Integer,Integer>
      Returns:
      a new immutable graph with the vertices and edges that were added to the builder.

    • buildMutable

      IntGraph buildMutable()
      Description copied from interface: GraphBuilder
      Build a new mutable graph with the builder vertices and edges.

      Before the graph is built, the edges are validated. If the graph does not support self or parallel edges and such edges were added to the builder, an exception will be thrown.

      Specified by:
      buildMutable in interface GraphBuilder<Integer,Integer>
      Returns:
      a new mutable graph with the vertices and edges that were added to the builder.

    • undirected

      static IntGraphBuilder undirected()
      Create a new builder that builds undirected graphs.

      The graphs built by this builder will have the same default capabilities as IntGraphFactory, namely they will not support self edges and will support parallel edges. See the factory documentation for more information.

      For more options to instantiate a builder, create a new IntGraphFactory and use one of its newBuilder methods.

      Returns:
      a new empty builder for undirected graphs

    • directed

      static IntGraphBuilder directed()
      Create a new builder that builds directed int graphs.

      The graphs built by this builder will have the same default capabilities as IntGraphFactory, namely they will not support self edges and will support parallel edges. See the factory documentation for more information.

      For more options to instantiate a builder, create a new IntGraphFactory and use one of its newBuilder methods.

      Returns:
      a new empty builder for directed graphs

    • newInstance

      static IntGraphBuilder newInstance(boolean directed)
      Create a new builder that builds un/directed int graphs.

      The graphs built by this builder will have the same default capabilities as IntGraphFactory, namely they will not support self edges and will support parallel edges. See the factory documentation for more information.

      For more options to instantiate a builder, create a new IntGraphFactory and use one of its newBuilder methods.

      Parameters:
      directed - if true, the new builder will build directed graphs, otherwise it will build undirected graphs
      Returns:
      a new empty builder for un/directed graphs

    • newCopyOf

      static IntGraphBuilder newCopyOf(Graph<Integer,Integer> 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.

      For more options to instantiate a builder, create a new IntGraphFactory and use one of its newBuilder methods.

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

    • newCopyOf

      static IntGraphBuilder newCopyOf(Graph<Integer,Integer> g, boolean copyVerticesWeights, boolean copyEdgesWeights)
      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.

      For more options to instantiate a builder, create a new IntGraphFactory and use one of its newBuilder methods.

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