Package com.github.tommyettinger.ds

Class CaseInsensitiveOrderedSet

java.lang.Object
com.github.tommyettinger.ds.ObjectSet<T>
com.github.tommyettinger.ds.ObjectOrderedSet<CharSequence>
com.github.tommyettinger.ds.CaseInsensitiveOrderedSet
All Implemented Interfaces:
Arrangeable, EnhancedCollection<CharSequence>, Ordered<CharSequence>, Iterable<CharSequence>, Collection<CharSequence>, Set<CharSequence>
public class CaseInsensitiveOrderedSet extends ObjectOrderedSet<CharSequence>
A custom variant on ObjectOrderedSet that always uses CharSequence keys and compares them as case-insensitive. This uses a fairly complex, quite-optimized hashing function because it needs to hash CharSequences rather often, and to do so ignoring case means String.hashCode() won't work, plus not all CharSequences implement hashCode() themselves (such as StringBuilder). User code similar to this can often get away with a simple polynomial hash (the typical Java kind, used by String and Arrays), or if more speed is needed, one with some of these optimizations by Richard Startin. If you don't want to write or benchmark a hash function (which is quite understandable), Utilities.hashCodeIgnoreCase(CharSequence) can get a case-insensitive hash of any CharSequence, as a long. It does this without allocating new Strings all over, where many case-insensitive algorithms do allocate quite a lot, but it does this by handling case incorrectly for the Georgian alphabet. If I see Georgian text in-the-wild, I may reconsider, but I don't think that particular alphabet is in widespread use. There's also Utilities.equalsIgnoreCase(CharSequence, CharSequence) for equality comparisons that are similarly case-insensitive, except for Georgian.
This is very similar to CaseInsensitiveSet, except that this class maintains insertion order and can be sorted with ObjectOrderedSet.sort(), ObjectOrderedSet.sort(Comparator), etc. Note that because each CharSequence is stored in here in its original form (not modified to make it ignore case), the sorted order might be different than you expect. Utilities.compareIgnoreCase(CharSequence, CharSequence) can be used to sort this as case-insensitive.
This is also very similar to FilteredStringOrderedSet when its editor is Character.toUpperCase(char) or Casing.caseUp(char). FilteredStringOrderedSet works with Strings rather than CharSequences, which may be more convenient, and allows filtering some characters out of hashing and equality comparisons. If you want a case-insensitive set that ignores any non-letter characters in a String, then CaseInsensitiveOrderedSet won't do, but new FilteredStringOrderedSet<>(CharPredicates.IS_LETTER, Casing::caseUp will work. Note that GWT only handles Character.isLetter(char) for ASCII letters; CharPredicates in this library provides cross-platform predicates that use CharBitSet to store their data, and the library RegExodus offers replacements in Category for other Unicode categories, such as upper-case letters, currency symbols, decimal digits, and so on.

  • Constructor Details

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(OrderType ordering)

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(int initialCapacity, float loadFactor, OrderType ordering)

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(int initialCapacity, OrderType ordering)

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(Iterator<? extends CharSequence> coll, OrderType ordering)
      Creates a new instance containing the items in the specified iterator.
      Parameters:
      coll - an iterator that will have its remaining contents added to this
      ordering -

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(ObjectOrderedSet<? extends CharSequence> set, OrderType ordering)

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(ObjectSet<? extends CharSequence> set, OrderType ordering)
      Creates a new set that contains all distinct elements in set.
      Parameters:
      set -
      ordering -

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(Collection<? extends CharSequence> coll, OrderType ordering)
      Creates a new set that contains all distinct elements in coll.
      Parameters:
      coll -
      ordering -

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(CharSequence[] array, int offset, int length, OrderType ordering)
      Creates a new set using length items from the given array, starting at offset (inclusive).
      Parameters:
      array - an array to draw items from
      offset - the first index in array to draw an item from
      length - how many items to take from array; bounds-checking is the responsibility of the using code
      ordering -

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(CharSequence[] items, OrderType ordering)
      Creates a new set that contains all distinct elements in items.
      Parameters:
      items - an array that will be used in full, except for duplicate items
      ordering -

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(Ordered<CharSequence> other, int offset, int count, OrderType ordering)
      Creates a new set by copying count items from the given Ordered, starting at offset in that Ordered, into this.
      Parameters:
      other - another Ordered of the same type
      offset - the first index in other's ordering to draw an item from
      count - how many items to copy from other
      ordering -

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet()
      Creates a new set with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor().

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(int initialCapacity)
      Creates a new set with the specified initial capacity a load factor of Utilities.getDefaultLoadFactor(). This set will hold initialCapacity items before growing the backing table.
      Parameters:
      initialCapacity - If not a power of two, it is increased to the next nearest power of two.

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(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:
      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

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(Iterator<? extends CharSequence> 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

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(ObjectSet<? extends CharSequence> set)
      Creates a new set identical to the specified set.
      Parameters:
      set - an ObjectSet or one of its subclasses

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(Collection<? extends CharSequence> coll)
      Creates a new set that contains all distinct elements in coll.
      Parameters:
      coll - a Collection implementation, such as an ObjectList

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(CharSequence[] array, int offset, int length)
      Creates a new set using length items from the given array, starting at offset (inclusive).
      Parameters:
      array - an array to draw items from
      offset - the first index in array to draw an item from
      length - how many items to take from array; bounds-checking is the responsibility of the using code

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(CharSequence[] array)
      Creates a new set containing all the items in the given array.
      Parameters:
      array - an array that will be used in full, except for duplicate items

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(CaseInsensitiveOrderedSet set)
      Creates a new set that contains all distinct elements in set.
      Parameters:
      set - another CaseInsensitiveOrderedSet

    • CaseInsensitiveOrderedSet

      public CaseInsensitiveOrderedSet(Ordered<CharSequence> other, int offset, int count)
      Creates a new set by copying count items from the given Ordered, starting at offset in that Ordered, into this.
      Parameters:
      other - another Ordered of CharSequence
      offset - the first index in other's ordering to draw an item from
      count - how many items to copy from other

  • Method Details

    • place

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

    • 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.
      Overrides:
      getHashMultiplier in class ObjectSet<CharSequence>
      Returns:
      any int; the value isn't used internally, but may be used by subclasses to identify something

    • 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.
      Overrides:
      setHashMultiplier in class ObjectSet<CharSequence>
      Parameters:
      hashMultiplier - any int; will be made odd if even.

    • equate

      protected boolean equate(Object left, Object right)
      Description copied from class: ObjectSet
      Compares the objects left and right, which are usually keys, 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, ObjectSet.place(Object) is also overridden if this method is.
      Overrides:
      equate in class ObjectSet<CharSequence>
      Parameters:
      left - must be non-null; typically a key being compared, but not necessarily
      right - may be null; typically a 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

    • hashCode

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

    • equals

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

    • resize

      protected void resize(int newSize)
      Overrides:
      resize in class ObjectSet<CharSequence>

    • with

      public static CaseInsensitiveOrderedSet with()
      Constructs an empty set. 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.
      Returns:
      a new set containing nothing

    • with

      public static CaseInsensitiveOrderedSet with(CharSequence item)
      Creates a new CaseInsensitiveOrderedSet that holds only the given item, but can be resized.
      Parameters:
      item - one CharSequence item
      Returns:
      a new CaseInsensitiveOrderedSet that holds the given item

    • with

      public static CaseInsensitiveOrderedSet with(CharSequence item0, CharSequence item1)
      Creates a new CaseInsensitiveOrderedSet that holds only the given items, but can be resized.
      Parameters:
      item0 - a CharSequence item
      item1 - a CharSequence item
      Returns:
      a new CaseInsensitiveOrderedSet that holds the given items

    • with

      public static CaseInsensitiveOrderedSet with(CharSequence item0, CharSequence item1, CharSequence item2)
      Creates a new CaseInsensitiveOrderedSet that holds only the given items, but can be resized.
      Parameters:
      item0 - a CharSequence item
      item1 - a CharSequence item
      item2 - a CharSequence item
      Returns:
      a new CaseInsensitiveOrderedSet that holds the given items

    • with

      public static CaseInsensitiveOrderedSet with(CharSequence item0, CharSequence item1, CharSequence item2, CharSequence item3)
      Creates a new CaseInsensitiveOrderedSet that holds only the given items, but can be resized.
      Parameters:
      item0 - a CharSequence item
      item1 - a CharSequence item
      item2 - a CharSequence item
      item3 - a CharSequence item
      Returns:
      a new CaseInsensitiveOrderedSet that holds the given items

    • with

      public static CaseInsensitiveOrderedSet with(CharSequence item0, CharSequence item1, CharSequence item2, CharSequence item3, CharSequence item4)
      Creates a new CaseInsensitiveOrderedSet that holds only the given items, but can be resized.
      Parameters:
      item0 - a CharSequence item
      item1 - a CharSequence item
      item2 - a CharSequence item
      item3 - a CharSequence item
      item4 - a CharSequence item
      Returns:
      a new CaseInsensitiveOrderedSet that holds the given items

    • with

      public static CaseInsensitiveOrderedSet with(CharSequence item0, CharSequence item1, CharSequence item2, CharSequence item3, CharSequence item4, CharSequence item5)
      Creates a new CaseInsensitiveOrderedSet that holds only the given items, but can be resized.
      Parameters:
      item0 - a CharSequence item
      item1 - a CharSequence item
      item2 - a CharSequence item
      item3 - a CharSequence item
      item4 - a CharSequence item
      item5 - a CharSequence item
      Returns:
      a new CaseInsensitiveOrderedSet that holds the given items

    • with

      public static CaseInsensitiveOrderedSet with(CharSequence item0, CharSequence item1, CharSequence item2, CharSequence item3, CharSequence item4, CharSequence item5, CharSequence item6)
      Creates a new CaseInsensitiveOrderedSet that holds only the given items, but can be resized.
      Parameters:
      item0 - a CharSequence item
      item1 - a CharSequence item
      item2 - a CharSequence item
      item3 - a CharSequence item
      item4 - a CharSequence item
      item5 - a CharSequence item
      item6 - a CharSequence item
      Returns:
      a new CaseInsensitiveOrderedSet that holds the given items

    • with

      public static CaseInsensitiveOrderedSet with(CharSequence item0, CharSequence item1, CharSequence item2, CharSequence item3, CharSequence item4, CharSequence item5, CharSequence item6, CharSequence item7)
      Creates a new CaseInsensitiveOrderedSet that holds only the given items, but can be resized.
      Parameters:
      item0 - a CharSequence item
      item1 - a CharSequence item
      item2 - a CharSequence item
      item3 - a CharSequence item
      item4 - a CharSequence item
      item5 - a CharSequence item
      item6 - a CharSequence item
      Returns:
      a new CaseInsensitiveOrderedSet that holds the given items

    • with

      public static CaseInsensitiveOrderedSet with(CharSequence... varargs)
      Creates a new CaseInsensitiveOrderedSet that holds only the given items, but can be resized. This overload will only be used when varargs are used and there are 9 or more arguments.
      Parameters:
      varargs - a CharSequence varargs or CharSequence array; remember that varargs allocate
      Returns:
      a new CaseInsensitiveOrderedSet that holds the given items

    • parse

      public static CaseInsensitiveOrderedSet parse(String str, String delimiter)
      Calls ObjectOrderedSet.parse(String, String, PartialParser, boolean) with brackets set to false.
      Parameters:
      str - a String that will be parsed in full
      delimiter - the delimiter between items in str
      Returns:
      a new collection parsed from str

    • parse

      public static CaseInsensitiveOrderedSet parse(String str, String delimiter, boolean brackets)
      Creates a new collection 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.
      Parameters:
      str - a String that will be parsed in full (depending on brackets)
      delimiter - the delimiter between items in str
      brackets - if true, the first and last chars in str will be ignored
      Returns:
      a new collection parsed from str

    • parse

      public static CaseInsensitiveOrderedSet parse(String str, String delimiter, int offset, int length)
      Creates a new collection and fills it by calling EnhancedCollection.addLegible(String, String, PartialParser, int, int) with the given five parameters as-is.
      Parameters:
      str - a String that will have the given section parsed
      delimiter - the delimiter between items in 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