package graph;

import java.awt.Point;
import java.util.Iterator;

/**
 * A Graph provides a view of objects as either vertices or edges in a graph.
 * It provides information about the vertices and edges needed by a
 * GraphSearcher to perform a graph search.
 * An implementation of the graph interface may throw an
 * IllegalArgumentException for any method parameters that it cannot interpret
 * as a vertex or edge in its view of objects or when its interpretation of an
 * object is of the wrong type (e.g. a vertex when the method expects an edge).
 *
 */
public interface Graph
        extends Iterable<Object> {

  /**
   * g.getUndirected() returns true if the edges in g are undirected edges.
   * @return true if the edges are undirected edges
   */
  public boolean isUndirected();

  /**
   * g.iterator() returns an iterator for the vertices in g.
   * This implements the java.lang.Iterable<Object> interface.
   * All of the vertices in g can be processed with the following loop:
   * <p>
   * for (Object v : g) { code to process vertex v }
   * </p>
   * @return an iterator for the vertices
   */
  public Iterator<Object> iterator();

  /**
   * g.getEdgesFrom(v) returns an iterable for the edges leaving from vertex v
   * in g.
   * @param v a vertex
   * @return an iterator for the edges leaving v
   */
  public Iterable<Object> getEdgesFrom(Object v);

  /**
   * g.getPosition(v) returns the position of vertex v in g.
   * @param v a vertex
   * @return its position
   */
  public Point getPosition(Object v);

  /**
   * g.getToVertex(e) returns the from vertex for the edge e in g.
   * @param e an edge
   * @return its from vertex (a.k.a. source, tail)
   */
  public Object getFromVertex(Object e);

  /**
   * g.getToVertex(e) returns the to vertex for the edge e in g.
   * @param e an edge
   * @return its to vertex (a.k.a. destination, head)
   */
  public Object getToVertex(Object e);

  /**
   * g.getWeight(e) returns the weight for the edge e in g.
   * If the weight is not defined NaN is returned.
   * @param e an edge
   * @return its weight
   */
  public double getWeight(Object e);

  /**
   * g.getWeight(e) returns the opposite edge for the edge e in g.
   * If g.isUndirected() is false then null is returned for all edges.
   * @param e an edge
   * @return it weight
   */
  public Object getOpposite(Object e);

}