001/* Set.java -- A collection that prohibits duplicates
002   Copyright (C) 1998, 2001, 2004, 2005
003   Free Software Foundation, Inc.
004
005This file is part of GNU Classpath.
006
007GNU Classpath is free software; you can redistribute it and/or modify
008it under the terms of the GNU General Public License as published by
009the Free Software Foundation; either version 2, or (at your option)
010any later version.
011
012GNU Classpath is distributed in the hope that it will be useful, but
013WITHOUT ANY WARRANTY; without even the implied warranty of
014MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015General Public License for more details.
016
017You should have received a copy of the GNU General Public License
018along with GNU Classpath; see the file COPYING.  If not, write to the
019Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02002110-1301 USA.
021
022Linking this library statically or dynamically with other modules is
023making a combined work based on this library.  Thus, the terms and
024conditions of the GNU General Public License cover the whole
025combination.
026
027As a special exception, the copyright holders of this library give you
028permission to link this library with independent modules to produce an
029executable, regardless of the license terms of these independent
030modules, and to copy and distribute the resulting executable under
031terms of your choice, provided that you also meet, for each linked
032independent module, the terms and conditions of the license of that
033module.  An independent module is a module which is not derived from
034or based on this library.  If you modify this library, you may extend
035this exception to your version of the library, but you are not
036obligated to do so.  If you do not wish to do so, delete this
037exception statement from your version. */
038
039
040package 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 */
070public 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}