/* * Copyright (C) 2007 The Guava Authors * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.common.collect; import static com.google.common.base.Preconditions.checkArgument; import static com.google.common.base.Preconditions.checkNotNull; import com.google.common.annotations.Beta; import com.google.common.annotations.GwtCompatible; import com.google.common.annotations.GwtIncompatible; import com.google.common.base.Function; import com.google.common.base.Objects; import com.google.common.base.Optional; import com.google.common.base.Preconditions; import com.google.common.base.Predicate; import java.util.Arrays; import java.util.Collection; import java.util.Collections; import java.util.Comparator; import java.util.HashSet; import java.util.Iterator; import java.util.List; import java.util.NoSuchElementException; import java.util.Queue; import java.util.RandomAccess; import java.util.Set; import java.util.SortedSet; import javax.annotation.Nullable; /** * This class contains static utility methods that operate on or return objects * of type {@code Iterable}. Except as noted, each method has a corresponding * {@link Iterator}-based method in the {@link Iterators} class. * *

Performance notes: Unless otherwise noted, all of the iterables * produced in this class are lazy, which means that their iterators * only advance the backing iteration when absolutely necessary. * * @author Kevin Bourrillion * @author Jared Levy * @since 2.0 (imported from Google Collections Library) */ @GwtCompatible(emulated = true) public final class Iterables { private Iterables() {} /** Returns an unmodifiable view of {@code iterable}. */ public static Iterable unmodifiableIterable( final Iterable iterable) { checkNotNull(iterable); if (iterable instanceof UnmodifiableIterable || iterable instanceof ImmutableCollection) { return iterable; } return new UnmodifiableIterable(iterable); } /** * Simply returns its argument. * * @deprecated no need to use this * @since 10.0 */ @Deprecated public static Iterable unmodifiableIterable( ImmutableCollection iterable) { return checkNotNull(iterable); } private static final class UnmodifiableIterable implements Iterable { private final Iterable iterable; private UnmodifiableIterable(Iterable iterable) { this.iterable = iterable; } @Override public Iterator iterator() { return Iterators.unmodifiableIterator(iterable.iterator()); } @Override public String toString() { return iterable.toString(); } // no equals and hashCode; it would break the contract! } /** * Returns the number of elements in {@code iterable}. */ public static int size(Iterable iterable) { return (iterable instanceof Collection) ? ((Collection) iterable).size() : Iterators.size(iterable.iterator()); } /** * Returns {@code true} if {@code iterable} contains {@code element}; that is, * any object for which {@code equals(element)} is true. */ public static boolean contains(Iterable iterable, @Nullable Object element) { if (iterable instanceof Collection) { Collection collection = (Collection) iterable; try { return collection.contains(element); } catch (NullPointerException e) { return false; } catch (ClassCastException e) { return false; } } return Iterators.contains(iterable.iterator(), element); } /** * Removes, from an iterable, every element that belongs to the provided * collection. * *

This method calls {@link Collection#removeAll} if {@code iterable} is a * collection, and {@link Iterators#removeAll} otherwise. * * @param removeFrom the iterable to (potentially) remove elements from * @param elementsToRemove the elements to remove * @return {@code true} if any element was removed from {@code iterable} */ public static boolean removeAll( Iterable removeFrom, Collection elementsToRemove) { return (removeFrom instanceof Collection) ? ((Collection) removeFrom).removeAll(checkNotNull(elementsToRemove)) : Iterators.removeAll(removeFrom.iterator(), elementsToRemove); } /** * Removes, from an iterable, every element that does not belong to the * provided collection. * *

This method calls {@link Collection#retainAll} if {@code iterable} is a * collection, and {@link Iterators#retainAll} otherwise. * * @param removeFrom the iterable to (potentially) remove elements from * @param elementsToRetain the elements to retain * @return {@code true} if any element was removed from {@code iterable} */ public static boolean retainAll( Iterable removeFrom, Collection elementsToRetain) { return (removeFrom instanceof Collection) ? ((Collection) removeFrom).retainAll(checkNotNull(elementsToRetain)) : Iterators.retainAll(removeFrom.iterator(), elementsToRetain); } /** * Removes, from an iterable, every element that satisfies the provided * predicate. * * @param removeFrom the iterable to (potentially) remove elements from * @param predicate a predicate that determines whether an element should * be removed * @return {@code true} if any elements were removed from the iterable * * @throws UnsupportedOperationException if the iterable does not support * {@code remove()}. * @since 2.0 */ public static boolean removeIf( Iterable removeFrom, Predicate predicate) { if (removeFrom instanceof RandomAccess && removeFrom instanceof List) { return removeIfFromRandomAccessList( (List) removeFrom, checkNotNull(predicate)); } return Iterators.removeIf(removeFrom.iterator(), predicate); } private static boolean removeIfFromRandomAccessList( List list, Predicate predicate) { // Note: Not all random access lists support set() so we need to deal with // those that don't and attempt the slower remove() based solution. int from = 0; int to = 0; for (; from < list.size(); from++) { T element = list.get(from); if (!predicate.apply(element)) { if (from > to) { try { list.set(to, element); } catch (UnsupportedOperationException e) { slowRemoveIfForRemainingElements(list, predicate, to, from); return true; } } to++; } } // Clear the tail of any remaining items list.subList(to, list.size()).clear(); return from != to; } private static void slowRemoveIfForRemainingElements(List list, Predicate predicate, int to, int from) { // Here we know that: // * (to < from) and that both are valid indices. // * Everything with (index < to) should be kept. // * Everything with (to <= index < from) should be removed. // * The element with (index == from) should be kept. // * Everything with (index > from) has not been checked yet. // Check from the end of the list backwards (minimize expected cost of // moving elements when remove() is called). Stop before 'from' because // we already know that should be kept. for (int n = list.size() - 1; n > from; n--) { if (predicate.apply(list.get(n))) { list.remove(n); } } // And now remove everything in the range [to, from) (going backwards). for (int n = from - 1; n >= to; n--) { list.remove(n); } } /** * Determines whether two iterables contain equal elements in the same order. * More specifically, this method returns {@code true} if {@code iterable1} * and {@code iterable2} contain the same number of elements and every element * of {@code iterable1} is equal to the corresponding element of * {@code iterable2}. */ public static boolean elementsEqual( Iterable iterable1, Iterable iterable2) { return Iterators.elementsEqual(iterable1.iterator(), iterable2.iterator()); } /** * Returns a string representation of {@code iterable}, with the format * {@code [e1, e2, ..., en]}. */ public static String toString(Iterable iterable) { return Iterators.toString(iterable.iterator()); } /** * Returns the single element contained in {@code iterable}. * * @throws NoSuchElementException if the iterable is empty * @throws IllegalArgumentException if the iterable contains multiple * elements */ public static T getOnlyElement(Iterable iterable) { return Iterators.getOnlyElement(iterable.iterator()); } /** * Returns the single element contained in {@code iterable}, or {@code * defaultValue} if the iterable is empty. * * @throws IllegalArgumentException if the iterator contains multiple * elements */ public static T getOnlyElement( Iterable iterable, @Nullable T defaultValue) { return Iterators.getOnlyElement(iterable.iterator(), defaultValue); } /** * Copies an iterable's elements into an array. * * @param iterable the iterable to copy * @param type the type of the elements * @return a newly-allocated array into which all the elements of the iterable * have been copied */ @GwtIncompatible("Array.newInstance(Class, int)") public static T[] toArray(Iterable iterable, Class type) { Collection collection = toCollection(iterable); T[] array = ObjectArrays.newArray(type, collection.size()); return collection.toArray(array); } /** * Copies an iterable's elements into an array. * * @param iterable the iterable to copy * @return a newly-allocated array into which all the elements of the iterable * have been copied */ static Object[] toArray(Iterable iterable) { return toCollection(iterable).toArray(); } /** * Converts an iterable into a collection. If the iterable is already a * collection, it is returned. Otherwise, an {@link java.util.ArrayList} is * created with the contents of the iterable in the same iteration order. */ private static Collection toCollection(Iterable iterable) { return (iterable instanceof Collection) ? (Collection) iterable : Lists.newArrayList(iterable.iterator()); } /** * Adds all elements in {@code iterable} to {@code collection}. * * @return {@code true} if {@code collection} was modified as a result of this * operation. */ public static boolean addAll( Collection addTo, Iterable elementsToAdd) { if (elementsToAdd instanceof Collection) { Collection c = Collections2.cast(elementsToAdd); return addTo.addAll(c); } return Iterators.addAll(addTo, elementsToAdd.iterator()); } /** * Returns the number of elements in the specified iterable that equal the * specified object. This implementation avoids a full iteration when the * iterable is a {@link Multiset} or {@link Set}. * * @see Collections#frequency */ public static int frequency(Iterable iterable, @Nullable Object element) { if ((iterable instanceof Multiset)) { return ((Multiset) iterable).count(element); } if ((iterable instanceof Set)) { return ((Set) iterable).contains(element) ? 1 : 0; } return Iterators.frequency(iterable.iterator(), element); } /** * Returns an iterable whose iterators cycle indefinitely over the elements of * {@code iterable}. * *

That iterator supports {@code remove()} if {@code iterable.iterator()} * does. After {@code remove()} is called, subsequent cycles omit the removed * element, which is no longer in {@code iterable}. The iterator's * {@code hasNext()} method returns {@code true} until {@code iterable} is * empty. * *

Warning: Typical uses of the resulting iterator may produce an * infinite loop. You should use an explicit {@code break} or be certain that * you will eventually remove all the elements. * *

To cycle over the iterable {@code n} times, use the following: * {@code Iterables.concat(Collections.nCopies(n, iterable))} */ public static Iterable cycle(final Iterable iterable) { checkNotNull(iterable); return new Iterable() { @Override public Iterator iterator() { return Iterators.cycle(iterable); } @Override public String toString() { return iterable.toString() + " (cycled)"; } }; } /** * Returns an iterable whose iterators cycle indefinitely over the provided * elements. * *

After {@code remove} is invoked on a generated iterator, the removed * element will no longer appear in either that iterator or any other iterator * created from the same source iterable. That is, this method behaves exactly * as {@code Iterables.cycle(Lists.newArrayList(elements))}. The iterator's * {@code hasNext} method returns {@code true} until all of the original * elements have been removed. * *

Warning: Typical uses of the resulting iterator may produce an * infinite loop. You should use an explicit {@code break} or be certain that * you will eventually remove all the elements. * *

To cycle over the elements {@code n} times, use the following: * {@code Iterables.concat(Collections.nCopies(n, Arrays.asList(elements)))} */ public static Iterable cycle(T... elements) { return cycle(Lists.newArrayList(elements)); } /** * Combines two iterables into a single iterable. The returned iterable has an * iterator that traverses the elements in {@code a}, followed by the elements * in {@code b}. The source iterators are not polled until necessary. * *

The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. */ @SuppressWarnings("unchecked") public static Iterable concat( Iterable a, Iterable b) { checkNotNull(a); checkNotNull(b); return concat(Arrays.asList(a, b)); } /** * Combines three iterables into a single iterable. The returned iterable has * an iterator that traverses the elements in {@code a}, followed by the * elements in {@code b}, followed by the elements in {@code c}. The source * iterators are not polled until necessary. * *

The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. */ @SuppressWarnings("unchecked") public static Iterable concat(Iterable a, Iterable b, Iterable c) { checkNotNull(a); checkNotNull(b); checkNotNull(c); return concat(Arrays.asList(a, b, c)); } /** * Combines four iterables into a single iterable. The returned iterable has * an iterator that traverses the elements in {@code a}, followed by the * elements in {@code b}, followed by the elements in {@code c}, followed by * the elements in {@code d}. The source iterators are not polled until * necessary. * *

The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. */ @SuppressWarnings("unchecked") public static Iterable concat(Iterable a, Iterable b, Iterable c, Iterable d) { checkNotNull(a); checkNotNull(b); checkNotNull(c); checkNotNull(d); return concat(Arrays.asList(a, b, c, d)); } /** * Combines multiple iterables into a single iterable. The returned iterable * has an iterator that traverses the elements of each iterable in * {@code inputs}. The input iterators are not polled until necessary. * *

The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. * * @throws NullPointerException if any of the provided iterables is null */ public static Iterable concat(Iterable... inputs) { return concat(ImmutableList.copyOf(inputs)); } /** * Combines multiple iterables into a single iterable. The returned iterable * has an iterator that traverses the elements of each iterable in * {@code inputs}. The input iterators are not polled until necessary. * *

The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. The methods of the returned * iterable may throw {@code NullPointerException} if any of the input * iterators is null. */ public static Iterable concat( final Iterable> inputs) { checkNotNull(inputs); return new IterableWithToString() { @Override public Iterator iterator() { return Iterators.concat(iterators(inputs)); } }; } /** * Returns an iterator over the iterators of the given iterables. */ private static UnmodifiableIterator> iterators( Iterable> iterables) { final Iterator> iterableIterator = iterables.iterator(); return new UnmodifiableIterator>() { @Override public boolean hasNext() { return iterableIterator.hasNext(); } @Override public Iterator next() { return iterableIterator.next().iterator(); } }; } /** * Divides an iterable into unmodifiable sublists of the given size (the final * iterable may be smaller). For example, partitioning an iterable containing * {@code [a, b, c, d, e]} with a partition size of 3 yields {@code * [[a, b, c], [d, e]]} -- an outer iterable containing two inner lists of * three and two elements, all in the original order. * *

Iterators returned by the returned iterable do not support the {@link * Iterator#remove()} method. The returned lists implement {@link * RandomAccess}, whether or not the input list does. * *

Note: if {@code iterable} is a {@link List}, use {@link * Lists#partition(List, int)} instead. * * @param iterable the iterable to return a partitioned view of * @param size the desired size of each partition (the last may be smaller) * @return an iterable of unmodifiable lists containing the elements of {@code * iterable} divided into partitions * @throws IllegalArgumentException if {@code size} is nonpositive */ public static Iterable> partition( final Iterable iterable, final int size) { checkNotNull(iterable); checkArgument(size > 0); return new IterableWithToString>() { @Override public Iterator> iterator() { return Iterators.partition(iterable.iterator(), size); } }; } /** * Divides an iterable into unmodifiable sublists of the given size, padding * the final iterable with null values if necessary. For example, partitioning * an iterable containing {@code [a, b, c, d, e]} with a partition size of 3 * yields {@code [[a, b, c], [d, e, null]]} -- an outer iterable containing * two inner lists of three elements each, all in the original order. * *

Iterators returned by the returned iterable do not support the {@link * Iterator#remove()} method. * * @param iterable the iterable to return a partitioned view of * @param size the desired size of each partition * @return an iterable of unmodifiable lists containing the elements of {@code * iterable} divided into partitions (the final iterable may have * trailing null elements) * @throws IllegalArgumentException if {@code size} is nonpositive */ public static Iterable> paddedPartition( final Iterable iterable, final int size) { checkNotNull(iterable); checkArgument(size > 0); return new IterableWithToString>() { @Override public Iterator> iterator() { return Iterators.paddedPartition(iterable.iterator(), size); } }; } /** * Returns the elements of {@code unfiltered} that satisfy a predicate. The * resulting iterable's iterator does not support {@code remove()}. */ public static Iterable filter( final Iterable unfiltered, final Predicate predicate) { checkNotNull(unfiltered); checkNotNull(predicate); return new IterableWithToString() { @Override public Iterator iterator() { return Iterators.filter(unfiltered.iterator(), predicate); } }; } /** * Returns all instances of class {@code type} in {@code unfiltered}. The * returned iterable has elements whose class is {@code type} or a subclass of * {@code type}. The returned iterable's iterator does not support * {@code remove()}. * * @param unfiltered an iterable containing objects of any type * @param type the type of elements desired * @return an unmodifiable iterable containing all elements of the original * iterable that were of the requested type */ @GwtIncompatible("Class.isInstance") public static Iterable filter( final Iterable unfiltered, final Class type) { checkNotNull(unfiltered); checkNotNull(type); return new IterableWithToString() { @Override public Iterator iterator() { return Iterators.filter(unfiltered.iterator(), type); } }; } /** * Returns {@code true} if one or more elements in {@code iterable} satisfy * the predicate. */ public static boolean any( Iterable iterable, Predicate predicate) { return Iterators.any(iterable.iterator(), predicate); } /** * Returns {@code true} if every element in {@code iterable} satisfies the * predicate. If {@code iterable} is empty, {@code true} is returned. */ public static boolean all( Iterable iterable, Predicate predicate) { return Iterators.all(iterable.iterator(), predicate); } /** * Returns the first element in {@code iterable} that satisfies the given * predicate; use this method only when such an element is known to exist. If * it is possible that no element will match, use {@link * #tryFind)} or {@link #find(Iterable, Predicate, T)} instead. * * @throws NoSuchElementException if no element in {@code iterable} matches * the given predicate */ public static T find(Iterable iterable, Predicate predicate) { return Iterators.find(iterable.iterator(), predicate); } /** * Returns the first element in {@code iterable} that satisfies the given * predicate, or {@code defaultValue} if none found. Note that this can * usually be handled more naturally using {@code * tryFind(iterable, predicate).or(defaultValue)}. * * @since 7.0 */ public static T find(Iterable iterable, Predicate predicate, @Nullable T defaultValue) { return Iterators.find(iterable.iterator(), predicate, defaultValue); } /** * Returns an {@link Optional} containing the first element in {@code * iterable} that satisfies the given predicate, if such an element exists. * *

Warning: avoid using a {@code predicate} that matches {@code * null}. If {@code null} is matched in {@code iterable}, a * NullPointerException will be thrown. * * @since 11.0 */ public static Optional tryFind(Iterable iterable, Predicate predicate) { return Iterators.tryFind(iterable.iterator(), predicate); } /** * Returns the index in {@code iterable} of the first element that satisfies * the provided {@code predicate}, or {@code -1} if the Iterable has no such * elements. * *

More formally, returns the lowest index {@code i} such that * {@code predicate.apply(Iterables.get(iterable, i))} returns {@code true}, * or {@code -1} if there is no such index. * * @since 2.0 */ public static int indexOf( Iterable iterable, Predicate predicate) { return Iterators.indexOf(iterable.iterator(), predicate); } /** * Returns an iterable that applies {@code function} to each element of {@code * fromIterable}. * *

The returned iterable's iterator supports {@code remove()} if the * provided iterator does. After a successful {@code remove()} call, * {@code fromIterable} no longer contains the corresponding element. * *

If the input {@code Iterable} is known to be a {@code List} or other * {@code Collection}, consider {@link Lists#transform} and {@link * Collections2#transform}. */ public static Iterable transform(final Iterable fromIterable, final Function function) { checkNotNull(fromIterable); checkNotNull(function); return new IterableWithToString() { @Override public Iterator iterator() { return Iterators.transform(fromIterable.iterator(), function); } }; } /** * Returns the element at the specified position in an iterable. * * @param position position of the element to return * @return the element at the specified position in {@code iterable} * @throws IndexOutOfBoundsException if {@code position} is negative or * greater than or equal to the size of {@code iterable} */ public static T get(Iterable iterable, int position) { checkNotNull(iterable); if (iterable instanceof List) { return ((List) iterable).get(position); } if (iterable instanceof Collection) { // Can check both ends Collection collection = (Collection) iterable; Preconditions.checkElementIndex(position, collection.size()); } else { // Can only check the lower end checkNonnegativeIndex(position); } return Iterators.get(iterable.iterator(), position); } private static void checkNonnegativeIndex(int position) { if (position < 0) { throw new IndexOutOfBoundsException( "position cannot be negative: " + position); } } /** * Returns the element at the specified position in an iterable or a default * value otherwise. * * @param position position of the element to return * @param defaultValue the default value to return if {@code position} is * greater than or equal to the size of the iterable * @return the element at the specified position in {@code iterable} or * {@code defaultValue} if {@code iterable} contains fewer than * {@code position + 1} elements. * @throws IndexOutOfBoundsException if {@code position} is negative * @since 4.0 */ public static T get(Iterable iterable, int position, @Nullable T defaultValue) { checkNotNull(iterable); checkNonnegativeIndex(position); try { return get(iterable, position); } catch (IndexOutOfBoundsException e) { return defaultValue; } } /** * Returns the first element in {@code iterable} or {@code defaultValue} if * the iterable is empty. The {@link Iterators} analog to this method is * {@link Iterators#getNext}. * * @param defaultValue the default value to return if the iterable is empty * @return the first element of {@code iterable} or the default value * @since 7.0 */ public static T getFirst(Iterable iterable, @Nullable T defaultValue) { return Iterators.getNext(iterable.iterator(), defaultValue); } /** * Returns the last element of {@code iterable}. * * @return the last element of {@code iterable} * @throws NoSuchElementException if the iterable is empty */ public static T getLast(Iterable iterable) { // TODO(kevinb): Support a concurrently modified collection? if (iterable instanceof List) { List list = (List) iterable; if (list.isEmpty()) { throw new NoSuchElementException(); } return getLastInNonemptyList(list); } /* * TODO(kevinb): consider whether this "optimization" is worthwhile. Users * with SortedSets tend to know they are SortedSets and probably would not * call this method. */ if (iterable instanceof SortedSet) { SortedSet sortedSet = (SortedSet) iterable; return sortedSet.last(); } return Iterators.getLast(iterable.iterator()); } /** * Returns the last element of {@code iterable} or {@code defaultValue} if * the iterable is empty. * * @param defaultValue the value to return if {@code iterable} is empty * @return the last element of {@code iterable} or the default value * @since 3.0 */ public static T getLast(Iterable iterable, @Nullable T defaultValue) { if (iterable instanceof Collection) { Collection collection = (Collection) iterable; if (collection.isEmpty()) { return defaultValue; } } if (iterable instanceof List) { List list = (List) iterable; return getLastInNonemptyList(list); } /* * TODO(kevinb): consider whether this "optimization" is worthwhile. Users * with SortedSets tend to know they are SortedSets and probably would not * call this method. */ if (iterable instanceof SortedSet) { SortedSet sortedSet = (SortedSet) iterable; return sortedSet.last(); } return Iterators.getLast(iterable.iterator(), defaultValue); } private static T getLastInNonemptyList(List list) { return list.get(list.size() - 1); } /** * Returns a view of {@code iterable} that skips its first * {@code numberToSkip} elements. If {@code iterable} contains fewer than * {@code numberToSkip} elements, the returned iterable skips all of its * elements. * *

Modifications to the underlying {@link Iterable} before a call to * {@code iterator()} are reflected in the returned iterator. That is, the * iterator skips the first {@code numberToSkip} elements that exist when the * {@code Iterator} is created, not when {@code skip()} is called. * *

The returned iterable's iterator supports {@code remove()} if the * iterator of the underlying iterable supports it. Note that it is * not possible to delete the last skipped element by immediately * calling {@code remove()} on that iterator, as the {@code Iterator} * contract states that a call to {@code remove()} before a call to * {@code next()} will throw an {@link IllegalStateException}. * * @since 3.0 */ public static Iterable skip(final Iterable iterable, final int numberToSkip) { checkNotNull(iterable); checkArgument(numberToSkip >= 0, "number to skip cannot be negative"); if (iterable instanceof List) { final List list = (List) iterable; return new IterableWithToString() { @Override public Iterator iterator() { // TODO(kevinb): Support a concurrently modified collection? return (numberToSkip >= list.size()) ? Iterators.emptyIterator() : list.subList(numberToSkip, list.size()).iterator(); } }; } return new IterableWithToString() { @Override public Iterator iterator() { final Iterator iterator = iterable.iterator(); Iterators.skip(iterator, numberToSkip); /* * We can't just return the iterator because an immediate call to its * remove() method would remove one of the skipped elements instead of * throwing an IllegalStateException. */ return new Iterator() { boolean atStart = true; @Override public boolean hasNext() { return iterator.hasNext(); } @Override public T next() { if (!hasNext()) { throw new NoSuchElementException(); } try { return iterator.next(); } finally { atStart = false; } } @Override public void remove() { if (atStart) { throw new IllegalStateException(); } iterator.remove(); } }; } }; } /** * Creates an iterable with the first {@code limitSize} elements of the given * iterable. If the original iterable does not contain that many elements, the * returned iterator will have the same behavior as the original iterable. The * returned iterable's iterator supports {@code remove()} if the original * iterator does. * * @param iterable the iterable to limit * @param limitSize the maximum number of elements in the returned iterator * @throws IllegalArgumentException if {@code limitSize} is negative * @since 3.0 */ public static Iterable limit( final Iterable iterable, final int limitSize) { checkNotNull(iterable); checkArgument(limitSize >= 0, "limit is negative"); return new IterableWithToString() { @Override public Iterator iterator() { return Iterators.limit(iterable.iterator(), limitSize); } }; } /** * Returns a view of the supplied iterable that wraps each generated * {@link Iterator} through {@link Iterators#consumingIterator(Iterator)}. * *

Note: If {@code iterable} is a {@link Queue}, the returned iterable will * get entries from {@link Queue#remove()} since {@link Queue}'s iteration * order is undefined. Calling {@link Iterator#hasNext()} on a generated * iterator from the returned iterable may cause an item to be immediately * dequeued for return on a subsequent call to {@link Iterator#next()}. * * @param iterable the iterable to wrap * @return a view of the supplied iterable that wraps each generated iterator * through {@link Iterators#consumingIterator(Iterator)}; for queues, * an iterable that generates iterators that return and consume the * queue's elements in queue order * * @see Iterators#consumingIterator(Iterator) * @since 2.0 */ public static Iterable consumingIterable(final Iterable iterable) { if (iterable instanceof Queue) { return new Iterable() { @Override public Iterator iterator() { return new ConsumingQueueIterator((Queue) iterable); } }; } checkNotNull(iterable); return new Iterable() { @Override public Iterator iterator() { return Iterators.consumingIterator(iterable.iterator()); } }; } private static class ConsumingQueueIterator extends AbstractIterator { private final Queue queue; private ConsumingQueueIterator(Queue queue) { this.queue = queue; } @Override public T computeNext() { try { return queue.remove(); } catch (NoSuchElementException e) { return endOfData(); } } } // Methods only in Iterables, not in Iterators /** * Adapts a list to an iterable with reversed iteration order. It is * especially useful in foreach-style loops:

   {@code
   *
   *   List mylist = ...
   *   for (String str : Iterables.reverse(mylist)) {
   *     ...
   *   }}
* * There is no corresponding method in {@link Iterators}, since {@link * Iterable#iterator} can simply be invoked on the result of calling this * method. * * @return an iterable with the same elements as the list, in reverse * * @deprecated use {@link Lists#reverse(List)} or {@link * ImmutableList#reverse()}. This method is scheduled for deletion in * July 2012. */ @Deprecated public static Iterable reverse(final List list) { return Lists.reverse(list); } /** * Determines if the given iterable contains no elements. * *

There is no precise {@link Iterator} equivalent to this method, since * one can only ask an iterator whether it has any elements remaining * (which one does using {@link Iterator#hasNext}). * * @return {@code true} if the iterable contains no elements */ public static boolean isEmpty(Iterable iterable) { if (iterable instanceof Collection) { return ((Collection) iterable).isEmpty(); } return !iterable.iterator().hasNext(); } // Non-public /** * Removes the specified element from the specified iterable. * *

This method iterates over the iterable, checking each element returned * by the iterator in turn to see if it equals the object {@code o}. If they * are equal, it is removed from the iterable with the iterator's * {@code remove} method. At most one element is removed, even if the iterable * contains multiple members that equal {@code o}. * *

Warning: Do not use this method for a collection, such as a * {@link HashSet}, that has a fast {@code remove} method. * * @param iterable the iterable from which to remove * @param o an element to remove from the collection * @return {@code true} if the iterable changed as a result * @throws UnsupportedOperationException if the iterator does not support the * {@code remove} method and the iterable contains the object */ static boolean remove(Iterable iterable, @Nullable Object o) { Iterator i = iterable.iterator(); while (i.hasNext()) { if (Objects.equal(i.next(), o)) { i.remove(); return true; } } return false; } abstract static class IterableWithToString implements Iterable { @Override public String toString() { return Iterables.toString(this); } } /** * Returns an iterable over the merged contents of all given * {@code iterables}. Equivalent entries will not be de-duplicated. * *

Callers must ensure that the source {@code iterables} are in * non-descending order as this method does not sort its input. * *

For any equivalent elements across all {@code iterables}, it is * undefined which element is returned first. * * @since 11.0 */ @Beta public static Iterable mergeSorted( final Iterable> iterables, final Comparator comparator) { checkNotNull(iterables, "iterables"); checkNotNull(comparator, "comparator"); Iterable iterable = new Iterable() { @Override public Iterator iterator() { return Iterators.mergeSorted( Iterables.transform(iterables, Iterables.toIterator()), comparator); } }; return new UnmodifiableIterable(iterable); } // TODO(user): Is this the best place for this? Move to fluent functions? // Useful as a public method? private static Function, Iterator> toIterator() { return new Function, Iterator>() { @Override public Iterator apply(Iterable iterable) { return iterable.iterator(); } }; } }