Provides static methods for working with Collection instances. @author Chris Povirk @author Mike Bostock @author Jared Levy @since 2.0
| 53 | * @since 2.0 |
| 54 | */ |
| 55 | @GwtCompatible |
| 56 | public final class Collections2 { |
| 57 | private Collections2() {} |
| 58 | |
| 59 | /** |
| 60 | * Returns the elements of {@code unfiltered} that satisfy a predicate. The |
| 61 | * returned collection is a live view of {@code unfiltered}; changes to one |
| 62 | * affect the other. |
| 63 | * |
| 64 | * <p>The resulting collection's iterator does not support {@code remove()}, |
| 65 | * but all other collection methods are supported. When given an element that |
| 66 | * doesn't satisfy the predicate, the collection's {@code add()} and {@code |
| 67 | * addAll()} methods throw an {@link IllegalArgumentException}. When methods |
| 68 | * such as {@code removeAll()} and {@code clear()} are called on the filtered |
| 69 | * collection, only elements that satisfy the filter will be removed from the |
| 70 | * underlying collection. |
| 71 | * |
| 72 | * <p>The returned collection isn't threadsafe or serializable, even if |
| 73 | * {@code unfiltered} is. |
| 74 | * |
| 75 | * <p>Many of the filtered collection's methods, such as {@code size()}, |
| 76 | * iterate across every element in the underlying collection and determine |
| 77 | * which elements satisfy the filter. When a live view is <i>not</i> needed, |
| 78 | * it may be faster to copy {@code Iterables.filter(unfiltered, predicate)} |
| 79 | * and use the copy. |
| 80 | * |
| 81 | * <p><b>Warning:</b> {@code predicate} must be <i>consistent with equals</i>, |
| 82 | * as documented at {@link Predicate#apply}. Do not provide a predicate such |
| 83 | * as {@code Predicates.instanceOf(ArrayList.class)}, which is inconsistent |
| 84 | * with equals. (See {@link Iterables#filter(Iterable, Class)} for related |
| 85 | * functionality.) |
| 86 | */ |
| 87 | // TODO(kevinb): how can we omit that Iterables link when building gwt |
| 88 | // javadoc? |
| 89 | public static <E> Collection<E> filter(Collection<E> unfiltered, Predicate<? super E> predicate) { |
| 90 | if (unfiltered instanceof FilteredCollection) { |
| 91 | // Support clear(), removeAll(), and retainAll() when filtering a filtered |
| 92 | // collection. |
| 93 | return ((FilteredCollection<E>) unfiltered).createCombined(predicate); |
| 94 | } |
| 95 | |
| 96 | return new FilteredCollection<E>(checkNotNull(unfiltered), checkNotNull(predicate)); |
| 97 | } |
| 98 | |
| 99 | /** |
| 100 | * Delegates to {@link Collection#contains}. Returns {@code false} if the |
| 101 | * {@code contains} method throws a {@code ClassCastException} or |
| 102 | * {@code NullPointerException}. |
| 103 | */ |
| 104 | static boolean safeContains(Collection<?> collection, @Nullable Object object) { |
| 105 | checkNotNull(collection); |
| 106 | try { |
| 107 | return collection.contains(object); |
| 108 | } catch (ClassCastException e) { |
| 109 | return false; |
| 110 | } catch (NullPointerException e) { |
| 111 | return false; |
| 112 | } |
nothing calls this directly
no test coverage detected