mathCollection
Class HashMathSet

java.lang.Object
  java.util.AbstractCollection
      java.util.AbstractSet
          mathCollection.AbstractMathSet
              mathCollection.HashMathSet

All Implemented Interfaces:

java.lang.Cloneable, java.util.Collection, MathSet, java.io.Serializable, java.util.Set

public class HashMathSet

extends AbstractMathSet

implements MathSet, java.lang.Cloneable, java.io.Serializable

This class implements the MathSet interface, backed by a hash table (specifically, a HashSet 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.

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 MathCollections.synchronizedMathSet method. This is best done at creation time, to prevent accidental unsynchronized access to the HashMathSet instance:

     MathSet ms = MathCollections.synchronizedMathSet(new HashMathSet(...));
 

See Also:

Set, MathSet, AbstractMathSet, HashSet, Serialized Form

Nested Class Summary

private class

HashMathSet.HashMathSetIterator A 'wrapper' iterator class that uses HashSet.iterator() while accounting for the additional storedHashCode attribute.

Field Summary

private java.util.HashSet	myHashSet The backing instance of HashSet where the elements of this set are stored.
private int	storedHashCode Acts as a cache for the hash code value of this set out of performance considerations.

Constructor Summary

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

HashMathSet(java.util.Collection c)
Constructs a new mathematical set containing the elements in the specified collection.

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

HashMathSet(int initialCapacity, float loadFactor)
Constructs a new, empty mathematical set; the backing HashSet 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.
void	clear() Removes all elements from this set.
java.lang.Object	clone() Returns a shallow copy of this HashMathSet instance: the elements themselves are not cloned.
boolean	contains(java.lang.Object o) Returns true if this set contains the specified element.
MathSet	difference(java.util.Set s) Returns the asymmetric difference between this mathematical set and the specified set.
boolean	equals(java.lang.Object o) Compares the specified object with this set for equality.
SetOfSets	fixedSizeSubsets(int size) Returns all possible subsets of this set with the specified size, contained in a HashSetOfSets instance.
int	hashCode() Returns the hash code value for this mathematical set.
MathSet	intersection(java.util.Set s) Returns the intersection with the specified set.
boolean	isEmpty() Returns true if this set contains no elements.
boolean	isSubset(java.util.Set s) Returns true if this mathematical set is a subset of the specified set.
java.util.Iterator	iterator() Returns an iterator over the elements in this mathematical set.
SetOfSets	powerSet() Returns the power set of this mathematical set.
private HashSetOfSets	recursiveFixedSizeSubsets(int numberToAdd, java.lang.Object[] elementPool, int elementPoolStart, HashMathSet setToAdd, HashSetOfSets result) Internal subroutine for recursively determining all fixed size subsets of a set.
boolean	remove(java.lang.Object o) Removes the specified element from this set if it is present.
int	size() Returns the number of elements in this set (its cardinality).
MathSet	symmetricDifference(java.util.Set s) Returns the symmetric difference between this mathematical set and the specified set.
MathSet	union(java.util.Set s) Returns the union with the specified set.

Methods inherited from class mathCollection.AbstractMathSet

isDisjoint, isSuperset, toString

Methods inherited from class java.util.AbstractSet

removeAll

Methods inherited from class java.util.AbstractCollection

addAll, containsAll, retainAll, toArray, toArray

Methods inherited from class java.lang.Object

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

Methods inherited from interface mathCollection.MathSet

isDisjoint, isSuperset

Methods inherited from interface java.util.Set

addAll, containsAll, removeAll, retainAll, toArray, toArray

Field Detail

myHashSet

private java.util.HashSet myHashSet

The backing instance of HashSet where the elements of this set are stored.

storedHashCode

private int storedHashCode

Acts as a cache for the hash code value of this set out of performance considerations. Whenever this set is changed, storedHashCode is set to 0 and gets updated as soon as the hashCode() method is called.

Constructor Detail

HashMathSet

public HashMathSet()

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

HashMathSet

public HashMathSet(java.util.Collection c)

Constructs a new mathematical set containing the elements in the specified collection. The HashSet 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.

Throws:

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

HashMathSet

public HashMathSet(int initialCapacity)

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

Parameters:

initialCapacity - the initial capacity of the hash set.

Throws:

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

HashMathSet

public HashMathSet(int initialCapacity,
                   float loadFactor)

Constructs a new, empty mathematical set; the backing HashSet instance has the specified initial capacity and the specified load factor.

Parameters:

initialCapacity - the initial capacity of the hash set.

loadFactor - the load factor of the hash set.

Throws:

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

Method Detail

iterator

public java.util.Iterator iterator()

Returns an iterator over the elements in this mathematical set. The elements are returned in no particular order.

Specified by:

iterator in interface java.util.Set

Returns:

an Iterator over the elements in this mathematical set.

See Also:

ConcurrentModificationException

hashCode

public int hashCode()

Returns the hash code value for this mathematical set. To get the hash code of this mathematical set, new hash code values for every element of this mathematical set are calculated from a polynomial of 3rd order and finally summed up. This ensures that s1.equals(s2) implies that s1.hashCode()==s2.hashCode() for any two mathematical sets s1 and s2, as required by the general contract of Object.hashCode().

This implementation first checks whether a cached hash code value is available. If not (i.e. storedHashCode is zero), the hash code gets calculated using hashCode() of the super class.

Specified by:

hashCode in interface java.util.Set

Overrides:

hashCode in class AbstractMathSet

Returns:

the hash code value for this mathematical set.

clone

public java.lang.Object clone()

Returns a shallow copy of this HashMathSet instance: the elements themselves are not cloned.

Returns:

a shallow copy of this set.

isEmpty

public boolean isEmpty()

Returns true if this set contains no elements.

Specified by:

isEmpty in interface java.util.Set

Returns:

true if this set contains no elements, false otherwise.

size

public int size()

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

Specified by:

size in interface java.util.Set

Returns:

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

clear

public void clear()

Removes all elements from this set.

Specified by:

clear in interface java.util.Set

contains

public boolean contains(java.lang.Object o)

Returns true if this set contains the specified element.

Specified by:

contains in interface java.util.Set

Parameters:

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

Returns:

true if this set contains the specified element, false otherwise.

add

public boolean add(java.lang.Object o)

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

If the set gets altered, this implementation sets storedHashCode to 0 (representing an unavailable hash code value), which forces hashCode() to recalculate the actual hash code value.

Specified by:

add in interface java.util.Set

Parameters:

o - element to be added to this set.

Returns:

true if the set did not already contain the specified element, false otherwise.

remove

public boolean remove(java.lang.Object o)

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

If the set gets altered, this implementation sets storedHashCode to 0 (representing an unavailable hash code value), which forces hashCode() to recalculate the actual hash code value.

Specified by:

remove in interface java.util.Set

Parameters:

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

Returns:

true if the set contained the specified element, false otherwise.

equals

public boolean equals(java.lang.Object o)

Compares the specified object with this set for equality. Returns true if the specified object is also a set, the two sets have the same size, and every element of the specified set is contained in this set.

This implementation first checks if the given object is a HashMathSet. If so, the hash code values of this mathematical set and the specified HashMathSet are compared. Since the hash code values are being cached, this represents a quick solution if the sets aren't equal. However, if the hash code values are equal, it cannot be assumed that the sets themselves are equal, since different sets can have the same hash code value. In this case, the result of the super method equals() is returned.

Specified by:

equals in interface java.util.Set

Parameters:

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

Returns:

true if the specified object is equal to this set, false otherwise.

isSubset

public boolean isSubset(java.util.Set s)

Returns true if this mathematical set is a subset of the specified set. That is, if all elements of this mathematical set are also present in the specified set.

Specified by:

isSubset in interface MathSet

Overrides:

isSubset in class AbstractMathSet

Parameters:

s - set to be checked for being a superset.

Returns:

true if this mathematical set is a subset of the specifed set, false otherwise.

See Also:

AbstractMathSet.isSuperset(Set)

union

public MathSet union(java.util.Set s)

Returns the union with the specified set. This is a new HashMathSet containing all elements that are present in this mathematical set or in the specified set.

Specified by:

union in interface MathSet

Parameters:

s - set that is to be united with.

Returns:

the union with the specified set.

intersection

public MathSet intersection(java.util.Set s)

Returns the intersection with the specified set. This is a new HashMathSet containing all elements that are present in this mathematical set as well as in the specified set.

Specified by:

intersection in interface MathSet

Parameters:

s - set that is to be intersected with.

Returns:

the intersection with the specified set.

difference

public MathSet difference(java.util.Set s)

Returns the asymmetric difference between this mathematical set and the specified set. This is a new HashMathSet containing all elements that are present in this mathematical set but not in the specified set.

Specified by:

difference in interface MathSet

Parameters:

s - set from what the difference is calculated.

Returns:

the difference with the specified set.

symmetricDifference

public MathSet symmetricDifference(java.util.Set s)

Returns the symmetric difference between this mathematical set and the specified set. This is a new HashMathSet containing all elements that are present either in this mathematical set or in the specified set but not in both.

Specified by:

symmetricDifference in interface MathSet

Parameters:

s - set from what the symmetric difference is calculated

Returns:

the symmetric difference with the specified set.

powerSet

public SetOfSets powerSet()

Returns the power set of this mathematical set. This is a set containing all subsets of this mathematical set, including, in particular, the empty set and this mathematical set itself.

Specified by:

powerSet in interface MathSet

Returns:

power set of this mathematical set.

recursiveFixedSizeSubsets

private HashSetOfSets recursiveFixedSizeSubsets(int numberToAdd,
                                                java.lang.Object[] elementPool,
                                                int elementPoolStart,
                                                HashMathSet setToAdd,
                                                HashSetOfSets result)

Internal subroutine for recursively determining all fixed size subsets of a set.

Parameters:

numberToAdd - number of elements to add to the subsets. Required to be a positive integer.

elementPool - array containing all source set elements.

elementPoolStart - array index specifying the first of the elements that are still to be processed.

setToAdd - the incomplete subset which more elements get added to.

result - SetOfSets accumulating the complete subsets.

Returns:

an intermediate result according to the parameters.

fixedSizeSubsets

public SetOfSets fixedSizeSubsets(int size)

Returns all possible subsets of this set with the specified size, contained in a HashSetOfSets instance. In case the size parameter is negative or greater than the size of the set itself, an empty SetOfSets is returned.

Specified by:

fixedSizeSubsets in interface MathSet

Parameters:

size - size of the returned subsets.

Returns:

a SetOfSets containing all subsets of this mathematical set with the specified size.