001: /*
002: * @(#)Set.java 1.30 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.util;
029:
030: /**
031: * A collection that contains no duplicate elements. More formally, sets
032: * contain no pair of elements <code>e1</code> and <code>e2</code> such that
033: * <code>e1.equals(e2)</code>, and at most one null element. As implied by
034: * its name, this interface models the mathematical <i>set</i> abstraction.<p>
035: *
036: * The <tt>Set</tt> interface places additional stipulations, beyond those
037: * inherited from the <tt>Collection</tt> interface, on the contracts of all
038: * constructors and on the contracts of the <tt>add</tt>, <tt>equals</tt> and
039: * <tt>hashCode</tt> methods. Declarations for other inherited methods are
040: * also included here for convenience. (The specifications accompanying these
041: * declarations have been tailored to the <tt>Set</tt> interface, but they do
042: * not contain any additional stipulations.)<p>
043: *
044: * The additional stipulation on constructors is, not surprisingly,
045: * that all constructors must create a set that contains no duplicate elements
046: * (as defined above).<p>
047: *
048: * Note: Great care must be exercised if mutable objects are used as set
049: * elements. The behavior of a set is not specified if the value of an object
050: * is changed in a manner that affects equals comparisons while the object is
051: * an element in the set. A special case of this prohibition is that it is
052: * not permissible for a set to contain itself as an element.
053: *
054: * <p>Some set implementations have restrictions on the elements that
055: * they may contain. For example, some implementations prohibit null elements,
056: * and some have restrictions on the types of their elements. Attempting to
057: * add an ineligible element throws an unchecked exception, typically
058: * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. Attempting
059: * to query the presence of an ineligible element may throw an exception,
060: * or it may simply return false; some implementations will exhibit the former
061: * behavior and some will exhibit the latter. More generally, attempting an
062: * operation on an ineligible element whose completion would not result in
063: * the insertion of an ineligible element into the set may throw an
064: * exception or it may succeed, at the option of the implementation.
065: * Such exceptions are marked as "optional" in the specification for this
066: * interface.
067: *
068: * <p>This interface is a member of the
069: * <a href="{@docRoot}/../guide/collections/index.html">
070: * Java Collections Framework</a>.
071: *
072: * @author Josh Bloch
073: * @version 1.23, 02/02/00
074: * @see Collection
075: * @see List
076: * @see SortedSet
077: * @see HashSet
078: * @see TreeSet
079: * @see AbstractSet
080: * @see Collections#singleton(java.lang.Object)
081: * @see Collections#EMPTY_SET
082: * @since 1.2
083: */
084:
085: public interface Set extends Collection {
086: // Query Operations
087:
088: /**
089: * Returns the number of elements in this set (its cardinality). If this
090: * set contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
091: * <tt>Integer.MAX_VALUE</tt>.
092: *
093: * @return the number of elements in this set (its cardinality).
094: */
095: int size();
096:
097: /**
098: * Returns <tt>true</tt> if this set contains no elements.
099: *
100: * @return <tt>true</tt> if this set contains no elements.
101: */
102: boolean isEmpty();
103:
104: /**
105: * Returns <tt>true</tt> if this set contains the specified element. More
106: * formally, returns <tt>true</tt> if and only if this set contains an
107: * element <code>e</code> such that <code>(o==null ? e==null :
108: * o.equals(e))</code>.
109: *
110: * @param o element whose presence in this set is to be tested.
111: * @return <tt>true</tt> if this set contains the specified element.
112: * @throws ClassCastException if the type of the specified element
113: * is incompatible with this set (optional).
114: * @throws NullPointerException if the specified element is null and this
115: * set does not support null elements (optional).
116: */
117: boolean contains(Object o);
118:
119: /**
120: * Returns an iterator over the elements in this set. The elements are
121: * returned in no particular order (unless this set is an instance of some
122: * class that provides a guarantee).
123: *
124: * @return an iterator over the elements in this set.
125: */
126: Iterator iterator();
127:
128: /**
129: * Returns an array containing all of the elements in this set.
130: * Obeys the general contract of the <tt>Collection.toArray</tt> method.
131: *
132: * @return an array containing all of the elements in this set.
133: */
134: Object[] toArray();
135:
136: /**
137: * Returns an array containing all of the elements in this set; the
138: * runtime type of the returned array is that of the specified array.
139: * Obeys the general contract of the
140: * <tt>Collection.toArray(Object[])</tt> method.
141: *
142: * @param a the array into which the elements of this set are to
143: * be stored, if it is big enough; otherwise, a new array of the
144: * same runtime type is allocated for this purpose.
145: * @return an array containing the elements of this set.
146: * @throws ArrayStoreException the runtime type of a is not a supertype
147: * of the runtime type of every element in this set.
148: * @throws NullPointerException if the specified array is <tt>null</tt>.
149: */
150: Object[] toArray(Object a[]);
151:
152: // Modification Operations
153:
154: /**
155: * Adds the specified element to this set if it is not already present
156: * (optional operation). More formally, adds the specified element,
157: * <code>o</code>, to this set if this set contains no element
158: * <code>e</code> such that <code>(o==null ? e==null :
159: * o.equals(e))</code>. If this set already contains the specified
160: * element, the call leaves this set unchanged and returns <tt>false</tt>.
161: * In combination with the restriction on constructors, this ensures that
162: * sets never contain duplicate elements.<p>
163: *
164: * The stipulation above does not imply that sets must accept all
165: * elements; sets may refuse to add any particular element, including
166: * <tt>null</tt>, and throwing an exception, as described in the
167: * specification for <tt>Collection.add</tt>. Individual set
168: * implementations should clearly document any restrictions on the the
169: * elements that they may contain.
170: *
171: * @param o element to be added to this set.
172: * @return <tt>true</tt> if this set did not already contain the specified
173: * element.
174: *
175: * @throws UnsupportedOperationException if the <tt>add</tt> method is not
176: * supported by this set.
177: * @throws ClassCastException if the class of the specified element
178: * prevents it from being added to this set.
179: * @throws NullPointerException if the specified element is null and this
180: * set does not support null elements.
181: * @throws IllegalArgumentException if some aspect of the specified element
182: * prevents it from being added to this set.
183: */
184: boolean add(Object o);
185:
186: /**
187: * Removes the specified element from this set if it is present (optional
188: * operation). More formally, removes an element <code>e</code> such that
189: * <code>(o==null ? e==null : o.equals(e))</code>, if the set contains
190: * such an element. Returns <tt>true</tt> if the set contained the
191: * specified element (or equivalently, if the set changed as a result of
192: * the call). (The set will not contain the specified element once the
193: * call returns.)
194: *
195: * @param o object to be removed from this set, if present.
196: * @return true if the set contained the specified element.
197: * @throws ClassCastException if the type of the specified element
198: * is incompatible with this set (optional).
199: * @throws NullPointerException if the specified element is null and this
200: * set does not support null elements (optional).
201: * @throws UnsupportedOperationException if the <tt>remove</tt> method is
202: * not supported by this set.
203: */
204: boolean remove(Object o);
205:
206: // Bulk Operations
207:
208: /**
209: * Returns <tt>true</tt> if this set contains all of the elements of the
210: * specified collection. If the specified collection is also a set, this
211: * method returns <tt>true</tt> if it is a <i>subset</i> of this set.
212: *
213: * @param c collection to be checked for containment in this set.
214: * @return <tt>true</tt> if this set contains all of the elements of the
215: * specified collection.
216: * @throws ClassCastException if the types of one or more elements
217: * in the specified collection are incompatible with this
218: * set (optional).
219: * @throws NullPointerException if the specified collection contains one
220: * or more null elements and this set does not support null
221: * elements (optional).
222: * @throws NullPointerException if the specified collection is
223: * <tt>null</tt>.
224: * @see #contains(Object)
225: */
226: boolean containsAll(Collection c);
227:
228: /**
229: * Adds all of the elements in the specified collection to this set if
230: * they're not already present (optional operation). If the specified
231: * collection is also a set, the <tt>addAll</tt> operation effectively
232: * modifies this set so that its value is the <i>union</i> of the two
233: * sets. The behavior of this operation is unspecified if the specified
234: * collection is modified while the operation is in progress.
235: *
236: * @param c collection whose elements are to be added to this set.
237: * @return <tt>true</tt> if this set changed as a result of the call.
238: *
239: * @throws UnsupportedOperationException if the <tt>addAll</tt> method is
240: * not supported by this set.
241: * @throws ClassCastException if the class of some element of the
242: * specified collection prevents it from being added to this
243: * set.
244: * @throws NullPointerException if the specified collection contains one
245: * or more null elements and this set does not support null
246: * elements, or if the specified collection is <tt>null</tt>.
247: * @throws IllegalArgumentException if some aspect of some element of the
248: * specified collection prevents it from being added to this
249: * set.
250: * @see #add(Object)
251: */
252: boolean addAll(Collection c);
253:
254: /**
255: * Retains only the elements in this set that are contained in the
256: * specified collection (optional operation). In other words, removes
257: * from this set all of its elements that are not contained in the
258: * specified collection. If the specified collection is also a set, this
259: * operation effectively modifies this set so that its value is the
260: * <i>intersection</i> of the two sets.
261: *
262: * @param c collection that defines which elements this set will retain.
263: * @return <tt>true</tt> if this collection changed as a result of the
264: * call.
265: * @throws UnsupportedOperationException if the <tt>retainAll</tt> method
266: * is not supported by this Collection.
267: * @throws ClassCastException if the types of one or more elements in this
268: * set are incompatible with the specified collection
269: * (optional).
270: * @throws NullPointerException if this set contains a null element and
271: * the specified collection does not support null elements
272: * (optional).
273: * @throws NullPointerException if the specified collection is
274: * <tt>null</tt>.
275: * @see #remove(Object)
276: */
277: boolean retainAll(Collection c);
278:
279: /**
280: * Removes from this set all of its elements that are contained in the
281: * specified collection (optional operation). If the specified
282: * collection is also a set, this operation effectively modifies this
283: * set so that its value is the <i>asymmetric set difference</i> of
284: * the two sets.
285: *
286: * @param c collection that defines which elements will be removed from
287: * this set.
288: * @return <tt>true</tt> if this set changed as a result of the call.
289: *
290: * @throws UnsupportedOperationException if the <tt>removeAll</tt>
291: * method is not supported by this Collection.
292: * @throws ClassCastException if the types of one or more elements in this
293: * set are incompatible with the specified collection
294: * (optional).
295: * @throws NullPointerException if this set contains a null element and
296: * the specified collection does not support null elements
297: * (optional).
298: * @throws NullPointerException if the specified collection is
299: * <tt>null</tt>.
300: * @see #remove(Object)
301: */
302: boolean removeAll(Collection c);
303:
304: /**
305: * Removes all of the elements from this set (optional operation).
306: * This set will be empty after this call returns (unless it throws an
307: * exception).
308: *
309: * @throws UnsupportedOperationException if the <tt>clear</tt> method
310: * is not supported by this set.
311: */
312: void clear();
313:
314: // Comparison and hashing
315:
316: /**
317: * Compares the specified object with this set for equality. Returns
318: * <tt>true</tt> if the specified object is also a set, the two sets
319: * have the same size, and every member of the specified set is
320: * contained in this set (or equivalently, every member of this set is
321: * contained in the specified set). This definition ensures that the
322: * equals method works properly across different implementations of the
323: * set interface.
324: *
325: * @param o Object to be compared for equality with this set.
326: * @return <tt>true</tt> if the specified Object is equal to this set.
327: */
328: boolean equals(Object o);
329:
330: /**
331: *
332: * Returns the hash code value for this set. The hash code of a set is
333: * defined to be the sum of the hash codes of the elements in the set,
334: * where the hashcode of a <tt>null</tt> element is defined to be zero.
335: * This ensures that <code>s1.equals(s2)</code> implies that
336: * <code>s1.hashCode()==s2.hashCode()</code> for any two sets
337: * <code>s1</code> and <code>s2</code>, as required by the general
338: * contract of the <tt>Object.hashCode</tt> method.
339: *
340: * @return the hash code value for this set.
341: * @see Object#hashCode()
342: * @see Object#equals(Object)
343: * @see Set#equals(Object)
344: */
345: int hashCode();
346: }
|