gr.james.simplegraph.DirectedGraph Maven / Gradle / Ivy
Show all versions of simple-graph Show documentation
package gr.james.simplegraph;
import java.util.Iterator;
import java.util.Set;
/**
* Represents an unweighted 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.
*
* 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 DirectedGraph 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 #adjacentIn(int)
*/
Set adjacentOut(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 #adjacentOut(int)
*/
Set adjacentIn(int v);
/**
* Returns a collection of all the edges in this graph.
*
* This method is suitable to use in a for-each loop:
*
* for (DirectedEdge 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 WeightedDirectedGraph} wrapper of this graph.
*
* The resulting graph will contain the same edges as this graph with assigned weight {@code 1.0}.
*
* Complexity: O(1)
*
* @return a {@link WeightedDirectedGraph} wrapper of this graph
*/
WeightedDirectedGraph asWeightedDirected();
/**
* {@inheritDoc}
*
* @return {@inheritDoc}
*/
@Override
String toString();
/**
* {@inheritDoc}
*
* @param obj {@inheritDoc}
* @return {@inheritDoc}
* @see Graphs#equals(DirectedGraph, DirectedGraph)
*/
@Override
boolean equals(Object obj);
/**
* {@inheritDoc}
*
* @return {@inheritDoc}
*/
@Override
int hashCode();
}