Package org.apache.commons.collections4

Class SetUtils

  • public class SetUtils
extends java.lang.Object
    Provides utility methods and decorators for Set and SortedSet instances.
    Since:
    2.1

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  SetUtils.SetView<E>
      An unmodifiable view of a set that may be backed by other sets.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.SortedSet EMPTY_SORTED_SET
      An empty unmodifiable sorted set.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <E> SetUtils.SetView<E> difference​(java.util.Set<? extends E> a, java.util.Set<? extends E> b)
      Returns a unmodifiable view containing the difference of the given Sets, denoted by a \ b (or a - b).
      static <E> SetUtils.SetView<E> disjunction​(java.util.Set<? extends E> a, java.util.Set<? extends E> b)
      Returns a unmodifiable view of the symmetric difference of the given Sets.
      static <T> java.util.Set<T> emptyIfNull​(java.util.Set<T> set)
      Returns an immutable empty set if the argument is null, or the argument itself otherwise.
      static <E> java.util.Set<E> emptySet()
      Get a typed empty unmodifiable Set.
      static <E> java.util.SortedSet<E> emptySortedSet()
      Get a typed empty unmodifiable sorted set.
      static <T> int hashCodeForSet​(java.util.Collection<T> set)
      Generates a hash code using the algorithm specified in Set.hashCode().
      static <E> java.util.HashSet<E> hashSet​(E... items)
      Creates a set from the given items.
      static <E> SetUtils.SetView<E> intersection​(java.util.Set<? extends E> a, java.util.Set<? extends E> b)
      Returns a unmodifiable view of the intersection of the given Sets.
      static boolean isEqualSet​(java.util.Collection<?> set1, java.util.Collection<?> set2)
      Tests two sets for equality as per the equals() contract in Set.equals(java.lang.Object).
      static <E> java.util.Set<E> newIdentityHashSet()
      Returns a new hash set that matches elements based on == not equals().
      static <E> java.util.Set<E> orderedSet​(java.util.Set<E> set)
      Returns a set that maintains the order of elements that are added backed by the given set.
      static <E> java.util.SortedSet<E> predicatedNavigableSet​(java.util.NavigableSet<E> set, Predicate<? super E> predicate)
      Returns a predicated (validating) navigable set backed by the given navigable set.
      static <E> java.util.Set<E> predicatedSet​(java.util.Set<E> set, Predicate<? super E> predicate)
      Returns a predicated (validating) set backed by the given set.
      static <E> java.util.SortedSet<E> predicatedSortedSet​(java.util.SortedSet<E> set, Predicate<? super E> predicate)
      Returns a predicated (validating) sorted set backed by the given sorted set.
      static <E> java.util.Set<E> synchronizedSet​(java.util.Set<E> set)
      Returns a synchronized set backed by the given set.
      static <E> java.util.SortedSet<E> synchronizedSortedSet​(java.util.SortedSet<E> set)
      Returns a synchronized sorted set backed by the given sorted set.
      static <E> java.util.SortedSet<E> transformedNavigableSet​(java.util.NavigableSet<E> set, Transformer<? super E,​? extends E> transformer)
      Returns a transformed navigable set backed by the given navigable set.
      static <E> java.util.Set<E> transformedSet​(java.util.Set<E> set, Transformer<? super E,​? extends E> transformer)
      Returns a transformed set backed by the given set.
      static <E> java.util.SortedSet<E> transformedSortedSet​(java.util.SortedSet<E> set, Transformer<? super E,​? extends E> transformer)
      Returns a transformed sorted set backed by the given set.
      static <E> SetUtils.SetView<E> union​(java.util.Set<? extends E> a, java.util.Set<? extends E> b)
      Returns a unmodifiable view of the union of the given Sets.
      static <E> java.util.SortedSet<E> unmodifiableNavigableSet​(java.util.NavigableSet<E> set)
      Returns an unmodifiable navigable set backed by the given navigable set.
      static <E> java.util.Set<E> unmodifiableSet​(E... items)
      Creates an unmodifiable set from the given items.
      static <E> java.util.Set<E> unmodifiableSet​(java.util.Set<? extends E> set)
      Returns an unmodifiable set backed by the given set.
      static <E> java.util.SortedSet<E> unmodifiableSortedSet​(java.util.SortedSet<E> set)
      Returns an unmodifiable sorted set backed by the given sorted set.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • EMPTY_SORTED_SET

        public static final java.util.SortedSet EMPTY_SORTED_SET
        An empty unmodifiable sorted set. This is not provided in the JDK.

    • Method Detail

      • difference

        public static <E> SetUtils.SetView<E> difference​(java.util.Set<? extends E> a,
                                                 java.util.Set<? extends E> b)
        Returns a unmodifiable view containing the difference of the given Sets, denoted by a \ b (or a - b).

        The returned view contains all elements of a that are not a member of b.

        Type Parameters:
        E - the generic type that is able to represent the types contained in both input sets.
        Parameters:
        a - the set to subtract from, must not be null
        b - the set to subtract, must not be null
        Returns:
        a view of the relative complement of of the two sets
        Since:
        4.1

      • disjunction

        public static <E> SetUtils.SetView<E> disjunction​(java.util.Set<? extends E> a,
                                                  java.util.Set<? extends E> b)
        Returns a unmodifiable view of the symmetric difference of the given Sets.

        The returned view contains all elements of a and b that are not a member of the other set.

        This is equivalent to union(difference(a, b), difference(b, a)).

        Type Parameters:
        E - the generic type that is able to represent the types contained in both input sets.
        Parameters:
        a - the first set, must not be null
        b - the second set, must not be null
        Returns:
        a view of the symmetric difference of the two sets
        Since:
        4.1

      • emptyIfNull

        public static <T> java.util.Set<T> emptyIfNull​(java.util.Set<T> set)
        Returns an immutable empty set if the argument is null, or the argument itself otherwise.
        Type Parameters:
        T - the element type
        Parameters:
        set - the set, possibly null
        Returns:
        an empty set if the argument is null

      • emptySet

        public static <E> java.util.Set<E> emptySet()
        Get a typed empty unmodifiable Set.
        Type Parameters:
        E - the element type
        Returns:
        an empty Set

      • emptySortedSet

        public static <E> java.util.SortedSet<E> emptySortedSet()
        Get a typed empty unmodifiable sorted set.
        Type Parameters:
        E - the element type
        Returns:
        an empty sorted Set

      • hashCodeForSet

        public static <T> int hashCodeForSet​(java.util.Collection<T> set)
        Generates a hash code using the algorithm specified in Set.hashCode().

        This method is useful for implementing Set when you cannot extend AbstractSet. The method takes Collection instances to enable other collection types to use the Set implementation algorithm.

        Type Parameters:
        T - the element type
        Parameters:
        set - the set to calculate the hash code for, may be null
        Returns:
        the hash code
        See Also:
        Set.hashCode()

      • hashSet

        public static <E> java.util.HashSet<E> hashSet​(E... items)
        Creates a set from the given items. If the passed var-args argument is null, then the method returns null.
        Type Parameters:
        E - the element type
        Parameters:
        items - the elements that make up the new set
        Returns:
        a set
        Since:
        4.3

      • intersection

        public static <E> SetUtils.SetView<E> intersection​(java.util.Set<? extends E> a,
                                                   java.util.Set<? extends E> b)
        Returns a unmodifiable view of the intersection of the given Sets.

        The returned view contains all elements that are members of both input sets (a and b).

        Type Parameters:
        E - the generic type that is able to represent the types contained in both input sets.
        Parameters:
        a - the first set, must not be null
        b - the second set, must not be null
        Returns:
        a view of the intersection of the two sets
        Since:
        4.1

      • isEqualSet

        public static boolean isEqualSet​(java.util.Collection<?> set1,
                                 java.util.Collection<?> set2)
        Tests two sets for equality as per the equals() contract in Set.equals(java.lang.Object).

        This method is useful for implementing Set when you cannot extend AbstractSet. The method takes Collection instances to enable other collection types to use the Set implementation algorithm.

        The relevant text (slightly paraphrased as this is a static method) is:

        Two sets are considered equal if they have the same size, and every member of the first set is contained in the second. This ensures that the equals method works properly across different implementations of the Set interface.

        This implementation first checks if the two sets are the same object: if so it returns true. Then, it checks if the two sets are identical in size; if not, it returns false. If so, it returns a.containsAll((Collection) b).

        Parameters:
        set1 - the first set, may be null
        set2 - the second set, may be null
        Returns:
        whether the sets are equal by value comparison
        See Also:
        Set

      • newIdentityHashSet

        public static <E> java.util.Set<E> newIdentityHashSet()
        Returns a new hash set that matches elements based on == not equals().

        This set will violate the detail of various Set contracts. As a general rule, don't compare this set to other sets. In particular, you can't use decorators like ListOrderedSet on it, which silently assume that these contracts are fulfilled.

        Note that the returned set is not synchronized and is not thread-safe. If you wish to use this set from multiple threads concurrently, you must use appropriate synchronization. The simplest approach is to wrap this map using Collections.synchronizedSet(Set). This class may throw exceptions when accessed by concurrent threads without synchronization.

        Type Parameters:
        E - the element type
        Returns:
        a new identity hash set
        Since:
        4.1

      • orderedSet

        public static <E> java.util.Set<E> orderedSet​(java.util.Set<E> set)
        Returns a set that maintains the order of elements that are added backed by the given set.

        If an element is added twice, the order is determined by the first add. The order is observed through the iterator or toArray.

        Type Parameters:
        E - the element type
        Parameters:
        set - the set to order, must not be null
        Returns:
        an ordered set backed by the given set
        Throws:
        java.lang.NullPointerException - if the set is null

      • predicatedNavigableSet

        public static <E> java.util.SortedSet<E> predicatedNavigableSet​(java.util.NavigableSet<E> set,
                                                                Predicate<? super E> predicate)
        Returns a predicated (validating) navigable set backed by the given navigable set.

        Only objects that pass the test in the given predicate can be added to the set. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original set after invoking this method, as it is a backdoor for adding invalid objects.

        Type Parameters:
        E - the element type
        Parameters:
        set - the navigable set to predicate, must not be null
        predicate - the predicate for the navigable set, must not be null
        Returns:
        a predicated navigable set backed by the given navigable set
        Throws:
        java.lang.NullPointerException - if the set or predicate is null
        Since:
        4.1

      • predicatedSet

        public static <E> java.util.Set<E> predicatedSet​(java.util.Set<E> set,
                                                 Predicate<? super E> predicate)
        Returns a predicated (validating) set backed by the given set.

        Only objects that pass the test in the given predicate can be added to the set. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original set after invoking this method, as it is a backdoor for adding invalid objects.

        Type Parameters:
        E - the element type
        Parameters:
        set - the set to predicate, must not be null
        predicate - the predicate for the set, must not be null
        Returns:
        a predicated set backed by the given set
        Throws:
        java.lang.NullPointerException - if the set or predicate is null

      • predicatedSortedSet

        public static <E> java.util.SortedSet<E> predicatedSortedSet​(java.util.SortedSet<E> set,
                                                             Predicate<? super E> predicate)
        Returns a predicated (validating) sorted set backed by the given sorted set.

        Only objects that pass the test in the given predicate can be added to the set. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original set after invoking this method, as it is a backdoor for adding invalid objects.

        Type Parameters:
        E - the element type
        Parameters:
        set - the sorted set to predicate, must not be null
        predicate - the predicate for the sorted set, must not be null
        Returns:
        a predicated sorted set backed by the given sorted set
        Throws:
        java.lang.NullPointerException - if the set or predicate is null

      • synchronizedSet

        public static <E> java.util.Set<E> synchronizedSet​(java.util.Set<E> set)
        Returns a synchronized set backed by the given set.

        You must manually synchronize on the returned set's iterator to avoid non-deterministic behavior: 

         Set s = SetUtils.synchronizedSet(mySet);
 synchronized (s) {
     Iterator i = s.iterator();
     while (i.hasNext()) {
         process (i.next());
     }
 }
        This method is just a wrapper for Collections.synchronizedSet(Set).
        Type Parameters:
        E - the element type
        Parameters:
        set - the set to synchronize, must not be null
        Returns:
        a synchronized set backed by the given set
        Throws:
        java.lang.NullPointerException - if the set is null

      • synchronizedSortedSet

        public static <E> java.util.SortedSet<E> synchronizedSortedSet​(java.util.SortedSet<E> set)
        Returns a synchronized sorted set backed by the given sorted set.

        You must manually synchronize on the returned set's iterator to avoid non-deterministic behavior: 

         Set s = SetUtils.synchronizedSortedSet(mySet);
 synchronized (s) {
     Iterator i = s.iterator();
     while (i.hasNext()) {
         process (i.next());
     }
 }
        This method is just a wrapper for Collections.synchronizedSortedSet(SortedSet).
        Type Parameters:
        E - the element type
        Parameters:
        set - the sorted set to synchronize, must not be null
        Returns:
        a synchronized set backed by the given set
        Throws:
        java.lang.NullPointerException - if the set is null

      • transformedNavigableSet

        public static <E> java.util.SortedSet<E> transformedNavigableSet​(java.util.NavigableSet<E> set,
                                                                 Transformer<? super E,​? extends E> transformer)
        Returns a transformed navigable set backed by the given navigable set.

        Each object is passed through the transformer as it is added to the Set. It is important not to use the original set after invoking this method, as it is a backdoor for adding untransformed objects.

        Existing entries in the specified set will not be transformed. If you want that behaviour, see TransformedNavigableSet.transformedNavigableSet(java.util.NavigableSet<E>, org.apache.commons.collections4.Transformer<? super E, ? extends E>).

        Type Parameters:
        E - the element type
        Parameters:
        set - the navigable set to transform, must not be null
        transformer - the transformer for the set, must not be null
        Returns:
        a transformed set backed by the given set
        Throws:
        java.lang.NullPointerException - if the set or transformer is null
        Since:
        4.1

      • transformedSet

        public static <E> java.util.Set<E> transformedSet​(java.util.Set<E> set,
                                                  Transformer<? super E,​? extends E> transformer)
        Returns a transformed set backed by the given set.

        Each object is passed through the transformer as it is added to the Set. It is important not to use the original set after invoking this method, as it is a backdoor for adding untransformed objects.

        Existing entries in the specified set will not be transformed. If you want that behaviour, see TransformedSet.transformedSet(java.util.Set<E>, org.apache.commons.collections4.Transformer<? super E, ? extends E>).

        Type Parameters:
        E - the element type
        Parameters:
        set - the set to transform, must not be null
        transformer - the transformer for the set, must not be null
        Returns:
        a transformed set backed by the given set
        Throws:
        java.lang.NullPointerException - if the set or transformer is null

      • transformedSortedSet

        public static <E> java.util.SortedSet<E> transformedSortedSet​(java.util.SortedSet<E> set,
                                                              Transformer<? super E,​? extends E> transformer)
        Returns a transformed sorted set backed by the given set.

        Each object is passed through the transformer as it is added to the Set. It is important not to use the original set after invoking this method, as it is a backdoor for adding untransformed objects.

        Existing entries in the specified set will not be transformed. If you want that behaviour, see TransformedSortedSet.transformedSortedSet(java.util.SortedSet<E>, org.apache.commons.collections4.Transformer<? super E, ? extends E>).

        Type Parameters:
        E - the element type
        Parameters:
        set - the set to transform, must not be null
        transformer - the transformer for the set, must not be null
        Returns:
        a transformed set backed by the given set
        Throws:
        java.lang.NullPointerException - if the set or transformer is null

      • union

        public static <E> SetUtils.SetView<E> union​(java.util.Set<? extends E> a,
                                            java.util.Set<? extends E> b)
        Returns a unmodifiable view of the union of the given Sets.

        The returned view contains all elements of a and b.

        Type Parameters:
        E - the generic type that is able to represent the types contained in both input sets.
        Parameters:
        a - the first set, must not be null
        b - the second set, must not be null
        Returns:
        a view of the union of the two set
        Throws:
        java.lang.NullPointerException - if either input set is null
        Since:
        4.1

      • unmodifiableNavigableSet

        public static <E> java.util.SortedSet<E> unmodifiableNavigableSet​(java.util.NavigableSet<E> set)
        Returns an unmodifiable navigable set backed by the given navigable set.

        This method uses the implementation in the decorators subpackage.

        Type Parameters:
        E - the element type
        Parameters:
        set - the navigable set to make unmodifiable, must not be null
        Returns:
        an unmodifiable set backed by the given set
        Throws:
        java.lang.NullPointerException - if the set is null
        Since:
        4.1

      • unmodifiableSet

        public static <E> java.util.Set<E> unmodifiableSet​(E... items)
        Creates an unmodifiable set from the given items. If the passed var-args argument is null, then the method returns null.
        Type Parameters:
        E - the element type
        Parameters:
        items - the elements that make up the new set
        Returns:
        a set
        Since:
        4.3

      • unmodifiableSet

        public static <E> java.util.Set<E> unmodifiableSet​(java.util.Set<? extends E> set)
        Returns an unmodifiable set backed by the given set.

        This method uses the implementation in the decorators subpackage.

        Type Parameters:
        E - the element type
        Parameters:
        set - the set to make unmodifiable, must not be null
        Returns:
        an unmodifiable set backed by the given set
        Throws:
        java.lang.NullPointerException - if the set is null

      • unmodifiableSortedSet

        public static <E> java.util.SortedSet<E> unmodifiableSortedSet​(java.util.SortedSet<E> set)
        Returns an unmodifiable sorted set backed by the given sorted set.

        This method uses the implementation in the decorators subpackage.

        Type Parameters:
        E - the element type
        Parameters:
        set - the sorted set to make unmodifiable, must not be null
        Returns:
        an unmodifiable set backed by the given set
        Throws:
        java.lang.NullPointerException - if the set is null