@GwtCompatible public final class Collections2 extends Object
Collection
instances.
Java 8 users: several common uses for this class are now more comprehensively addressed
by the new Stream
library. Read the method documentation below for
comparisons. These methods are not being deprecated, but we gently encourage you to migrate to
streams.
Modifier and Type | Method and Description |
---|---|
static <E> Collection<E> |
filter(Collection<E> unfiltered,
Predicate<? super E> predicate)
Returns the elements of
unfiltered that satisfy a predicate. |
static <E extends Comparable<? super E>> |
orderedPermutations(Iterable<E> elements)
Returns a
Collection of all the permutations of the specified Iterable . |
static <E> Collection<List<E>> |
orderedPermutations(Iterable<E> elements,
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> Collection<List<E>> |
permutations(Collection<E> elements)
Returns a
Collection of all the permutations of the specified Collection . |
static <F,T> Collection<T> |
transform(Collection<F> fromCollection,
Function<? super F,T> function)
Returns a collection that applies
function to each element of fromCollection . |
public static <E> Collection<E> filter(Collection<E> unfiltered, Predicate<? super E> predicate)
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.)
Stream
equivalent: Stream.filter
.
public static <F,T> Collection<T> transform(Collection<F> fromCollection, Function<? super F,T> function)
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>)
.
Stream
equivalent: Stream.map
.
@Beta public static <E extends Comparable<? super E>> Collection<List<E>> orderedPermutations(Iterable<E> elements)
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())
.
elements
- the original iterable whose elements have to be permuted.Collection
containing all the different permutations of the
original iterable.NullPointerException
- if the specified iterable is null or has any null elements.@Beta public static <E> Collection<List<E>> orderedPermutations(Iterable<E> elements, Comparator<? super E> comparator)
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.
elements
- the original iterable whose elements have to be permuted.comparator
- a comparator for the iterable's elements.Collection
containing all the different permutations of the
original iterable.NullPointerException
- If the specified iterable is null, has any null elements, or if
the specified comparator is null.@Beta public static <E> Collection<List<E>> permutations(Collection<E> elements)
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.
elements
- the original collection whose elements have to be permuted.Collection
containing all the different permutations of the
original collection.NullPointerException
- if the specified collection is null or has any null elements.Copyright © 2010–2020. All rights reserved.