1. /*

  2.  * @(#)Set.java	1.19 01/11/29

  3.  *

  4.  * Copyright 2002 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.util;

  9. 

  10. /**

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

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

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

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

  15.  *

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

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

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

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

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

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

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

  23.  *

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

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

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

  27.  *

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

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

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

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

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

  33.  *

  34.  * @author  Josh Bloch

  35.  * @version 1.19 11/29/01

  36.  * @see Collection

  37.  * @see List

  38.  * @see SortedSet

  39.  * @see HashSet

  40.  * @see TreeSet

  41.  * @see AbstractSet

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

  43.  * @see Collections#EMPTY_SET

  44.  * @since JDK1.2

  45.  */

  46. 

  47. public interface Set extends Collection {

  48.     // Query Operations

  49. 

  50.     /**

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

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

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

  54.      *

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

  56.      */

  57.     int size();

  58. 

  59.     /**

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

  61.      *

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

  63.      */

  64.     boolean isEmpty();

  65. 

  66.     /**

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

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

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

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

  71.      *

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

  73.      */

  74.     boolean contains(Object o);

  75. 

  76.     /**

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

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

  79.      * class that provides a guarantee).

  80.      *

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

  82.      */

  83.     Iterator iterator();

  84. 

  85.     /**

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

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

  88.      *

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

  90.      */

  91.     Object[] toArray();

  92. 

  93.     /**

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

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

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

  97.      *

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

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

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

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

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

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

  104.      */

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

  106. 

  107. 

  108.     // Modification Operations

  109. 

  110.     /**

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

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

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

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

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

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

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

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

  119.      *

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

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

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

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

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

  125.      * elements that they may contain.

  126.      *

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

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

  129.      *         element.

  130.      * 

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

  132.      * 	       supported by this set.

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

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

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

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

  137.      */

  138.     boolean add(Object o);

  139. 

  140. 

  141.     /**

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

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

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

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

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

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

  148.      * call returns.)

  149.      *

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

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

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

  153.      *         not supported by this set.

  154.      */

  155.     boolean remove(Object o);

  156. 

  157. 

  158.     // Bulk Operations

  159. 

  160.     /**

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

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

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

  164.      *

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

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

  167.      * 	       specified collection.

  168.      */

  169.     boolean containsAll(Collection c);

  170. 

  171.     /**

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

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

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

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

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

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

  178.      *

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

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

  181.      * 

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

  183.      * 		  not supported by this set.

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

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

  186.      * 		  set.

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

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

  189.      *		  set.

  190.      * @see #add(Object)

  191.      */

  192.     boolean addAll(Collection c);

  193. 

  194.     /**

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

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

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

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

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

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

  201.      *

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

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

  204.      *         call.

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

  206.      * 		  is not supported by this Collection.

  207.      * 

  208.      * @see #remove(Object)

  209.      */

  210.     boolean retainAll(Collection c);

  211. 

  212. 

  213.     /**

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

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

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

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

  218.      * the two sets.

  219.      *

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

  221.      *          this set.

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

  223.      * 

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

  225.      * 		  method is not supported by this Collection.

  226.      * 

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

  228.     boolean removeAll(Collection c);

  229. 

  230.     /**

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

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

  233.      * exception).

  234.      *

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

  236.      * 		  is not supported by this set.

  237.      */

  238.     void clear();

  239. 

  240. 

  241.     // Comparison and hashing

  242. 

  243.     /**

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

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

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

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

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

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

  250.      * set interface.

  251.      *

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

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

  254.      */

  255.     boolean equals(Object o);

  256. 

  257.     /**

  258.      * 

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

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

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

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

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

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

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

  266.      *

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

  268.      * @see Object#hashCode()

  269.      * @see Object#equals(Object)

  270.      * @see Set#equals(Object)

  271.      */

  272.     int hashCode();

  273. }