KTypeOpenHashSet (HPPC v0.6.0 API Documentation (JavaDoc))

java.lang.Object
- com.carrotsearch.hppc.KTypeOpenHashSet<KType>

All Implemented Interfaces:: KTypeCollection<KType>, KTypeContainer<KType>, KTypeLookupContainer<KType>, KTypeSet<KType>, java.lang.Cloneable, java.lang.Iterable<KTypeCursor<KType>>

public class KTypeOpenHashSet<KType>
extends java.lang.Object
implements KTypeLookupContainer<KType>, KTypeSet<KType>, java.lang.Cloneable

A hash set of KTypes, implemented using using open addressing with linear probing for collision resolution.

The internal buffers of this implementation (keys), allocated) are always allocated to the nearest size that is a power of two. When the capacity exceeds the given load factor, the buffer size is doubled.

#if ($TemplateOptions.KTypeGeneric)

A brief comparison of the API against the Java Collections framework:

Java Collections `HashSet` and HPPC `ObjectOpenHashSet`, related methods.
java.util.HashSet	`ObjectOpenHashSet`
boolean add(E)	boolean add(E)
boolean remove(E)	int removeAllOccurrences(E)
size, clear, isEmpty	size, clear, isEmpty
contains(E)	contains(E), lkey()
iterator	iterator over set values, pseudo-closures

This implementation supports null keys.

#else

See ObjectOpenHashSet class for API similarities and differences against Java Collections. #end

Important node. The implementation uses power-of-two tables and linear probing, which may cause poor performance (many collisions) if hash values are not properly distributed. This implementation uses MurmurHash3 for rehashing keys.

Author:: This code is inspired by the collaboration and implementation in the fastutil project.

Field Summary

Fields
Modifier and Type	Field and Description
`boolean[]`	`allocated` Information if an entry (slot) in the `keys` table is allocated or empty.
`int`	`assigned` Cached number of assigned slots in `allocated`.
`static int`	`DEFAULT_CAPACITY` Default capacity.
`static float`	`DEFAULT_LOAD_FACTOR` Default load factor.
`KType[]`	`keys` Hash-indexed array holding all set entries.
`protected int`	`lastSlot` The most recent slot accessed in `contains(KType)`.
`float`	`loadFactor` The load factor for this map (fraction of allocated slots before the buffers must be rehashed or reallocated).
`static int`	`MIN_CAPACITY` Minimum capacity for the map.
`protected int`	`perturbation` We perturb hashed values with the array size to avoid problems with nearly-sorted-by-hash values on iterations.
`protected int`	`resizeAt` Resize buffers when `allocated` hits this value.

Constructor Summary

Constructors
Constructor and Description
`KTypeOpenHashSet()` Creates a hash set with the default capacity of 16, load factor of 0.75f.
`KTypeOpenHashSet(int initialCapacity)` Creates a hash set with the given capacity, load factor of 0.75f.
`KTypeOpenHashSet(int initialCapacity, float loadFactor)` Creates a hash set with the given capacity and load factor.
`KTypeOpenHashSet(KTypeContainer<KType> container)` Creates a hash set from elements of another container.

Method Summary

Methods
Modifier and Type	Method and Description
`int`	`add(KType... elements)` Vararg-signature method for adding elements to this set.
`boolean`	`add(KType e)` Adds `k` to the set.
`int`	`add(KType e1, KType e2)` Adds two elements to the set.
`int`	`addAll(java.lang.Iterable<? extends KTypeCursor<? extends KType>> iterable)` Adds all elements from a given iterable to this set.
`int`	`addAll(KTypeContainer<? extends KType> container)` Adds all elements from a given container to this set.
`void`	`clear()` Removes all elements from this collection.
`KTypeOpenHashSet<KType>`	`clone()`
`protected int`	`computePerturbationValue(int capacity)` Compute the key perturbation value applied before hashing.
`boolean`	`contains(KType key)` Lookup a given element in the container.
`boolean`	`equals(java.lang.Object obj)` Compares the specified object with this set for equality.
`<T extends KTypePredicate<? super KType>> T`	`forEach(T predicate)` Applies a `predicate` to container elements as long, as the predicate returns `true`.
`<T extends KTypeProcedure<? super KType>> T`	`forEach(T procedure)` Applies a `procedure` to all container elements.
`static <KType> KTypeOpenHashSet<KType>`	`from(KType... elements)` Create a set from a variable number of arguments or an array of `KType`.
`static <KType> KTypeOpenHashSet<KType>`	`from(KTypeContainer<KType> container)` Create a set from elements of another container.
`int`	`hashCode()`
`boolean`	`isEmpty()` Shortcut for `size() == 0`.
`java.util.Iterator<KTypeCursor<KType>>`	`iterator()` Returns an iterator to a cursor traversing the collection.
`KType`	`lkey()` Returns the last key saved in a call to `contains(KType)` if it returned `true`.
`int`	`lslot()`
`static <KType> KTypeOpenHashSet<KType>`	`newInstance()` Returns a new object of this class with no need to declare generic type (shortcut instead of using a constructor).
`static <KType> KTypeOpenHashSet<KType>`	`newInstanceWithCapacity(int initialCapacity, float loadFactor)` Returns a new object of this class with no need to declare generic type (shortcut instead of using a constructor).
`static <KType> KTypeOpenHashSet<KType>`	`newInstanceWithExpectedSize(int expectedSize)` Returns a new object of this class with no need to declare generic type (shortcut instead of using a constructor).
`static <KType> KTypeOpenHashSet<KType>`	`newInstanceWithExpectedSize(int expectedSize, float loadFactor)` Returns a new object of this class with no need to declare generic type (shortcut instead of using a constructor).
`static <KType> KTypeOpenHashSet<KType>`	`newInstanceWithoutPerturbations()` Returns a new object with no key perturbations (see `computePerturbationValue(int)`).
`boolean`	`remove(KType key)` An alias for the (preferred) `removeAllOccurrences(KType)`.
`int`	`removeAll(KTypeLookupContainer<? extends KType> c)` Default implementation uses a predicate for removal.
`int`	`removeAll(KTypePredicate<? super KType> predicate)` Removes all elements in this collection for which the given predicate returns `true`.
`int`	`removeAllOccurrences(KType key)` Removes all occurrences of `e` from this collection.
`int`	`retainAll(KTypeLookupContainer<? extends KType> c)` Default implementation uses a predicate for retaining.
`int`	`retainAll(KTypePredicate<? super KType> predicate)` Default implementation redirects to `KTypeCollection.removeAll(KTypePredicate)` and negates the predicate.
`protected void`	`shiftConflictingKeys(int slotCurr)` Shift all the slot-conflicting keys allocated to (and including) `slot`.
`int`	`size()` Return the current number of elements in this container.
`java.lang.Object[]`	`toArray()` Copies all elements from this container to an Object array.
`KType[]`	`toArray(java.lang.Class<? super KType> clazz)` Default implementation of copying to an array.
`java.lang.String`	`toString()` Convert the contents of this container to a human-friendly string.

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.carrotsearch.hppc.KTypeCollection
removeAll, retainAll, retainAll

Methods inherited from interface com.carrotsearch.hppc.KTypeContainer
toArray

- Field Detail
  - MIN_CAPACITY
```
public static final int MIN_CAPACITY
```
    Minimum capacity for the map.
    
    See Also:
    Constant Field Values
  - DEFAULT_CAPACITY
```
public static final int DEFAULT_CAPACITY
```
    Default capacity.
    
    See Also:
    Constant Field Values
  - DEFAULT_LOAD_FACTOR
```
public static final float DEFAULT_LOAD_FACTOR
```
    Default load factor.
    
    See Also:
    Constant Field Values
  - keys
```
public KType[] keys
```
    Hash-indexed array holding all set entries. #if ($TemplateOptions.KTypeGeneric)
    Important! The actual value in this field is always an instance of Object[]. Be warned that javac emits additional casts when keys are directly accessed; these casts may result in exceptions at runtime. A workaround is to cast directly to Object[] before accessing the buffer's elements (although it is highly recommended to use a iterator() instead. #end
    
    See Also:
    allocated
  - allocated
```
public boolean[] allocated
```
    Information if an entry (slot) in the keys table is allocated or empty.
    
    See Also:
    assigned
  - assigned
```
public int assigned
```
    Cached number of assigned slots in allocated.
  - loadFactor
```
public final float loadFactor
```
    The load factor for this map (fraction of allocated slots before the buffers must be rehashed or reallocated).
  - resizeAt
```
protected int resizeAt
```
    Resize buffers when allocated hits this value.
  - lastSlot
```
protected int lastSlot
```
    The most recent slot accessed in contains(KType).
    
    See Also:
    contains(KType), lkey()
  - perturbation
```
protected int perturbation
```
    We perturb hashed values with the array size to avoid problems with nearly-sorted-by-hash values on iterations.
    
    See Also:
    "http://issues.carrot2.org/browse/HPPC-80"
- Constructor Detail
  - KTypeOpenHashSet
```
public KTypeOpenHashSet()
```
    Creates a hash set with the default capacity of 16, load factor of 0.75f. `
  - KTypeOpenHashSet
```
public KTypeOpenHashSet(int initialCapacity)
```
    Creates a hash set with the given capacity, load factor of 0.75f.
  - KTypeOpenHashSet
```
public KTypeOpenHashSet(int initialCapacity,
                float loadFactor)
```
    Creates a hash set with the given capacity and load factor.
  - KTypeOpenHashSet
```
public KTypeOpenHashSet(KTypeContainer<KType> container)
```
    Creates a hash set from elements of another container. Default load factor is used.
- Method Detail
  - add
```
public boolean add(KType e)
```
    Adds k to the set.
    
    Specified by:
    
    add in interface KTypeSet<KType>
    
    Returns:
    Returns true if this element was not part of the set before. Returns false if an equal element is part of the set, and replaces the existing equal element with the argument (if keys are object types).
  - add
```
public int add(KType e1,
      KType e2)
```
    Adds two elements to the set.
  - add
```
public int add(KType... elements)
```
    Vararg-signature method for adding elements to this set.
    This method is handy, but costly if used in tight loops (anonymous array passing)
    
    Returns:
    Returns the number of elements that were added to the set (were not present in the set).
  - addAll
```
public int addAll(KTypeContainer<? extends KType> container)
```
    Adds all elements from a given container to this set.
    
    Returns:
    Returns the number of elements actually added as a result of this call (not previously present in the set).
  - addAll
```
public int addAll(java.lang.Iterable<? extends KTypeCursor<? extends KType>> iterable)
```
    Adds all elements from a given iterable to this set.
    
    Returns:
    Returns the number of elements actually added as a result of this call (not previously present in the set).
  - computePerturbationValue
```
protected int computePerturbationValue(int capacity)
```
    Compute the key perturbation value applied before hashing. The returned value should be non-zero and ideally different for each capacity. This matters because keys are nearly-ordered by their hashed values so when adding one container's values to the other, the number of collisions can skyrocket into the worst case possible.
    If it is known that hash containers will not be added to each other (will be used for counting only, for example) then some speed can be gained by not perturbing keys before hashing and returning a value of zero for all possible capacities. The speed gain is a result of faster rehash operation (keys are mostly in order).
  - removeAllOccurrences
```
public int removeAllOccurrences(KType key)
```
    Removes all occurrences of e from this collection.
    
    Specified by:
    
    removeAllOccurrences in interface KTypeCollection<KType>
    
    Parameters:
    key - Element to be removed from this collection, if present.
    
    Returns:
    The number of removed elements as a result of this call.
  - remove
```
public boolean remove(KType key)
```
    An alias for the (preferred) removeAllOccurrences(KType).
  - shiftConflictingKeys
```
protected void shiftConflictingKeys(int slotCurr)
```
    Shift all the slot-conflicting keys allocated to (and including) slot.
  - lkey
```
public KType lkey()
```
    Returns the last key saved in a call to contains(KType) if it returned true.
    
    See Also:
    contains(KType)
  - lslot
```
public int lslot()
```
    Returns:
    Returns the slot of the last key looked up in a call to contains(KType) if it returned true.
    See Also:
    contains(KType)
  - contains
```
public boolean contains(KType key)
```
    Lookup a given element in the container. This operation has no speed guarantees (may be linear with respect to the size of this container). #if ($TemplateOptions.KTypeGeneric)
    Saves the associated value for fast access using lkey().
```
 if (map.contains(key))
   value = map.lkey(); 
 
```
    #end
    Specified by:
    
    contains in interface KTypeContainer<KType>
    
    Specified by:
    
    contains in interface KTypeLookupContainer<KType>
    
    Returns:
    Returns true if this container has an element equal to e.
  - clear
```
public void clear()
```
    Removes all elements from this collection.
    Does not release internal buffers.
    
    Specified by:
    
    clear in interface KTypeCollection<KType>
  - size
```
public int size()
```
    Return the current number of elements in this container. The time for calculating the container's size may take O(n) time, although implementing classes should try to maintain the current size and return in constant time.
    
    Specified by:
    
    size in interface KTypeContainer<KType>
  - isEmpty
```
public boolean isEmpty()
```
    Shortcut for size() == 0.
    
    Specified by:
    
    isEmpty in interface KTypeContainer<KType>
  - hashCode
```
public int hashCode()
```
    Specified by:
    
    hashCode in interface KTypeSet<KType>
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    A hash code of elements stored in the set. The hash code is defined identically to Set.hashCode() (sum of hash codes of elements within the set). Because sum is commutative, this ensures that different order of elements in a set does not affect the hash code.
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Compares the specified object with this set for equality. Returns true if and only if the specified object is also a ObjectSet and both objects contains exactly the same objects.
    
    Specified by:
    
    equals in interface KTypeSet<KType>
    
    Overrides:
    
    equals in class java.lang.Object
  - iterator
```
public java.util.Iterator<KTypeCursor<KType>> iterator()
```
    Returns an iterator to a cursor traversing the collection. The order of traversal is not defined. More than one cursor may be active at a time. The behavior of iterators is undefined if structural changes are made to the underlying collection.
    The iterator is implemented as a cursor and it returns the same cursor instance on every call to Iterator.next() (to avoid boxing of primitive types). To read the current list's value (or index in the list) use the cursor's public fields. An example is shown below.
```
 for (KTypeCursor<KType> c : container) {
   System.out.println("index=" + c.index + " value=" + c.value);
 }
 
```
    Specified by:
    
    iterator in interface KTypeContainer<KType>
    
    Specified by:
    
    iterator in interface java.lang.Iterable<KTypeCursor<KType>>
  - forEach
```
public <T extends KTypeProcedure<? super KType>> T forEach(T procedure)
```
    Applies a procedure to all container elements. Returns the argument (any subclass of KTypeProcedure. This lets the caller to call methods of the argument by chaining the call (even if the argument is an anonymous type) to retrieve computed values, for example (IntContainer):
```
 int count = container.forEach(new IntProcedure() {
      int count; // this is a field declaration in an anonymous class.
      public void apply(int value) { count++; }}).count;
 
```
    Specified by:
    
    forEach in interface KTypeContainer<KType>
  - toArray
```
public java.lang.Object[] toArray()
```
    Copies all elements from this container to an Object array. If you need an array of the type identical with this container's generic type, use KTypeContainer.toArray(Class).
    
    Specified by:
    
    toArray in interface KTypeContainer<KType>
    
    See Also:
    KTypeContainer.toArray(Class)
  - clone
```
public KTypeOpenHashSet<KType> clone()
```
    Overrides:
    
    clone in class java.lang.Object
  - forEach
```
public <T extends KTypePredicate<? super KType>> T forEach(T predicate)
```
    Applies a predicate to container elements as long, as the predicate returns true. The iteration is interrupted otherwise.
    
    Specified by:
    
    forEach in interface KTypeContainer<KType>
  - removeAll
```
public int removeAll(KTypePredicate<? super KType> predicate)
```
    Removes all elements in this collection for which the given predicate returns true.
    
    Specified by:
    
    removeAll in interface KTypeCollection<KType>
  - from
```
public static <KType> KTypeOpenHashSet<KType> from(KType... elements)
```
    Create a set from a variable number of arguments or an array of KType. The elements are copied from the argument to the internal buffer.
  - from
```
public static <KType> KTypeOpenHashSet<KType> from(KTypeContainer<KType> container)
```
    Create a set from elements of another container.
  - newInstance
```
public static <KType> KTypeOpenHashSet<KType> newInstance()
```
    Returns a new object of this class with no need to declare generic type (shortcut instead of using a constructor).
  - newInstanceWithoutPerturbations
```
public static <KType> KTypeOpenHashSet<KType> newInstanceWithoutPerturbations()
```
    Returns a new object with no key perturbations (see computePerturbationValue(int)). Only use when sure the container will not be used for direct copying of keys to another hash container.
  - newInstanceWithCapacity
```
public static <KType> KTypeOpenHashSet<KType> newInstanceWithCapacity(int initialCapacity,
                                                      float loadFactor)
```
    Returns a new object of this class with no need to declare generic type (shortcut instead of using a constructor).
  - newInstanceWithExpectedSize
```
public static <KType> KTypeOpenHashSet<KType> newInstanceWithExpectedSize(int expectedSize)
```
    Returns a new object of this class with no need to declare generic type (shortcut instead of using a constructor). The returned instance will have enough initial capacity to hold expectedSize elements without having to resize.
  - newInstanceWithExpectedSize
```
public static <KType> KTypeOpenHashSet<KType> newInstanceWithExpectedSize(int expectedSize,
                                                          float loadFactor)
```
    Returns a new object of this class with no need to declare generic type (shortcut instead of using a constructor). The returned instance will have enough initial capacity to hold expectedSize elements without having to resize.
  - removeAll
```
public int removeAll(KTypeLookupContainer<? extends KType> c)
```
    Default implementation uses a predicate for removal.
    
    Specified by:
    
    removeAll in interface KTypeCollection<KType>
    
    Returns:
    Returns the number of removed elements.
  - retainAll
```
public int retainAll(KTypeLookupContainer<? extends KType> c)
```
    Default implementation uses a predicate for retaining.
    
    Specified by:
    
    retainAll in interface KTypeCollection<KType>
    
    Returns:
    Returns the number of removed elements.
  - retainAll
```
public int retainAll(KTypePredicate<? super KType> predicate)
```
    Default implementation redirects to KTypeCollection.removeAll(KTypePredicate) and negates the predicate.
    
    Specified by:
    
    retainAll in interface KTypeCollection<KType>
  - toArray
```
public KType[] toArray(java.lang.Class<? super KType> clazz)
```
    Default implementation of copying to an array.
    
    Specified by:
    
    toArray in interface KTypeContainer<KType>
  - toString
```
public java.lang.String toString()
```
    Convert the contents of this container to a human-friendly string.
    
    Overrides:
    
    toString in class java.lang.Object

Class KTypeOpenHashSet<KType>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.carrotsearch.hppc.KTypeCollection

Methods inherited from interface com.carrotsearch.hppc.KTypeContainer

Field Detail

MIN_CAPACITY

DEFAULT_CAPACITY

DEFAULT_LOAD_FACTOR

keys

allocated

assigned

loadFactor

resizeAt

lastSlot

perturbation

Constructor Detail

KTypeOpenHashSet

KTypeOpenHashSet

KTypeOpenHashSet

KTypeOpenHashSet

Method Detail

add

add

add

addAll

addAll

computePerturbationValue

removeAllOccurrences

remove

shiftConflictingKeys

lkey

lslot

contains

clear

size

isEmpty

hashCode

equals

iterator

forEach

toArray

clone

forEach

removeAll

from

from

newInstance

newInstanceWithoutPerturbations

newInstanceWithCapacity

newInstanceWithExpectedSize

newInstanceWithExpectedSize

removeAll

retainAll

retainAll

toArray

toString