## org.apache.commons.collections
Class SetUtils

    java.lang.Object
      org.apache.commons.collections.SetUtils

    public class SetUtils

extends java.lang.Object

Provides utility methods and decorators for `Set` and `SortedSet` instances.

Since:
  Commons Collections 2.1
Version:
  $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
Author:
  Paul Jack, Stephen Colebourne, Neil O'Toole, Matthew Hawthorne

Field Summary
`static java.util.Set` `EMPTY_SET` An empty unmodifiable set.
`static java.util.SortedSet` `EMPTY_SORTED_SET` An empty unmodifiable sorted set.

Constructor Summary
`SetUtils()` `SetUtils` should not normally be instantiated.

Method Summary
`static int` `hashCodeForSet(java.util.Collection set)` Generates a hash code using the algorithm specified in `Set.hashCode()`.
`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 java.util.Set` `orderedSet(java.util.Set set)` Returns a set that maintains the order of elements that are added backed by the given set.
`static java.util.Set` `predicatedSet(java.util.Set set, Predicate predicate)` Returns a predicated (validating) set backed by the given set.
`static java.util.SortedSet` `predicatedSortedSet(java.util.SortedSet set, Predicate predicate)` Returns a predicated (validating) sorted set backed by the given sorted set.
`static java.util.Set` `synchronizedSet(java.util.Set set)` Returns a synchronized set backed by the given set.
`static java.util.SortedSet` `synchronizedSortedSet(java.util.SortedSet set)` Returns a synchronized sorted set backed by the given sorted set.
`static java.util.Set` `transformedSet(java.util.Set set, Transformer transformer)` Returns a transformed set backed by the given set.
`static java.util.SortedSet` `transformedSortedSet(java.util.SortedSet set, Transformer transformer)` Returns a transformed sorted set backed by the given set.
`static java.util.Set` `typedSet(java.util.Set set, java.lang.Class type)` Returns a typed set backed by the given set.
`static java.util.SortedSet` `typedSortedSet(java.util.SortedSet set, java.lang.Class type)` Returns a typed sorted set backed by the given set.
`static java.util.Set` `unmodifiableSet(java.util.Set set)` Returns an unmodifiable set backed by the given set.
`static java.util.SortedSet` `unmodifiableSortedSet(java.util.SortedSet 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_SET

    public static final java.util.Set EMPTY_SET

  An empty unmodifiable set. This uses the `Collections` implementation and is provided for completeness.

### EMPTY_SORTED_SET

    public static final java.util.SortedSet EMPTY_SORTED_SET

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

Constructor Detail

### SetUtils

    public SetUtils()

  `SetUtils` should not normally be instantiated.

Method Detail

### 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`

### hashCodeForSet

    public static int hashCodeForSet(java.util.Collection 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.

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

### synchronizedSet

    public static java.util.Set synchronizedSet(java.util.Set set)

  Returns a synchronized set backed by the given set.

  You must manually synchronize on the returned buffer'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 uses the implementation in the decorators subpackage.

  Parameters:
    `set` - the set to synchronize, must not be null
  Returns:
    a synchronized set backed by the given set
  Throws:
    `java.lang.IllegalArgumentException` - if the set is null

### unmodifiableSet

    public static java.util.Set unmodifiableSet(java.util.Set set)

  Returns an unmodifiable set backed by the given set.

  This method uses the implementation in the decorators subpackage.

  Parameters:
    `set` - the set to make unmodifiable, must not be null
  Returns:
    an unmodifiable set backed by the given set
  Throws:
    `java.lang.IllegalArgumentException` - if the set is null

### predicatedSet

    public static java.util.Set predicatedSet(java.util.Set set,
                                              Predicate 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.

  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.IllegalArgumentException` - if the Set or Predicate is null

### typedSet

    public static java.util.Set typedSet(java.util.Set set,
                                         java.lang.Class type)

  Returns a typed set backed by the given set.

  Only objects of the specified type can be added to the set.

  Parameters:
    `set` - the set to limit to a specific type, must not be null
    `type` - the type of objects which may be added to the set
  Returns:
    a typed set backed by the specified set

### transformedSet

    public static java.util.Set transformedSet(java.util.Set set,
                                               Transformer 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.

  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.IllegalArgumentException` - if the Set or Transformer is null

### orderedSet

    public static java.util.Set orderedSet(java.util.Set 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.

  Parameters:
    `set` - the set to order, must not be null
  Returns:
    an ordered set backed by the given set
  Throws:
    `java.lang.IllegalArgumentException` - if the Set is null

### synchronizedSortedSet

    public static java.util.SortedSet synchronizedSortedSet(java.util.SortedSet set)

  Returns a synchronized sorted set backed by the given sorted set.

  You must manually synchronize on the returned buffer'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 uses the implementation in the decorators subpackage.

  Parameters:
    `set` - the sorted set to synchronize, must not be null
  Returns:
    a synchronized set backed by the given set
  Throws:
    `java.lang.IllegalArgumentException` - if the set is null

### unmodifiableSortedSet

    public static java.util.SortedSet unmodifiableSortedSet(java.util.SortedSet set)

  Returns an unmodifiable sorted set backed by the given sorted set.

  This method uses the implementation in the decorators subpackage.

  Parameters:
    `set` - the sorted set to make unmodifiable, must not be null
  Returns:
    an unmodifiable set backed by the given set
  Throws:
    `java.lang.IllegalArgumentException` - if the set is null

### predicatedSortedSet

    public static java.util.SortedSet predicatedSortedSet(java.util.SortedSet set,
                                                          Predicate 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.

  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.IllegalArgumentException` - if the Set or Predicate is null

### typedSortedSet

    public static java.util.SortedSet typedSortedSet(java.util.SortedSet set,
                                                     java.lang.Class type)

  Returns a typed sorted set backed by the given set.

  Only objects of the specified type can be added to the set.

  Parameters:
    `set` - the set to limit to a specific type, must not be null
    `type` - the type of objects which may be added to the set
  Returns:
    a typed set backed by the specified set

### transformedSortedSet

    public static java.util.SortedSet transformedSortedSet(java.util.SortedSet set,
                                                           Transformer 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.

  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.IllegalArgumentException` - if the Set or Transformer is null

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.