package username.graph;

/**
 * Something that permits us to mark the vertices in a graph.  As
 * in WDG, vertices are represented by integers in the range
 * 0 .. (size-1).  Implementations may choose whether or not 
 * clients must specify the size in advance.
 *
 * @author Samuel A. Rebelsky
 * @version 1.0 of April 2006
 */
public interface Marker<T>
{

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

  /**
   * Determine whether a vertex is marked.  If v >= size(), returns
   * false.
   */
  public boolean isMarked(int v);

  /**
   * Get the mark associated with a particular vertex.
   *
   * @return m
   *   a mark
   * @pre
   *   v is marked
   * @post
   *   m is a value s.t. the most recent call to mark with the 
   *   specified vertex used mark m.
   */
  public T getMark(int v);


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

  /**
   * Mark a vertex.  If v >= size(), the implementation may either
   * throw an exception or expand the number of marks.
   *
   * @post
   *   isMarked(v) holds.
   * @post
   *   getMark(v) returns mark.
   */
  public void mark(int v, T mark)
    throws Exception;

  /**
   * Remove the mark on the vertex.  
   *
   * @post
   *   isMarked(v) does not hold.
   */
  public void unmark(int v);

} // interface Marker