1 |
/* Set.java -- A collection that prohibits duplicates |
/* Set.java -- A collection that prohibits duplicates |
2 |
Copyright (C) 1998 Free Software Foundation, Inc. |
Copyright (C) 1998, 2001 Free Software Foundation, Inc. |
3 |
|
|
4 |
This file is part of GNU Classpath. |
This file is part of GNU Classpath. |
5 |
|
|
25 |
executable file might be covered by the GNU General Public License. */ |
executable file might be covered by the GNU General Public License. */ |
26 |
|
|
27 |
|
|
|
// TO DO: |
|
|
// ~ Doc comments for everything. |
|
|
|
|
28 |
package java.util; |
package java.util; |
29 |
|
|
30 |
|
/** |
31 |
|
* A collection that contains no duplicates. In other words, for two set |
32 |
|
* elements e1 and e2, <code>e1.equals(e2)</code> returns false. There |
33 |
|
* are additional stipulations on <code>add</code>, <code>equals</code> |
34 |
|
* and <code>hashCode</code>, as well as the requirements that constructors |
35 |
|
* do not permit duplicate elements. The Set interface is incompatible with |
36 |
|
* List; you cannot implement both simultaneously. |
37 |
|
* <p> |
38 |
|
* |
39 |
|
* Note: Be careful about using mutable objects in sets. In particular, |
40 |
|
* if a mutable object changes to become equal to another set element, you |
41 |
|
* have violated the contract. As a special case of this, a Set is not |
42 |
|
* allowed to be an element of itself, without risking undefined behavior. |
43 |
|
* |
44 |
|
* @author Original author unknown |
45 |
|
* @author Eric Blake <ebb9@email.byu.edu> |
46 |
|
* @see Collection |
47 |
|
* @see List |
48 |
|
* @see SortedSet |
49 |
|
* @see HashSet |
50 |
|
* @see TreeSet |
51 |
|
* @see LinkedHashSet |
52 |
|
* @see AbstractSet |
53 |
|
* @see Collections#singleton(Object) |
54 |
|
* @see Collections#EMPTY_SET |
55 |
|
* @since 1.2 |
56 |
|
* @status updated to 1.4 |
57 |
|
*/ |
58 |
public interface Set extends Collection |
public interface Set extends Collection |
59 |
{ |
{ |
60 |
|
/** |
61 |
|
* Adds the specified element to the set if it is not already present |
62 |
|
* (optional operation). In particular, the comparison algorithm is |
63 |
|
* <code>o == null ? e == null : o.equals(e)</code>. Sets need not permit |
64 |
|
* all values, and may document what exceptions will be thrown if |
65 |
|
* a value is not permitted. |
66 |
|
* |
67 |
|
* @param o the object to add |
68 |
|
* @return true if the object was not previously in the set |
69 |
|
* @throws UnsupportedOperationException if this operation is not allowed |
70 |
|
* @throws ClassCastException if the class of o prevents it from being added |
71 |
|
* @throws IllegalArgumentException if some aspect of o prevents it from |
72 |
|
* being added |
73 |
|
* @throws NullPointerException if null is not permitted in this set |
74 |
|
*/ |
75 |
boolean add(Object o); |
boolean add(Object o); |
76 |
|
|
77 |
|
/** |
78 |
|
* Adds all of the elements of the given collection to this set (optional |
79 |
|
* operation). If the argument is also a Set, this returns the mathematical |
80 |
|
* <i>union</i> of the two. The behavior is unspecified if the set is |
81 |
|
* modified while this is taking place. |
82 |
|
* |
83 |
|
* @param c the collection to add |
84 |
|
* @return true if the set changed as a result |
85 |
|
* @throws UnsupportedOperationException if this operation is not allowed |
86 |
|
* @throws ClassCastException if the class of an element prevents it from |
87 |
|
* being added |
88 |
|
* @throws IllegalArgumentException if something about an element prevents |
89 |
|
* it from being added |
90 |
|
* @throws NullPointerException if null is not permitted in this set, or |
91 |
|
* if the argument c is null |
92 |
|
* @see #add(Object) |
93 |
|
*/ |
94 |
boolean addAll(Collection c); |
boolean addAll(Collection c); |
95 |
|
|
96 |
|
/** |
97 |
|
* Removes all elements from this set (optional operation). This set will |
98 |
|
* be empty afterwords, unless an exception occurs. |
99 |
|
* |
100 |
|
* @throws UnsupportedOperationException if this operation is not allowed |
101 |
|
*/ |
102 |
void clear(); |
void clear(); |
103 |
|
|
104 |
|
/** |
105 |
|
* Returns true if the set contains the specified element. In other words, |
106 |
|
* this looks for <code>o == null ? e == null : o.equals(e)</code>. |
107 |
|
* |
108 |
|
* @param o the object to look for |
109 |
|
* @return true if it is found in the set |
110 |
|
*/ |
111 |
boolean contains(Object o); |
boolean contains(Object o); |
112 |
|
|
113 |
|
/** |
114 |
|
* Returns true if this set contains all elements in the specified |
115 |
|
* collection. If the argument is also a set, this is the <i>subset</i> |
116 |
|
* relationship. |
117 |
|
* |
118 |
|
* @param c the collection to check membership in |
119 |
|
* @return true if all elements in this set are in c |
120 |
|
* @throws NullPointerException if c is null |
121 |
|
* @see #contains(Object) |
122 |
|
*/ |
123 |
boolean containsAll(Collection c); |
boolean containsAll(Collection c); |
124 |
|
|
125 |
|
/** |
126 |
|
* Compares the specified object to this for equality. For sets, the object |
127 |
|
* must be a set, the two must have the same size, and every element in |
128 |
|
* one must be in the other. |
129 |
|
* |
130 |
|
* @param o the object to compare to |
131 |
|
* @return true if it is an equal set |
132 |
|
*/ |
133 |
boolean equals(Object o); |
boolean equals(Object o); |
134 |
|
|
135 |
|
/** |
136 |
|
* Returns the hash code for this set. In order to satisfy the contract of |
137 |
|
* equals, this is the sum of the hashcode of all elements in the set. |
138 |
|
* |
139 |
|
* @return the sum of the hashcodes of all set elements |
140 |
|
*/ |
141 |
int hashCode(); |
int hashCode(); |
142 |
|
|
143 |
|
/** |
144 |
|
* Returns true if the set contains no elements. |
145 |
|
* |
146 |
|
* @return true if the set is empty |
147 |
|
*/ |
148 |
boolean isEmpty(); |
boolean isEmpty(); |
149 |
|
|
150 |
|
/** |
151 |
|
* Returns an iterator over the set. The iterator has no specific order, |
152 |
|
* unless further specified. |
153 |
|
* |
154 |
|
* @return a set iterator |
155 |
|
*/ |
156 |
Iterator iterator(); |
Iterator iterator(); |
157 |
|
|
158 |
|
/** |
159 |
|
* Removes the specified element from this set (optional operation). If |
160 |
|
* an element e exists, <code>o == null ? e == null : o.equals(e)</code>, |
161 |
|
* it is removed from the set. |
162 |
|
* |
163 |
|
* @param o the object to remove |
164 |
|
* @return true if the set changed (an object was removed) |
165 |
|
* @throws UnsupportedOperationException if this operation is not allowed |
166 |
|
*/ |
167 |
boolean remove(Object o); |
boolean remove(Object o); |
168 |
|
|
169 |
|
/** |
170 |
|
* Removes from this set all elements contained in the specified collection |
171 |
|
* (optional operation). If the argument is a set, this returns the |
172 |
|
* <i>asymmetric set difference</i> of the two sets. |
173 |
|
* |
174 |
|
* @param c the collection to remove from this set |
175 |
|
* @return true if this set changed as a result |
176 |
|
* @throws UnsupportedOperationException if this operation is not allowed |
177 |
|
* @throws NullPointerException if c is null |
178 |
|
* @see #remove(Object) |
179 |
|
*/ |
180 |
boolean removeAll(Collection c); |
boolean removeAll(Collection c); |
181 |
|
|
182 |
|
/** |
183 |
|
* Retains only the elements in this set that are also in the specified |
184 |
|
* collection (optional operation). If the argument is also a set, this |
185 |
|
* performs the <i>intersection</i> of the two sets. |
186 |
|
* |
187 |
|
* @param c the collection to keep |
188 |
|
* @return true if this set was modified |
189 |
|
* @throws UnsupportedOperationException if this operation is not allowed |
190 |
|
* @throws NullPointerException if c is null |
191 |
|
* @see #remove(Object) |
192 |
|
*/ |
193 |
boolean retainAll(Collection c); |
boolean retainAll(Collection c); |
194 |
|
|
195 |
|
/** |
196 |
|
* Returns the number of elements in the set. If there are more |
197 |
|
* than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE. This is |
198 |
|
* the <i>cardinality</i> of the set. |
199 |
|
* |
200 |
|
* @return the number of elements |
201 |
|
*/ |
202 |
int size(); |
int size(); |
203 |
|
|
204 |
|
/** |
205 |
|
* Returns an array containing the elements of this set. If the set |
206 |
|
* makes a guarantee about iteration order, the array has the same |
207 |
|
* order. The array is distinct from the set; modifying one does not |
208 |
|
* affect the other. |
209 |
|
* |
210 |
|
* @return an array of this set's elements |
211 |
|
* @see #toArray(Object[]) |
212 |
|
*/ |
213 |
Object[] toArray(); |
Object[] toArray(); |
214 |
|
|
215 |
|
/** |
216 |
|
* Returns an array containing the elements of this set, of the same runtime |
217 |
|
* type of the argument. If the given set is large enough, it is reused, |
218 |
|
* and null is inserted in the first unused slot. Otherwise, reflection |
219 |
|
* is used to build a new array. If the set makes a guarantee about iteration |
220 |
|
* order, the array has the same order. The array is distinct from the set; |
221 |
|
* modifying one does not affect the other. |
222 |
|
* |
223 |
|
* @param a the array to determine the return type; if it is big enough |
224 |
|
* it is used and returned |
225 |
|
* @return an array holding the elements of the set |
226 |
|
* @throws ArrayStoreException if the runtime type of a is not a supertype |
227 |
|
* of all elements in the set |
228 |
|
* @throws NullPointerException if a is null |
229 |
|
* @see #toArray() |
230 |
|
*/ |
231 |
|
Object[] toArray(Object[] a); |
232 |
} |
} |