org.j3d.util
Class HashSet

java.lang.Object
  org.j3d.util.HashSet

public class HashSet
extends java.lang.Object

A custom HashSet implementation.

This implementation is designed for realtime work and in particular with the goal of absolute minimum garbage generation. The standard implementation in java.util generates excessive amounts of garbage and is unsuitable for the task.

The implementation does not have a backing class and the internals are based on the hashing code in IntHashMap. The method signature is almost the same as java.util.HashSet, except we leave out garbage generating methods like iterator().

Version:

$Revision: 1.6 $

Author:

Rob Nielsen

Constructor Summary

HashSet()
Constructs a new, empty set; the backing HashMap instance has default initial capacity (16) and load factor (0.75).

HashSet(int initialCapacity)
Constructs a new, empty set; the backing HashMap instance has the specified initial capacity and default load factor, which is 0.75.

HashSet(int initialCapacity, float loadFactor)
Constructs a new, empty set; the backing HashMap instance has the specified initial capacity and the specified load factor.

Method Summary

boolean	add(java.lang.Object o) Adds the specified element to this set if it is not already present.
boolean	addAll(java.util.Collection c) Adds all of the elements in the specified collection to this set.
boolean	addAll(HashSet hs) Adds all of the elements in the specified hash set to this set.
void	clear() Removes all of the elements from this set.
boolean	contains(java.lang.Object o) Returns true if this set contains the specified element.
boolean	equals(java.lang.Object o) Compares the specified object with this set for equality.
int	hashCode() Returns the hash code value for this set.
boolean	isEmpty() Check to see if this set contains elements.
boolean	remove(java.lang.Object o) Removes the specified element from this set if it is present.
boolean	removeAll(java.util.Collection c) Removes from this set all of its elements that are contained in the specified collection.
boolean	removeAll(HashSet hs) Removes from this collection all of its elements that are contained in the specified hash set.
void	retainAll(HashSet set) Retain everything that is in the given set, in this set.
void	retainAll(HashSet set, HashSet diff) Retain everything that is in the given set, in this set, and move anything that is not, into the alternate set.
int	size() Returns the number of elements in this set (its cardinality).
java.lang.Object[]	toArray() Returns an array containing all of the elements in this collection.
java.lang.Object[]	toArray(java.lang.Object[] array) Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array.
java.lang.String	toString() Returns a string representation of this set.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

HashSet

public HashSet()

Constructs a new, empty set; the backing HashMap instance has default initial capacity (16) and load factor (0.75).

HashSet

public HashSet(int initialCapacity,
               float loadFactor)

Constructs a new, empty set; the backing HashMap instance has 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.

Throws:

java.lang.IllegalArgumentException - if the initial capacity is less than zero, or if the load factor is nonpositive.

HashSet

public HashSet(int initialCapacity)

Constructs a new, empty set; the backing HashMap instance has the specified initial capacity and default load factor, which is 0.75.

Parameters:

initialCapacity - the initial capacity of the hash table.

Throws:

java.lang.IllegalArgumentException - if the initial capacity is less than zero.

Method Detail

size

public int size()

Returns the number of elements in this set (its cardinality).

Returns:

the number of elements in this set

isEmpty

public boolean isEmpty()

Check to see if this set contains elements.

Returns:

true if this set contains no elements.

contains

public boolean contains(java.lang.Object o)

Returns true if this set contains the specified element.

Parameters:

o - element whose presence in this set is to be tested.

Returns:

true if this set contains the specified element.

retainAll

public void retainAll(HashSet set)

Retain everything that is in the given set, in this set. If this set contains something that the given set does not, then delete it.

Parameters:

set - The set to compare against

retainAll

public void retainAll(HashSet set,
                      HashSet diff)

Retain everything that is in the given set, in this set, and move anything that is not, into the alternate set.

Parameters:

set - The set to compare against

diff - The set to place the non-equal values into

add

public boolean add(java.lang.Object o)

Adds the specified element to this set if it is not already present.

Parameters:

o - element to be added to this set.

Returns:

true if the set did not already contain the specified element.

remove

public boolean remove(java.lang.Object o)

Removes the specified element from this set if it is present.

Parameters:

o - object to be removed from this set, if present.

Returns:

true if the set contained the specified element.

clear

public void clear()

Removes all of the elements from this set.

addAll

public boolean addAll(java.util.Collection c)

Adds all of the elements in the specified collection to this set. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

This implementation iterates over the specified collection, and adds each object returned by the iterator to this collection, in turn.

Parameters:

c - collection whose elements are to be added to this collection.

Returns:

true if this collection changed as a result of the call.

Throws:

java.lang.UnsupportedOperationException - if this collection does not support the addAll method.

java.lang.NullPointerException - if the specified collection is null.

addAll

public boolean addAll(HashSet hs)

Adds all of the elements in the specified hash set to this set. The behavior of this operation is undefined if the specified set is modified while the operation is in progress.

Parameters:

hs - The set whose elements are to be added to this set

Returns:

true if this collection changed as a result of the call

Throws:

java.lang.UnsupportedOperationException - if this collection does not support the addAll method

java.lang.NullPointerException - if the specified collection is null

removeAll

public boolean removeAll(java.util.Collection c)

Removes from this set all of its elements that are contained in the specified collection.

This implementation iterates over this collection, checking each element returned by the iterator in turn to see if it's contained in the specified collection. If it's so contained, it's removed from this collection with the iterator's remove method.

Parameters:

c - elements to be removed from this set.

Returns:

true if this collection changed as a result of the call.

Throws:

java.lang.UnsupportedOperationException - if the removeAll method is not supported by this collection.

java.lang.NullPointerException - if the specified collection is null.

See Also:

remove(Object), contains(Object)

removeAll

public boolean removeAll(HashSet hs)

Removes from this collection all of its elements that are contained in the specified hash set.

This implementation iterates over this collection, checking each element returned by the iterator in turn to see if it's contained in the specified collection. If it's so contained, it's removed from this collection with the iterator's remove method.

Parameters:

hs - elements to be removed from this set.

Returns:

true if this set changed as a result of the call.

Throws:

java.lang.UnsupportedOperationException - if the removeAll method is not supported by this collection.

java.lang.NullPointerException - if the specified collection is null.

toArray

public java.lang.Object[] toArray()

Returns an array containing all of the elements in this collection. If the collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order. The returned array will be "safe" in that no references to it are maintained by the collection. (In other words, this method must allocate a new array even if the collection is backed by an Array). The caller is thus free to modify the returned array.

This implementation allocates the array to be returned, and iterates over the elements in the collection, storing each object reference in the next consecutive element of the array, starting with element 0.

Returns:

an array containing all of the elements in this collection.

toArray

public java.lang.Object[] toArray(java.lang.Object[] array)

Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

If the collection fits in the specified array with room to spare (i.e., the array has more elements than the collection), the element in the array immediately following the end of the collection is set to null. This is useful in determining the length of the collection only if the caller knows that the collection does not contain any null elements.)

If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

This implementation checks if the array is large enough to contain the collection; if not, it allocates a new array of the correct size and type (using reflection). Then, it iterates over the collection, storing each object reference in the next consecutive element of the array, starting with element 0. If the array is larger than the collection, a null is stored in the first location after the end of the collection.

Parameters:

array - the array into which the elements of the set are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:

an array containing the elements of the collection.

Throws:

java.lang.NullPointerException - if the specified array is null.

java.lang.ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this collection.

equals

public boolean equals(java.lang.Object o)

Compares the specified object with this set for equality. Returns true if the given object is also a set, the two sets have the same size, and every member of the given set is contained in this set. This implementation first checks if the specified object is this set; if so it returns true. Then, it checks if the specified object is a set whose size is identical to the size of this set; if not, it it returns false. If so, it returns containsAll((Collection) o).

Overrides:

equals in class java.lang.Object

Parameters:

o - Object to be compared for equality with this set.

Returns:

true if the specified object is equal to this set.

hashCode

public int hashCode()

Returns the hash code value for this set. The hash code of a set is defined to be the sum of the hash codes of the elements in the set. This ensures that s1.equals(s2) implies that s1.hashCode()==s2.hashCode() for any two sets s1 and s2, as required by the general contract of Object.hashCode.

This implementation enumerates over the set, calling the hashCode method on each element in the collection, and adding up the results.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value for this set.

toString

public java.lang.String toString()

Returns a string representation of this set. The string representation consists of a list of the collection's elements in the order they are returned by its iterator, enclosed in square brackets ("[]"). Adjacent elements are separated by the characters ", " (comma and space). Elements are converted to strings as by String.valueOf(Object).

This implementation creates an empty string buffer, appends a left square bracket, and iterates over the collection appending the string representation of each element in turn. After appending each element except the last, the string ", " is appended. Finally a right bracket is appended. A string is obtained from the string buffer, and returned.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this collection.