Class Collections2
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.
- Since:
- 2.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static classprivate static final classprivate static final classprivate static final classprivate static class(package private) static class -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription(package private) static booleancontainsAllImpl(Collection<?> self, Collection<?> c) Returnstrueif the collectionselfcontains all of the elements in the collectionc.static <E> Collection<E> filter(Collection<E> unfiltered, Predicate<? super E> predicate) Returns the elements ofunfilteredthat satisfy a predicate.private static booleanisPermutation(List<?> first, List<?> second) Returnstrueif the second list is a permutation of the first.(package private) static StringBuildernewStringBuilderForCollection(int size) Returns best-effort-sized StringBuilder based on the given collection size.static <E extends Comparable<? super E>>
Collection<List<E>> orderedPermutations(Iterable<E> elements) Returns aCollectionof all the permutations of the specifiedIterable.static <E> Collection<List<E>> orderedPermutations(Iterable<E> elements, Comparator<? super E> comparator) Returns aCollectionof all the permutations of the specifiedIterableusing the specifiedComparatorfor establishing the lexicographical ordering.static <E> Collection<List<E>> permutations(Collection<E> elements) Returns aCollectionof all the permutations of the specifiedCollection.(package private) static booleansafeContains(Collection<?> collection, Object object) Delegates toCollection.contains(java.lang.Object).(package private) static booleansafeRemove(Collection<?> collection, Object object) Delegates toCollection.remove(java.lang.Object).(package private) static StringtoStringImpl(Collection<?> collection) An implementation of.invalid reference
Collection#toString()static <F,T> Collection <T> transform(Collection<F> fromCollection, Function<? super F, T> function) Returns a collection that appliesfunctionto each element offromCollection.
-
Constructor Details
-
Collections2
private Collections2()
-
-
Method Details
-
filter
Returns the elements ofunfilteredthat satisfy a predicate. The returned collection is a live view ofunfiltered; 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'sadd()andaddAll()methods throw anIllegalArgumentException. When methods such asremoveAll()andclear()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
unfilteredis.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 copyIterables.filter(unfiltered, predicate)and use the copy.Warning:
predicatemust be consistent with equals, as documented atPredicate.apply(T). Do not provide a predicate such asPredicates.instanceOf(ArrayList.class), which is inconsistent with equals. (SeeIterables.filter(Iterable, Class)for related functionality.)Streamequivalent:Stream.filter. -
safeContains
Delegates toCollection.contains(java.lang.Object). Returnsfalseif thecontainsmethod throws aClassCastExceptionorNullPointerException. -
safeRemove
Delegates toCollection.remove(java.lang.Object). Returnsfalseif theremovemethod throws aClassCastExceptionorNullPointerException. -
transform
public static <F,T> Collection<T> transform(Collection<F> fromCollection, Function<? super F, T> function) Returns a collection that appliesfunctionto each element offromCollection. The returned collection is a live view offromCollection; changes to one affect the other.The returned collection's
add()andaddAll()methods throw anUnsupportedOperationException. All other collection methods are supported, as long asfromCollectionsupports them.The returned collection isn't threadsafe or serializable, even if
fromCollectionis.When a live view is not needed, it may be faster to copy the transformed collection and use the copy.
If the input
Collectionis known to be aList, considerLists.transform(java.util.List<F>, com.google.common.base.Function<? super F, ? extends T>). If only anIterableis available, useIterables.transform(java.lang.Iterable<F>, com.google.common.base.Function<? super F, ? extends T>).Streamequivalent:Stream.map. -
containsAllImpl
Returnstrueif the collectionselfcontains all of the elements in the collectionc.This method iterates over the specified collection
c, checking each element returned by the iterator in turn to see if it is contained in the specified collectionself. If all elements are so contained,trueis returned, otherwisefalse.- Parameters:
self- a collection which might contain all elements incc- a collection whose elements might be contained byself
-
toStringImpl
An implementation of.invalid reference
Collection#toString() -
newStringBuilderForCollection
Returns best-effort-sized StringBuilder based on the given collection size. -
orderedPermutations
public static <E extends Comparable<? super E>> Collection<List<E>> orderedPermutations(Iterable<E> elements) Returns aCollectionof all the permutations of the specifiedIterable.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
Collectioncontaining all the different permutations of the original iterable. - Throws:
NullPointerException- if the specified iterable is null or has any null elements.- Since:
- 12.0
-
orderedPermutations
public static <E> Collection<List<E>> orderedPermutations(Iterable<E> elements, Comparator<? super E> comparator) Returns aCollectionof all the permutations of the specifiedIterableusing the specifiedComparatorfor 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
Collectioncontaining all the different permutations of the original iterable. - Throws:
NullPointerException- If the specified iterable is null, has any null elements, or if the specified comparator is null.- Since:
- 12.0
-
permutations
Returns aCollectionof all the permutations of the specifiedCollection.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
Collectioncontaining all the different permutations of the original collection. - Throws:
NullPointerException- if the specified collection is null or has any null elements.- Since:
- 12.0
-
isPermutation
Returnstrueif the second list is a permutation of the first.
-