java::util::HashSet Class Reference

Inheritance diagram for java::util::HashSet:

Inheritance graph
java::util::AbstractSetjava::util::AbstractCollectionjava::util::Collectionjava::util::Setjava::lang::Interfacejava::lang::Object
[legend]
Collaboration diagram for java::util::HashSet:

Collaboration graph
java::util::AbstractSetjava::util::AbstractCollectionjava::util::Collectionjava::util::Setjava::lang::Interfacejava::lang::Comparablejava::lang::Objectjava::lang::ObjectRef
[legend]

List of all members.


Detailed Description

This class implements the Set interface, backed by a hash table (actually a HashMap instance).

It makes no guarantees as to the iteration order of the set; in particular, it does not guarantee that the order will remain constant over time. This class permits the null element.

This class offers constant time performance for the basic operations (add, remove, contains and size), assuming the hash function disperses the elements properly among the buckets. Iterating over this set requires time proportional to the sum of the HashSet instance's size (the number of elements) plus the "capacity" of the backing HashMap instance (the number of buckets). Thus, it's very important not to set the initial capacity too high (or the load factor too low) if iteration performance is important.

Note that this implementation is not synchronized. If multiple threads access a set concurrently, and at least one of the threads modifies the set, it must be synchronized externally. This is typically accomplished by synchronizing on some object that naturally encapsulates the set. If no such object exists, the set should be "wrapped" using the Collections.synchronizedSet method. This is best done at creation time, to prevent accidental unsynchronized access to the HashSet instance:

     Set s = Collections.synchronizedSet(new HashSet(...));
 

The iterators returned by this class's iterator method are fail-fast: if the set is modified at any time after the iterator is created, in any way except through the iterator's own remove method, the Iterator throws a ConcurrentModificationException. Thus, in the face of concurrent modification, the iterator fails quickly and cleanly, rather than risking arbitrary, non-deterministic behavior at an undetermined time in the future.

Note that the fail-fast behavior of an iterator cannot be guaranteed as it is, generally speaking, impossible to make any hard guarantees in the presence of unsynchronized concurrent modification. Fail-fast iterators throw ConcurrentModificationException on a best-effort basis. Therefore, it would be wrong to write a program that depended on this exception for its correctness: the fail-fast behavior of iterators should be used only to detect bugs.

Author:
Josh Bloch
Version:
1.25, 12/03/01
See also:
Collection

Set

TreeSet

Collections::synchronizedSet(Set)

HashMap

Since:
1.2

Public Member Functions

 HashSet (jint initialCapacity=DEFAULT_INITIAL_CAPACITY, jfloat loadFactor=DEFAULT_LOAD_FACTOR)
 Constructs a new, empty linked hash set.
 HashSet (const Collection &c)
 Constructs a new set containing the elements in the specified collection.
virtual jint size () const
 Returns the number of elements in this collection.
virtual jboolean isEmpty () const
 Returns true if this collection contains no elements.
virtual jboolean contains (const ObjectRef &o) const
 Returns true if this collection contains the specified element.
virtual Ref< Iteratoriterator () const
 Returns an iterator over the elements in this collection.
virtual jboolean add (const ObjectRef &o)
 Ensures that this collection contains the specified element (optional operation).
virtual jboolean remove (const ObjectRef &o)
 Removes a single instance of the specified element from this collection, if it is present (optional operation).
virtual void clear ()
 Removes all of the elements from this collection (optional operation).

Static Public Attributes

static const jint DEFAULT_INITIAL_CAPACITY
 The default initial capacity - MUST be a power of two.
static const jfloat DEFAULT_LOAD_FACTOR
 The load fast used when none specified in constructor.

Constructor & Destructor Documentation

java::util::HashSet::HashSet ( jint  initialCapacity = DEFAULT_INITIAL_CAPACITY,
jfloat  loadFactor = DEFAULT_LOAD_FACTOR 
)

Constructs a new, empty linked hash set.

(This package private constructor is only used by LinkedHashSet.) The backing HashMap instance is a LinkedHashMap with the specified initial capacity and the specified load factor.

Parameters:
initialCapacity the initial capacity of the hash map.
loadFactor the load factor of the hash map.
dummy ignored (distinguishes this constructor from other int, float constructor.)
Exceptions:
IllegalArgumentException if the initial capacity is less than zero, or if the load factor is nonpositive.

java::util::HashSet::HashSet ( const Collection c  ) 

Constructs a new set containing the elements in the specified collection.

The HashMap is created with default load factor (0.75) and an initial capacity sufficient to contain the elements in the specified collection.

Parameters:
c the collection whose elements are to be placed into this set.
Exceptions:
NullPointerException if the specified collection is null.


Member Function Documentation

virtual jint java::util::HashSet::size (  )  const [virtual]

Returns the number of elements in this collection.

If this collection contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:
the number of elements in this collection

Implements java::util::Collection.

virtual jboolean java::util::HashSet::isEmpty (  )  const [virtual]

Returns true if this collection contains no elements.

This implementation returns size() == 0.

Returns:
true if this collection contains no elements.

Reimplemented from java::util::AbstractSet.

virtual jboolean java::util::HashSet::contains ( const ObjectRef o  )  const [virtual]

Returns true if this collection contains the specified element.

More formally, returns true if and only if this collection contains at least one element e such that (o==null ? e==null : o.equals(e)).

This implementation iterates over the elements in the collection, checking each element in turn for equality with the specified element.

Parameters:
o object to be checked for containment in this collection.
Returns:
true if this collection contains the specified element.

Reimplemented from java::util::AbstractSet.

virtual Ref<Iterator> java::util::HashSet::iterator (  )  const [virtual]

Returns an iterator over the elements in this collection.

There are no guarantees concerning the order in which the elements are returned (unless this collection is an instance of some class that provides a guarantee).

Returns:
an Iterator over the elements in this collection

Implements java::util::Collection.

virtual jboolean java::util::HashSet::add ( const ObjectRef o  )  [virtual]

Ensures that this collection contains the specified element (optional operation).

Returns true if the collection changed as a result of the call. (Returns false if this collection does not permit duplicates and already contains the specified element.) Collections that support this operation may place limitations on what elements may be added to the collection. In particular, some collections will refuse to add null elements, and others will impose restrictions on the type of elements that may be added. Collection classes should clearly specify in their documentation any restrictions on what elements may be added.

This implementation always throws an UnsupportedOperationException.

Parameters:
o element whose presence in this collection is to be ensured.
Returns:
true if the collection changed as a result of the call.
Exceptions:
UnsupportedOperationException if the add method is not supported by this collection.
NullPointerException if this collection does not permit null elements, and the specified element is null.
ClassCastException if the class of the specified element prevents it from being added to this collection.
IllegalArgumentException if some aspect of this element prevents it from being added to this collection.

Reimplemented from java::util::AbstractSet.

virtual jboolean java::util::HashSet::remove ( const ObjectRef o  )  [virtual]

Removes a single instance of the specified element from this collection, if it is present (optional operation).

More formally, removes an element e such that (o==null ? e==null : o.equals(e)), if the collection contains one or more such elements. Returns true if the collection contained the specified element (or equivalently, if the collection changed as a result of the call).

This implementation iterates over the collection looking for the specified element. If it finds the element, it removes the element from the collection using the iterator's remove method.

Note that this implementation throws an UnsupportedOperationException if the iterator returned by this collection's iterator method does not implement the remove method and this collection contains the specified object.

Parameters:
o element to be removed from this collection, if present.
Returns:
true if the collection contained the specified element.
Exceptions:
UnsupportedOperationException if the remove method is not supported by this collection.

Reimplemented from java::util::AbstractSet.

virtual void java::util::HashSet::clear (  )  [virtual]

Removes all of the elements from this collection (optional operation).

The collection will be empty after this call returns (unless it throws an exception).

This implementation iterates over this collection, removing each element using the Iterator.remove operation. Most implementations will probably choose to override this method for efficiency.

Note that this implementation will throw an UnsupportedOperationException if the iterator returned by this collection's iterator method does not implement the remove method and this collection is non-empty.

Exceptions:
UnsupportedOperationException if the clear method is not supported by this collection.

Reimplemented from java::util::AbstractSet.


Member Data Documentation

const jint java::util::HashSet::DEFAULT_INITIAL_CAPACITY [static]

The default initial capacity - MUST be a power of two.

const jfloat java::util::HashSet::DEFAULT_LOAD_FACTOR [static]

The load fast used when none specified in constructor.


The documentation for this class was generated from the following file:
Generated on Fri May 16 11:56:48 2008 for CrossPlatformJavaLikeC++API by  doxygen 1.5.3