squidpony.squidmath.UnorderedSet<K>

All Implemented Interfaces:: Serializable, Cloneable, Iterable<K>, Collection<K>, Set<K>

public class UnorderedSet<K>
extends Object
implements Set<K>, Serializable, Cloneable

A generic unordered hash set with with a fast implementation, based on OrderedSet in this library, which is based on the fastutil library's ObjectLinkedOpenHashSet class; the ordering and indexed access have been removed to potentially reduce the time cost of insertion and removal at the expense of increasing time cost for access by index. This does support optional hash strategies for array (and other) keys, which fastutil's collections can do in a different way, and has better support than HashSet for construction with an array of items or construction with a Collection of items (this also helps addAll(Object[])).

Instances of this class use a hash table to represent a set. The table is filled up to a specified load factor, and then doubled in size to accommodate new entries. If the table is emptied below one fourth of the load factor, it is halved in size. However, halving is not performed when deleting entries from an iterator, as it would interfere with the iteration process.

Note that clear() does not modify the hash table size. Rather, a family of trimming methods lets you control the size of the table; this is particularly useful if you reuse instances of this class.

This class implements the interface of a Set, not a SortedSet.

You can pass an CrossHash.IHasher instance such as CrossHash.generalHasher as an extra parameter to most of this class' constructors, which allows the OrderedSet to use arrays (usually primitive arrays) as items. If you expect only one type of array, you can use an instance like CrossHash.intHasher to hash int arrays, or the aforementioned generalHasher to hash most kinds of arrays (it can't handle most multi-dimensional arrays well). If you aren't using array items, you don't need to give an IHasher to the constructor and can ignore this feature.

Thank you, Sebastiano Vigna, for making FastUtil available to the public with such high quality.
See https://github.com/vigna/fastutil for the original library.

Author:: Sebastiano Vigna (responsible for all the hard parts), Tommy Ettinger (mostly responsible for squashing several layers of parent classes into one monster class)
See Also:: Serialized Form

Field Summary

Fields
Modifier and Type	Field	Description
`protected boolean`	`containsNull`	Whether this set contains the key zero.
`static int`	`DEFAULT_INITIAL_SIZE`	The initial default size of a hash table.
`static float`	`DEFAULT_LOAD_FACTOR`	The default load factor of a hash table.
`float`	`f`	The acceptable load factor.
`static float`	`FAST_LOAD_FACTOR`	The load factor for a (usually small) table that is meant to be particularly fast.
`protected CrossHash.IHasher`	`hasher`
`protected K[]`	`key`	The array of keys.
`protected int`	`mask`	The mask for wrapping a position counter.
`protected int`	`maxFill`	Threshold after which we rehash.
`protected int`	`n`	The current table size.
`protected int`	`size`	Number of entries in the set (including the key zero, if present).
`static float`	`VERY_FAST_LOAD_FACTOR`	The load factor for a (usually very small) table that is meant to be extremely fast.

Constructor Summary

Constructors
Constructor	Description
`UnorderedSet()`	Creates a new hash set with initial expected `DEFAULT_INITIAL_SIZE` elements and `DEFAULT_LOAD_FACTOR` as load factor.
`UnorderedSet(int expected)`	Creates a new hash set with `DEFAULT_LOAD_FACTOR` as load factor.
`UnorderedSet(int expected, float f)`	Creates a new hash map.
`UnorderedSet(int expected, float f, CrossHash.IHasher hasher)`	Creates a new hash map.
`UnorderedSet(int expected, CrossHash.IHasher hasher)`	Creates a new hash set with `DEFAULT_LOAD_FACTOR` as load factor.
`UnorderedSet(Collection<? extends K> c)`	Creates a new hash set with `DEFAULT_LOAD_FACTOR` as load factor copying a given collection.
`UnorderedSet(Collection<? extends K> c, float f)`	Creates a new hash set copying a given collection.
`UnorderedSet(Collection<? extends K> c, float f, CrossHash.IHasher hasher)`	Creates a new hash set copying a given collection.
`UnorderedSet(Collection<? extends K> c, CrossHash.IHasher hasher)`	Creates a new hash set with `DEFAULT_LOAD_FACTOR` as load factor copying a given collection.
`UnorderedSet(Iterator<? extends K> i)`	Creates a new hash set with `DEFAULT_LOAD_FACTOR` as load factor using elements provided by a type-specific iterator.
`UnorderedSet(Iterator<? extends K> i, float f)`	Creates a new hash set using elements provided by a type-specific iterator.
`UnorderedSet(K[] a)`	Creates a new hash set with `DEFAULT_LOAD_FACTOR` as load factor copying the elements of an array.
`UnorderedSet(K[] a, float f)`	Creates a new hash set copying the elements of an array.
`UnorderedSet(K[] a, float f, CrossHash.IHasher hasher)`	Creates a new hash set copying the elements of an array.
`UnorderedSet(K[] a, int offset, int length)`	Creates a new hash set with `DEFAULT_LOAD_FACTOR` as load factor and fills it with the elements of a given array.
`UnorderedSet(K[] a, int offset, int length, float f)`	Creates a new hash set and fills it with the elements of a given array.
`UnorderedSet(K[] a, int offset, int length, float f, CrossHash.IHasher hasher)`	Creates a new hash set and fills it with the elements of a given array.
`UnorderedSet(K[] a, int offset, int length, CrossHash.IHasher hasher)`	Creates a new hash set with `DEFAULT_LOAD_FACTOR` as load factor and fills it with the elements of a given array.
`UnorderedSet(K[] a, CrossHash.IHasher hasher)`	Creates a new hash set with `DEFAULT_LOAD_FACTOR` as load factor copying the elements of an array.
`UnorderedSet(CrossHash.IHasher hasher)`	Creates a new hash set with `DEFAULT_LOAD_FACTOR` as load factor.

Method Summary

Modifier and Type	Method	Description
`boolean`	`add(K k)`
`boolean`	`addAll(Collection<? extends K> c)`
`boolean`	`addAll(K[] a)`
`K`	`addOrGet(K k)`	Add a random element if not present, get the existing value if already present.
`static int`	`arraySize(int expected, float f)`	Returns the least power of two smaller than or equal to 2³⁰ and larger than or equal to `Math.ceil( expected / f )`.
`void`	`clear()`
`Object`	`clone()`	Returns a deep copy of this map.
`boolean`	`contains(Object k)`
`boolean`	`containsAll(Collection<?> c)`	Checks whether this collection contains all elements from the given collection.
`boolean`	`equals(Object o)`
`K`	`get(Object k)`	Returns the element of this set that is equal to the given key, or `null`.
`long`	`hash64()`
`int`	`hashCode()`	Returns a hash code for this set.
`boolean`	`isEmpty()`
`Iterator<K>`	`iterator()`
`static int`	`maxFill(int n, float f)`	Returns the maximum number of entries that can be filled before rehashing.
`static long`	`maxFill(long n, float f)`	Returns the maximum number of entries that can be filled before rehashing.
`protected int`	`positionOf(Object k)`
`protected void`	`rehash(int newN)`	Rehashes the map.
`boolean`	`remove(Object k)`
`boolean`	`removeAll(Collection<?> c)`	Remove from this collection all elements in the given collection.
`boolean`	`retainAll(Collection<?> c)`	Retains in this collection only elements from the given collection.
`protected void`	`shiftKeys(int pos)`	Shifts left entries with the specified hash code, starting at the specified position, and empties the resulting free entry.
`int`	`size()`
`Object[]`	`toArray()`
`<T> T[]`	`toArray(T[] a)`
`String`	`toString()`
`boolean`	`trim()`	Rehashes the map, making the table as small as possible.
`boolean`	`trim(int n)`	Rehashes this map if the table is too large.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.Set

spliterator

Field Details
- key
  
  protected K[] key
  
  The array of keys.
- mask
  
  protected int mask
  
  The mask for wrapping a position counter.
- containsNull
  
  protected boolean containsNull
  
  Whether this set contains the key zero.
- n
  
  protected int n
  
  The current table size.
- maxFill
  
  protected int maxFill
  
  Threshold after which we rehash. It must be the table size times f.
- size
  
  protected int size
  
  Number of entries in the set (including the key zero, if present).
- f
  
  public final float f
  
  The acceptable load factor.
- DEFAULT_INITIAL_SIZE
  
  public static final int DEFAULT_INITIAL_SIZE
  
  The initial default size of a hash table.
  
  See Also:
  
  Constant Field Values
- DEFAULT_LOAD_FACTOR
  
  public static final float DEFAULT_LOAD_FACTOR
  
  The default load factor of a hash table.
  
  See Also:
  
  Constant Field Values
- FAST_LOAD_FACTOR
  
  public static final float FAST_LOAD_FACTOR
  
  The load factor for a (usually small) table that is meant to be particularly fast.
  
  See Also:
  
  Constant Field Values
- VERY_FAST_LOAD_FACTOR
  
  public static final float VERY_FAST_LOAD_FACTOR
  
  The load factor for a (usually very small) table that is meant to be extremely fast.
  
  See Also:
  
  Constant Field Values
- hasher
  
  protected final CrossHash.IHasher hasher
Constructor Details
- UnorderedSet
  
  public UnorderedSet(int expected, float f)
  
  Creates a new hash map.
  
  The actual table size will be the least power of two greater than expected/f.
  
  Parameters:
  
  expected - the expected number of elements in the hash set.
  
  f - the load factor.
- UnorderedSet
  
  public UnorderedSet(int expected)
  
  Creates a new hash set with DEFAULT_LOAD_FACTOR as load factor.
  
  Parameters:
  
  expected - the expected number of elements in the hash set.
- UnorderedSet
  
  public UnorderedSet()
  
  Creates a new hash set with initial expected DEFAULT_INITIAL_SIZE elements and DEFAULT_LOAD_FACTOR as load factor.
- UnorderedSet
  
  public UnorderedSet(Collection<? extends K> c, float f)
  
  Creates a new hash set copying a given collection.
  
  Parameters:
  
  c - a Collection to be copied into the new hash set.
  
  f - the load factor.
- UnorderedSet
  
  public UnorderedSet(Collection<? extends K> c)
  
  Creates a new hash set with DEFAULT_LOAD_FACTOR as load factor copying a given collection.
  
  Parameters:
  
  c - a Collection to be copied into the new hash set.
- UnorderedSet
  
  public UnorderedSet(Iterator<? extends K> i, float f)
  
  Creates a new hash set using elements provided by a type-specific iterator.
  
  Parameters:
  
  i - a type-specific iterator whose elements will fill the set.
  
  f - the load factor.
- UnorderedSet
  
  public UnorderedSet(Iterator<? extends K> i)
  
  Creates a new hash set with DEFAULT_LOAD_FACTOR as load factor using elements provided by a type-specific iterator.
  
  Parameters:
  
  i - a type-specific iterator whose elements will fill the set.
- UnorderedSet
  
  public UnorderedSet(K[] a, int offset, int length, float f)
  
  Creates a new hash set and fills it with the elements of a given array.
  
  Parameters:
  
  a - an array whose elements will be used to fill the set.
  
  offset - the first element to use.
  
  length - the number of elements to use.
  
  f - the load factor.
- UnorderedSet
  
  public UnorderedSet(K[] a, int offset, int length)
  
  Creates a new hash set with DEFAULT_LOAD_FACTOR as load factor and fills it with the elements of a given array.
  
  Parameters:
  
  a - an array whose elements will be used to fill the set.
  
  offset - the first element to use.
  
  length - the number of elements to use.
- UnorderedSet
  
  public UnorderedSet(K[] a, float f)
  
  Creates a new hash set copying the elements of an array.
  
  Parameters:
  
  a - an array to be copied into the new hash set.
  
  f - the load factor.
- UnorderedSet
  
  public UnorderedSet(K[] a)
  
  Creates a new hash set with DEFAULT_LOAD_FACTOR as load factor copying the elements of an array.
  
  Parameters:
  
  a - an array to be copied into the new hash set.
- UnorderedSet
  
  public UnorderedSet(int expected, float f, CrossHash.IHasher hasher)
  
  Creates a new hash map.
  
  The actual table size will be the least power of two greater than expected/f.
  
  Parameters:
  
  expected - the expected number of elements in the hash set.
  
  f - the load factor.
  
  hasher - used to hash items; typically only needed when K is an array, where CrossHash has implementations
- UnorderedSet
  
  public UnorderedSet(CrossHash.IHasher hasher)
  
  Creates a new hash set with DEFAULT_LOAD_FACTOR as load factor.
  
  Parameters:
  
  hasher - used to hash items; typically only needed when K is an array, where CrossHash has implementations
- UnorderedSet
  
  public UnorderedSet(int expected, CrossHash.IHasher hasher)
  
  Creates a new hash set with DEFAULT_LOAD_FACTOR as load factor.
  
  Parameters:
  
  hasher - used to hash items; typically only needed when K is an array, where CrossHash has implementations
- UnorderedSet
  
  public UnorderedSet(Collection<? extends K> c, float f, CrossHash.IHasher hasher)
  
  Creates a new hash set copying a given collection.
  
  Parameters:
  
  c - a Collection to be copied into the new hash set.
  
  f - the load factor.
  
  hasher - used to hash items; typically only needed when K is an array, where CrossHash has implementations
- UnorderedSet
  
  public UnorderedSet(Collection<? extends K> c, CrossHash.IHasher hasher)
  
  Creates a new hash set with DEFAULT_LOAD_FACTOR as load factor copying a given collection.
  
  Parameters:
  
  c - a Collection to be copied into the new hash set.
  
  hasher - used to hash items; typically only needed when K is an array, where CrossHash has implementations
- UnorderedSet
  
  public UnorderedSet(K[] a, int offset, int length, float f, CrossHash.IHasher hasher)
  
  Creates a new hash set and fills it with the elements of a given array.
  
  Parameters:
  
  a - an array whose elements will be used to fill the set.
  
  offset - the first element to use.
  
  length - the number of elements to use.
  
  f - the load factor.
- UnorderedSet
  
  public UnorderedSet(K[] a, int offset, int length, CrossHash.IHasher hasher)
  
  Creates a new hash set with DEFAULT_LOAD_FACTOR as load factor and fills it with the elements of a given array.
  
  Parameters:
  
  a - an array whose elements will be used to fill the set.
  
  offset - the first element to use.
  
  length - the number of elements to use.
- UnorderedSet
  
  public UnorderedSet(K[] a, float f, CrossHash.IHasher hasher)
  
  Creates a new hash set copying the elements of an array.
  
  Parameters:
  
  a - an array to be copied into the new hash set.
  
  f - the load factor.
- UnorderedSet
  
  public UnorderedSet(K[] a, CrossHash.IHasher hasher)
  
  Creates a new hash set with DEFAULT_LOAD_FACTOR as load factor copying the elements of an array.
  
  Parameters:
  
  a - an array to be copied into the new hash set.
Method Details
- addAll
  
  public boolean addAll(Collection<? extends K> c)
  
  Specified by:
  
  addAll in interface Collection<K>
  
  Specified by:
  
  addAll in interface Set<K>
- addAll
  
  public boolean addAll(K[] a)
- add
  
  public boolean add(K k)
  
  Specified by:
  
  add in interface Collection<K>
  
  Specified by:
  
  add in interface Set<K>
- addOrGet
  
  public K addOrGet(K k)
  Add a random element if not present, get the existing value if already present.
  This is equivalent to (but faster than) doing a:
  
  K exist = set.get(k); if (exist == null) { set.add(k); exist = k; }
- shiftKeys
  
  protected final void shiftKeys(int pos)
  
  Shifts left entries with the specified hash code, starting at the specified position, and empties the resulting free entry.
  
  Parameters:
  
  pos - a starting position.
- remove
  
  public boolean remove(Object k)
  
  Specified by:
  
  remove in interface Collection<K>
  
  Specified by:
  
  remove in interface Set<K>
- get
  
  public K get(Object k)
  
  Returns the element of this set that is equal to the given key, or null.
  
  Returns:
  
  the element of this set that is equal to the given key, or null.
- contains
  
  public boolean contains(Object k)
  
  Specified by:
  
  contains in interface Collection<K>
  
  Specified by:
  
  contains in interface Set<K>
- positionOf
  
  protected int positionOf(Object k)
- clear
  
  public void clear()
  
  Specified by:
  
  clear in interface Collection<K>
  
  Specified by:
  
  clear in interface Set<K>
- size
  
  public int size()
  
  Specified by:
  
  size in interface Collection<K>
  
  Specified by:
  
  size in interface Set<K>
- containsAll
  
  public boolean containsAll(Collection<?> c)
  
  Checks whether this collection contains all elements from the given collection.
  
  Specified by:
  
  containsAll in interface Collection<K>
  
  Specified by:
  
  containsAll in interface Set<K>
  
  Parameters:
  
  c - a collection.
  
  Returns:
  
  true if this collection contains all elements of the argument.
- retainAll
  
  public boolean retainAll(Collection<?> c)
  
  Retains in this collection only elements from the given collection.
  
  Specified by:
  
  retainAll in interface Collection<K>
  
  Specified by:
  
  retainAll in interface Set<K>
  
  Parameters:
  
  c - a collection.
  
  Returns:
  
  true if this collection changed as a result of the call.
- removeAll
  
  public boolean removeAll(Collection<?> c)
  
  Remove from this collection all elements in the given collection. If the collection is an instance of this class, it uses faster iterators.
  
  Specified by:
  
  removeAll in interface Collection<K>
  
  Specified by:
  
  removeAll in interface Set<K>
  
  Parameters:
  
  c - a collection.
  
  Returns:
  
  true if this collection changed as a result of the call.
- isEmpty
  
  public boolean isEmpty()
  
  Specified by:
  
  isEmpty in interface Collection<K>
  
  Specified by:
  
  isEmpty in interface Set<K>
- iterator
  
  public Iterator<K> iterator()
  
  Specified by:
  
  iterator in interface Collection<K>
  
  Specified by:
  
  iterator in interface Iterable<K>
  
  Specified by:
  
  iterator in interface Set<K>
- trim
  
  public boolean trim()
  
  Rehashes the map, making the table as small as possible.
  
  This method rehashes the table to the smallest size satisfying the load factor. It can be used when the set will not be changed anymore, so to optimize access speed and size.
  
  If the table size is already the minimum possible, this method does nothing.
  
  Returns:
  
  true if there was enough memory to trim the map.
  
  See Also:
  
  trim(int)
- trim
  
  public boolean trim(int n)
  
  Rehashes this map if the table is too large.
  
  Let N be the smallest table size that can hold max(n,size()) entries, still satisfying the load factor. If the current table size is smaller than or equal to N, this method does nothing. Otherwise, it rehashes this map in a table of size N.
  
  This method is useful when reusing maps. Clearing a map leaves the table size untouched. If you are reusing a map many times, you can call this method with a typical size to avoid keeping around a very large table just because of a few large transient maps.
  
  Parameters:
  
  n - the threshold for the trimming.
  
  Returns:
  
  true if there was enough memory to trim the map.
  
  See Also:
  
  trim()
- rehash
  
  protected void rehash(int newN)
  
  Rehashes the map.
  
  This method implements the basic rehashing strategy, and may be overriden by subclasses implementing different rehashing strategies (e.g., disk-based rehashing). However, you should not override this method unless you understand the internal workings of this class.
  
  Parameters:
  
  newN - the new size
- clone
  
  public Object clone()
  
  Returns a deep copy of this map.
  
  This method performs a deep copy of this hash map; the data stored in the map, however, is not cloned. Note that this makes a difference only for object keys.
  
  Overrides:
  
  clone in class Object
  
  Returns:
  
  a deep copy of this map.
- hashCode
  
  public int hashCode()
  
  Returns a hash code for this set.
  This method overrides the generic method provided by the superclass. Since equals() is not overriden, it is important that the value returned by this method is the same value as the one returned by the overriden method.
  
  Specified by:
  
  hashCode in interface Collection<K>
  
  Specified by:
  
  hashCode in interface Set<K>
  
  Overrides:
  
  hashCode in class Object
  
  Returns:
  
  a hash code for this set.
- hash64
  
  public long hash64()
- maxFill
  
  public static int maxFill(int n, float f)
  
  Returns the maximum number of entries that can be filled before rehashing.
  
  Parameters:
  
  n - the size of the backing array.
  
  f - the load factor.
  
  Returns:
  
  the maximum number of entries before rehashing.
- maxFill
  
  public static long maxFill(long n, float f)
  
  Returns the maximum number of entries that can be filled before rehashing.
  
  Parameters:
  
  n - the size of the backing array.
  
  f - the load factor.
  
  Returns:
  
  the maximum number of entries before rehashing.
- arraySize
  
  public static int arraySize(int expected, float f)
  
  Returns the least power of two smaller than or equal to 2³⁰ and larger than or equal to Math.ceil( expected / f ).
  
  Parameters:
  
  expected - the expected number of elements in a hash table.
  
  f - the load factor.
  
  Returns:
  
  the minimum possible size for a backing array.
  
  Throws:
  
  IllegalArgumentException - if the necessary size is larger than 2³⁰.
- toArray
  
  public Object[] toArray()
  
  Specified by:
  
  toArray in interface Collection<K>
  
  Specified by:
  
  toArray in interface Set<K>
- toArray
  
  public <T> T[] toArray(T[] a)
  
  Specified by:
  
  toArray in interface Collection<K>
  
  Specified by:
  
  toArray in interface Set<K>
- toString
  
  public String toString()
  
  Overrides:
  
  toString in class Object
- equals
  
  public boolean equals(Object o)
  
  Specified by:
  
  equals in interface Collection<K>
  
  Specified by:
  
  equals in interface Set<K>
  
  Overrides:
  
  equals in class Object

Class UnorderedSet<K>