Package com.cedarsoftware.util

Class CaseInsensitiveSet<E>

java.lang.Object
com.cedarsoftware.util.CaseInsensitiveSet<E>
Type Parameters:
E - the type of elements maintained by this set
All Implemented Interfaces:
Iterable<E>, Collection<E>, Set<E>
public class CaseInsensitiveSet<E> extends Object implements Set<E>
A Set implementation that performs case-insensitive comparisons for String elements, while preserving the original case of the strings. This set can contain both String and non-String elements, providing support for homogeneous and heterogeneous collections.

Key Features

  • Case-Insensitive String Handling: For String elements, comparisons are performed in a case-insensitive manner, but the original case is preserved when iterating or retrieving elements.
  • Homogeneous and Heterogeneous Collections: Supports mixed types within the set, treating non-String elements as in a normal Set.
  • Customizable Backing Map: Allows specifying the underlying Map implementation, providing flexibility for use cases requiring custom performance or ordering guarantees.
  • Compatibility with Java Collections Framework: Fully implements the Set interface, supporting standard operations like add(), remove(), and retainAll().

Usage Examples


 // Create a case-insensitive set
 CaseInsensitiveSet<String> set = new CaseInsensitiveSet<>();
 set.add("Hello");
 set.add("HELLO"); // No effect, as "Hello" already exists
 LOG.info(set); // Outputs: [Hello]

 // Mixed types in the set
 CaseInsensitiveSet<Object> mixedSet = new CaseInsensitiveSet<>();
 mixedSet.add("Apple");
 mixedSet.add(123);
 mixedSet.add("apple"); // No effect, as "Apple" already exists
 LOG.info(mixedSet); // Outputs: [Apple, 123]

Backing Map Selection

The backing map for this set can be customized using various constructors:

  • The default constructor uses a CaseInsensitiveMap with a LinkedHashMap backing to preserve insertion order.
  • Other constructors allow specifying the backing map explicitly or initializing the set from another collection.

Deprecated Methods

The following methods are deprecated and retained for backward compatibility:

Additional Notes

  • String comparisons are case-insensitive but preserve original case for iteration and output.
  • Thread safety depends on the thread safety of the chosen backing map.
  • Set operations like contains(), add(), and remove() rely on the behavior of the underlying CaseInsensitiveMap.
Author:
John DeRegnaucourt ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

License

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
See Also:

  • Constructor Details

    • CaseInsensitiveSet

      public CaseInsensitiveSet()
      Constructs an empty CaseInsensitiveSet backed by a CaseInsensitiveMap with a default LinkedHashMap implementation.

      This constructor is useful for creating a case-insensitive set with predictable iteration order and default configuration.

    • CaseInsensitiveSet

      public CaseInsensitiveSet(Collection<? extends E> collection)
      Constructs a CaseInsensitiveSet containing the elements of the specified collection.

      The backing map is chosen based on the type of the input collection:

      • If the input collection is a ConcurrentNavigableSetNullSafe, the backing map is a ConcurrentNavigableMapNullSafe.
      • If the input collection is a ConcurrentSkipListSet, the backing map is a ConcurrentSkipListMap.
      • If the input collection is a ConcurrentSet, the backing map is a ConcurrentHashMapNullSafe.
      • If the input collection is a SortedSet, the backing map is a TreeMap.
      • For all other collection types, the backing map is a LinkedHashMap with an initial capacity based on the size of the input collection.

      Parameters:
      collection - the collection whose elements are to be placed into this set
      Throws:
      NullPointerException - if the specified collection is null

    • CaseInsensitiveSet

      public CaseInsensitiveSet(Collection<? extends E> source, Map backingMap)
      Constructs a CaseInsensitiveSet containing the elements of the specified collection, using the provided map as the backing implementation.

      This constructor allows full control over the underlying map implementation, enabling custom behavior for the set.

      Parameters:
      source - the collection whose elements are to be placed into this set
      backingMap - the map to be used as the backing implementation
      Throws:
      NullPointerException - if the specified collection or map is null

    • CaseInsensitiveSet

      public CaseInsensitiveSet(int initialCapacity)
      Constructs an empty CaseInsensitiveSet with the specified initial capacity.

      This constructor is useful for creating a set with a predefined capacity to reduce resizing overhead during population.

      Parameters:
      initialCapacity - the initial capacity of the backing map
      Throws:
      IllegalArgumentException - if the specified initial capacity is negative

    • CaseInsensitiveSet

      public CaseInsensitiveSet(int initialCapacity, float loadFactor)
      Constructs an empty CaseInsensitiveSet with the specified initial capacity and load factor.

      This constructor allows fine-grained control over the performance characteristics of the backing map.

      Parameters:
      initialCapacity - the initial capacity of the backing map
      loadFactor - the load factor of the backing map, which determines when resizing occurs
      Throws:
      IllegalArgumentException - if the specified initial capacity is negative or if the load factor is non-positive

  • Method Details

    • hashCode

      public int hashCode()

      For String elements, the hash code computation is case-insensitive, as it relies on the case-insensitive hash codes provided by the underlying CaseInsensitiveMap.

      Specified by:
      hashCode in interface Collection<E>
      Specified by:
      hashCode in interface Set<E>
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object other)

      For String elements, equality is determined in a case-insensitive manner, ensuring that two sets containing equivalent strings with different cases (e.g., "Hello" and "hello") are considered equal.

      Specified by:
      equals in interface Collection<E>
      Specified by:
      equals in interface Set<E>
      Overrides:
      equals in class Object
      Parameters:
      other - the object to be compared for equality with this set
      Returns:
      true if the specified object is equal to this set
      See Also:

    • size

      public int size()

      Returns the number of elements in this set. For String elements, the count is determined in a case-insensitive manner, ensuring that equivalent strings with different cases (e.g., "Hello" and "hello") are counted as a single element.

      Specified by:
      size in interface Collection<E>
      Specified by:
      size in interface Set<E>
      Returns:
      the number of elements in this set

    • isEmpty

      public boolean isEmpty()

      Returns true if this set contains no elements. For String elements, the check is performed in a case-insensitive manner, ensuring that equivalent strings with different cases are treated as a single element.

      Specified by:
      isEmpty in interface Collection<E>
      Specified by:
      isEmpty in interface Set<E>
      Returns:
      true if this set contains no elements, false otherwise

    • contains

      public boolean contains(Object o)

      Returns true if this set contains the specified element. For String elements, the check is performed in a case-insensitive manner, meaning that strings differing only by case (e.g., "Hello" and "hello") are considered equal.

      Specified by:
      contains in interface Collection<E>
      Specified by:
      contains in interface Set<E>
      Parameters:
      o - the element whose presence in this set is to be tested
      Returns:
      true if this set contains the specified element, false otherwise

    • iterator

      public Iterator<E> iterator()

      Returns an iterator over the elements in this set. For String elements, the iterator preserves the original case of the strings, even though the set performs case-insensitive comparisons.

      When the backing map is a ConcurrentHashMap, the returned iterator is weakly consistent and will not throw ConcurrentModificationException. The iterator may reflect updates made during traversal, but is not required to do so.

      Specified by:
      iterator in interface Collection<E>
      Specified by:
      iterator in interface Iterable<E>
      Specified by:
      iterator in interface Set<E>
      Returns:
      an iterator over the elements in this set

    • toArray

      public Object[] toArray()

      Returns an array containing all the elements in this set. For String elements, the array preserves the original case of the strings, even though the set performs case-insensitive comparisons.

      Specified by:
      toArray in interface Collection<E>
      Specified by:
      toArray in interface Set<E>
      Returns:
      an array containing all the elements in this set

    • toArray

      public <T> T[] toArray(T[] a)

      Returns an array containing all the elements in this set. The runtime type of the returned array is that of the specified array. For String elements, the array preserves the original case of the strings, even though the set performs case-insensitive comparisons.

      Specified by:
      toArray in interface Collection<E>
      Specified by:
      toArray in interface Set<E>
      Parameters:
      a - the array into which the elements of the 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
      Throws:
      ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this set
      NullPointerException - if the specified array is null

    • add

      public boolean add(E e)

      Adds the specified element to this set if it is not already present. For String elements, the addition is case-insensitive, meaning that strings differing only by case (e.g., "Hello" and "hello") are considered equal, and only one instance is added to the set.

      Specified by:
      add in interface Collection<E>
      Specified by:
      add in interface Set<E>
      Parameters:
      e - the element to be added to this set
      Returns:
      true if this set did not already contain the specified element

    • remove

      public boolean remove(Object o)

      Removes the specified element from this set if it is present. For String elements, the removal is case-insensitive, meaning that strings differing only by case (e.g., "Hello" and "hello") are treated as equal, and removing any of them will remove the corresponding entry from the set.

      Specified by:
      remove in interface Collection<E>
      Specified by:
      remove in interface Set<E>
      Parameters:
      o - the object to be removed from this set, if present
      Returns:
      true if this set contained the specified element

    • containsAll

      public boolean containsAll(Collection<?> c)

      Returns true if this set contains all of the elements in the specified collection. For String elements, the comparison is case-insensitive, meaning that strings differing only by case (e.g., "Hello" and "hello") are treated as equal.

      Specified by:
      containsAll in interface Collection<E>
      Specified by:
      containsAll in interface Set<E>
      Parameters:
      c - the collection to be checked for containment in this set
      Returns:
      true if this set contains all of the elements in the specified collection
      Throws:
      NullPointerException - if the specified collection is null

    • addAll

      public boolean addAll(Collection<? extends E> c)

      Adds all the elements in the specified collection to this set if they're not already present. For String elements, the addition is case-insensitive, meaning that strings differing only by case (e.g., "Hello" and "hello") are treated as equal, and only one instance is added to the set.

      Specified by:
      addAll in interface Collection<E>
      Specified by:
      addAll in interface Set<E>
      Parameters:
      c - the collection containing elements to be added to this set
      Returns:
      true if this set changed as a result of the call
      Throws:
      NullPointerException - if the specified collection is null or contains null elements

    • retainAll

      public boolean retainAll(Collection<?> c)

      Retains only the elements in this set that are contained in the specified collection. For String elements, the comparison is case-insensitive, meaning that strings differing only by case (e.g., "Hello" and "hello") are treated as equal.

      Specified by:
      retainAll in interface Collection<E>
      Specified by:
      retainAll in interface Set<E>
      Parameters:
      c - the collection containing elements to be retained in this set
      Returns:
      true if this set changed as a result of the call
      Throws:
      NullPointerException - if the specified collection is null

    • removeAll

      public boolean removeAll(Collection<?> c)

      Removes from this set all of its elements that are contained in the specified collection. For String elements, the removal is case-insensitive, meaning that strings differing only by case (e.g., "Hello" and "hello") are treated as equal, and removing any of them will remove the corresponding entry from the set.

      Specified by:
      removeAll in interface Collection<E>
      Specified by:
      removeAll in interface Set<E>
      Parameters:
      c - the collection containing elements to be removed from this set
      Returns:
      true if this set changed as a result of the call
      Throws:
      NullPointerException - if the specified collection is null

    • clear

      public void clear()

      Removes all elements from this set. After this call, the set will be empty. For String elements, the case-insensitive behavior of the set has no impact on the clearing operation.

      Specified by:
      clear in interface Collection<E>
      Specified by:
      clear in interface Set<E>

    • elementCount

      public long elementCount()
      Returns an estimate of the number of elements in this set when backed by a ConcurrentHashMap. This method provides better performance and handles large sets (size > Integer.MAX_VALUE).

      When the backing map is not a ConcurrentHashMap, this method delegates to size(). The estimate may not reflect recent additions or removals due to concurrent modifications.

      Returns:
      the estimated number of elements in this set
      Since:
      3.6.0

    • forEach

      public void forEach(long parallelismThreshold, Consumer<? super E> action)
      Performs the given action for each element in this set, with operations potentially performed in parallel when the parallelism threshold is met and the set is backed by a ConcurrentHashMap.

      This method provides high-performance parallel iteration over set elements when using concurrent backing maps. The parallelism threshold determines the minimum set size required to enable parallel processing.

      Parameters:
      parallelismThreshold - the threshold for parallel execution (typically use 1 for parallel, Long.MAX_VALUE for sequential)
      action - the action to be performed for each element
      Throws:
      NullPointerException - if the specified action is null
      Since:
      3.6.0

    • searchElements

      public <U> U searchElements(long parallelismThreshold, Function<? super E,? extends U> searchFunction)
      Returns a non-null result from applying the given search function to each element in this set, or null if none are found. The search may be performed in parallel when the parallelism threshold is met and the set is backed by a ConcurrentHashMap.

      This method provides high-performance parallel search over set elements when using concurrent backing maps. The search terminates early upon finding the first non-null result.

      Type Parameters:
      U - the type of the search result
      Parameters:
      parallelismThreshold - the threshold for parallel execution (typically use 1 for parallel, Long.MAX_VALUE for sequential)
      searchFunction - the function to apply to each element
      Returns:
      a non-null result from applying the search function, or null if none found
      Throws:
      NullPointerException - if the specified search function is null
      Since:
      3.6.0

    • reduceElements

      public <U> U reduceElements(long parallelismThreshold, Function<? super E,? extends U> transformer, BiFunction<? super U,? super U,? extends U> reducer)
      Returns the result of accumulating all elements in this set using the given reducer and transformer functions. The reduction may be performed in parallel when the parallelism threshold is met and the set is backed by a ConcurrentHashMap.

      This method provides high-performance parallel reduction over set elements when using concurrent backing maps. The transformer is applied to each element before reduction.

      Type Parameters:
      U - the type of the transformed elements and the result
      Parameters:
      parallelismThreshold - the threshold for parallel execution (typically use 1 for parallel, Long.MAX_VALUE for sequential)
      transformer - the function to transform each element before reduction
      reducer - the function to combine transformed elements
      Returns:
      the result of the reduction, or null if the set is empty
      Throws:
      NullPointerException - if the specified transformer or reducer is null
      Since:
      3.6.0

    • getBackingMap

      public Map<E,Object> getBackingMap()
      Returns the underlying map used to implement this set.

      This method provides access to the backing CaseInsensitiveMap implementation, allowing advanced operations and inspections. The returned map maintains the same case-insensitive semantics as this set.

      Warning: Modifying the returned map directly may affect this set's state. Use with caution and prefer the set's public methods when possible.

      Returns:
      the backing map implementation
      Since:
      3.6.0

    • minus

      @Deprecated public Set<E> minus(Iterable<E> removeMe)
      Deprecated.

    • minus

      @Deprecated public Set<E> minus(E removeMe)
      Deprecated.

    • plus

      @Deprecated public Set<E> plus(Iterable<E> right)
      Deprecated.

    • plus

      @Deprecated public Set<E> plus(Object right)
      Deprecated.

    • toString

      public String toString()

      Returns a string representation of this set. The string representation consists of a list of the set's elements in their original case, enclosed in square brackets ("[]"). For String elements, the original case is preserved, even though the set performs case-insensitive comparisons.

      The order of elements in the string representation matches the iteration order of the backing map.

      Overrides:
      toString in class Object
      Returns:
      a string representation of this set