1 /* Set.java -- A collection that prohibits duplicates 2 Copyright (C) 1998, 2001, 2004, 2005 3 Free Software Foundation, Inc. 4 5 This file is part of GNU Classpath. 6 7 GNU Classpath is free software; you can redistribute it and/or modify 8 it under the terms of the GNU General Public License as published by 9 the Free Software Foundation; either version 2, or (at your option) 10 any later version. 11 12 GNU Classpath is distributed in the hope that it will be useful, but 13 WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with GNU Classpath; see the file COPYING. If not, write to the 19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 20 02110-1301 USA. 21 22 Linking this library statically or dynamically with other modules is 23 making a combined work based on this library. Thus, the terms and 24 conditions of the GNU General Public License cover the whole 25 combination. 26 27 As a special exception, the copyright holders of this library give you 28 permission to link this library with independent modules to produce an 29 executable, regardless of the license terms of these independent 30 modules, and to copy and distribute the resulting executable under 31 terms of your choice, provided that you also meet, for each linked 32 independent module, the terms and conditions of the license of that 33 module. An independent module is a module which is not derived from 34 or based on this library. If you modify this library, you may extend 35 this exception to your version of the library, but you are not 36 obligated to do so. If you do not wish to do so, delete this 37 exception statement from your version. */ 38 39 40 package java.util; 41 42 /** 43 * A collection that contains no duplicates. In other words, for two set 44 * elements e1 and e2, <code>e1.equals(e2)</code> returns false. There 45 * are additional stipulations on <code>add</code>, <code>equals</code> 46 * and <code>hashCode</code>, as well as the requirements that constructors 47 * do not permit duplicate elements. The Set interface is incompatible with 48 * List; you cannot implement both simultaneously. 49 * <p> 50 * 51 * Note: Be careful about using mutable objects in sets. In particular, 52 * if a mutable object changes to become equal to another set element, you 53 * have violated the contract. As a special case of this, a Set is not 54 * allowed to be an element of itself, without risking undefined behavior. 55 * 56 * @author Original author unknown 57 * @author Eric Blake (ebb9@email.byu.edu) 58 * @see Collection 59 * @see List 60 * @see SortedSet 61 * @see HashSet 62 * @see TreeSet 63 * @see LinkedHashSet 64 * @see AbstractSet 65 * @see Collections#singleton(Object) 66 * @see Collections#EMPTY_SET 67 * @since 1.2 68 * @status updated to 1.4 69 */ 70 public interface Set<E> extends Collection<E> 71 { 72 /** 73 * Adds the specified element to the set if it is not already present 74 * (optional operation). In particular, the comparison algorithm is 75 * <code>o == null ? e == null : o.equals(e)</code>. Sets need not permit 76 * all values, and may document what exceptions will be thrown if 77 * a value is not permitted. 78 * 79 * @param o the object to add 80 * @return true if the object was not previously in the set 81 * @throws UnsupportedOperationException if this operation is not allowed 82 * @throws ClassCastException if the class of o prevents it from being added 83 * @throws IllegalArgumentException if some aspect of o prevents it from 84 * being added 85 * @throws NullPointerException if null is not permitted in this set 86 */ add(E o)87 boolean add(E o); 88 89 /** 90 * Adds all of the elements of the given collection to this set (optional 91 * operation). If the argument is also a Set, this returns the mathematical 92 * <i>union</i> of the two. The behavior is unspecified if the set is 93 * modified while this is taking place. 94 * 95 * @param c the collection to add 96 * @return true if the set changed as a result 97 * @throws UnsupportedOperationException if this operation is not allowed 98 * @throws ClassCastException if the class of an element prevents it from 99 * 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 */ addAll(Collection<? extends E> c)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 */ clear()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 */ contains(Object o)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 */ containsAll(Collection<?> c)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 */ equals(Object o)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 */ hashCode()162 int hashCode(); 163 164 /** 165 * Returns true if the set contains no elements. 166 * 167 * @return true if the set is empty 168 */ isEmpty()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 */ iterator()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 */ remove(Object o)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 */ removeAll(Collection<?> c)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 */ retainAll(Collection<?> c)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 */ size()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 */ toArray()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 */ toArray(T[] a)264 <T> T[] toArray(T[] a); 265 } 266