kodkod.util.collections
Class CacheSet<E>

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

public final class CacheSet<E>
extends java.util.AbstractSet<E>

Implements the Set interface, backed by a hash table. 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 does not permit 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 map (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.

This set differs from Java's HashSet in that it provides methods for retrieving elements with a particular hashcode. This makes it easy to set as a cache in which cached objects' hashcodes are their keys.

Note that this implementation is not synchronized. The iterators returned by this class's iterator method are not fail-fast

Author:
Emina Torlak
specfield:
elts: set T

Constructor Summary
CacheSet()
          Constructs a new, empty set; the backing map has default initial capacity (16) and load factor (0.75).
CacheSet(java.util.Collection<? extends E> c)
          Constructs a new set containing the elements in the specified collection.
CacheSet(int initialCapacity, float loadFactor)
          Constructs a new, empty set; the backing map has the specified initial capacity and the specified load factor.
 
Method Summary
 boolean add(E elt)
          Adds the given element to this set, if not already present.
 void clear()
          Removes all elements from this set.
 boolean contains(java.lang.Object elt)
          Returns true if this set contains the given element.
 java.util.Iterator<E> get(int hash)
          Returns an iterator over the elements whose hashcode() method returns the given hash.
 boolean isEmpty()
          Returns true if this set is empty.
 java.util.Iterator<E> iterator()
          Returns an iterator over the elements in this set.
 boolean remove(java.lang.Object elt)
          Removes the specified object from this set, if present.
 int size()
          Returns the number of elements in this set.
 
Methods inherited from class java.util.AbstractSet
equals, hashCode, removeAll
 
Methods inherited from class java.util.AbstractCollection
addAll, 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
addAll, containsAll, retainAll, toArray, toArray
 

Constructor Detail

CacheSet

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

effects:
no this.elts'

CacheSet

public CacheSet(int initialCapacity,
                float loadFactor)
Constructs a new, empty set; the backing map 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.
effects:
no this.elts'

CacheSet

public CacheSet(java.util.Collection<? extends E> 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.
Throws:
java.lang.NullPointerException - if the specified collection is null.
Method Detail

size

public int size()
Returns the number of elements in this set.

Specified by:
size in interface java.util.Collection<E>
Specified by:
size in interface java.util.Set<E>
Specified by:
size in class java.util.AbstractCollection<E>
Returns:
#this.elts
See Also:
Set.size()

isEmpty

public boolean isEmpty()
Returns true if this set is empty.

Specified by:
isEmpty in interface java.util.Collection<E>
Specified by:
isEmpty in interface java.util.Set<E>
Overrides:
isEmpty in class java.util.AbstractCollection<E>
Returns:
no this.elts
See Also:
Set.isEmpty()

contains

public boolean contains(java.lang.Object elt)
Returns true if this set contains the given element.

Specified by:
contains in interface java.util.Collection<E>
Specified by:
contains in interface java.util.Set<E>
Overrides:
contains in class java.util.AbstractCollection<E>
Returns:
elt in this.elts
Throws:
java.lang.NullPointerException - - elt = null
See Also:
Set.contains(java.lang.Object)

iterator

public java.util.Iterator<E> iterator()
Returns an iterator over the elements in this set.

Specified by:
iterator in interface java.lang.Iterable<E>
Specified by:
iterator in interface java.util.Collection<E>
Specified by:
iterator in interface java.util.Set<E>
Specified by:
iterator in class java.util.AbstractCollection<E>
Returns:
an iterator over this.elts.
See Also:
Set.iterator()

add

public boolean add(E elt)
Adds the given element to this set, if not already present.

Specified by:
add in interface java.util.Collection<E>
Specified by:
add in interface java.util.Set<E>
Overrides:
add in class java.util.AbstractCollection<E>
Returns:
elt !in this.elts
Throws:
java.lang.NullPointerException - - elt = null
effects:
this.elts' = this.elts + elt

remove

public boolean remove(java.lang.Object elt)
Removes the specified object from this set, if present.

Specified by:
remove in interface java.util.Collection<E>
Specified by:
remove in interface java.util.Set<E>
Overrides:
remove in class java.util.AbstractCollection<E>
Returns:
elt in this.elts
Throws:
java.lang.NullPointerException - - elt = null
See Also:
Set.remove(java.lang.Object)
effects:
this.elts' = this.elts - elt

get

public java.util.Iterator<E> get(int hash)
Returns an iterator over the elements whose hashcode() method returns the given hash.

Returns:
an iterator over {e: this.elts | e.hashCode() = hash }

clear

public void clear()
Removes all elements from this set.

Specified by:
clear in interface java.util.Collection<E>
Specified by:
clear in interface java.util.Set<E>
Overrides:
clear in class java.util.AbstractCollection<E>
See Also:
Set.clear()
effects:
no this.elts'