java.util
Interface Set
java.lang.Object
|
+--java.util.Collection
|
+--java.util.Set
All Implemented Interfaces:
Collection
A collection that contains no duplicates. In other words, for two set
elements e1 and e2,
e1.equals(e2)
returns false. There
are additional stipulations on
add
,
equals
and
hashCode
, as well as the requirements that constructors
do not permit duplicate elements. The Set interface is incompatible with
List; you cannot implement both simultaneously.
Note: Be careful about using mutable objects in sets. In particular,
if a mutable object changes to become equal to another set element, you
have violated the contract. As a special case of this, a Set is not
allowed to be an element of itself, without risking undefined behavior.
Since:Authors:- Original author unknown
- Eric Blake <ebb9@email.byu.edu>
See Also:
add
public boolean add(java.lang.Object o)
Adds the specified element to the set if it is not already present
(optional operation). In particular, the comparison algorithm is
o == null ? e == null : o.equals(e)
. Sets need not permit
all values, and may document what exceptions will be thrown if
a value is not permitted.
Parameters:
Returns:
- true if the object was not previously in the set
Throws:
addAll
public boolean addAll(java.util.Collection c)
Adds all of the elements of the given collection to this set (optional
operation). If the argument is also a Set, this returns the mathematical
union of the two. The behavior is unspecified if the set is
modified while this is taking place.
Parameters:
Returns:
- true if the set changed as a result
Throws:
See Also:
clear
public void clear()
Removes all elements from this set (optional operation). This set will
be empty afterwords, unless an exception occurs.
Throws:
contains
public boolean contains(java.lang.Object o)
Returns true if the set contains the specified element. In other words,
this looks for o == null ? e == null : o.equals(e)
.
Parameters:
Returns:
- true if it is found in the set
containsAll
public boolean containsAll(java.util.Collection c)
Returns true if this set contains all elements in the specified
collection. If the argument is also a set, this is the subset
relationship.
Parameters:
Returns:
- true if all elements in this set are in c
Throws:
See Also:
equals
public boolean equals(java.lang.Object o)
Compares the specified object to this for equality. For sets, the object
must be a set, the two must have the same size, and every element in
one must be in the other.
Parameters:
Returns:
- true if it is an equal set
hashCode
public int hashCode()
Returns the hash code for this set. In order to satisfy the contract of
equals, this is the sum of the hashcode of all elements in the set.
Returns:
- the sum of the hashcodes of all set elements
isEmpty
public boolean isEmpty()
Returns true if the set contains no elements.
Returns:
iterator
public Iterator iterator()
Returns an iterator over the set. The iterator has no specific order,
unless further specified.
Returns:
remove
public boolean remove(java.lang.Object o)
Removes the specified element from this set (optional operation). If
an element e exists, o == null ? e == null : o.equals(e)
,
it is removed from the set.
Parameters:
Returns:
- true if the set changed (an object was removed)
Throws:
removeAll
public boolean removeAll(java.util.Collection c)
Removes from this set all elements contained in the specified collection
(optional operation). If the argument is a set, this returns the
asymmetric set difference of the two sets.
Parameters:
Returns:
- true if this set changed as a result
Throws:
See Also:
retainAll
public boolean retainAll(java.util.Collection c)
Retains only the elements in this set that are also in the specified
collection (optional operation). If the argument is also a set, this
performs the intersection of the two sets.
Parameters:
Returns:
- true if this set was modified
Throws:
See Also:
size
public int size()
Returns the number of elements in the set. If there are more
than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE. This is
the cardinality of the set.
Returns:
toArray
public Object[] toArray()
Returns an array containing the elements of this set. If the set
makes a guarantee about iteration order, the array has the same
order. The array is distinct from the set; modifying one does not
affect the other.
Returns:
- an array of this set's elements
See Also:
toArray
public Object[] toArray(java.lang.Object[] a)
Returns an array containing the elements of this set, of the same runtime
type of the argument. If the given set is large enough, it is reused,
and null is inserted in the first unused slot. Otherwise, reflection
is used to build a new array. If the set makes a guarantee about iteration
order, the array has the same order. The array is distinct from the set;
modifying one does not affect the other.
Parameters:
Returns:
- an array holding the elements of the set
Throws:
See Also:
e1.equals(e2)
returns false. There are additional stipulations onadd
,equals
andhashCode
, as well as the requirements that constructors do not permit duplicate elements. The Set interface is incompatible with List; you cannot implement both simultaneously.Note: Be careful about using mutable objects in sets. In particular, if a mutable object changes to become equal to another set element, you have violated the contract. As a special case of this, a Set is not allowed to be an element of itself, without risking undefined behavior.