1. /*

  2.  * @(#)Set.java	1.23 00/02/02

  3.  *

  4.  * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.util;

  12. 

  13. /**

  14.  * A collection that contains no duplicate elements.  More formally, sets

  15.  * contain no pair of elements <code>e1</code> and <code>e2</code> such that

  16.  * <code>e1.equals(e2)</code>, and at most one null element.  As implied by

  17.  * its name, this interface models the mathematical <i>set</i> abstraction.<p>

  18.  *

  19.  * The <tt>Set</tt> interface places additional stipulations, beyond those

  20.  * inherited from the <tt>Collection</tt> interface, on the contracts of all

  21.  * constructors and on the contracts of the <tt>add</tt>, <tt>equals</tt> and

  22.  * <tt>hashCode</tt> methods.  Declarations for other inherited methods are

  23.  * also included here for convenience.  (The specifications accompanying these

  24.  * declarations have been tailored to the <tt>Set</tt> interface, but they do

  25.  * not contain any additional stipulations.)<p>

  26.  *

  27.  * The additional stipulation on constructors is, not surprisingly,

  28.  * that all constructors must create a set that contains no duplicate elements

  29.  * (as defined above).<p>

  30.  *

  31.  * Note: Great care must be exercised if mutable objects are used as set

  32.  * elements.  The behavior of a set is not specified if the value of an object

  33.  * is changed in a manner that affects equals comparisons while the object is

  34.  * an element in the set.  A special case of this prohibition is that it is

  35.  * not permissible for a set to contain itself as an element.

  36.  *

  37.  * @author  Josh Bloch

  38.  * @version 1.23, 02/02/00

  39.  * @see Collection

  40.  * @see List

  41.  * @see SortedSet

  42.  * @see HashSet

  43.  * @see TreeSet

  44.  * @see AbstractSet

  45.  * @see Collections#singleton(java.lang.Object)

  46.  * @see Collections#EMPTY_SET

  47.  * @since 1.2

  48.  */

  49. 

  50. public interface Set extends Collection {

  51.     // Query Operations

  52. 

  53.     /**

  54.      * Returns the number of elements in this set (its cardinality).  If this

  55.      * set contains more than <tt>Integer.MAX_VALUE</tt> elements, returns

  56.      * <tt>Integer.MAX_VALUE</tt>.

  57.      *

  58.      * @return the number of elements in this set (its cardinality).

  59.      */

  60.     int size();

  61. 

  62.     /**

  63.      * Returns <tt>true</tt> if this set contains no elements.

  64.      *

  65.      * @return <tt>true</tt> if this set contains no elements.

  66.      */

  67.     boolean isEmpty();

  68. 

  69.     /**

  70.      * Returns <tt>true</tt> if this set contains the specified element.  More

  71.      * formally, returns <tt>true</tt> if and only if this set contains an

  72.      * element <code>e</code> such that <code>(o==null ? e==null :

  73.      * o.equals(e))</code>.

  74.      *

  75.      * @param o element whose presence in this set is to be tested.

  76.      * @return <tt>true</tt> if this set contains the specified element.

  77.      */

  78.     boolean contains(Object o);

  79. 

  80.     /**

  81.      * Returns an iterator over the elements in this set.  The elements are

  82.      * returned in no particular order (unless this set is an instance of some

  83.      * class that provides a guarantee).

  84.      *

  85.      * @return an iterator over the elements in this set.

  86.      */

  87.     Iterator iterator();

  88. 

  89.     /**

  90.      * Returns an array containing all of the elements in this set.

  91.      * Obeys the general contract of the <tt>Collection.toArray</tt> method.

  92.      *

  93.      * @return an array containing all of the elements in this set.

  94.      */

  95.     Object[] toArray();

  96. 

  97.     /**

  98.      * Returns an array containing all of the elements in this set whose

  99.      * runtime type is that of the specified array.  Obeys the general

  100.      * contract of the <tt>Collection.toArray(Object[])</tt> method.

  101.      *

  102.      * @param a the array into which the elements of this set are to

  103.      *		be stored, if it is big enough; otherwise, a new array of the

  104.      * 		same runtime type is allocated for this purpose.

  105.      * @return an array containing the elements of this set.

  106.      * @throws    ArrayStoreException the runtime type of a is not a supertype

  107.      * of the runtime type of every element in this set.

  108.      */

  109.     Object[] toArray(Object a[]);

  110. 

  111. 

  112.     // Modification Operations

  113. 

  114.     /**

  115.      * Adds the specified element to this set if it is not already present

  116.      * (optional operation).  More formally, adds the specified element,

  117.      * <code>o</code>, to this set if this set contains no element

  118.      * <code>e</code> such that <code>(o==null ? e==null :

  119.      * o.equals(e))</code>.  If this set already contains the specified

  120.      * element, the call leaves this set unchanged and returns <tt>false</tt>.

  121.      * In combination with the restriction on constructors, this ensures that

  122.      * sets never contain duplicate elements.<p>

  123.      *

  124.      * The stipulation above does not imply that sets must accept all

  125.      * elements; sets may refuse to add any particular element, including

  126.      * <tt>null</tt>, and throwing an exception, as described in the

  127.      * specification for <tt>Collection.add</tt>.  Individual set

  128.      * implementations should clearly document any restrictions on the the

  129.      * elements that they may contain.

  130.      *

  131.      * @param o element to be added to this set.

  132.      * @return <tt>true</tt> if this set did not already contain the specified

  133.      *         element.

  134.      * 

  135.      * @throws UnsupportedOperationException if the <tt>add</tt> method is not

  136.      * 	       supported by this set.

  137.      * @throws ClassCastException if the class of the specified element

  138.      * 	       prevents it from being added to this set.

  139.      * @throws IllegalArgumentException if some aspect of this element

  140.      *         prevents it from being added to this set.

  141.      */

  142.     boolean add(Object o);

  143. 

  144. 

  145.     /**

  146.      * Removes the specified element from this set if it is present (optional

  147.      * operation).  More formally, removes an element <code>e</code> such that

  148.      * <code>(o==null ?  e==null : o.equals(e))</code>, if the set contains

  149.      * such an element.  Returns <tt>true</tt> if the set contained the

  150.      * specified element (or equivalently, if the set changed as a result of

  151.      * the call).  (The set will not contain the specified element once the

  152.      * call returns.)

  153.      *

  154.      * @param o object to be removed from this set, if present.

  155.      * @return true if the set contained the specified element.

  156.      * @throws UnsupportedOperationException if the <tt>remove</tt> method is

  157.      *         not supported by this set.

  158.      */

  159.     boolean remove(Object o);

  160. 

  161. 

  162.     // Bulk Operations

  163. 

  164.     /**

  165.      * Returns <tt>true</tt> if this set contains all of the elements of the

  166.      * specified collection.  If the specified collection is also a set, this

  167.      * method returns <tt>true</tt> if it is a <i>subset</i> of this set.

  168.      *

  169.      * @param c collection to be checked for containment in this set.

  170.      * @return <tt>true</tt> if this set contains all of the elements of the

  171.      * 	       specified collection.

  172.      */

  173.     boolean containsAll(Collection c);

  174. 

  175.     /**

  176.      * Adds all of the elements in the specified collection to this set if

  177.      * they're not already present (optional operation).  If the specified

  178.      * collection is also a set, the <tt>addAll</tt> operation effectively

  179.      * modifies this set so that its value is the <i>union</i> of the two

  180.      * sets.  The behavior of this operation is unspecified if the specified

  181.      * collection is modified while the operation is in progress.

  182.      *

  183.      * @param c collection whose elements are to be added to this set.

  184.      * @return <tt>true</tt> if this set changed as a result of the call.

  185.      * 

  186.      * @throws UnsupportedOperationException if the <tt>addAll</tt> method is

  187.      * 		  not supported by this set.

  188.      * @throws ClassCastException if the class of some element of the

  189.      * 		  specified collection prevents it from being added to this

  190.      * 		  set.

  191.      * @throws IllegalArgumentException if some aspect of some element of the

  192.      *		  specified collection prevents it from being added to this

  193.      *		  set.

  194.      * @see #add(Object)

  195.      */

  196.     boolean addAll(Collection c);

  197. 

  198.     /**

  199.      * Retains only the elements in this set that are contained in the

  200.      * specified collection (optional operation).  In other words, removes

  201.      * from this set all of its elements that are not contained in the

  202.      * specified collection.  If the specified collection is also a set, this

  203.      * operation effectively modifies this set so that its value is the

  204.      * <i>intersection</i> of the two sets.

  205.      *

  206.      * @param c collection that defines which elements this set will retain.

  207.      * @return <tt>true</tt> if this collection changed as a result of the

  208.      *         call.

  209.      * @throws UnsupportedOperationException if the <tt>retainAll</tt> method

  210.      * 		  is not supported by this Collection.

  211.      * 

  212.      * @see #remove(Object)

  213.      */

  214.     boolean retainAll(Collection c);

  215. 

  216. 

  217.     /**

  218.      * Removes from this set all of its elements that are contained in the

  219.      * specified collection (optional operation).  If the specified

  220.      * collection is also a set, this operation effectively modifies this

  221.      * set so that its value is the <i>asymmetric set difference</i> of

  222.      * the two sets.

  223.      *

  224.      * @param c collection that defines which elements will be removed from

  225.      *          this set.

  226.      * @return <tt>true</tt> if this set changed as a result of the call.

  227.      * 

  228.      * @throws UnsupportedOperationException if the <tt>removeAll</tt>

  229.      * 		  method is not supported by this Collection.

  230.      * 

  231.      * @see #remove(Object) */

  232.     boolean removeAll(Collection c);

  233. 

  234.     /**

  235.      * Removes all of the elements from this set (optional operation).

  236.      * This set will be empty after this call returns (unless it throws an

  237.      * exception).

  238.      *

  239.      * @throws UnsupportedOperationException if the <tt>clear</tt> method

  240.      * 		  is not supported by this set.

  241.      */

  242.     void clear();

  243. 

  244. 

  245.     // Comparison and hashing

  246. 

  247.     /**

  248.      * Compares the specified object with this set for equality.  Returns

  249.      * <tt>true</tt> if the specified object is also a set, the two sets

  250.      * have the same size, and every member of the specified set is

  251.      * contained in this set (or equivalently, every member of this set is

  252.      * contained in the specified set).  This definition ensures that the

  253.      * equals method works properly across different implementations of the

  254.      * set interface.

  255.      *

  256.      * @param o Object to be compared for equality with this set.

  257.      * @return <tt>true</tt> if the specified Object is equal to this set.

  258.      */

  259.     boolean equals(Object o);

  260. 

  261.     /**

  262.      * 

  263.      * Returns the hash code value for this set.  The hash code of a set is

  264.      * defined to be the sum of the hash codes of the elements in the set,

  265.      * where the hashcode of a <tt>null</tt> element is defined to be zero.

  266.      * This ensures that <code>s1.equals(s2)</code> implies that

  267.      * <code>s1.hashCode()==s2.hashCode()</code> for any two sets

  268.      * <code>s1</code> and <code>s2</code>, as required by the general

  269.      * contract of the <tt>Object.hashCode</tt> method.

  270.      *

  271.      * @return the hash code value for this set.

  272.      * @see Object#hashCode()

  273.      * @see Object#equals(Object)

  274.      * @see Set#equals(Object)

  275.      */

  276.     int hashCode();

  277. }