1 *java.util.Set* *Set* A collection that contains no duplicate elements.
3 public interface interface Set
5 implements |java.util.Collection|
7 |java.util.Set_Description|
9 |java.util.Set_Constructors|
10 |java.util.Set_Methods|
12 ================================================================================
14 *java.util.Set_Methods*
15 |java.util.Set.add(E)|Adds the specified element to this set if it is not alrea
16 |java.util.Set.addAll(Collection)|Adds all of the elements in the specified col
17 |java.util.Set.clear()|Removes all of the elements from this set (optional oper
18 |java.util.Set.contains(Object)|Returns true if this set contains the specified
19 |java.util.Set.containsAll(Collection)|Returns true if this set contains all of
20 |java.util.Set.equals(Object)|Compares the specified object with this set for e
21 |java.util.Set.hashCode()|Returns the hash code value for this set.
22 |java.util.Set.isEmpty()|Returns true if this set contains no elements.
23 |java.util.Set.iterator()|Returns an iterator over the elements in this set.
24 |java.util.Set.remove(Object)|Removes the specified element from this set if it
25 |java.util.Set.removeAll(Collection)|Removes from this set all of its elements
26 |java.util.Set.retainAll(Collection)|Retains only the elements in this set that
27 |java.util.Set.size()|Returns the number of elements in this set (its cardinali
28 |java.util.Set.toArray()|Returns an array containing all of the elements in thi
29 |java.util.Set.toArray(T[])|Returns an array containing all of the elements in
31 *java.util.Set_Description*
33 A collection that contains no duplicate elements. More formally, sets contain
34 no pair of elements e1 and e2 such that e1.equals(e2), and at most one null
35 element. As implied by its name, this interface models the mathematical set
38 The Set interface places additional stipulations, beyond those inherited from
39 the Collection interface, on the contracts of all constructors and on the
40 contracts of the add, equals and hashCode methods. Declarations for other
41 inherited methods are also included here for convenience. (The specifications
42 accompanying these declarations have been tailored to the Set interface, but
43 they do not contain any additional stipulations.)
45 The additional stipulation on constructors is, not surprisingly, that all
46 constructors must create a set that contains no duplicate elements (as defined
49 Note: Great care must be exercised if mutable objects are used as set elements.
50 The behavior of a set is not specified if the value of an object is changed in
51 a manner that affects equals comparisons while the object is an element in the
52 set. A special case of this prohibition is that it is not permissible for a set
53 to contain itself as an element.
55 Some set implementations have restrictions on the elements that they may
56 contain. For example, some implementations prohibit null elements, and some
57 have restrictions on the types of their elements. Attempting to add an
58 ineligible element throws an unchecked exception, typically
59 NullPointerException or ClassCastException. Attempting to query the presence of
60 an ineligible element may throw an exception, or it may simply return false;
61 some implementations will exhibit the former behavior and some will exhibit the
62 latter. More generally, attempting an operation on an ineligible element whose
63 completion would not result in the insertion of an ineligible element into the
64 set may throw an exception or it may succeed, at the option of the
65 implementation. Such exceptions are marked as "optional" in the specification
68 This interface is a member of the <a href="/../guide/collections/index.html">
69 Java Collections Framework.
72 *java.util.Set.add(E)*
74 public boolean add(java.lang.Object o)
76 Adds the specified element to this set if it is not already present (optional
77 operation). More formally, adds the specified element, o, to this set if this
78 set contains no element e such that (o==null ? e==null : o.equals(e)). If this
79 set already contains the specified element, the call leaves this set unchanged
80 and returns false. In combination with the restriction on constructors, this
81 ensures that sets never contain duplicate elements.
83 The stipulation above does not imply that sets must accept all elements; sets
84 may refuse to add any particular element, including null, and throwing an
85 exception, as described in the specification for Collection.add. Individual set
86 implementations should clearly document any restrictions on the elements that
89 o - element to be added to this set.
91 Returns: true if this set did not already contain the specified element.
92 *java.util.Set.addAll(Collection)*
94 public boolean addAll(java.util.Collection c)
96 Adds all of the elements in the specified collection to this set if they're not
97 already present (optional operation). If the specified collection is also a
98 set, the addAll operation effectively modifies this set so that its value is
99 the union of the two sets. The behavior of this operation is unspecified if the
100 specified collection is modified while the operation is in progress.
102 c - collection whose elements are to be added to this set.
104 Returns: true if this set changed as a result of the call.
105 *java.util.Set.clear()*
109 Removes all of the elements from this set (optional operation). This set will
110 be empty after this call returns (unless it throws an exception).
113 *java.util.Set.contains(Object)*
115 public boolean contains(java.lang.Object o)
117 Returns true if this set contains the specified element. More formally, returns
118 true if and only if this set contains an element e such that (o==null ? e==null
121 o - element whose presence in this set is to be tested.
123 Returns: true if this set contains the specified element.
124 *java.util.Set.containsAll(Collection)*
126 public boolean containsAll(java.util.Collection c)
128 Returns true if this set contains all of the elements of the specified
129 collection. If the specified collection is also a set, this method returns true
130 if it is a subset of this set.
132 c - collection to be checked for containment in this set.
134 Returns: true if this set contains all of the elements of the specified collection.
135 *java.util.Set.equals(Object)*
137 public boolean equals(java.lang.Object o)
139 Compares the specified object with this set for equality. Returns true if the
140 specified object is also a set, the two sets have the same size, and every
141 member of the specified set is contained in this set (or equivalently, every
142 member of this set is contained in the specified set). This definition ensures
143 that the equals method works properly across different implementations of the
146 o - Object to be compared for equality with this set.
148 Returns: true if the specified Object is equal to this set.
149 *java.util.Set.hashCode()*
151 public int hashCode()
153 Returns the hash code value for this set. The hash code of a set is defined to
154 be the sum of the hash codes of the elements in the set, where the hashcode of
155 a null element is defined to be zero. This ensures that s1.equals(s2) implies
156 that s1.hashCode()==s2.hashCode() for any two sets s1 and s2, as required by
157 the general contract of the Object.hashCode method.
160 Returns: the hash code value for this set.
161 *java.util.Set.isEmpty()*
163 public boolean isEmpty()
165 Returns true if this set contains no elements.
168 Returns: true if this set contains no elements.
169 *java.util.Set.iterator()*
171 public |java.util.Iterator| iterator()
173 Returns an iterator over the elements in this set. The elements are returned in
174 no particular order (unless this set is an instance of some class that provides
178 Returns: an iterator over the elements in this set.
179 *java.util.Set.remove(Object)*
181 public boolean remove(java.lang.Object o)
183 Removes the specified element from this set if it is present (optional
184 operation). More formally, removes an element e such that (o==null ? e==null :
185 o.equals(e)), if the set contains such an element. Returns true if the set
186 contained the specified element (or equivalently, if the set changed as a
187 result of the call). (The set will not contain the specified element once the
190 o - object to be removed from this set, if present.
192 Returns: true if the set contained the specified element.
193 *java.util.Set.removeAll(Collection)*
195 public boolean removeAll(java.util.Collection c)
197 Removes from this set all of its elements that are contained in the specified
198 collection (optional operation). If the specified collection is also a set,
199 this operation effectively modifies this set so that its value is the
200 asymmetric set difference of the two sets.
202 c - collection that defines which elements will be removed from this set.
204 Returns: true if this set changed as a result of the call.
205 *java.util.Set.retainAll(Collection)*
207 public boolean retainAll(java.util.Collection c)
209 Retains only the elements in this set that are contained in the specified
210 collection (optional operation). In other words, removes from this set all of
211 its elements that are not contained in the specified collection. If the
212 specified collection is also a set, this operation effectively modifies this
213 set so that its value is the intersection of the two sets.
215 c - collection that defines which elements this set will retain.
217 Returns: true if this collection changed as a result of the call.
218 *java.util.Set.size()*
222 Returns the number of elements in this set (its cardinality). If this set
223 contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
226 Returns: the number of elements in this set (its cardinality).
227 *java.util.Set.toArray()*
229 public |java.lang.Object| toArray()
231 Returns an array containing all of the elements in this set. Obeys the general
232 contract of the Collection.toArray method.
235 Returns: an array containing all of the elements in this set.
236 *java.util.Set.toArray(T[])*
238 public |java.lang.Object| toArray(java.lang.Object[] a)
240 Returns an array containing all of the elements in this set; the runtime type
241 of the returned array is that of the specified array. Obeys the general
242 contract of the Collection.toArray(Object[]) method.
244 a - the array into which the elements of this set are to be stored, if it is big
245 enough; otherwise, a new array of the same runtime type is allocated for
248 Returns: an array containing the elements of this set.