Collections2
Date: 2016-05-24

com.google.common.collect

## Class Collections2

- java.lang.Object
- - com.google.common.collect.Collections2

-     @CheckReturnValue
      @GwtCompatible
      public final class Collections2
      extends java.lang.Object

  Provides static methods for working with `Collection` instances.
  Since:
    2.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <E> java.util.Collection<E>` | `filter(java.util.Collection<E> unfiltered, Predicate<? super E> predicate)` Returns the elements of `unfiltered` that satisfy a predicate.
    `static <E extends java.lang.Comparable<? super E>> java.util.Collection<java.util.List<E>>` | `orderedPermutations(java.lang.Iterable<E> elements)` Returns a `Collection` of all the permutations of the specified `Iterable`.
    `static <E> java.util.Collection<java.util.List<E>>` | `orderedPermutations(java.lang.Iterable<E> elements, java.util.Comparator<? super E> comparator)` Returns a `Collection` of all the permutations of the specified `Iterable` using the specified `Comparator` for establishing the lexicographical ordering.
    `static <E> java.util.Collection<java.util.List<E>>` | `permutations(java.util.Collection<E> elements)` Returns a `Collection` of all the permutations of the specified `Collection`.
    `static <F,T> java.util.Collection<T>` | `transform(java.util.Collection<F> fromCollection, Function<? super F,T> function)` Returns a collection that applies `function` to each element of `fromCollection`.

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

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

- - ### Method Detail

    - #### filter

          @CheckReturnValue
          public static <E> java.util.Collection<E> filter(java.util.Collection<E> unfiltered,
                                                            Predicate<? super E> predicate)

      Returns the elements of `unfiltered` that satisfy a predicate. The returned collection is a live view of `unfiltered`; changes to one affect the other.

      The resulting collection's iterator does not support `remove()`, but all other collection methods are supported. When given an element that doesn't satisfy the predicate, the collection's `add()` and `addAll()` methods throw an `IllegalArgumentException`. When methods such as `removeAll()` and `clear()` are called on the filtered collection, only elements that satisfy the filter will be removed from the underlying collection.

      The returned collection isn't threadsafe or serializable, even if `unfiltered` is.

      Many of the filtered collection's methods, such as `size()`, iterate across every element in the underlying collection and determine which elements satisfy the filter. When a live view is not needed, it may be faster to copy `Iterables.filter(unfiltered, predicate)` and use the copy.

      Warning: `predicate` must be consistent with equals, as documented at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals. (See `Iterables.filter(Iterable, Class)` for related functionality.)

    - #### transform

          public static <F,T> java.util.Collection<T> transform(java.util.Collection<F> fromCollection,
                                                Function<? super F,T> function)

      Returns a collection that applies `function` to each element of `fromCollection`. The returned collection is a live view of `fromCollection`; changes to one affect the other.

      The returned collection's `add()` and `addAll()` methods throw an `UnsupportedOperationException`. All other collection methods are supported, as long as `fromCollection` supports them.

      The returned collection isn't threadsafe or serializable, even if `fromCollection` is.

      When a live view is not needed, it may be faster to copy the transformed collection and use the copy.

      If the input `Collection` is known to be a `List`, consider `Lists.transform(java.util.List<F>, com.google.common.base.Function<? super F, ? extends T>)`. If only an `Iterable` is available, use `Iterables.transform(java.lang.Iterable<F>, com.google.common.base.Function<? super F, ? extends T>)`.

    - #### orderedPermutations

          @Beta
          public static <E extends java.lang.Comparable<? super E>> java.util.Collection<java.util.List<E>> orderedPermutations(java.lang.Iterable<E> elements)

      Returns a `Collection` of all the permutations of the specified `Iterable`.

      Notes: This is an implementation of the algorithm for Lexicographical Permutations Generation, described in Knuth's "The Art of Computer Programming", Volume 4, Chapter 7, Section 7.2.1.2. The iteration order follows the lexicographical order. This means that the first permutation will be in ascending order, and the last will be in descending order.

      Duplicate elements are considered equal. For example, the list [1, 1] will have only one permutation, instead of two. This is why the elements have to implement `Comparable`.

      An empty iterable has only one permutation, which is an empty list.

      This method is equivalent to `Collections2.orderedPermutations(list, Ordering.natural())`.

      Parameters:
        `elements` - the original iterable whose elements have to be permuted.
      Returns:
        an immutable `Collection` containing all the different permutations of the original iterable.
      Throws:
        `java.lang.NullPointerException` - if the specified iterable is null or has any null elements.
      Since:
        12.0

    - #### orderedPermutations

          @Beta
          public static <E> java.util.Collection<java.util.List<E>> orderedPermutations(java.lang.Iterable<E> elements,
                                                                             java.util.Comparator<? super E> comparator)

      Returns a `Collection` of all the permutations of the specified `Iterable` using the specified `Comparator` for establishing the lexicographical ordering.

      Examples:

             for (List<String> perm : orderedPermutations(asList("b", "c", "a"))) {
               println(perm);
             }
             // -> ["a", "b", "c"]
             // -> ["a", "c", "b"]
             // -> ["b", "a", "c"]
             // -> ["b", "c", "a"]
             // -> ["c", "a", "b"]
             // -> ["c", "b", "a"]

             for (List<Integer> perm : orderedPermutations(asList(1, 2, 2, 1))) {
               println(perm);
             }
             // -> [1, 1, 2, 2]
             // -> [1, 2, 1, 2]
             // -> [1, 2, 2, 1]
             // -> [2, 1, 1, 2]
             // -> [2, 1, 2, 1]
             // -> [2, 2, 1, 1]

      Notes: This is an implementation of the algorithm for Lexicographical Permutations Generation, described in Knuth's "The Art of Computer Programming", Volume 4, Chapter 7, Section 7.2.1.2. The iteration order follows the lexicographical order. This means that the first permutation will be in ascending order, and the last will be in descending order.

      Elements that compare equal are considered equal and no new permutations are created by swapping them.

      An empty iterable has only one permutation, which is an empty list.

      Parameters:
        `elements` - the original iterable whose elements have to be permuted.
        `comparator` - a comparator for the iterable's elements.
      Returns:
        an immutable `Collection` containing all the different permutations of the original iterable.
      Throws:
        `java.lang.NullPointerException` - If the specified iterable is null, has any null elements, or if the specified comparator is null.
      Since:
        12.0

    - #### permutations

          @Beta
          public static <E> java.util.Collection<java.util.List<E>> permutations(java.util.Collection<E> elements)

      Returns a `Collection` of all the permutations of the specified `Collection`.

      Notes: This is an implementation of the Plain Changes algorithm for permutations generation, described in Knuth's "The Art of Computer Programming", Volume 4, Chapter 7, Section 7.2.1.2.

      If the input list contains equal elements, some of the generated permutations will be equal.

      An empty collection has only one permutation, which is an empty list.

      Parameters:
        `elements` - the original collection whose elements have to be permuted.
      Returns:
        an immutable `Collection` containing all the different permutations of the original collection.
      Throws:
        `java.lang.NullPointerException` - if the specified collection is null or has any null elements.
      Since:
        12.0