/**
 * Generic Interface defintion for Bag Adapted slightly from Carrano and Henry
 * 
 * @author GTowell Created: July 2021
 */
public interface BagOfStuff<S> {

    /**
     * The mount of stuff in the bag
     * 
     * @return the amount of stuff in the bag
     */
    public int numberOfItems();

    /**
     * true if there is nothing in the bag
     * 
     * @return true if there is nothing in the bag, false otherwise
     */
    public boolean isEmpty();

    /**
     * Put stuff into the bag
     * 
     * @param p the stuff to be added to the bag
     * @return true if there is space in the bag for the stuff, false otherwise
     */
    public boolean add(S p);

    /**
     * Remove one piece of stuff from the bag
     * 
     * @return the removed stuff, or null if the bag is empty
     */
    public S remove();

    /**
     * Remove a particular stuff from the the bag. This will remove ALL instance of
     * the stuff
     * 
     * @param p the stuff to be removed
     * @return true if there is at least one instance of the stuff in the bag, false
     *         otherwise
     */
    public boolean remove(S p);

    /**
     * Remove all stuff from the bag
     */
    public void clear();

    /**
     * The number of instances of the given stuff in the bag. This comparison
     * requires identical objects
     * 
     * @param p the stuff to be counted
     * @return The number of instances of the given stuff in the bag
     */
    public int countOf(S p);

    /**
     * True if the given stuff is in the bag, false otherwise. This comparison
     * requires identical objects.
     * 
     * @param p the stuff to check for
     * @return True if the given stuff is in the bag, false otherwise
     */
    public boolean contains(S p);

    /**
     * Return an object from the bag that is equal to the provided object. Note that
     * the comparison is equal not ==. Hence, while the returned object is equal to
     * the provided object, it may not be the same object. If there is more than one
     * object equal to the provided object, the implementation may return any of the
     * equal objects and could return a different object on consecutive calls.
     * 
     * @param p the object to find the equivalent of
     * @return an object equal to the provided object, or null.
     */
    public S getInstance(S p);

    /**
     * Print the contents of the bag.
     */
    public void display();
}