package org.eclipse.jst.jsf.common.sets.internal.provisional;

import java.util.Set;

/**
 * A java.util.Set with the basic mathematic set axioms of 
 * extensionality (equality), union, intersection, 
 * relative complement (set subtraction) and empty (already 
 * supported by Set).
 * 
 * @author cbateman
 *
 */
public interface AxiomaticSet extends Set 
{
    /**
     * Implementations should aim to provide O(mn) time cost
     * where n is the number of elements in this set.  And
     * m is the cost to check membership of an element in this
     * set in toSet.  When a set is itself a member of a set,
     * the implementation must call isEquivalent on those subsets
     * recursively.
     * 
     * @return true iff this set is equivalent toSet.  Note
     * that extensionality holds that two sets are equivalent
     * if and only if they contain exactly the same elements.
     * 
     *
     */
    boolean isEquivalent(AxiomaticSet toSet);
    
    /**
     * @param set
     * @return the axiomatic union of this set with set
     */
    AxiomaticSet union(AxiomaticSet set);
    
    
    /**
     * @param set
     * @return the axiomatic intersection of this set with set
     */
    AxiomaticSet intersect(AxiomaticSet set);
    
    /**
     * @param set
     * @return convenience method that must be equivalent to
     * (this.intersect(set).isEmpty())
     */
    boolean isDisjoint(AxiomaticSet set);
    
    /**
     * The set constructed by the removing the intersection
     * of this with set from this.  The set will contain all
     * elements in this that are not in set.
     * 
     * Eqivalence: this - set
     * 
     * @param set
     * @return the relative complement or theoretic difference of 
     * set from this
     */
    AxiomaticSet subtract(AxiomaticSet set);
    
    /**
     * @return the first element in the set.  There is no guarantee which element
     * will be chosen, but the call should always return the same element of the set
     * for multiple invocations on the same set.  Generally this is a convience method
     * for when the set only contains one element.
     * 
     * @throws NoSuchElementException if the set is empty.
     */
    Object getFirstElement();
}