gr.james.simplegraph.WeightedDirectedGraph Maven / Gradle / Ivy
Show all versions of simple-graph Show documentation
package gr.james.simplegraph;
import java.util.Iterator;
import java.util.Set;
/**
* Represents a weighted and directed graph.
*
* The graph can contain self loops but cannot contain parallel edges. More formally, any ordered pair of endpoints may
* correspond to at most one edge. The edge weights can only be finite {@link Double} values.
*
* An ordered pair {@code (a, b)} is a pair of objects where the order in which the objects appear in the pair is
* significant: the ordered pair {@code (a, b)} is different from the ordered pair {@code (b, a)} unless {@code a = b}.
*
* Memory Complexity: O(V+E)
*/
public interface WeightedDirectedGraph extends BaseGraph {
/**
* {@inheritDoc}
*
* @return {@inheritDoc}
*/
@Override
int size();
/**
* Get the outbound adjacent vertices of a vertex.
*
* More formally, returns an unmodifiable view of all vertices in this graph adjacent to {@code v} which can be
* reached by traversing {@code v}'s outgoing edges in the direction of the edge. The vertices returned are in no
* particular order inside the {@link Set}.
*
* You can use the result of this method in a for-each loop like so:
*
* for (int v : g.adjacentOut(X)) {
* // Do something with v
* }
*
*
* You can also use the classic iterator approach:
*
* Iterator<Integer> it = g.adjacentOut(X).iterator();
* while (it.hasNext()) {
* int v = it.next();
* // Do something with v
* }
*
* The iterator doesn't support the {@link Iterator#remove()} method, which will always throw
* {@link UnsupportedOperationException}.
*
* You can get the out degree of a certain vertex {@code v} by querying the size of the collection returned by this
* method:
*
* int outDegree = g.adjacentOut(v).size();
*
* The snippet will include the edge to {@code v} itself, if present.
*
* You can also use this method to check if a directed edge from {@code a} to {@code b} exists:
*
* if (g.adjacentOut(a).contains(b)) {
* System.out.printf("There exists an edge from %d to %d%n", a, b);
* }
*
* Be careful when using such construct: {@code g.adjacentOut(a).contains(b)} will return {@code false} if {@code b}
* is not an element of this graph.
*
* Likewise, you can check if the opposite parallel edge exists:
*
* if (g.adjacentOut(b).contains(a)) {
* System.out.printf("There exists an edge from %d to %d%n", b, a);
* }
*
*
* Complexity: O(1)
*
* @param v the vertex
* @return a {@link Set} that holds all the outbound adjacent vertices of {@code v}
* @throws IndexOutOfBoundsException if {@code v} is outside the range {@code [O,V)}
* @see #getInEdges(int)
*/
Set getOutEdges(int v);
/**
* Get the inbound adjacent vertices of a vertex.
*
* More formally, returns an unmodifiable view of all vertices in this graph adjacent to {@code v} which can be
* reached by traversing {@code v}'s incoming edges against the direction of the edge. The vertices returned are in
* no particular order inside the {@link Set}.
*
* You can use this method in the same way you would use {@code adjacentOut(int)} and you can refer to that for
* additional information.
*
* Complexity: O(1)
*
* @param v the vertex
* @return a {@link Set} that holds all the inbound adjacent vertices of {@code v}
* @throws IndexOutOfBoundsException if {@code v} is outside the range {@code [O,V)}
* @see #getOutEdges(int)
*/
Set getInEdges(int v);
/**
* Get the weight of the edge from {@code source} to {@code target}.
*
* The weight of an edge can be any {@link Double} value except {@link Double#NaN}, {@link Double#POSITIVE_INFINITY}
* and {@link Double#NEGATIVE_INFINITY}. In other words, it can be any finite {@link Double} value.
*
* Complexity: O(1)
*
* @param source the source of the edge
* @param target the target of the edge
* @return the weight of the edge from {@code source} to {@code target}
* @throws IndexOutOfBoundsException if {@code source} or {@code target} are outside of {@code [O,V)}
* @throws IllegalArgumentException if there is no edge from {@code source} to {@code target}
*/
double getEdgeWeight(int source, int target);
/**
* Returns a collection of all the edges in this graph.
*
* This method is suitable to use in a for-each loop:
*
* for (WeightedDirectedEdge e : g.edges()) {
* System.out.println(e);
* }
*
*
* Complexity: O(1)
*
* @return a collection of all the edges in this graph
*/
Iterable edges();
/**
* Returns a {@link DirectedGraph} wrapper of this graph.
*
* The resulting graph is treated like unweighted and will, thus, lose the ability to get the weights assigned to
* the edges of this graph.
*
* Complexity: O(1)
*
* @return a {@link DirectedGraph} wrapper of this graph
*/
DirectedGraph asDirected();
/**
* {@inheritDoc}
*
* @return {@inheritDoc}
*/
@Override
String toString();
/**
* {@inheritDoc}
*
* @param obj {@inheritDoc}
* @return {@inheritDoc}
* @see Graphs#equals(WeightedDirectedGraph, WeightedDirectedGraph)
*/
@Override
boolean equals(Object obj);
/**
* {@inheritDoc}
*
* @return {@inheritDoc}
*/
@Override
int hashCode();
}