Class CharFilter

java.lang.Object
com.github.tommyettinger.ds.CharFilter

public class CharFilter extends Object
A small class that holds two functional-interface values used for filtering and editing characters, and a name they are associated with. Every time a CharFilter is constructed, it is registered internally, so it can be looked up at a later time by name, using get(String) or getOrDefault(String, CharFilter). Actually obtaining CharFilter objects is done with getOrCreate(String, CharPredicate, CharToCharFunction), which tries to get an existing CharFilter first, and if it can't find one, then it creates, registers, and returns one. A suggested practice for names is to describe the filter's effects first, if any, followed by the editor's effects. A typical filter might only allow letter chars through, and would convert them to upper-case so that they can (almost always) be treated as case-insensitive. This could use com.github.tommyettinger.ds.support.util.CharPredicates.IS_LETTER (or a method reference to Character.isLetter(char)) for the filter, Casing.caseUp(char) (or Character.toUpperCase(char)) for the editor, and could be named "LetterOnlyCaseInsensitive".
Any CharFilter can be used as a factory to create FilteredStringSet and FilteredStringOrderedSet collections as if using their ObjectSet.with() static method and this CharFilter. These use the makeSet() and makeOrderedSet() methods, which can take 0-8 String parameters without allocating, or any number of String parameters if given an array or varargs.
Any CharFilter can be also used as a factory to create FilteredStringMap and FilteredStringOrderedMap collections as if using their ObjectObjectMap.with() static method and this CharFilter. These use the makeMap() and makeOrderedMap() methods, which can take 0-4 String-V pairs without allocating, or one or more String-V pairs if given an array or varargs.
If you target GWT, be aware that several built-in JDK methods for handling chars may work differently in HTML than on desktop, Android, or other platforms. In particular, Character.isLetter(char) will not work on most Unicode chars on GWT, so you need another way to handle checks like that. com.github.tommyettinger.ds.support.util.CharPredicates.IS_LETTER is a CharPredicate you can use instead of isLetter on any platform, and acts as Character.isLetter(char) does on Java 24, but on all Java versions and target platforms (including GWT). Other fields in CharPredicates may also be useful, and you can create your own CharBitSet objects to serve as predefined predicates that look up a char in an uncompressed bit set.
  • Field Details

    • name

      public final String name
      The unique identifying name for this combination of filter and editor.
    • filter

      public final com.github.tommyettinger.function.CharPredicate filter
      A CharPredicate that should return true iff a character should be considered for equality/hashing.
    • editor

      public final com.github.tommyettinger.function.CharToCharFunction editor
      A CharToCharFunction that will take a char from a key String and return a potentially different char.
  • Constructor Details

    • CharFilter

      protected CharFilter()
    • CharFilter

      protected CharFilter(String name, com.github.tommyettinger.function.CharPredicate filter, com.github.tommyettinger.function.CharToCharFunction editor)
  • Method Details

    • getOrCreate

      public static CharFilter getOrCreate(String name, com.github.tommyettinger.function.CharPredicate filter, com.github.tommyettinger.function.CharToCharFunction editor)
      Tries to get an existing CharFilter known by name, and if one exists, this returns that CharFilter. Otherwise, this will construct and return a new CharFilter with the given name, filter, and editor, registering it in the process.
      Parameters:
      name - the String name to look up, or to register by if none was found
      filter - a CharPredicate that should return true iff a character should be considered for equality/hashing
      editor - a CharToCharFunction that will take a char from a key String and return a potentially different char
      Returns:
      a CharFilter, either one that already exists by the given name, or a newly-registered one that was just created
    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • getName

      public String getName()
    • getFilter

      public com.github.tommyettinger.function.CharPredicate getFilter()
    • getEditor

      public com.github.tommyettinger.function.CharToCharFunction getEditor()
    • contains

      public static boolean contains(String name)
      Checks if a CharFilter is registered to name, returning true if one is, or false otherwise.
      Parameters:
      name - the name to look up
      Returns:
      true if a CharFilter is registered by name, or false otherwise
    • get

      public static CharFilter get(String name)
      Gets the CharFilter registered to name, or null if none exists.
      Parameters:
      name - the name to look up
      Returns:
      a registered CharFilter or null
    • getOrDefault

      public static CharFilter getOrDefault(String name, CharFilter defaultValue)
      Gets the CharFilter registered to name, or defaultValue if none exists.
      Parameters:
      name - the name to look up
      defaultValue - a CharFilter to return if none was found; may be null
      Returns:
      a registered CharFilter or defaultValue
    • makeSet

      public FilteredStringSet makeSet()
      Constructs an empty set using this 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.
      Returns:
      a new set containing nothing
    • makeSet

      public FilteredStringSet makeSet(String item)
      Creates a new FilteredStringSet that holds only the given item, but can be resized. Uses this CharFilter in the new set.
      Parameters:
      item - one String item
      Returns:
      a new FilteredStringSet that holds the given item
    • makeSet

      public FilteredStringSet makeSet(String item0, String item1)
      Creates a new FilteredStringSet that holds only the given items, but can be resized. Uses this CharFilter in the new set.
      Parameters:
      item0 - a String item
      item1 - a String item
      Returns:
      a new FilteredStringSet that holds the given items
    • makeSet

      public FilteredStringSet makeSet(String item0, String item1, String item2)
      Creates a new FilteredStringSet that holds only the given items, but can be resized. Uses this CharFilter in the new set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      Returns:
      a new FilteredStringSet that holds the given items
    • makeSet

      public FilteredStringSet makeSet(String item0, String item1, String item2, String item3)
      Creates a new FilteredStringSet that holds only the given items, but can be resized. Uses this CharFilter in the new set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      item3 - a String item
      Returns:
      a new FilteredStringSet that holds the given items
    • makeSet

      public FilteredStringSet makeSet(String item0, String item1, String item2, String item3, String item4)
      Creates a new FilteredStringSet that holds only the given items, but can be resized. Uses this CharFilter in the new set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      item3 - a String item
      item4 - a String item
      Returns:
      a new FilteredStringSet that holds the given items
    • makeSet

      public FilteredStringSet makeSet(String item0, String item1, String item2, String item3, String item4, String item5)
      Creates a new FilteredStringSet that holds only the given items, but can be resized. Uses this CharFilter in the new set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      item3 - a String item
      item4 - a String item
      item5 - a String item
      Returns:
      a new FilteredStringSet that holds the given items
    • makeSet

      public FilteredStringSet makeSet(String item0, String item1, String item2, String item3, String item4, String item5, String item6)
      Creates a new FilteredStringSet that holds only the given items, but can be resized. Uses this CharFilter in the new set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      item3 - a String item
      item4 - a String item
      item5 - a String item
      item6 - a String item
      Returns:
      a new FilteredStringSet that holds the given items
    • makeSet

      public FilteredStringSet makeSet(String item0, String item1, String item2, String item3, String item4, String item5, String item6, String item7)
      Creates a new FilteredStringSet that holds only the given items, but can be resized. Uses this CharFilter in the new set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      item3 - a String item
      item4 - a String item
      item5 - a String item
      item6 - a String item
      Returns:
      a new FilteredStringSet that holds the given items
    • makeSet

      public FilteredStringSet makeSet(String... varargs)
      Creates a new FilteredStringSet that holds only the given items, but can be resized. Uses this CharFilter in the new set. This overload will only be used when an array is supplied or if varargs are used and there are 9 or more arguments.
      Parameters:
      varargs - a String varargs or String array; remember that varargs allocate
      Returns:
      a new FilteredStringSet that holds the given items
    • makeOrderedSet

      public FilteredStringOrderedSet makeOrderedSet()
      Constructs an empty ordered set using this 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.
      Returns:
      a new ordered set containing nothing
    • makeOrderedSet

      public FilteredStringOrderedSet makeOrderedSet(String item)
      Creates a new FilteredStringOrderedSet that holds only the given item, but can be resized. Uses this CharFilter in the new ordered set.
      Parameters:
      item - one String item
      Returns:
      a new FilteredStringOrderedSet that holds the given item
    • makeOrderedSet

      public FilteredStringOrderedSet makeOrderedSet(String item0, String item1)
      Creates a new FilteredStringOrderedSet that holds only the given items, but can be resized. Uses this CharFilter in the new ordered set.
      Parameters:
      item0 - a String item
      item1 - a String item
      Returns:
      a new FilteredStringOrderedSet that holds the given items
    • makeOrderedSet

      public FilteredStringOrderedSet makeOrderedSet(String item0, String item1, String item2)
      Creates a new FilteredStringOrderedSet that holds only the given items, but can be resized. Uses this CharFilter in the new ordered set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      Returns:
      a new FilteredStringOrderedSet that holds the given items
    • makeOrderedSet

      public FilteredStringOrderedSet makeOrderedSet(String item0, String item1, String item2, String item3)
      Creates a new FilteredStringOrderedSet that holds only the given items, but can be resized. Uses this CharFilter in the new ordered set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      item3 - a String item
      Returns:
      a new FilteredStringOrderedSet that holds the given items
    • makeOrderedSet

      public FilteredStringOrderedSet makeOrderedSet(String item0, String item1, String item2, String item3, String item4)
      Creates a new FilteredStringOrderedSet that holds only the given items, but can be resized. Uses this CharFilter in the new ordered set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      item3 - a String item
      item4 - a String item
      Returns:
      a new FilteredStringOrderedSet that holds the given items
    • makeOrderedSet

      public FilteredStringOrderedSet makeOrderedSet(String item0, String item1, String item2, String item3, String item4, String item5)
      Creates a new FilteredStringOrderedSet that holds only the given items, but can be resized. Uses this CharFilter in the new ordered set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      item3 - a String item
      item4 - a String item
      item5 - a String item
      Returns:
      a new FilteredStringOrderedSet that holds the given items
    • makeOrderedSet

      public FilteredStringOrderedSet makeOrderedSet(String item0, String item1, String item2, String item3, String item4, String item5, String item6)
      Creates a new FilteredStringOrderedSet that holds only the given items, but can be resized. Uses this CharFilter in the new ordered set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      item3 - a String item
      item4 - a String item
      item5 - a String item
      item6 - a String item
      Returns:
      a new FilteredStringOrderedSet that holds the given items
    • makeOrderedSet

      public FilteredStringOrderedSet makeOrderedSet(String item0, String item1, String item2, String item3, String item4, String item5, String item6, String item7)
      Creates a new FilteredStringOrderedSet that holds only the given items, but can be resized. Uses this CharFilter in the new ordered set.
      Parameters:
      item0 - a String item
      item1 - a String item
      item2 - a String item
      item3 - a String item
      item4 - a String item
      item5 - a String item
      item6 - a String item
      Returns:
      a new FilteredStringOrderedSet that holds the given items
    • makeOrderedSet

      public FilteredStringOrderedSet makeOrderedSet(String... varargs)
      Creates a new FilteredStringOrderedSet that holds only the given items, but can be resized. Uses this CharFilter in the new ordered set. This overload will only be used when an array is supplied or if varargs are used and there are 9 or more arguments.
      Parameters:
      varargs - a String varargs or String array; remember that varargs allocate
      Returns:
      a new FilteredStringOrderedSet that holds the given items
    • makeMap

      public <V> FilteredStringMap<V> makeMap()
      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
      Returns:
      a new map containing nothing
    • makeMap

      public <V> FilteredStringMap<V> makeMap(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 makeMap(String, Object, Object...) when there's no "rest" of the keys or values.
      Type Parameters:
      V - the type of value0
      Parameters:
      key0 - the first and only key
      value0 - the first and only value
      Returns:
      a new map containing just the entry mapping key0 to value0
    • makeMap

      public <V> FilteredStringMap<V> makeMap(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 makeMap(String, Object, Object...) when there's no "rest" of the keys or values.
      Type Parameters:
      V - the type of value0
      Parameters:
      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
    • makeMap

      public <V> FilteredStringMap<V> makeMap(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 makeMap(String, Object, Object...) when there's no "rest" of the keys or values.
      Type Parameters:
      V - the type of value0
      Parameters:
      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
    • makeMap

      public <V> FilteredStringMap<V> makeMap(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 makeMap(String, Object, Object...) when there's no "rest" of the keys or values.
      Type Parameters:
      V - the type of value0
      Parameters:
      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
    • makeMap

      public <V> FilteredStringMap<V> makeMap(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 FilteredStringMap(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:
      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
    • makeOrderedMap

      public <V> FilteredStringOrderedMap<V> makeOrderedMap()
      Constructs an empty ordered 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
      Returns:
      a new ordered map containing nothing
    • makeOrderedMap

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

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

      public <V> FilteredStringOrderedMap<V> makeOrderedMap(String key0, V value0, String key1, V value1, String key2, V value2)
      Constructs a single-entry ordered map given a CharFilter and three key-value pairs. This is mostly useful as an optimization for makeOrderedMap(String, Object, Object...) when there's no "rest" of the keys or values.
      Type Parameters:
      V - the type of value0
      Parameters:
      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 ordered map containing entries mapping each key to the following value
    • makeOrderedMap

      public <V> FilteredStringOrderedMap<V> makeOrderedMap(String key0, V value0, String key1, V value1, String key2, V value2, String key3, V value3)
      Constructs a single-entry ordered map given a CharFilter and four key-value pairs. This is mostly useful as an optimization for makeOrderedMap(String, Object, Object...) when there's no "rest" of the keys or values.
      Type Parameters:
      V - the type of value0
      Parameters:
      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 ordered map containing entries mapping each key to the following value
    • makeOrderedMap

      public <V> FilteredStringOrderedMap<V> makeOrderedMap(String key0, V value0, Object... rest)
      Constructs a ordered 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 ordered 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:
      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 ordered map containing the given keys and values