package username.graph;

import java.util.Iterator;

/**
 * A simple representation of weighted, directed, graphs (WDG,
 * as an abbreviation).  These graphs are /directed/ in that edges are
 * directed, from one vertex to another, rather than bidirectional,
 * between vertices.  These graphs are /weighted/ in that each edge
 * has an integer value associated with it (the "weight" of that edge.
 * 
 * The representation is simple in that the vertices in the graph 
 * are represented by integers in the range 0 .. (n-1).  Implementations
 * may choose whether or not the n must be specified in the constructor.
 *
 * @author Samuel A. Rebelsky
 * @version 1.0 of April 2006
 */
public interface WDG
{

// +-----------+---------------------------------------------------------
// | Observers |
// +-----------+

  /**
   * Determine the number of vertices in the graph.
   */
  public int size();
    
  /**
   * Determine whether there is an edge from source to target
   * in the graph.
   *
   * @return 
   *   true, if a call to makeEdge(source,target,_) has been made
   *   and no more recent call to deleteEdge(source,target) has
   *   been made.  false, otherwise.
   * @pre
   *   0 <= source < size()
   * @pre
   *   0 <= target < size()
   */
  public boolean edge(int source, int target)
    throws Exception;

  /**
   * Determine the weight of the edge from source to target.
   *
   * @return weight
   *   The weight of that edge.
   * @pre
   *   There is an edge from source to target.
   * @pre
   *   0 <= source < size()
   * @pre
   *   0 <= target < size()
   * @post
   *   weight is the w in the most recent call to makeEdge(s,t,w)
   *   for which s=source and t=target.
   */
  public int weight(int source, int target)
    throws Exception;

  /**
   * Get the successors of source.  
   *
   * @return succ
   *   The successors of source
   * @pre
   *   0 <= source < size()
   * @post
   *   For all vertices, t, if edge(source,t) then t is "in" 
   *   succ.  If !edge(source,t), then t is not "in" succ.
   */
  public Iterator<Integer> successors(int source);

  /**
   * Get the predecessors of target.  
   *
   * @return pred
   *   The predecessors of target
   * @pre
   *   0 <= target < size()
   * @post
   *   For all vertices, s, if edge(s,target) then s is "in" 
   *   pred.  If !edge(s,target), then t is not "in" pred
   */
  public Iterator<Integer> predecessors(int target);


// +----------+----------------------------------------------------------
// | Mutators |
// +----------+

  /**
   * Create an edge from s to t of weight w.  If
   * s or t is at least as large as size, an implementation
   * may expand the graph or throw an exception.
   *
   * @post
   *   edge(s,t) holds.
   */
  public void makeEdge(int s, int t, int w)
    throws Exception;

  /**
   * Delete the edge from s to t.
   *
   * @pre
   *   edge(s,t) holds
   * @post
   *   edge(s,t) does not hold.
   */
  public void deleteEdge(int s, int t);

} // interface WDG