Package com.github.tommyettinger.ds

Class FilteredStringOrderedMap<V>

java.lang.Object
com.github.tommyettinger.ds.ObjectObjectMap<K,V>
com.github.tommyettinger.ds.ObjectObjectOrderedMap<String,V>
com.github.tommyettinger.ds.FilteredStringOrderedMap<V>
All Implemented Interfaces:
Arrangeable, Ordered<String>, Iterable<Map.Entry<String,V>>, Map<String,V>
public class FilteredStringOrderedMap<V> extends ObjectObjectOrderedMap<String,V>
A custom variant on ObjectObjectOrderedMap that always uses String keys, but only considers any character in an item (for equality and hashing purposes) if that character satisfies a predicate. This can also edit the characters that pass the filter, such as by changing their case during comparisons (and hashing). You will usually want to call setFilter(CharFilter) to change the behavior of hashing and equality before you enter any items, unless you have specified the CharFilter you want in the constructor.
You can use this class as a replacement for CaseInsensitiveMap if you set the editor to a method reference to Character.toUpperCase(char) or Casing.caseUp(char). You can go further by setting the filter to make the hashing and equality checks ignore characters that don't satisfy a predicate, such as Character.isLetter(char). CaseInsensitiveOrderedMap does allow taking arbitrary CharSequence types as keys, but it doesn't permit modifying them, so usually Strings are a good choice anyway.
Be advised that if you use some (most) checks in Character for properties of a char, and you try to use them on GWT, those checks will not work as expected for non-ASCII characters. Some other platforms might also be affected, such as TeaVM, but it isn't clear yet which platforms have full Unicode support. You can consider depending upon RegExodus for more cross-platform Unicode support; a method reference to Category.L::contains acts like Character::isLetter, but works on GWT. com.github.tommyettinger.ds.support.util.CharPredicates provides a few common CharPredicate constants that will work identically on all platforms.
This is very similar to FilteredStringMap, except that this class maintains insertion order and can be sorted with ObjectObjectOrderedMap.sort(), ObjectObjectOrderedMap.sort(Comparator), etc. Note that because each String is stored in here in its original form (not modified to make it use the CharFilter), the sorted order might be different than you expect. You can use FilteredComparators.makeStringComparator(CharPredicate, CharToCharFunction) to create a Comparator for Strings that uses the same rules this class does.

  • Field Details

  • Constructor Details

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(OrderType type)
      Creates a new map with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor().
      Parameters:
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(int initialCapacity, OrderType type)
      Creates a new map with the specified initial capacity and a load factor of Utilities.getDefaultLoadFactor(). This map 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.
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(int initialCapacity, float loadFactor, OrderType type)
      Creates a new map with the specified initial capacity and load factor. This map 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
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, OrderType type)
      Creates a new map with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor(). This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, int initialCapacity, OrderType type)
      Creates a new map with the specified initial capacity and th default load factor. This map will hold initialCapacity items before growing the backing table. This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      initialCapacity - If not a power of two, it is increased to the next nearest power of two.
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, int initialCapacity, float loadFactor, OrderType type)
      Creates a new map with the specified initial capacity and load factor. This map will hold initialCapacity items before growing the backing table. This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      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
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(FilteredStringOrderedMap<? extends V> map, OrderType type)
      Creates a new map identical to the specified map.
      Parameters:
      map - an FilteredStringOrderedMap to copy
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, Map<String,? extends V> map, OrderType type)
      Creates a new map identical to the specified map. This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      map - a Map to copy; ObjectObjectOrderedMap and subclasses of it will be faster to load from
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, String[] keys, V[] values, OrderType type)
      Given two side-by-side arrays, one of keys, one of values, this constructs a map and inserts each pair of key and value into it. If keys and values have different lengths, this only uses the length of the smaller array. This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      keys - an array of keys
      values - an array of values
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, Collection<String> keys, Collection<? extends V> values, OrderType type)
      Given two side-by-side collections, one of keys, one of values, this constructs a map and inserts each pair of key and value into it. If keys and values have different lengths, this only uses the length of the smaller collection. This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      keys - a Collection of keys
      values - a Collection of values
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, ObjectObjectOrderedMap<String,? extends V> other, int offset, int count, OrderType type)
      Creates a new set by copying count items from the given ObjectObjectOrderedMap (or a subclass, such as CaseInsensitiveOrderedMap), starting at offset in that Map, into this.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      other - another ObjectObjectOrderedMap of the same types (key must be String)
      offset - the first index in other's ordering to draw an item from
      count - how many items to copy from other
      type - either OrderType.BAG to use unreliable ordering with faster deletion, or anything else to use a list type that takes longer to delete but maintains insertion order reliably

    • FilteredStringOrderedMap

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

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(int initialCapacity)
      Creates a new map with the specified initial capacity and a load factor of Utilities.getDefaultLoadFactor(). This map 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.

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(int initialCapacity, float loadFactor)
      Creates a new map with the specified initial capacity and load factor. This map 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

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter)
      Creates a new map with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor(). This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, int initialCapacity)
      Creates a new map with the specified initial capacity and th default load factor. This map will hold initialCapacity items before growing the backing table. This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      initialCapacity - If not a power of two, it is increased to the next nearest power of two.

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, int initialCapacity, float loadFactor)
      Creates a new map with the specified initial capacity and load factor. This map will hold initialCapacity items before growing the backing table. This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      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

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(FilteredStringOrderedMap<? extends V> map)
      Creates a new map identical to the specified map.
      Parameters:
      map - an FilteredStringOrderedMap to copy

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, Map<String,? extends V> map)
      Creates a new map identical to the specified map. This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      map - a Map to copy; ObjectObjectOrderedMap and subclasses of it will be faster to load from

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, String[] keys, V[] values)
      Given two side-by-side arrays, one of keys, one of values, this constructs a map and inserts each pair of key and value into it. If keys and values have different lengths, this only uses the length of the smaller array. This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      keys - an array of keys
      values - an array of values

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, Collection<String> keys, Collection<? extends V> values)
      Given two side-by-side collections, one of keys, one of values, this constructs a map and inserts each pair of key and value into it. If keys and values have different lengths, this only uses the length of the smaller collection. This uses the specified CharFilter.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      keys - a Collection of keys
      values - a Collection of values

    • FilteredStringOrderedMap

      public FilteredStringOrderedMap(CharFilter filter, ObjectObjectOrderedMap<String,? extends V> other, int offset, int count)
      Creates a new set by copying count items from the given ObjectObjectOrderedMap (or a subclass, such as CaseInsensitiveOrderedMap), starting at offset in that Map, into this.
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      other - another ObjectObjectOrderedMap of the same types (key must be String)
      offset - the first index in other's ordering to draw an item from
      count - how many items to copy from other

  • Method Details

    • getFilter

      public CharFilter getFilter()

    • setFilter

      public FilteredStringOrderedMap<V> setFilter(CharFilter filter)
      Sets the filter that determines which characters in a String are considered for equality and hashing, then returns this object, for chaining. Common CharPredicate filters you might use could be method references to Character.isLetter(char) or CharList.contains(char), for example. If the filter returns true for a given character, that character will be used for hashing/equality; otherwise it will be ignored. The default filter always returns true. If the filter changes, that invalidates anything previously entered into this, so before changing the filter this clears the entire data structure, removing all existing items.
      Parameters:
      filter - a CharPredicate that should return true iff a character should be considered for equality/hashing
      Returns:
      this, for chaining

    • hashHelper

      protected int hashHelper(String s)
      Gets a low-to-moderate quality 32-bit hash code from the given String. This operates by checking if a char in s matches the filter, and if it does, it rotates the current hash, multiplies it by the hash multiplier, and XORs with the current char after editing. This finalizes the hash by multiplying it again by the hash multiplier, then using the reversible XOR-rotate-XOR-rotate sequence of operations to adequately jumble the bits.
      Parameters:
      s - a String to hash
      Returns:
      a 32-bit hash of s

    • place

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

    • equate

      public boolean equate(Object left, Object right)
      Compares two objects for equality by the rules this filtered data structure uses for keys. This will return true if the arguments are reference-equivalent or both null. Otherwise, it requires that both are Strings and compares them using the filter of this object.
      Overrides:
      equate in class ObjectObjectMap<String,V>
      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 equivalent according to the rules this filtered type uses

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface Map<String,V>
      Overrides:
      hashCode in class ObjectObjectMap<String,V>

    • equals

      public boolean equals(Object obj)
      Specified by:
      equals in interface Map<String,V>
      Overrides:
      equals in class ObjectObjectMap<String,V>

    • with

      public static <V> FilteredStringOrderedMap<V> with(CharFilter filter)
      Constructs an empty map given just a CharFilter. 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:
      V - the type of values
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      Returns:
      a new map containing nothing

    • with

      public static <V> FilteredStringOrderedMap<V> with(CharFilter filter, String key0, V value0)
      Constructs a single-entry map given a CharFilter, one key and one value. This is mostly useful as an optimization for ObjectObjectOrderedMap.with(Object, Object, Object...) when there's no "rest" of the keys or values.
      Type Parameters:
      V - the type of value0
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      key0 - the first and only key
      value0 - the first and only value
      Returns:
      a new map containing just the entry mapping key0 to value0

    • with

      public static <V> FilteredStringOrderedMap<V> with(CharFilter filter, String key0, V value0, String key1, V value1)
      Constructs a single-entry map given a CharFilter and two key-value pairs. This is mostly useful as an optimization for ObjectObjectOrderedMap.with(Object, Object, Object...) when there's no "rest" of the keys or values.
      Type Parameters:
      V - the type of value0
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      key0 - a String key
      value0 - a V value
      key1 - a String key
      value1 - a V value
      Returns:
      a new map containing entries mapping each key to the following value

    • with

      public static <V> FilteredStringOrderedMap<V> with(CharFilter filter, String key0, V value0, String key1, V value1, String key2, V value2)
      Constructs a single-entry map given a CharFilter and three key-value pairs. This is mostly useful as an optimization for ObjectObjectOrderedMap.with(Object, Object, Object...) when there's no "rest" of the keys or values.
      Type Parameters:
      V - the type of value0
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      key0 - a String key
      value0 - a V value
      key1 - a String key
      value1 - a V value
      key2 - a String key
      value2 - a V value
      Returns:
      a new map containing entries mapping each key to the following value

    • with

      public static <V> FilteredStringOrderedMap<V> with(CharFilter filter, String key0, V value0, String key1, V value1, String key2, V value2, String key3, V value3)
      Constructs a single-entry map given a CharFilter and four key-value pairs. This is mostly useful as an optimization for ObjectObjectOrderedMap.with(Object, Object, Object...) when there's no "rest" of the keys or values.
      Type Parameters:
      V - the type of value0
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      key0 - a String key
      value0 - a V value
      key1 - a String key
      value1 - a V value
      key2 - a String key
      value2 - a V value
      key3 - a String key
      value3 - a V value
      Returns:
      a new map containing entries mapping each key to the following value

    • with

      public static <V> FilteredStringOrderedMap<V> with(CharFilter filter, String key0, V value0, Object... rest)
      Constructs a map given a CharFilter, then alternating keys and values. This can be useful in some code-generation scenarios, or when you want to make a map conveniently by-hand and have it populated at the start. You can also use FilteredStringOrderedMap(CharFilter, String[], Object[]), which takes all keys and then all values. This needs all keys to have the same type and all values to have the same type, because it gets those types from the first key parameter and first value parameter. Any keys that don't have String as their type or values that don't have V as their type have that entry skipped.
      Type Parameters:
      V - the type of values, inferred from value0
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      key0 - the first key; will be used to determine the type of all keys
      value0 - the first value; will be used to determine the type of all values
      rest - an array or varargs of alternating String, V, String, V... elements
      Returns:
      a new map containing the given keys and values

    • parse

      public static <V> FilteredStringOrderedMap<V> parse(CharFilter filter, String str, String entrySeparator, String keyValueSeparator, PartialParser<V> valueParser)
      Creates a new map by parsing all of str with the given PartialParser for values, with entries separated by entrySeparator, such as ", " and the keys separated from values by keyValueSeparator, such as "=".
      Various PartialParser instances are defined as constants, such as PartialParser.DEFAULT_STRING, and others can be created by static methods in PartialParser, such as PartialParser.objectListParser(PartialParser, String, boolean).
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      str - a String containing parseable text
      entrySeparator - the String separating every key-value pair
      keyValueSeparator - the String separating every key from its corresponding value
      valueParser - a PartialParser that returns a V value from a section of str

    • parse

      public static <V> FilteredStringOrderedMap<V> parse(CharFilter filter, String str, String entrySeparator, String keyValueSeparator, PartialParser<V> valueParser, boolean brackets)
      Creates a new map by parsing all of str (or if brackets is true, all but the first and last chars) with the given PartialParser for values, with entries separated by entrySeparator, such as ", " and the keys separated from values by keyValueSeparator, such as "=".
      Various PartialParser instances are defined as constants, such as PartialParser.DEFAULT_STRING, and others can be created by static methods in PartialParser, such as PartialParser.objectListParser(PartialParser, String, boolean).
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      str - a String containing parseable text
      entrySeparator - the String separating every key-value pair
      keyValueSeparator - the String separating every key from its corresponding value
      valueParser - a PartialParser that returns a V value from a section of str
      brackets - if true, the first and last chars in str will be ignored

    • parse

      public static <V> FilteredStringOrderedMap<V> parse(CharFilter filter, String str, String entrySeparator, String keyValueSeparator, PartialParser<V> valueParser, int offset, int length)
      Creates a new map by parsing the given subrange of str with the given PartialParser for values, with entries separated by entrySeparator, such as ", " and the keys separated from values by keyValueSeparator, such as "=".
      Various PartialParser instances are defined as constants, such as PartialParser.DEFAULT_STRING, and others can be created by static methods in PartialParser, such as PartialParser.objectListParser(PartialParser, String, boolean).
      Parameters:
      filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)
      str - a String containing parseable text
      entrySeparator - the String separating every key-value pair
      keyValueSeparator - the String separating every key from its corresponding value
      valueParser - a PartialParser that returns a V value from a section of str
      offset - the first position to read parseable text from in str
      length - how many chars to read; -1 is treated as maximum length