Package com.github.tommyettinger.ds

Class FilteredStringSet

java.lang.Object

com.github.tommyettinger.ds.ObjectSet<String>

com.github.tommyettinger.ds.FilteredStringSet

All Implemented Interfaces:

EnhancedCollection<String>, Iterable<String>, Collection<String>, Set<String>

public class FilteredStringSet
extends ObjectSet<String>

A customizable variant on ObjectSet 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 CaseInsensitiveSet 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). CaseInsensitiveSet 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.

Nested Class Summary

Nested classes/interfaces inherited from class com.github.tommyettinger.ds.ObjectSet

ObjectSet.ObjectSetIterator<T>

Field Summary

Fields

Modifier and Type	Field	Description
protected CharFilter	filter

Fields inherited from class com.github.tommyettinger.ds.ObjectSet

hashMultiplier, iterator1, iterator2, keyTable, loadFactor, mask, shift, size, threshold

Constructor Summary

Constructors

Constructor	Description
FilteredStringSet()	Creates a new set with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor().
FilteredStringSet(int initialCapacity)	Creates a new set with the specified initial capacity a load factor of Utilities.getDefaultLoadFactor().
FilteredStringSet(int initialCapacity, float loadFactor)	Creates a new set with the specified initial capacity and load factor.
FilteredStringSet(CharFilter filter)	Creates a new set with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor().
FilteredStringSet(CharFilter filter, int initialCapacity)	Creates a new set with the specified initial capacity and the default load factor.
FilteredStringSet(CharFilter filter, int initialCapacity, float loadFactor)	Creates a new set with the specified initial capacity and load factor.
FilteredStringSet(CharFilter filter, String[] array)	Creates a new set containing all the items in the given array.
FilteredStringSet(CharFilter filter, String[] array, int offset, int length)	Creates a new set using length items from the given array, starting at offset (inclusive).
FilteredStringSet(CharFilter filter, Collection<? extends String> coll)	Creates a new set that contains all distinct elements in coll.
FilteredStringSet(FilteredStringSet set)	Creates a new set identical to the specified set.

Method Summary

Modifier and Type	Method	Description
boolean	equate(Object left, Object right)	Compares two objects for equality by the rules this filtered data structure uses for keys.
CharFilter	getFilter()
int	hashCode()
protected int	hashHelper(String s)	Gets a low-to-moderate quality 32-bit hash code from the given String.
static FilteredStringSet	parse(CharFilter filter, String str, String delimiter)	Calls ObjectSet.parse(String, String, PartialParser, boolean) with brackets set to false.
static FilteredStringSet	parse(CharFilter filter, String str, String delimiter, boolean brackets)	Creates a new FilteredStringSet using filter 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 FilteredStringSet	parse(CharFilter filter, String str, String delimiter, int offset, int length)	Creates a new FilteredStringSet using filter and fills it by calling EnhancedCollection.addLegible(String, String, PartialParser, int, int), using PartialParser.DEFAULT_STRING and with the other four parameters as-is.
protected int	place(Object item)	Returns an index >= 0 and <= ObjectSet.mask for the specified item, mixed.
FilteredStringSet	setFilter(CharFilter filter)	Sets the CharFilter that determines which characters in a String are considered for equality and hashing, as well as any changes made to characters before hashing or equating, then returns this object, for chaining.
static FilteredStringSet	with(CharFilter filter)	Constructs an empty set given a CharFilter.
static FilteredStringSet	with(CharFilter filter, String item)	Creates a new FilteredStringSet that holds only the given item, but can be resized.
static FilteredStringSet	with(CharFilter filter, String... varargs)	Creates a new FilteredStringSet that holds only the given items, but can be resized.
static FilteredStringSet	with(CharFilter filter, String item0, String item1)	Creates a new FilteredStringSet that holds only the given items, but can be resized.
static FilteredStringSet	with(CharFilter filter, String item0, String item1, String item2)	Creates a new FilteredStringSet that holds only the given items, but can be resized.
static FilteredStringSet	with(CharFilter filter, String item0, String item1, String item2, String item3)	Creates a new FilteredStringSet that holds only the given items, but can be resized.
static FilteredStringSet	with(CharFilter filter, String item0, String item1, String item2, String item3, String item4)	Creates a new FilteredStringSet that holds only the given items, but can be resized.
static FilteredStringSet	with(CharFilter filter, 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.
static FilteredStringSet	with(CharFilter filter, 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.
static FilteredStringSet	with(CharFilter filter, 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.

Methods inherited from class com.github.tommyettinger.ds.ObjectSet

add, addAll, addAll, addAll, addAll, addResize, appendTo, clear, clear, contains, containsAll, containsAll, containsAll, containsAny, containsAny, containsAnyIterable, ensureCapacity, equals, first, get, getHashMultiplier, getLoadFactor, getTableSize, isEmpty, iterator, locateKey, notEmpty, parse, parse, parse, remove, removeAll, removeAll, removeAll, resize, retainAll, setHashMultiplier, setLoadFactor, shrink, size, toArray, toArray, toString, truncate, with, with, with, with, with, with, with, with, with, with

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

filter

protected CharFilter filter

Constructor Details

FilteredStringSet

public FilteredStringSet()

Creates a new set with an initial capacity of Utilities.getDefaultTableCapacity() and a load factor of Utilities.getDefaultLoadFactor(). This considers all characters in a String key and does not edit them.

FilteredStringSet

public FilteredStringSet(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. This considers all characters in a String key and does not edit them.

Parameters:

initialCapacity - If not a power of two, it is increased to the next nearest power of two.

FilteredStringSet

public FilteredStringSet(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. This considers all characters in a String key and does not edit them.

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

FilteredStringSet

public FilteredStringSet(CharFilter filter)

Creates a new set 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)

FilteredStringSet

public FilteredStringSet(CharFilter filter,
 int initialCapacity)

Creates a new set with the specified initial capacity and the default load factor. This set 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.

FilteredStringSet

public FilteredStringSet(CharFilter filter,
 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. 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

FilteredStringSet

public FilteredStringSet(FilteredStringSet set)

Creates a new set identical to the specified set.

Parameters:

set - another FilteredStringSet to copy

FilteredStringSet

public FilteredStringSet(CharFilter filter,
 Collection<? extends String> coll)

Creates a new set that contains all distinct elements in coll. This uses the specified CharFilter, including while it enters the items in coll.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

coll - a Collection implementation to copy, such as an ObjectList or a Set that isn't a FilteredStringSet

FilteredStringSet

public FilteredStringSet(CharFilter filter,
 String[] array,
 int offset,
 int length)

Creates a new set using length items from the given array, starting at offset (inclusive). This uses the specified CharFilter, including while it enters the items in array.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

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

FilteredStringSet

public FilteredStringSet(CharFilter filter,
 String[] array)

Creates a new set containing all the items in the given array. This uses the specified CharFilter, including while it enters the items in array.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

array - an array that will be used in full, except for duplicate items

Method Details

getFilter

public CharFilter getFilter()

setFilter

public FilteredStringSet setFilter(CharFilter filter)

Sets the CharFilter that determines which characters in a String are considered for equality and hashing, as well as any changes made to characters before hashing or equating, then returns this object, for chaining. 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 CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

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: ObjectSet

Returns an index >= 0 and <= ObjectSet.mask for the specified item, mixed.

Overrides:

place in class ObjectSet<String>

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)

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 ObjectSet<String>

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 Collection<String>

Specified by:

hashCode in interface Set<String>

Overrides:

hashCode in class ObjectSet<String>

with

public static FilteredStringSet with(CharFilter filter)

Constructs an empty set given 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.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

Returns:

a new set containing nothing

with

public static FilteredStringSet with(CharFilter filter,
 String item)

Creates a new FilteredStringSet that holds only the given item, but can be resized.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

item - one String item

Returns:

a new FilteredStringSet that holds the given item

with

public static FilteredStringSet with(CharFilter filter,
 String item0,
 String item1)

Creates a new FilteredStringSet that holds only the given items, but can be resized.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

item0 - a String item

item1 - a String item

Returns:

a new FilteredStringSet that holds the given items

with

public static FilteredStringSet with(CharFilter filter,
 String item0,
 String item1,
 String item2)

Creates a new FilteredStringSet that holds only the given items, but can be resized.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

item0 - a String item

item1 - a String item

item2 - a String item

Returns:

a new FilteredStringSet that holds the given items

with

public static FilteredStringSet with(CharFilter filter,
 String item0,
 String item1,
 String item2,
 String item3)

Creates a new FilteredStringSet that holds only the given items, but can be resized.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

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

with

public static FilteredStringSet with(CharFilter filter,
 String item0,
 String item1,
 String item2,
 String item3,
 String item4)

Creates a new FilteredStringSet that holds only the given items, but can be resized.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

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

with

public static FilteredStringSet with(CharFilter filter,
 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.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

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

with

public static FilteredStringSet with(CharFilter filter,
 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.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

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

with

public static FilteredStringSet with(CharFilter filter,
 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.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

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

with

public static FilteredStringSet with(CharFilter filter,
 String... varargs)

Creates a new FilteredStringSet that holds only the given items, but can be resized. This overload will only be used when an array is supplied or if varargs are used and there are 9 or more arguments.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

varargs - a String varargs or String array; remember that varargs allocate

Returns:

a new FilteredStringSet that holds the given items

parse

public static FilteredStringSet parse(CharFilter filter,
 String str,
 String delimiter)

Calls ObjectSet.parse(String, String, PartialParser, boolean) with brackets set to false.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

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 FilteredStringSet parse(CharFilter filter,
 String str,
 String delimiter,
 boolean brackets)

Creates a new FilteredStringSet using filter 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:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

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 FilteredStringSet parse(CharFilter filter,
 String str,
 String delimiter,
 int offset,
 int length)

Creates a new FilteredStringSet using filter and fills it by calling EnhancedCollection.addLegible(String, String, PartialParser, int, int), using PartialParser.DEFAULT_STRING and with the other four parameters as-is.

Parameters:

filter - a CharFilter that can be obtained with CharFilter.getOrCreate(String, CharPredicate, CharToCharFunction)

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