/**
 * An interface that all Priority Queues should abide with
 * 
 * @param <K>
 * @param <V>
 */
public interface PriorityQInterface<K extends Comparable<K>, V> {
    
    /** enum specifying ordering styles. 
     * ASCENDING and MIN give element with smallest key first
     * DESCENDING and MAX give element with largest key first
     * Note that enum is a weird case of something that can be declared in an interface. 
     * Enums can be thought of a "public static final" 
     */
    enum Ordering { ASCENDING, DESCENDING, MIN, MAX}

    /**
     * The number of items in the queue
     * 
     * @return the number of items in the queie
     */
    int size();

    /**
     * Return true iff the queue is empty
     * 
     * @return true iff the queue is empty
     */
    boolean isEmpty();

    
    /**
     * Inserts the specified element into this queue if it is possible to do so
     * immediately without violating capacity restrictions, returning true upon
     * success and false on failure
     * 
     * @param k the key of the element to be added
     * @param v the value of the ek=lement 
     * @return true on success, false on failure
     */
    boolean offer(K k, V v);

    /**
     * Retrieves and removes the head of this priority queue.
     * 
     * @return the removed element, or null if the queue is empty
     */
    V poll();

    /**
     * Retrieves, but does not remove, the head of this priority queue. 
     * 
     * @return the element at the head of the queue or null if the queue is empty
     */
    V peek();

    /**
     * Remove an item from the priority queue.  The item to be removed may be anywhere within 
     * the priority queue. If the item is not in the priority queue, then return false; otherwise the 
     * removal must succeed and the function will return true.
     * @param toBeRemoved the item to be removed from the priority queue.
     * @return true if the item was removed, false otherwise.
     */
    boolean remove(V toBeRemoved);

}