/* Dictionary.java */

package dict;

/**
 *  An interface for (unordered) dictionary ADTs.
 *
 *  DO NOT CHANGE THIS FILE.
 **/
public interface Dictionary {

  /**
   *  Special element returned by the search and remove methods when
   *  no item with the specified key is stored in the dictionary.
   **/
  public static final Object NO_SUCH_KEY =
          new String("Dictionary.NO_SUCH_KEY");

  /** 
   *  Returns the number of items stored in the dictionary, where each item
   *  is counted according to its multiplicity.
   *  @return number of items in the dictionary.
   **/
  public int size(); 

  /** 
   *  Tests if the dictionary is empty.
   *
   *  @return true if the dictionary has no items, false otherwise.
   **/
  public boolean isEmpty();

  /** 
   *  Insert an item (a key and an associated element).  Multiple items with
   *  the same key can coexist in the dictionary.
   *
   *  @param key the key by which the item can be retrieved.
   *  @param element an arbitrary object.
   **/
  public void insertItem(Object key, Object element);

  /** 
   *  Search for an item with the specified key.  If such an item is found,
   *  return its element; otherwise return the special element NO_SUCH_KEY.
   *  If several items have the specified key, one is chosen arbitrarily and
   *  returned.
   *
   *  @param key the search key.
   *  @return element an element associated with the key, or NO_SUCH_KEY if no
   *  item is associated with the specified key.
   **/
  public Object findElement(Object key);
  
  /** 
   *  Remove an item with the specified key.  If such an item is found, return
   *  its element and remove it from the table; otherwise else return the
   *  special element NO_SUCH_KEY.  If several items have the specified key,
   *  one is chosen arbitrarily, removed, and returned.
   *
   *  @param key the search key.
   *  @return element an element associated with the key, or NO_SUCH_KEY if no
   *  item is associated with the specified key.
   */
  public Object remove(Object key);

  /**
   *  Remove all items from the dictionary.
   */
  public void makeEmpty();

}