Package com.github.tommyettinger.ds

Class HolderSet<T,K>

java.lang.Object
com.github.tommyettinger.ds.HolderSet<T,K>
Type Parameters:
T - the type of full items stored in the set; each T must have a way to get a K from it
K - the type of lookup keys stored in each T item
All Implemented Interfaces:
EnhancedCollection<T>, Iterable<T>, Collection<T>, Set<T>
Direct Known Subclasses:
HolderOrderedSet
public class HolderSet<T,K> extends Object implements Iterable<T>, Set<T>, EnhancedCollection<T>
An unordered set where the items are objects but access to items is done with a specific key component held by each item, and the component is extracted from an item by a given Function. Neither null items nor null keys are allowed. No allocation is done except when growing the table size. The function is called the extractor, and is often a method reference.
Some operations are different here from a normal Set; contains(Object) expects a K key, and remove(Object) does as well. You can use get(Object) to go back to a T value from a K key.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    HolderSet.HolderSetIterator<T,K>
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected com.github.tommyettinger.function.ObjToObjFunction<T,K>
    extractor
     
    protected int
    hashMultiplier
    Used by place(Object) to mix hashCode() results.
    protected HolderSet.HolderSetIterator<T,K>
    iterator1
     
    protected HolderSet.HolderSetIterator<T,K>
    iterator2
     
    protected T[]
    keyTable
     
    protected float
    loadFactor
    Between 0f (exclusive) and 1f (inclusive, if you're careful), this determines how full the backing table can get before this increases its size.
    protected int
    mask
    A bitmask used to confine hashcodes to the size of the table.
    protected int
    shift
    Used by place(Object) typically, this should always equal com.github.tommyettinger.digital.BitConversion.countLeadingZeros(mask).
    protected int
    size
     
    protected int
    threshold
    Precalculated value of (int)(keyTable.length * loadFactor), used to determine when to resize.

  • Constructor Summary

    Constructors
    Constructor
    Description
    HolderSet()
    Creates a new set with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor().
    HolderSet(HolderSet<T,K> set)
    Creates a new set identical to the specified set.
    HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor)
    Creates a new set with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor().
    HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, int initialCapacity)
    Creates a new set with a load factor of Utilities.getDefaultLoadFactor().
    HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, int initialCapacity, float loadFactor)
    Creates a new set with the specified initial capacity and load factor.
    HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, Collection<? extends T> coll)
    Creates a new set that contains all distinct elements in coll, using extractor to get the keys that determine distinctness.
    HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, Iterator<? extends T> coll)
    Creates a new instance containing the items in the specified iterator.
    HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T[] items)
    Creates a new set that contains all distinct elements in items, using extractor to get the keys that determine distinctness.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    add(T key)
    Returns true if the item was not already in the set.
    boolean
    addAll(HolderSet<T,?> set)
     
    boolean
    addAll(Collection<? extends T> coll)
     
    boolean
    addAll(T[] array)
     
    boolean
    addAll(T[] array, int offset, int length)
     
    protected void
    addResize(T key)
    Skips checks for existing keys, doesn't increment size.
    void
    clear()
    Clears the set, leaving the backing arrays at the current capacity.
    void
    clear(int maximumCapacity)
    Clears the set and reduces the size of the backing arrays to be the specified capacity / loadFactor, if they are larger.
    boolean
    contains(Object key)
    Checks for the presence of a K key, not a T value.
    boolean
    containsAll(Object[] array)
    Exactly like containsAll(Collection), but takes an array instead of a Collection.
    boolean
    containsAll(Object[] array, int offset, int length)
    Like containsAll(Object[]), but only uses at most length items from array, starting at offset.
    boolean
    containsAll(Collection<?> c)
     
    boolean
    containsAny(Object[] values)
    Returns true if this set contains any of the specified values.
    boolean
    containsAny(Object[] values, int offset, int length)
    Returns true if this set contains any items from the specified range of values.
    boolean
    containsAnyIterable(Iterable<?> values)
    Returns true if this set contains any of the specified values.
    void
    ensureCapacity(int additionalCapacity)
    Increases the size of the backing array to accommodate the specified number of additional items / loadFactor.
    boolean
    equals(Object o)
     
    protected boolean
    equate(Object left, Object right)
    Compares the objects left and right, which should be K keys (not T items), for equality, returning true if they are considered equal.
    T
    first()
    Gets the (arbitrarily-chosen) first item in this HolderSet.
    T
    get(Object key)
    Given a K key that could have been extracted or extractable from a T item in this, this returns the T item that holds that key, or null if no item holds key.
    com.github.tommyettinger.function.ObjToObjFunction<T,K>
    getExtractor()
    Gets the function this uses to extract keys from items.
    int
    getHashMultiplier()
    Gets the current hashMultiplier, used in place(Object) to mix hash codes.
    float
    getLoadFactor()
     
    T
    getOrDefault(Object key, T defaultValue)
    Given a K key that could have been extracted or extractable from a T item in this, this returns the T item that holds that key, or defaultValue if no item holds key.
    int
    getTableSize()
    Gets the length of the internal array used to store all items, as well as empty space awaiting more items to be entered.
    int
    hashCode()
     
    boolean
    isEmpty()
    Returns true if the set is empty.
    HolderSet.HolderSetIterator<T,K>
    iterator()
    Returns an iterator for the keys in the set.
    protected int
    locateKey(Object key)
    Returns the index of the key if already present, else ~index for the next empty index.
    boolean
    notEmpty()
    Returns true if the set has one or more items.
    static <T, K> HolderSet<T,K>
    parse(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, String str, String delimiter, PartialParser<T> parser)
    Calls parse(ObjToObjFunction, String, String, PartialParser, boolean) with brackets set to false.
    static <T, K> HolderSet<T,K>
    parse(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, String str, String delimiter, PartialParser<T> parser, boolean brackets)
    Creates a new HolderSet using extractor and fills it by calling EnhancedCollection.addLegible(String, String, PartialParser, int, int) on either all of str (if brackets is false) or str without its first and last chars (if brackets is true).
    static <T, K> HolderSet<T,K>
    parse(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, String str, String delimiter, PartialParser<T> parser, int offset, int length)
    Creates a new HolderSet using extractor and fills it by calling EnhancedCollection.addLegible(String, String, PartialParser, int, int) with the other five parameters as-is.
    protected int
    place(Object item)
    Returns an index >= 0 and <= mask for the specified item, mixed.
    boolean
    remove(Object key)
    Takes a K key and not a T value! Returns true if the key was removed.
    boolean
    removeAll(Object[] values)
    Removes from this collection all occurrences of any elements contained in the specified array.
    boolean
    removeAll(Object[] values, int offset, int length)
    Removes from this collection all occurrences of any elements contained in the specified array, but only starts reading elements from the array starting at the given offset and only uses length items.
    boolean
    removeAll(Collection<?> c)
    Removes from this Set a Collection of K key types (not T items).
    protected void
    resize(int newSize)
     
    boolean
    retainAll(Collection<?> c)
    Makes this Set retain a Collection of K key types (not T items).
    void
    setExtractor(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor)
    Sets the function this will use to extract keys from items; this will only have an effect if the extractor function is currently null/invalid.
    void
    setHashMultiplier(int hashMultiplier)
    Sets the hashMultiplier to the given int, which will be made odd if even and always negative (by OR-ing with 0x80000001).
    void
    setLoadFactor(float loadFactor)
     
    void
    shrink(int maximumCapacity)
    Reduces the size of the backing arrays to be the specified capacity / loadFactor, or less.
    int
    size()
    Returns the number of elements in this set (its cardinality).
    Object[]
    toArray()
     
    <E> E[]
    toArray(E[] a)
    Returns an array containing all the elements in this set; the runtime type of the returned array is that of the specified array.
    String
    toString()
     
    void
    truncate(int newSize)
    Reduces the size of the set to the specified size.
    static <T, K> HolderSet<T,K>
    with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor)
    Constructs an empty set given only an extractor function.
    static <T, K> HolderSet<T,K>
    with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item)
    Creates a new HolderSet that holds only the given item, but can be resized.
    static <T, K> HolderSet<T,K>
    with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T... varargs)
    Creates a new HolderSet that holds only the given items, but can be resized.
    static <T, K> HolderSet<T,K>
    with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1)
    Creates a new HolderSet that holds only the given items, but can be resized.
    static <T, K> HolderSet<T,K>
    with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2)
    Creates a new HolderSet that holds only the given items, but can be resized.
    static <T, K> HolderSet<T,K>
    with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2, T item3)
    Creates a new HolderSet that holds only the given items, but can be resized.
    static <T, K> HolderSet<T,K>
    with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2, T item3, T item4)
    Creates a new HolderSet that holds only the given items, but can be resized.
    static <T, K> HolderSet<T,K>
    with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2, T item3, T item4, T item5)
    Creates a new HolderSet that holds only the given items, but can be resized.
    static <T, K> HolderSet<T,K>
    with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2, T item3, T item4, T item5, T item6)
    Creates a new HolderSet that holds only the given items, but can be resized.
    static <T, K> HolderSet<T,K>
    with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2, T item3, T item4, T item5, T item6, T item7)
    Creates a new HolderSet that holds only the given items, but can be resized.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.util.Collection

    parallelStream, removeIf, stream, toArray

    Methods inherited from interface com.github.tommyettinger.ds.EnhancedCollection

    add, add, add, addAll, addAllIterable, addLegible, addLegible, addVarargs, appendTo, appendTo, containsAll, containsAllIterable, containsAny, removeAll, removeAllIterable, removeEach, removeEach, removeEach, removeEachIterable, toString, toString, toString

    Methods inherited from interface java.lang.Iterable

    forEach

    Methods inherited from interface java.util.Set

    spliterator

  • Field Details

    • size

      protected int size

    • keyTable

      protected T[] keyTable

    • loadFactor

      protected float loadFactor
      Between 0f (exclusive) and 1f (inclusive, if you're careful), this determines how full the backing table can get before this increases its size. Larger values use less memory but make the data structure slower.

    • threshold

      protected int threshold
      Precalculated value of (int)(keyTable.length * loadFactor), used to determine when to resize.

    • shift

      protected int shift
      Used by place(Object) typically, this should always equal com.github.tommyettinger.digital.BitConversion.countLeadingZeros(mask). For a table that could hold 2 items (with 1 bit indices), this would be 64 - 1 == 63. For a table that could hold 256 items (with 8 bit indices), this would be 64 - 8 == 56.

    • mask

      protected int mask
      A bitmask used to confine hashcodes to the size of the table. Must be all 1 bits in its low positions, ie a power of two minus 1. If place(Object) is overridden, this can be used instead of shift to isolate usable bits of a hash.

    • hashMultiplier

      protected int hashMultiplier
      Used by place(Object) to mix hashCode() results. Changes on every call to resize(int) by default. This should always change when shift changes, meaning, when the backing table resizes. This only needs to be serialized if the full key and value tables are serialized, or if the iteration order should be the same before and after serialization. Iteration order is better handled by using HolderOrderedSet.

    • iterator1

      protected transient HolderSet.HolderSetIterator<T,K> iterator1

    • iterator2

      protected transient HolderSet.HolderSetIterator<T,K> iterator2

    • extractor

      protected transient com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor

  • Constructor Details

    • HolderSet

      public HolderSet()
      Creates a new set with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor(). This does not set the extractor, so the HolderSet will not be usable until setExtractor(ObjToObjFunction) is called with a valid ObjToObjFunction that gets K keys from T items.

    • HolderSet

      public HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor)
      Creates a new set with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor().
      Parameters:
      extractor - a function that will be used to extract K keys from the T items put into this

    • HolderSet

      public HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, int initialCapacity)
      Creates a new set with a load factor of Utilities.getDefaultLoadFactor().
      Parameters:
      extractor - a function that will be used to extract K keys from the T items put into this
      initialCapacity - If not a power of two, it is increased to the next nearest power of two.

    • HolderSet

      public HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, int initialCapacity, float loadFactor)
      Creates a new set with the specified initial capacity and load factor. This set will hold initialCapacity items before growing the backing table.
      Parameters:
      extractor - a function that will be used to extract K keys from the T items put into this
      initialCapacity - If not a power of two, it is increased to the next nearest power of two.
      loadFactor - what fraction of the capacity can be filled before this has to resize; 0 < loadFactor <= 1

    • HolderSet

      public HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, Iterator<? extends T> coll)
      Creates a new instance containing the items in the specified iterator.
      Parameters:
      coll - an iterator that will have its remaining contents added to this

    • HolderSet

      public HolderSet(HolderSet<T,K> set)
      Creates a new set identical to the specified set. This doesn't copy the extractor; instead it references the same ObjToObjFunction from the argument. This can have issues if the extractor causes side effects or is stateful.

    • HolderSet

      public HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, Collection<? extends T> coll)
      Creates a new set that contains all distinct elements in coll, using extractor to get the keys that determine distinctness.
      Parameters:
      extractor - a function that will be used to extract K keys from the T items in coll
      coll - a Collection of T items; depending on extractor, some different T items may not be added because their K key is equal

    • HolderSet

      public HolderSet(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T[] items)
      Creates a new set that contains all distinct elements in items, using extractor to get the keys that determine distinctness.
      Parameters:
      extractor - a function that will be used to extract K keys from the T items in coll
      items - an array of T items; depending on extractor, some different T items may not be added because their K key is equal

  • Method Details

    • getExtractor

      public com.github.tommyettinger.function.ObjToObjFunction<T,K> getExtractor()
      Gets the function this uses to extract keys from items. This may be null if HolderSet() was used to construct this object (or technically if HolderSet(HolderSet) was used to copy a HolderSet with an invalid extractor); in that case, this cannot have items added, removed, or inserted until a valid extractor is set with setExtractor(ObjToObjFunction).
      Returns:
      the extractor function this uses to get keys from items

    • setExtractor

      public void setExtractor(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor)
      Sets the function this will use to extract keys from items; this will only have an effect if the extractor function is currently null/invalid. This is typically needed if HolderSet() was used to construct the HolderSet, but can also be required if HolderSet(HolderSet) was used to copy another HolderSet with an invalid extractor. All other cases should require the extractor function to be specified at construction-time.
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference

    • place

      protected int place(Object item)
      Returns an index >= 0 and <= mask for the specified item, mixed.
      Parameters:
      item - a non-null Object; its hashCode() method should be used by most implementations
      Returns:
      an index between 0 and mask (both inclusive)

    • equate

      protected boolean equate(Object left, Object right)
      Compares the objects left and right, which should be K keys (not T items), for equality, returning true if they are considered equal. This is used by the rest of this class to determine whether two keys are considered equal. Normally, this returns left.equals(right), but subclasses can override it to use reference equality, fuzzy equality, deep array equality, or any other custom definition of equality. Usually, place(Object) is also overridden if this method is.
      Parameters:
      left - must be non-null; typically a K key being compared, but not necessarily
      right - may be null; typically a K key being compared, but can often be null for an empty key slot, or some other type
      Returns:
      true if left and right are considered equal for the purposes of this class

    • locateKey

      protected int locateKey(Object key)
      Returns the index of the key if already present, else ~index for the next empty index. This calls equate(Object, Object) to determine if two keys are equivalent. This expects key to be a K object, not a T item, and will extract keys from existing items to compare against.
      Parameters:
      key - a non-null Object that should probably be a K

    • add

      public boolean add(T key)
      Returns true if the item was not already in the set. If this set already contains the item, the call leaves the set unchanged and returns false. Note that this does not take a K key, but a T item
      Specified by:
      add in interface Collection<T>
      Specified by:
      add in interface Set<T>

    • addAll

      public boolean addAll(Collection<? extends T> coll)
      Specified by:
      addAll in interface Collection<T>
      Specified by:
      addAll in interface Set<T>

    • addAll

      public boolean addAll(T[] array)
      Specified by:
      addAll in interface EnhancedCollection<T>

    • addAll

      public boolean addAll(T[] array, int offset, int length)
      Specified by:
      addAll in interface EnhancedCollection<T>

    • addAll

      public boolean addAll(HolderSet<T,?> set)

    • retainAll

      public boolean retainAll(Collection<?> c)
      Makes this Set retain a Collection of K key types (not T items).
      Specified by:
      retainAll in interface Collection<T>
      Specified by:
      retainAll in interface Set<T>
      Parameters:
      c - a Collection that should hold K keys to retain in this
      Returns:
      true if this Set was modified

    • removeAll

      public boolean removeAll(Collection<?> c)
      Removes from this Set a Collection of K key types (not T items).
      Specified by:
      removeAll in interface Collection<T>
      Specified by:
      removeAll in interface Set<T>
      Parameters:
      c - a Collection that should hold K keys to remove from this
      Returns:
      true if this Set was modified

    • removeAll

      public boolean removeAll(Object[] values)
      Description copied from interface: EnhancedCollection
      Removes from this collection all occurrences of any elements contained in the specified array.
      Specified by:
      removeAll in interface EnhancedCollection<T>
      Parameters:
      values - a non-null array of items to remove fully
      Returns:
      true if this collection was modified.

    • removeAll

      public boolean removeAll(Object[] values, int offset, int length)
      Description copied from interface: EnhancedCollection
      Removes from this collection all occurrences of any elements contained in the specified array, but only starts reading elements from the array starting at the given offset and only uses length items.
      Specified by:
      removeAll in interface EnhancedCollection<T>
      Parameters:
      values - a non-null array of items to remove fully
      offset - the first index in array to use
      length - how many items from array should be used
      Returns:
      true if this collection was modified.

    • containsAll

      public boolean containsAll(Collection<?> c)
      Specified by:
      containsAll in interface Collection<T>
      Specified by:
      containsAll in interface Set<T>

    • containsAll

      public boolean containsAll(Object[] array)
      Exactly like containsAll(Collection), but takes an array instead of a Collection.
      Specified by:
      containsAll in interface EnhancedCollection<T>
      Parameters:
      array - array to be checked for containment in this set
      Returns:
      true if this set contains all the elements in the specified array
      See Also:

    • containsAll

      public boolean containsAll(Object[] array, int offset, int length)
      Like containsAll(Object[]), but only uses at most length items from array, starting at offset.
      Specified by:
      containsAll in interface EnhancedCollection<T>
      Parameters:
      array - array to be checked for containment in this set
      offset - the index of the first item in array to check
      length - how many items, at most, to check from array
      Returns:
      true if this set contains all the elements in the specified range of array
      See Also:

    • containsAnyIterable

      public boolean containsAnyIterable(Iterable<?> values)
      Returns true if this set contains any of the specified values.
      Specified by:
      containsAnyIterable in interface EnhancedCollection<T>
      Parameters:
      values - must not contain nulls, and must not be null itself
      Returns:
      true if this set contains any of the items in values, false otherwise

    • containsAny

      public boolean containsAny(Object[] values)
      Returns true if this set contains any of the specified values.
      Specified by:
      containsAny in interface EnhancedCollection<T>
      Parameters:
      values - must not contain nulls, and must not be null itself
      Returns:
      true if this set contains any of the items in values, false otherwise

    • containsAny

      public boolean containsAny(Object[] values, int offset, int length)
      Returns true if this set contains any items from the specified range of values.
      Specified by:
      containsAny in interface EnhancedCollection<T>
      Parameters:
      values - must not contain nulls, and must not be null itself
      offset - the index to start checking in values
      length - how many items to check from values
      Returns:
      true if this set contains any of the items in the given range of values, false otherwise

    • addResize

      protected void addResize(T key)
      Skips checks for existing keys, doesn't increment size.

    • remove

      public boolean remove(Object key)
      Takes a K key and not a T value! Returns true if the key was removed.
      Specified by:
      remove in interface Collection<T>
      Specified by:
      remove in interface Set<T>

    • notEmpty

      public boolean notEmpty()
      Returns true if the set has one or more items.

    • size

      public int size()
      Returns the number of elements in this set (its cardinality). If this set contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
      Specified by:
      size in interface Collection<T>
      Specified by:
      size in interface Set<T>
      Returns:
      the number of elements in this set (its cardinality)

    • isEmpty

      public boolean isEmpty()
      Returns true if the set is empty.
      Specified by:
      isEmpty in interface Collection<T>
      Specified by:
      isEmpty in interface Set<T>

    • shrink

      public void shrink(int maximumCapacity)
      Reduces the size of the backing arrays to be the specified capacity / loadFactor, or less. If the capacity is already less, nothing is done. If the set contains more items than the specified capacity, the next highest power of two capacity is used instead.

    • clear

      public void clear(int maximumCapacity)
      Clears the set and reduces the size of the backing arrays to be the specified capacity / loadFactor, if they are larger. The reduction is done by allocating new arrays, though for large arrays this can be faster than clearing the existing array.

    • clear

      public void clear()
      Clears the set, leaving the backing arrays at the current capacity. When the capacity is high and the population is low, iteration can be unnecessarily slow. clear(int) can be used to reduce the capacity.
      Specified by:
      clear in interface Collection<T>
      Specified by:
      clear in interface Set<T>

    • contains

      public boolean contains(Object key)
      Checks for the presence of a K key, not a T value.
      Specified by:
      contains in interface Collection<T>
      Specified by:
      contains in interface Set<T>
      Parameters:
      key - may be any non-null Object, but should be a K key
      Returns:
      true if this contains the given key

    • get

      public T get(Object key)
      Given a K key that could have been extracted or extractable from a T item in this, this returns the T item that holds that key, or null if no item holds key.
      Parameters:
      key - a K key that could have been extracted from a T item in this
      Returns:
      the T item that holds the given key, or null if none was found

    • getOrDefault

      public T getOrDefault(Object key, T defaultValue)
      Given a K key that could have been extracted or extractable from a T item in this, this returns the T item that holds that key, or defaultValue if no item holds key.
      Parameters:
      key - a K key that could have been extracted from a T item in this
      defaultValue - the T value to return if key could not be found
      Returns:
      the T item that holds the given key, or defaultValue if none was found

    • first

      public T first()
      Gets the (arbitrarily-chosen) first item in this HolderSet. Which item is "first" can change when this resizes, and you can't rely on the order of items in an unordered set like this. If this HolderSet is empty, this will return null. Note that this set cannot contain null.
      Specified by:
      first in interface EnhancedCollection<T>
      Returns:
      the "first" item in this HolderSet; really an arbitrary item in this

    • ensureCapacity

      public void ensureCapacity(int additionalCapacity)
      Increases the size of the backing array to accommodate the specified number of additional items / loadFactor. Useful before adding many items to avoid multiple backing array resizes.
      Parameters:
      additionalCapacity - how many additional items this should be able to hold without resizing (probably)

    • resize

      protected void resize(int newSize)

    • getHashMultiplier

      public int getHashMultiplier()
      Gets the current hashMultiplier, used in place(Object) to mix hash codes. If setHashMultiplier(int) is never called, the hashMultiplier will always be drawn from Utilities.GOOD_MULTIPLIERS, with the index equal to 64 - shift.
      Returns:
      the current hashMultiplier

    • setHashMultiplier

      public void setHashMultiplier(int hashMultiplier)
      Sets the hashMultiplier to the given int, which will be made odd if even and always negative (by OR-ing with 0x80000001). This can be any negative, odd int, but should almost always be drawn from Utilities.GOOD_MULTIPLIERS or something like it.
      Parameters:
      hashMultiplier - any int; will be made odd if even.

    • getTableSize

      public int getTableSize()
      Gets the length of the internal array used to store all items, as well as empty space awaiting more items to be entered. This is also called the capacity.
      Returns:
      the length of the internal array that holds all items

    • toArray

      public Object[] toArray()
      Specified by:
      toArray in interface Collection<T>
      Specified by:
      toArray in interface Set<T>

    • toArray

      public <E> E[] toArray(E[] a)
      Returns an array containing all the elements in this set; the runtime type of the returned array is that of the specified array. If the set fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this set.
      Implementation is mostly copied from GWT, but uses Arrays.copyOf() instead of their internal APIs.
      Specified by:
      toArray in interface Collection<T>
      Specified by:
      toArray in interface Set<T>
      Type Parameters:
      E - must be the same as T or a superclass/interface of it; not checked
      Parameters:
      a - the array into which the elements of this set are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
      Returns:
      an array containing all the elements in this set

    • getLoadFactor

      public float getLoadFactor()

    • setLoadFactor

      public void setLoadFactor(float loadFactor)

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface Collection<T>
      Specified by:
      hashCode in interface Set<T>
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Specified by:
      equals in interface Collection<T>
      Specified by:
      equals in interface Set<T>
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • truncate

      public void truncate(int newSize)
      Reduces the size of the set to the specified size. If the set is already smaller than the specified size, no action is taken. This indiscriminately removes items from the backing array until the requested newSize is reached, or until the full backing array has had its elements removed.
      This tries to remove from the end of the iteration order, but because the iteration order is not guaranteed by an unordered set, this can remove essentially any item(s) from the set if it is larger than newSize.
      Parameters:
      newSize - the target size to try to reach by removing items, if smaller than the current size

    • iterator

      public HolderSet.HolderSetIterator<T,K> iterator()
      Returns an iterator for the keys in the set. Remove is supported.

      Reuses one of two iterators for this set. For nested or multithreaded iteration, use HolderSetIterator(HolderSet).

      Specified by:
      iterator in interface Collection<T>
      Specified by:
      iterator in interface Iterable<T>
      Specified by:
      iterator in interface Set<T>

    • with

      public static <T, K> HolderSet<T,K> with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor)
      Constructs an empty set given only an extractor function. This is usually less useful than just using the constructor, but can be handy in some code-generation scenarios when you don't know how many arguments you will have.
      Type Parameters:
      T - the type of items; must be given explicitly
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      Returns:
      a new set containing nothing

    • with

      public static <T, K> HolderSet<T,K> with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item)
      Creates a new HolderSet that holds only the given item, but can be resized.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      item - one T item
      Returns:
      a new HolderSet that holds the given item

    • with

      public static <T, K> HolderSet<T,K> with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1)
      Creates a new HolderSet that holds only the given items, but can be resized.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      item0 - a T item
      item1 - a T item
      Returns:
      a new HolderSet that holds the given items

    • with

      public static <T, K> HolderSet<T,K> with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2)
      Creates a new HolderSet that holds only the given items, but can be resized.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      item0 - a T item
      item1 - a T item
      item2 - a T item
      Returns:
      a new HolderSet that holds the given items

    • with

      public static <T, K> HolderSet<T,K> with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2, T item3)
      Creates a new HolderSet that holds only the given items, but can be resized.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      item0 - a T item
      item1 - a T item
      item2 - a T item
      item3 - a T item
      Returns:
      a new HolderSet that holds the given items

    • with

      public static <T, K> HolderSet<T,K> with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2, T item3, T item4)
      Creates a new HolderSet that holds only the given items, but can be resized.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      item0 - a T item
      item1 - a T item
      item2 - a T item
      item3 - a T item
      item4 - a T item
      Returns:
      a new HolderSet that holds the given items

    • with

      public static <T, K> HolderSet<T,K> with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2, T item3, T item4, T item5)
      Creates a new HolderSet that holds only the given items, but can be resized.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      item0 - a T item
      item1 - a T item
      item2 - a T item
      item3 - a T item
      item4 - a T item
      item5 - a T item
      Returns:
      a new HolderSet that holds the given items

    • with

      public static <T, K> HolderSet<T,K> with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2, T item3, T item4, T item5, T item6)
      Creates a new HolderSet that holds only the given items, but can be resized.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      item0 - a T item
      item1 - a T item
      item2 - a T item
      item3 - a T item
      item4 - a T item
      item5 - a T item
      item6 - a T item
      Returns:
      a new HolderSet that holds the given items

    • with

      public static <T, K> HolderSet<T,K> with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T item0, T item1, T item2, T item3, T item4, T item5, T item6, T item7)
      Creates a new HolderSet that holds only the given items, but can be resized.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      item0 - a T item
      item1 - a T item
      item2 - a T item
      item3 - a T item
      item4 - a T item
      item5 - a T item
      item6 - a T item
      Returns:
      a new HolderSet that holds the given items

    • with

      @SafeVarargs public static <T, K> HolderSet<T,K> with(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, T... varargs)
      Creates a new HolderSet that holds only the given items, but can be resized. This overload will only be used when an array is supplied and the type of the items requested is the component type of the array, or if varargs are used and there are 9 or more arguments.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      varargs - a T varargs or T array; remember that varargs allocate
      Returns:
      a new HolderSet that holds the given items

    • parse

      public static <T, K> HolderSet<T,K> parse(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, String str, String delimiter, PartialParser<T> parser)
      Calls parse(ObjToObjFunction, String, String, PartialParser, boolean) with brackets set to false.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      str - a String that will be parsed in full
      delimiter - the delimiter between items in str
      parser - a PartialParser that returns a T item from a section of str
      Returns:
      a new collection parsed from str

    • parse

      public static <T, K> HolderSet<T,K> parse(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, String str, String delimiter, PartialParser<T> parser, boolean brackets)
      Creates a new HolderSet using extractor and fills it by calling EnhancedCollection.addLegible(String, String, PartialParser, int, int) on either all of str (if brackets is false) or str without its first and last chars (if brackets is true). Each item is expected to be separated by delimiter.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      str - a String that will be parsed in full (depending on brackets)
      delimiter - the delimiter between items in str
      parser - a PartialParser that returns a T item from a section of str
      brackets - if true, the first and last chars in str will be ignored
      Returns:
      a new collection parsed from str

    • parse

      public static <T, K> HolderSet<T,K> parse(com.github.tommyettinger.function.ObjToObjFunction<T,K> extractor, String str, String delimiter, PartialParser<T> parser, int offset, int length)
      Creates a new HolderSet using extractor and fills it by calling EnhancedCollection.addLegible(String, String, PartialParser, int, int) with the other five parameters as-is.
      Type Parameters:
      T - the type of item, typically inferred
      K - the type of keys that extractor pulls from T items
      Parameters:
      extractor - a ObjToObjFunction that takes a T and gets a unique K from it; often a method reference
      str - a String that will have the given section parsed
      delimiter - the delimiter between items in str
      parser - a PartialParser that returns a T item from a section of str
      offset - the first position to parse in str, inclusive
      length - how many chars to parse, starting from offset
      Returns:
      a new collection parsed from str