org.apache.commons.collections4

## Class SetUtils

- java.lang.Object
- - org.apache.commons.collections4.SetUtils

-     public class SetUtils
      extends Object

  Provides utility methods and decorators for `Set` and `SortedSet` instances.
  Since:
    2.1
  Version:
    $Id: SetUtils.java 1543964 2013-11-20 21:53:39Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static SortedSet` | `EMPTY_SORTED_SET` An empty unmodifiable sorted set.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> Set<T>` | `emptyIfNull(Set<T> set)` Returns an immutable empty set if the argument is `null`, or the argument itself otherwise.
    `static <E> Set<E>` | `emptySet()` Get a typed empty unmodifiable Set.
    `static <E> SortedSet<E>` | `emptySortedSet()` Get a typed empty unmodifiable sorted set.
    `static <T> int` | `hashCodeForSet(Collection<T> set)` Generates a hash code using the algorithm specified in `Set.hashCode()`.
    `static boolean` | `isEqualSet(Collection<?> set1, Collection<?> set2)` Tests two sets for equality as per the `equals()` contract in `Set.equals(java.lang.Object)`.
    `static <E> Set<E>` | `orderedSet(Set<E> set)` Returns a set that maintains the order of elements that are added backed by the given set.
    `static <E> Set<E>` | `predicatedSet(Set<E> set, Predicate<? super E> predicate)` Returns a predicated (validating) set backed by the given set.
    `static <E> SortedSet<E>` | `predicatedSortedSet(SortedSet<E> set, Predicate<? super E> predicate)` Returns a predicated (validating) sorted set backed by the given sorted set.
    `static <E> Set<E>` | `synchronizedSet(Set<E> set)` Returns a synchronized set backed by the given set.
    `static <E> SortedSet<E>` | `synchronizedSortedSet(SortedSet<E> set)` Returns a synchronized sorted set backed by the given sorted set.
    `static <E> Set<E>` | `transformedSet(Set<E> set, Transformer<? super E,? extends E> transformer)` Returns a transformed set backed by the given set.
    `static <E> SortedSet<E>` | `transformedSortedSet(SortedSet<E> set, Transformer<? super E,? extends E> transformer)` Returns a transformed sorted set backed by the given set.
    `static <E> Set<E>` | `unmodifiableSet(Set<? extends E> set)` Returns an unmodifiable set backed by the given set.
    `static <E> SortedSet<E>` | `unmodifiableSortedSet(SortedSet<E> set)` Returns an unmodifiable sorted set backed by the given sorted set.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### EMPTY_SORTED_SET

          public static final SortedSet EMPTY_SORTED_SET

      An empty unmodifiable sorted set. This is not provided in the JDK.

  - ### Method Detail

    - #### emptySet

          public static <E> Set<E> emptySet()

      Get a typed empty unmodifiable Set.
      Type Parameters:
        `E` - the element type
      Returns:
        an empty Set

    - #### emptySortedSet

          public static <E> SortedSet<E> emptySortedSet()

      Get a typed empty unmodifiable sorted set.
      Type Parameters:
        `E` - the element type
      Returns:
        an empty sorted Set

    - #### emptyIfNull

          public static <T> Set<T> emptyIfNull(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`

    - #### isEqualSet

          public static boolean isEqualSet(Collection<?> set1,
                           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`

    - #### hashCodeForSet

          public static <T> int hashCodeForSet(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()`

    - #### synchronizedSet

          public static <E> Set<E> synchronizedSet(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:
        `IllegalArgumentException` - if the set is null

    - #### unmodifiableSet

          public static <E> Set<E> unmodifiableSet(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:
        `IllegalArgumentException` - if the set is null

    - #### predicatedSet

          public static <E> Set<E> predicatedSet(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:
        `IllegalArgumentException` - if the Set or Predicate is null

    - #### transformedSet

          public static <E> Set<E> transformedSet(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:
        `IllegalArgumentException` - if the Set or Transformer is null

    - #### orderedSet

          public static <E> Set<E> orderedSet(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:
        `IllegalArgumentException` - if the Set is null

    - #### synchronizedSortedSet

          public static <E> SortedSet<E> synchronizedSortedSet(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.synchronizedSet(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:
        `IllegalArgumentException` - if the set is null

    - #### unmodifiableSortedSet

          public static <E> SortedSet<E> unmodifiableSortedSet(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:
        `IllegalArgumentException` - if the set is null

    - #### predicatedSortedSet

          public static <E> SortedSet<E> predicatedSortedSet(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:
        `IllegalArgumentException` - if the Set or Predicate is null

    - #### transformedSortedSet

          public static <E> SortedSet<E> transformedSortedSet(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:
        `IllegalArgumentException` - if the Set or Transformer is null

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.