001 /*
002 * Copyright (C) 2008 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package com.google.common.collect;
018
019 import static com.google.common.base.Preconditions.checkArgument;
020 import static com.google.common.base.Preconditions.checkNotNull;
021 import static com.google.common.math.LongMath.binomial;
022
023 import com.google.common.annotations.Beta;
024 import com.google.common.annotations.GwtCompatible;
025 import com.google.common.base.Function;
026 import com.google.common.base.Joiner;
027 import com.google.common.base.Predicate;
028 import com.google.common.base.Predicates;
029 import com.google.common.math.IntMath;
030 import com.google.common.primitives.Ints;
031
032 import java.util.AbstractCollection;
033 import java.util.ArrayList;
034 import java.util.Collection;
035 import java.util.Collections;
036 import java.util.Comparator;
037 import java.util.Iterator;
038 import java.util.List;
039
040 import javax.annotation.Nullable;
041
042 /**
043 * Provides static methods for working with {@code Collection} instances.
044 *
045 * @author Chris Povirk
046 * @author Mike Bostock
047 * @author Jared Levy
048 * @since 2.0 (imported from Google Collections Library)
049 */
050 @GwtCompatible
051 public final class Collections2 {
052 private Collections2() {}
053
054 /**
055 * Returns the elements of {@code unfiltered} that satisfy a predicate. The
056 * returned collection is a live view of {@code unfiltered}; changes to one
057 * affect the other.
058 *
059 * <p>The resulting collection's iterator does not support {@code remove()},
060 * but all other collection methods are supported. When given an element that
061 * doesn't satisfy the predicate, the collection's {@code add()} and {@code
062 * addAll()} methods throw an {@link IllegalArgumentException}. When methods
063 * such as {@code removeAll()} and {@code clear()} are called on the filtered
064 * collection, only elements that satisfy the filter will be removed from the
065 * underlying collection.
066 *
067 * <p>The returned collection isn't threadsafe or serializable, even if
068 * {@code unfiltered} is.
069 *
070 * <p>Many of the filtered collection's methods, such as {@code size()},
071 * iterate across every element in the underlying collection and determine
072 * which elements satisfy the filter. When a live view is <i>not</i> needed,
073 * it may be faster to copy {@code Iterables.filter(unfiltered, predicate)}
074 * and use the copy.
075 *
076 * <p><b>Warning:</b> {@code predicate} must be <i>consistent with equals</i>,
077 * as documented at {@link Predicate#apply}. Do not provide a predicate such
078 * as {@code Predicates.instanceOf(ArrayList.class)}, which is inconsistent
079 * with equals. (See {@link Iterables#filter(Iterable, Class)} for related
080 * functionality.)
081 */
082 // TODO(kevinb): how can we omit that Iterables link when building gwt
083 // javadoc?
084 public static <E> Collection<E> filter(
085 Collection<E> unfiltered, Predicate<? super E> predicate) {
086 if (unfiltered instanceof FilteredCollection) {
087 // Support clear(), removeAll(), and retainAll() when filtering a filtered
088 // collection.
089 return ((FilteredCollection<E>) unfiltered).createCombined(predicate);
090 }
091
092 return new FilteredCollection<E>(
093 checkNotNull(unfiltered), checkNotNull(predicate));
094 }
095
096 /**
097 * Delegates to {@link Collection#contains}. Returns {@code false} if the
098 * {@code contains} method throws a {@code ClassCastException}.
099 */
100 static boolean safeContains(Collection<?> collection, Object object) {
101 try {
102 return collection.contains(object);
103 } catch (ClassCastException e) {
104 return false;
105 }
106 }
107
108 static class FilteredCollection<E> implements Collection<E> {
109 final Collection<E> unfiltered;
110 final Predicate<? super E> predicate;
111
112 FilteredCollection(Collection<E> unfiltered,
113 Predicate<? super E> predicate) {
114 this.unfiltered = unfiltered;
115 this.predicate = predicate;
116 }
117
118 FilteredCollection<E> createCombined(Predicate<? super E> newPredicate) {
119 return new FilteredCollection<E>(unfiltered,
120 Predicates.<E>and(predicate, newPredicate));
121 // .<E> above needed to compile in JDK 5
122 }
123
124 public boolean add(E element) {
125 checkArgument(predicate.apply(element));
126 return unfiltered.add(element);
127 }
128
129 public boolean addAll(Collection<? extends E> collection) {
130 for (E element : collection) {
131 checkArgument(predicate.apply(element));
132 }
133 return unfiltered.addAll(collection);
134 }
135
136 public void clear() {
137 Iterables.removeIf(unfiltered, predicate);
138 }
139
140 public boolean contains(Object element) {
141 try {
142 // unsafe cast can result in a CCE from predicate.apply(), which we
143 // will catch
144 @SuppressWarnings("unchecked")
145 E e = (E) element;
146
147 /*
148 * We check whether e satisfies the predicate, when we really mean to
149 * check whether the element contained in the set does. This is ok as
150 * long as the predicate is consistent with equals, as required.
151 */
152 return predicate.apply(e) && unfiltered.contains(element);
153 } catch (NullPointerException e) {
154 return false;
155 } catch (ClassCastException e) {
156 return false;
157 }
158 }
159
160 public boolean containsAll(Collection<?> collection) {
161 for (Object element : collection) {
162 if (!contains(element)) {
163 return false;
164 }
165 }
166 return true;
167 }
168
169 public boolean isEmpty() {
170 return !Iterators.any(unfiltered.iterator(), predicate);
171 }
172
173 public Iterator<E> iterator() {
174 return Iterators.filter(unfiltered.iterator(), predicate);
175 }
176
177 public boolean remove(Object element) {
178 try {
179 // unsafe cast can result in a CCE from predicate.apply(), which we
180 // will catch
181 @SuppressWarnings("unchecked")
182 E e = (E) element;
183
184 // See comment in contains() concerning predicate.apply(e)
185 return predicate.apply(e) && unfiltered.remove(element);
186 } catch (NullPointerException e) {
187 return false;
188 } catch (ClassCastException e) {
189 return false;
190 }
191 }
192
193 public boolean removeAll(final Collection<?> collection) {
194 checkNotNull(collection);
195 Predicate<E> combinedPredicate = new Predicate<E>() {
196 public boolean apply(E input) {
197 return predicate.apply(input) && collection.contains(input);
198 }
199 };
200 return Iterables.removeIf(unfiltered, combinedPredicate);
201 }
202
203 public boolean retainAll(final Collection<?> collection) {
204 checkNotNull(collection);
205 Predicate<E> combinedPredicate = new Predicate<E>() {
206 public boolean apply(E input) {
207 // See comment in contains() concerning predicate.apply(e)
208 return predicate.apply(input) && !collection.contains(input);
209 }
210 };
211 return Iterables.removeIf(unfiltered, combinedPredicate);
212 }
213
214 public int size() {
215 return Iterators.size(iterator());
216 }
217
218 public Object[] toArray() {
219 // creating an ArrayList so filtering happens once
220 return Lists.newArrayList(iterator()).toArray();
221 }
222
223 public <T> T[] toArray(T[] array) {
224 return Lists.newArrayList(iterator()).toArray(array);
225 }
226
227
228 @Override
229 public String toString() {
230 return Iterators.toString(iterator());
231 }
232 }
233
234 /**
235 * Returns a collection that applies {@code function} to each element of
236 * {@code fromCollection}. The returned collection is a live view of {@code
237 * fromCollection}; changes to one affect the other.
238 *
239 * <p>The returned collection's {@code add()} and {@code addAll()} methods
240 * throw an {@link UnsupportedOperationException}. All other collection
241 * methods are supported, as long as {@code fromCollection} supports them.
242 *
243 * <p>The returned collection isn't threadsafe or serializable, even if
244 * {@code fromCollection} is.
245 *
246 * <p>When a live view is <i>not</i> needed, it may be faster to copy the
247 * transformed collection and use the copy.
248 *
249 * <p>If the input {@code Collection} is known to be a {@code List}, consider
250 * {@link Lists#transform}. If only an {@code Iterable} is available, use
251 * {@link Iterables#transform}.
252 */
253 public static <F, T> Collection<T> transform(Collection<F> fromCollection,
254 Function<? super F, T> function) {
255 return new TransformedCollection<F, T>(fromCollection, function);
256 }
257
258 static class TransformedCollection<F, T> extends AbstractCollection<T> {
259 final Collection<F> fromCollection;
260 final Function<? super F, ? extends T> function;
261
262 TransformedCollection(Collection<F> fromCollection,
263 Function<? super F, ? extends T> function) {
264 this.fromCollection = checkNotNull(fromCollection);
265 this.function = checkNotNull(function);
266 }
267
268
269 @Override
270 public void clear() {
271 fromCollection.clear();
272 }
273
274
275 @Override
276 public boolean isEmpty() {
277 return fromCollection.isEmpty();
278 }
279
280
281 @Override
282 public Iterator<T> iterator() {
283 return Iterators.transform(fromCollection.iterator(), function);
284 }
285
286
287 @Override
288 public int size() {
289 return fromCollection.size();
290 }
291 }
292
293 /**
294 * Returns {@code true} if the collection {@code self} contains all of the
295 * elements in the collection {@code c}.
296 *
297 * <p>This method iterates over the specified collection {@code c}, checking
298 * each element returned by the iterator in turn to see if it is contained in
299 * the specified collection {@code self}. If all elements are so contained,
300 * {@code true} is returned, otherwise {@code false}.
301 *
302 * @param self a collection which might contain all elements in {@code c}
303 * @param c a collection whose elements might be contained by {@code self}
304 */
305 static boolean containsAllImpl(Collection<?> self, Collection<?> c) {
306 checkNotNull(self);
307 for (Object o : c) {
308 if (!self.contains(o)) {
309 return false;
310 }
311 }
312 return true;
313 }
314
315 /**
316 * An implementation of {@link Collection#toString()}.
317 */
318 static String toStringImpl(final Collection<?> collection) {
319 StringBuilder sb
320 = newStringBuilderForCollection(collection.size()).append('[');
321 STANDARD_JOINER.appendTo(
322 sb, Iterables.transform(collection, new Function<Object, Object>() {
323 public Object apply(Object input) {
324 return input == collection ? "(this Collection)" : input;
325 }
326 }));
327 return sb.append(']').toString();
328 }
329
330 /**
331 * Returns best-effort-sized StringBuilder based on the given collection size.
332 */
333 static StringBuilder newStringBuilderForCollection(int size) {
334 checkArgument(size >= 0, "size must be non-negative");
335 return new StringBuilder((int) Math.min(size * 8L, Ints.MAX_POWER_OF_TWO));
336 }
337
338 /**
339 * Used to avoid http://bugs.sun.com/view_bug.do?bug_id=6558557
340 */
341 static <T> Collection<T> cast(Iterable<T> iterable) {
342 return (Collection<T>) iterable;
343 }
344
345 static final Joiner STANDARD_JOINER = Joiner.on(", ").useForNull("null");
346
347 /**
348 * Returns a {@link Collection} of all the permutations of the specified
349 * {@link Iterable}.
350 *
351 * <p><i>Notes:</i> This is an implementation of the algorithm for
352 * Lexicographical Permutations Generation, described in Knuth's "The Art of
353 * Computer Programming", Volume 4, Chapter 7, Section 7.2.1.2. The
354 * iteration order follows the lexicographical order. This means that
355 * the first permutation will be in ascending order, and the last will be in
356 * descending order.
357 *
358 * <p>Duplicate elements are considered equal. For example, the list [1, 1]
359 * will have only one permutation, instead of two. This is why the elements
360 * have to implement {@link Comparable}.
361 *
362 * <p>An empty iterable has only one permutation, which is an empty list.
363 *
364 * <p>This method is equivalent to
365 * {@code Collections2.orderedPermutations(list, Ordering.natural())}.
366 *
367 * @param elements the original iterable whose elements have to be permuted.
368 * @return an immutable {@link Collection} containing all the different
369 * permutations of the original iterable.
370 * @throws NullPointerException if the specified iterable is null or has any
371 * null elements.
372 * @since 12.0
373 */
374 @Beta public static <E extends Comparable<? super E>>
375 Collection<List<E>> orderedPermutations(Iterable<E> elements) {
376 return orderedPermutations(elements, Ordering.natural());
377 }
378
379 /**
380 * Returns a {@link Collection} of all the permutations of the specified
381 * {@link Iterable} using the specified {@link Comparator} for establishing
382 * the lexicographical ordering.
383 *
384 * <p>Examples: <pre> {@code
385 *
386 * for (List<String> perm : orderedPermutations(asList("b", "c", "a"))) {
387 * println(perm);
388 * }
389 * // -> ["a", "b", "c"]
390 * // -> ["a", "c", "b"]
391 * // -> ["b", "a", "c"]
392 * // -> ["b", "c", "a"]
393 * // -> ["c", "a", "b"]
394 * // -> ["c", "b", "a"]
395 *
396 * for (List<Integer> perm : orderedPermutations(asList(1, 2, 2, 1))) {
397 * println(perm);
398 * }
399 * // -> [1, 1, 2, 2]
400 * // -> [1, 2, 1, 2]
401 * // -> [1, 2, 2, 1]
402 * // -> [2, 1, 1, 2]
403 * // -> [2, 1, 2, 1]
404 * // -> [2, 2, 1, 1]}</pre>
405 *
406 * <p><i>Notes:</i> This is an implementation of the algorithm for
407 * Lexicographical Permutations Generation, described in Knuth's "The Art of
408 * Computer Programming", Volume 4, Chapter 7, Section 7.2.1.2. The
409 * iteration order follows the lexicographical order. This means that
410 * the first permutation will be in ascending order, and the last will be in
411 * descending order.
412 *
413 * <p>Elements that compare equal are considered equal and no new permutations
414 * are created by swapping them.
415 *
416 * <p>An empty iterable has only one permutation, which is an empty list.
417 *
418 * @param elements the original iterable whose elements have to be permuted.
419 * @param comparator a comparator for the iterable's elements.
420 * @return an immutable {@link Collection} containing all the different
421 * permutations of the original iterable.
422 * @throws NullPointerException If the specified iterable is null, has any
423 * null elements, or if the specified comparator is null.
424 * @since 12.0
425 */
426 @Beta public static <E> Collection<List<E>> orderedPermutations(
427 Iterable<E> elements, Comparator<? super E> comparator) {
428 return new OrderedPermutationCollection<E>(elements, comparator);
429 }
430
431 private static final class OrderedPermutationCollection<E>
432 extends AbstractCollection<List<E>> {
433 final ImmutableList<E> inputList;
434 final Comparator<? super E> comparator;
435 final int size;
436
437 OrderedPermutationCollection(Iterable<E> input,
438 Comparator<? super E> comparator) {
439 this.inputList = Ordering.from(comparator).immutableSortedCopy(input);
440 this.comparator = comparator;
441 this.size = calculateSize(inputList, comparator);
442 }
443
444 /**
445 * The number of permutations with repeated elements is calculated as
446 * follows:
447 * <ul>
448 * <li>For an empty list, it is 1 (base case).</li>
449 * <li>When r numbers are added to a list of n-r elements, the number of
450 * permutations is increased by a factor of (n choose r).</li>
451 * </ul>
452 */
453 private static <E> int calculateSize(
454 List<E> sortedInputList, Comparator<? super E> comparator) {
455 long permutations = 1;
456 int n = 1;
457 int r = 1;
458 while (n < sortedInputList.size()) {
459 int comparison = comparator.compare(
460 sortedInputList.get(n - 1), sortedInputList.get(n));
461 if (comparison < 0) {
462 // We move to the next non-repeated element.
463 permutations *= binomial(n, r);
464 r = 0;
465 if (!isPositiveInt(permutations)) {
466 return Integer.MAX_VALUE;
467 }
468 }
469 n++;
470 r++;
471 }
472 permutations *= binomial(n, r);
473 if (!isPositiveInt(permutations)) {
474 return Integer.MAX_VALUE;
475 }
476 return (int) permutations;
477 }
478
479
480 @Override
481 public int size() {
482 return size;
483 }
484
485
486 @Override
487 public boolean isEmpty() {
488 return false;
489 }
490
491
492 @Override
493 public Iterator<List<E>> iterator() {
494 return new OrderedPermutationIterator<E>(inputList, comparator);
495 }
496
497 @Override
498 public boolean contains(@Nullable Object obj) {
499 if (obj instanceof List) {
500 List<?> list = (List<?>) obj;
501 return isPermutation(inputList, list);
502 }
503 return false;
504 }
505
506
507 @Override
508 public String toString() {
509 return "orderedPermutationCollection(" + inputList + ")";
510 }
511 }
512
513 private static final class OrderedPermutationIterator<E>
514 extends AbstractIterator<List<E>> {
515
516 List<E> nextPermutation;
517 final Comparator<? super E> comparator;
518
519 OrderedPermutationIterator(List<E> list,
520 Comparator<? super E> comparator) {
521 this.nextPermutation = Lists.newArrayList(list);
522 this.comparator = comparator;
523 }
524
525
526 @Override
527 protected List<E> computeNext() {
528 if (nextPermutation == null) {
529 return endOfData();
530 }
531 ImmutableList<E> next = ImmutableList.copyOf(nextPermutation);
532 calculateNextPermutation();
533 return next;
534 }
535
536 void calculateNextPermutation() {
537 int j = findNextJ();
538 if (j == -1) {
539 nextPermutation = null;
540 return;
541 }
542
543 int l = findNextL(j);
544 Collections.swap(nextPermutation, j, l);
545 int n = nextPermutation.size();
546 Collections.reverse(nextPermutation.subList(j + 1, n));
547 }
548
549 int findNextJ() {
550 for (int k = nextPermutation.size() - 2; k >= 0; k--) {
551 if (comparator.compare(nextPermutation.get(k),
552 nextPermutation.get(k + 1)) < 0) {
553 return k;
554 }
555 }
556 return -1;
557 }
558
559 int findNextL(int j) {
560 E ak = nextPermutation.get(j);
561 for (int l = nextPermutation.size() - 1; l > j; l--) {
562 if (comparator.compare(ak, nextPermutation.get(l)) < 0) {
563 return l;
564 }
565 }
566 throw new AssertionError("this statement should be unreachable");
567 }
568 }
569
570 /**
571 * Returns a {@link Collection} of all the permutations of the specified
572 * {@link Collection}.
573 *
574 * <p><i>Notes:</i> This is an implementation of the Plain Changes algorithm
575 * for permutations generation, described in Knuth's "The Art of Computer
576 * Programming", Volume 4, Chapter 7, Section 7.2.1.2.
577 *
578 * <p>If the input list contains equal elements, some of the generated
579 * permutations will be equal.
580 *
581 * <p>An empty collection has only one permutation, which is an empty list.
582 *
583 * @param elements the original collection whose elements have to be permuted.
584 * @return an immutable {@link Collection} containing all the different
585 * permutations of the original collection.
586 * @throws NullPointerException if the specified collection is null or has any
587 * null elements.
588 * @since 12.0
589 */
590 @Beta public static <E> Collection<List<E>> permutations(
591 Collection<E> elements) {
592 return new PermutationCollection<E>(ImmutableList.copyOf(elements));
593 }
594
595 private static final class PermutationCollection<E>
596 extends AbstractCollection<List<E>> {
597 final ImmutableList<E> inputList;
598
599 PermutationCollection(ImmutableList<E> input) {
600 this.inputList = input;
601 }
602
603
604 @Override
605 public int size() {
606 return IntMath.factorial(inputList.size());
607 }
608
609
610 @Override
611 public boolean isEmpty() {
612 return false;
613 }
614
615
616 @Override
617 public Iterator<List<E>> iterator() {
618 return new PermutationIterator<E>(inputList);
619 }
620
621 @Override
622 public boolean contains(@Nullable Object obj) {
623 if (obj instanceof List) {
624 List<?> list = (List<?>) obj;
625 return isPermutation(inputList, list);
626 }
627 return false;
628 }
629
630
631 @Override
632 public String toString() {
633 return "permutations(" + inputList + ")";
634 }
635 }
636
637 private static class PermutationIterator<E>
638 extends AbstractIterator<List<E>> {
639 final List<E> list;
640 final int[] c;
641 final int[] o;
642 int j;
643
644 PermutationIterator(List<E> list) {
645 this.list = new ArrayList<E>(list);
646 int n = list.size();
647 c = new int[n];
648 o = new int[n];
649 for (int i = 0; i < n; i++) {
650 c[i] = 0;
651 o[i] = 1;
652 }
653 j = Integer.MAX_VALUE;
654 }
655
656
657 @Override
658 protected List<E> computeNext() {
659 if (j <= 0) {
660 return endOfData();
661 }
662 ImmutableList<E> next = ImmutableList.copyOf(list);
663 calculateNextPermutation();
664 return next;
665 }
666
667 void calculateNextPermutation() {
668 j = list.size() - 1;
669 int s = 0;
670
671 // Handle the special case of an empty list. Skip the calculation of the
672 // next permutation.
673 if (j == -1) {
674 return;
675 }
676
677 while (true) {
678 int q = c[j] + o[j];
679 if (q < 0) {
680 switchDirection();
681 continue;
682 }
683 if (q == j + 1) {
684 if (j == 0) {
685 break;
686 }
687 s++;
688 switchDirection();
689 continue;
690 }
691
692 Collections.swap(list, j - c[j] + s, j - q + s);
693 c[j] = q;
694 break;
695 }
696 }
697
698 void switchDirection() {
699 o[j] = -o[j];
700 j--;
701 }
702 }
703
704 /**
705 * Returns {@code true} if the second list is a permutation of the first.
706 */
707 private static boolean isPermutation(List<?> first,
708 List<?> second) {
709 if (first.size() != second.size()) {
710 return false;
711 }
712 Multiset<?> firstSet = HashMultiset.create(first);
713 Multiset<?> secondSet = HashMultiset.create(second);
714 return firstSet.equals(secondSet);
715 }
716
717 private static boolean isPositiveInt(long n) {
718 return n >= 0 && n <= Integer.MAX_VALUE;
719 }
720 }