001    /* Set.java -- A collection that prohibits duplicates
002       Copyright (C) 1998, 2001, 2004, 2005
003       Free Software Foundation, Inc.
004    
005    This file is part of GNU Classpath.
006    
007    GNU Classpath is free software; you can redistribute it and/or modify
008    it under the terms of the GNU General Public License as published by
009    the Free Software Foundation; either version 2, or (at your option)
010    any later version.
011    
012    GNU Classpath is distributed in the hope that it will be useful, but
013    WITHOUT ANY WARRANTY; without even the implied warranty of
014    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015    General Public License for more details.
016    
017    You should have received a copy of the GNU General Public License
018    along with GNU Classpath; see the file COPYING.  If not, write to the
019    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020    02110-1301 USA.
021    
022    Linking this library statically or dynamically with other modules is
023    making a combined work based on this library.  Thus, the terms and
024    conditions of the GNU General Public License cover the whole
025    combination.
026    
027    As a special exception, the copyright holders of this library give you
028    permission to link this library with independent modules to produce an
029    executable, regardless of the license terms of these independent
030    modules, and to copy and distribute the resulting executable under
031    terms of your choice, provided that you also meet, for each linked
032    independent module, the terms and conditions of the license of that
033    module.  An independent module is a module which is not derived from
034    or based on this library.  If you modify this library, you may extend
035    this exception to your version of the library, but you are not
036    obligated to do so.  If you do not wish to do so, delete this
037    exception statement from your version. */
038    
039    
040    package java.util;
041    
042    /**
043     * A collection that contains no duplicates. In other words, for two set
044     * elements e1 and e2, <code>e1.equals(e2)</code> returns false. There
045     * are additional stipulations on <code>add</code>, <code>equals</code>
046     * and <code>hashCode</code>, as well as the requirements that constructors
047     * do not permit duplicate elements. The Set interface is incompatible with
048     * List; you cannot implement both simultaneously.
049     * <p>
050     *
051     * Note: Be careful about using mutable objects in sets.  In particular,
052     * if a mutable object changes to become equal to another set element, you
053     * have violated the contract.  As a special case of this, a Set is not
054     * allowed to be an element of itself, without risking undefined behavior.
055     *
056     * @author Original author unknown
057     * @author Eric Blake (ebb9@email.byu.edu)
058     * @see Collection
059     * @see List
060     * @see SortedSet
061     * @see HashSet
062     * @see TreeSet
063     * @see LinkedHashSet
064     * @see AbstractSet
065     * @see Collections#singleton(Object)
066     * @see Collections#EMPTY_SET
067     * @since 1.2
068     * @status updated to 1.4
069     */
070    public interface Set<E> extends Collection<E>
071    {
072      /**
073       * Adds the specified element to the set if it is not already present
074       * (optional operation). In particular, the comparison algorithm is
075       * <code>o == null ? e == null : o.equals(e)</code>. Sets need not permit
076       * all values, and may document what exceptions will be thrown if
077       * a value is not permitted.
078       *
079       * @param o the object to add
080       * @return true if the object was not previously in the set
081       * @throws UnsupportedOperationException if this operation is not allowed
082       * @throws ClassCastException if the class of o prevents it from being added
083       * @throws IllegalArgumentException if some aspect of o prevents it from
084       *         being added
085       * @throws NullPointerException if null is not permitted in this set
086       */
087      boolean add(E o);
088    
089      /**
090       * Adds all of the elements of the given collection to this set (optional
091       * operation). If the argument is also a Set, this returns the mathematical
092       * <i>union</i> of the two. The behavior is unspecified if the set is
093       * modified while this is taking place.
094       *
095       * @param c the collection to add
096       * @return true if the set changed as a result
097       * @throws UnsupportedOperationException if this operation is not allowed
098       * @throws ClassCastException if the class of an element prevents it from
099       *         being added
100       * @throws IllegalArgumentException if something about an element prevents
101       *         it from being added
102       * @throws NullPointerException if null is not permitted in this set, or
103       *         if the argument c is null
104       * @see #add(Object)
105       */
106      boolean addAll(Collection<? extends E> c);
107    
108      /**
109       * Removes all elements from this set (optional operation). This set will
110       * be empty afterwords, unless an exception occurs.
111       *
112       * @throws UnsupportedOperationException if this operation is not allowed
113       */
114      void clear();
115    
116      /**
117       * Returns true if the set contains the specified element. In other words,
118       * this looks for <code>o == null ? e == null : o.equals(e)</code>.
119       *
120       * @param o the object to look for
121       * @return true if it is found in the set
122       * @throws ClassCastException if the type of o is not a valid type
123       *         for this set.
124       * @throws NullPointerException if o is null and this set doesn't
125       *         support null values.
126       */
127      boolean contains(Object o);
128    
129      /**
130       * Returns true if this set contains all elements in the specified
131       * collection. If the argument is also a set, this is the <i>subset</i>
132       * relationship.
133       *
134       * @param c the collection to check membership in
135       * @return true if all elements in this set are in c
136       * @throws NullPointerException if c is null
137       * @throws ClassCastException if the type of any element in c is not
138       *         a valid type for this set.
139       * @throws NullPointerException if some element of c is null and this
140       *         set doesn't support null values.
141       * @see #contains(Object)
142       */
143      boolean containsAll(Collection<?> c);
144    
145      /**
146       * Compares the specified object to this for equality. For sets, the object
147       * must be a set, the two must have the same size, and every element in
148       * one must be in the other.
149       *
150       * @param o the object to compare to
151       * @return true if it is an equal set
152       */
153      boolean equals(Object o);
154    
155      /**
156       * Returns the hash code for this set. In order to satisfy the contract of
157       * equals, this is the sum of the hashcode of all elements in the set.
158       *
159       * @return the sum of the hashcodes of all set elements
160       * @see #equals(Object)
161       */
162      int hashCode();
163    
164      /**
165       * Returns true if the set contains no elements.
166       *
167       * @return true if the set is empty
168       */
169      boolean isEmpty();
170    
171      /**
172       * Returns an iterator over the set.  The iterator has no specific order,
173       * unless further specified.
174       *
175       * @return a set iterator
176       */
177      Iterator<E> iterator();
178    
179      /**
180       * Removes the specified element from this set (optional operation). If
181       * an element e exists, <code>o == null ? e == null : o.equals(e)</code>,
182       * it is removed from the set.
183       *
184       * @param o the object to remove
185       * @return true if the set changed (an object was removed)
186       * @throws UnsupportedOperationException if this operation is not allowed
187       * @throws ClassCastException if the type of o is not a valid type
188       *         for this set.
189       * @throws NullPointerException if o is null and this set doesn't allow
190       *         the removal of a null value.
191       */
192      boolean remove(Object o);
193    
194      /**
195       * Removes from this set all elements contained in the specified collection
196       * (optional operation). If the argument is a set, this returns the
197       * <i>asymmetric set difference</i> of the two sets.
198       *
199       * @param c the collection to remove from this set
200       * @return true if this set changed as a result
201       * @throws UnsupportedOperationException if this operation is not allowed
202       * @throws NullPointerException if c is null
203       * @throws ClassCastException if the type of any element in c is not
204       *         a valid type for this set.
205       * @throws NullPointerException if some element of c is null and this
206       *         set doesn't support removing null values.
207       * @see #remove(Object)
208       */
209      boolean removeAll(Collection<?> c);
210    
211      /**
212       * Retains only the elements in this set that are also in the specified
213       * collection (optional operation). If the argument is also a set, this
214       * performs the <i>intersection</i> of the two sets.
215       *
216       * @param c the collection to keep
217       * @return true if this set was modified
218       * @throws UnsupportedOperationException if this operation is not allowed
219       * @throws NullPointerException if c is null
220       * @throws ClassCastException if the type of any element in c is not
221       *         a valid type for this set.
222       * @throws NullPointerException if some element of c is null and this
223       *         set doesn't support retaining null values.
224       * @see #remove(Object)
225       */
226      boolean retainAll(Collection<?> c);
227    
228      /**
229       * Returns the number of elements in the set. If there are more
230       * than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE. This is
231       * the <i>cardinality</i> of the set.
232       *
233       * @return the number of elements
234       */
235      int size();
236    
237      /**
238       * Returns an array containing the elements of this set. If the set
239       * makes a guarantee about iteration order, the array has the same
240       * order. The array is distinct from the set; modifying one does not
241       * affect the other.
242       *
243       * @return an array of this set's elements
244       * @see #toArray(Object[])
245       */
246      Object[] toArray();
247    
248      /**
249       * Returns an array containing the elements of this set, of the same runtime
250       * type of the argument. If the given set is large enough, it is reused,
251       * and null is inserted in the first unused slot. Otherwise, reflection
252       * is used to build a new array. If the set makes a guarantee about iteration
253       * order, the array has the same order. The array is distinct from the set;
254       * modifying one does not affect the other.
255       *
256       * @param a the array to determine the return type; if it is big enough
257       *        it is used and returned
258       * @return an array holding the elements of the set
259       * @throws ArrayStoreException if the runtime type of a is not a supertype
260       *         of all elements in the set
261       * @throws NullPointerException if a is null
262       * @see #toArray()
263       */
264      <T> T[] toArray(T[] a);
265    }