kodkod.util.collections
Class IdentityHashSet<T>

java.lang.Object
  extended by java.util.AbstractCollection<E>
      extended by java.util.AbstractSet<T>
          extended by kodkod.util.collections.IdentityHashSet<T>
All Implemented Interfaces:
java.lang.Iterable<T>, java.util.Collection<T>, java.util.Set<T>

public final class IdentityHashSet<T>
extends java.util.AbstractSet<T>

Implements the Set interface with a hash table, using reference-equality in place of object-equality when comparing elements. In other words, in an IdentityHashSet, two elements e1 and e2 are considered equal if and only if (e1==e2). (In normal Set implementations (like Set) two elements e1 and e2 are considered equal if and only if (e1==null ? e2==null : e1.equals(e2)).)

This class is not a general-purpose Set implementation! While this class implements the Set interface, it intentionally violates Set's general contract, which mandates the use of the equals method when comparing objects. This class is designed for use only in the rare cases wherein reference-equality semantics are required.

This class provides all of the optional set operations, and permits null elements. This class makes no guarantees as to the order of the set; in particular, it does not guarantee that the order will remain constant over time.

This class provides constant-time performance for the basic operations (get and put), assuming the system identity hash function (System.identityHashCode(Object)) disperses elements properly among the buckets.

This class has one tuning parameter (which affects performance but not semantics): expected maximum size. This parameter is the maximum number of elements that the set is expected to hold. Internally, this parameter is used to determine the number of buckets initially comprising the hash table. The precise relationship between the expected maximum size and the number of buckets is unspecified.

If the size of the set sufficiently exceeds the expected maximum size, the number of buckets is increased Increasing the number of buckets ("rehashing") may be fairly expensive, so it pays to create identity hash sets with a sufficiently large expected maximum size. On the other hand, iteration requires time proportional to the number of buckets in the hash table, so it pays not to set the expected maximum size too high if you are especially concerned with iteration performance or memory usage.

Note that this implementation is not synchronized. The iterators returned by all of this class are not fail-fast: in the face of concurrent modification, the iterator risks arbitrary, non-deterministic behavior at an undetermined time in the future.

Implementation note: This is a simple linear-probe hash table, as described for example in texts by Sedgewick and Knuth. For many JRE implementations and operation mixes, this class will yield better performance than HashSet (which uses chaining rather than linear-probing).

Author:
Emina Torlak
specfield:
elems: set T

Constructor Summary
IdentityHashSet()
          Constructs a new, empty identity hash map with a default expected maximum size of 16.
IdentityHashSet(java.util.Collection<? extends T> c)
          Constructs a new identity hash set containing the elements in the specified collection.
IdentityHashSet(int expectedMaxSize)
          Constructs a new, empty set with the specified expected maximum size.
 
Method Summary
 boolean add(T element)
           
 boolean addAll(java.util.Collection<? extends T> c)
           
 void clear()
           
 boolean contains(java.lang.Object o)
          Tests whether the specified object reference is an element in this identity hash map.
 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()
           
 java.util.Iterator<T> iterator()
           
 boolean remove(java.lang.Object o)
           
 boolean removeAll(java.util.Collection<?> c)
           
 int size()
           
 
Methods inherited from class java.util.AbstractCollection
containsAll, retainAll, toArray, toArray, toString
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Set
containsAll, retainAll, toArray, toArray
 

Constructor Detail

IdentityHashSet

public IdentityHashSet()
Constructs a new, empty identity hash map with a default expected maximum size of 16.

effects:
no this.elems'

IdentityHashSet

public IdentityHashSet(int expectedMaxSize)
Constructs a new, empty set with the specified expected maximum size. Putting more than the expected number of elements into the set may cause the internal data structure to grow, which may be somewhat time-consuming.

Throws:
java.lang.IllegalArgumentException - - expectedMaxSize < 0
effects:
no this.elems'

IdentityHashSet

public IdentityHashSet(java.util.Collection<? extends T> c)
Constructs a new identity hash set containing the elements in the specified collection.

Throws:
java.lang.NullPointerException - - c = null
effects:
this.elems' = c.elems
Method Detail

iterator

public java.util.Iterator<T> iterator()
Specified by:
iterator in interface java.lang.Iterable<T>
Specified by:
iterator in interface java.util.Collection<T>
Specified by:
iterator in interface java.util.Set<T>
Specified by:
iterator in class java.util.AbstractCollection<T>

size

public int size()
Specified by:
size in interface java.util.Collection<T>
Specified by:
size in interface java.util.Set<T>
Specified by:
size in class java.util.AbstractCollection<T>

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface java.util.Collection<T>
Specified by:
isEmpty in interface java.util.Set<T>
Overrides:
isEmpty in class java.util.AbstractCollection<T>

contains

public boolean contains(java.lang.Object o)
Tests whether the specified object reference is an element in this identity hash map.

Specified by:
contains in interface java.util.Collection<T>
Specified by:
contains in interface java.util.Set<T>
Overrides:
contains in class java.util.AbstractCollection<T>
Returns:
o in this.elems

add

public boolean add(T element)
Specified by:
add in interface java.util.Collection<T>
Specified by:
add in interface java.util.Set<T>
Overrides:
add in class java.util.AbstractCollection<T>

remove

public boolean remove(java.lang.Object o)
Specified by:
remove in interface java.util.Collection<T>
Specified by:
remove in interface java.util.Set<T>
Overrides:
remove in class java.util.AbstractCollection<T>

addAll

public boolean addAll(java.util.Collection<? extends T> c)
Specified by:
addAll in interface java.util.Collection<T>
Specified by:
addAll in interface java.util.Set<T>
Overrides:
addAll in class java.util.AbstractCollection<T>

removeAll

public boolean removeAll(java.util.Collection<?> c)
Specified by:
removeAll in interface java.util.Collection<T>
Specified by:
removeAll in interface java.util.Set<T>
Overrides:
removeAll in class java.util.AbstractSet<T>

clear

public void clear()
Specified by:
clear in interface java.util.Collection<T>
Specified by:
clear in interface java.util.Set<T>
Overrides:
clear in class java.util.AbstractCollection<T>

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 and the two sets contain identical object-references.

Owing to the reference-equality-based semantics of this set it is possible that the symmetry and transitivity requirements of the Object.equals contract may be violated if this set is compared to a normal set. However, the Object.equals contract is guaranteed to hold among IdentityHashSet instances.

Specified by:
equals in interface java.util.Collection<T>
Specified by:
equals in interface java.util.Set<T>
Overrides:
equals in class java.util.AbstractSet<T>
Returns:
true if the specified object is equal to this set.
See Also:
Object.equals(Object)

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 hashcode of each entry in the set. This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two IdentityHashSet instances t1 and t2, as required by the general contract of Object.hashCode().

Owing to the reference-equality-based semantics of the elements in this set, it is possible that the contractual requirement of Object.hashCode mentioned in the previous paragraph will be violated if one of the two objects being compared is an IdentityHashSet instance and the other is a normal set.

Specified by:
hashCode in interface java.util.Collection<T>
Specified by:
hashCode in interface java.util.Set<T>
Overrides:
hashCode in class java.util.AbstractSet<T>
Returns:
the hash code value for this set.
See Also:
Object.hashCode(), Object.equals(Object), equals(Object)