//-------------------------------------------------------------------------
/**
 * The Set interface defines the operations on a set collection.  It
 * includes a selected group of methods from the {@link java.util.Set}
 * interface.
 *
 * @param <Item> The type of items this bag will hold.
 *
 * @author Stephen Edwards
 * @version 2010.09.29
 */
public interface Set<Item>
{
    // ----------------------------------------------------------
    /**
     * Returns true if this set contains the specified item.
     *
     * @param target item to be found
     * @return true if target is in the collection, false otherwise
     *
     * @precondition target != null
     * @postcondition returned value == true if this set contains target,
     *                and false if it does not
     */
    public boolean contains(Item target);


    // ----------------------------------------------------------
    /**
     * Adds the specified item to this set if it is not already
     * present.  If this set already contains the item, the call
     * leaves the set unchanged and returns false.
     *
     * @param element item to be added to this set
     * @return True if this set did not already contain the specified item
     *
     * @precondition element != null
     * @postcondition returned value == true if this set was changed
     *                as a result of the call
     */
    public boolean add(Item element);


    // ----------------------------------------------------------
    /**
     * Removes the specified item from this set if it is present.
     * Returns true if this set contained the item (or equivalently, if
     * this set changed as a result of the call). (This set will not
     * contain the element once the call returns.)
     *
     * @param target item to be removed from this set, if present
     * @return true if this set contained the specified item
     * @precondition target != null
     * @postcondition returned value == true if this set was changed
     *                as a result of the call
     */
    public boolean remove(Item target);


    // ----------------------------------------------------------
    /**
     * Removes and returns an arbitrary item from the set.
     *
     * @return the item removed
     * @precondition this set is not empty
     * @postcondition returned value is some item X such that contains(X)
     *                would have been true before the call, and contains(X)
     *                will be false after the call
     */
    public Item removeAny();


    // ----------------------------------------------------------
    /**
     * Returns true if this set contains no items.
     *
     * @return true if this set contains no items, false otherwise
     */
    public boolean isEmpty();


    // ----------------------------------------------------------
    /**
     * Returns the number of items in this set (its cardinality).
     *
     * @return the number of items in this set (its cardinality)
     */
    public int size();


    // ----------------------------------------------------------
    /**
     * Removes all of the elements from this set. The set will be empty
     * after this call returns.
     *
     * @postcondition this set will be empty, meaning isEmpty() == true,
     * size() == 0, and for all items X: contains(X) == false
     */
    public void clear();


    // ----------------------------------------------------------
    /**
     * Compares the specified object with this set for equality. Returns
     * true if the specified object is also a set, the two sets have the
     * same size, and every member of the specified set is contained
     * in this set (or equivalently, every member of this set is
     * contained in the specified set). This definition ensures that
     * the equals method works properly across different implementations
     * of the set interface.
     *
     * @param other object to be compared for equality with this set
     * @return true if the specified object is equal to this set
     */
    public boolean equals(Object other);


    // ----------------------------------------------------------
    /**
     * Returns a string representation of this set.  A set's string
     * representation is written as a comma-separated list of its
     * contents (in some arbitrary order) surrounded by curly braces,
     * like this:
     * <pre>
     * {52, 14, 12, 119, 73, 80, 35}
     * </pre>
     * <p>
     * An empty string is simply <code>{}</code>.
     * </p>
     *
     * @return a string representation of the set
     */
    public String toString();
}