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 }