Class Iterables
Iterable. Except as noted, each method has a corresponding Iterator-based method
in the Iterators class.
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. This class is not being deprecated, but we gently encourage you to migrate to
streams.
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.
See the Guava User Guide article on
Iterables.
- Since:
- 2.0
-
Nested Class Summary
Nested Classes -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic <T> booleanaddAll(Collection<T> addTo, Iterable<? extends T> elementsToAdd) Adds all elements initerabletocollection.static <T> booleanReturnstrueif every element initerablesatisfies the predicate.static <T> booleanReturnstrueif any element initerablesatisfies the predicate.private static <E> Collection<E>castOrCopyToCollection(Iterable<E> iterable) Converts an iterable into a collection.static <T> Iterable<T>Combines multiple iterables into a single iterable.static <T> Iterable<T>Combines multiple iterables into a single iterable.static <T> Iterable<T>Combines two iterables into a single iterable.static <T> Iterable<T>Combines three iterables into a single iterable.static <T> Iterable<T>concat(Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c, Iterable<? extends T> d) Combines four iterables into a single iterable.static <T> Iterable<T>consumingIterable(Iterable<T> iterable) Returns a view of the supplied iterable that wraps each generatedIteratorthroughIterators.consumingIterator(Iterator).static booleanReturnstrueifiterablecontains any elementofor whichObjects.equals(o, element)would returntrue.static <T> Iterable<T>Returns an iterable whose iterators cycle indefinitely over the elements ofiterable.static <T> Iterable<T>cycle(T... elements) Returns an iterable whose iterators cycle indefinitely over the provided elements.static booleanelementsEqual(Iterable<?> iterable1, Iterable<?> iterable2) Determines whether two iterables contain equal elements in the same order.static <T> Iterable<T>Returns a view ofunfilteredcontaining all elements that are of the typedesiredType.static <T> Iterable<T>Returns a view ofunfilteredcontaining all elements that satisfy the input predicateretainIfTrue.static <T> TReturns the first element initerablethat satisfies the given predicate, ordefaultValueif none found.static <T> TReturns the first element initerablethat satisfies the given predicate; use this method only when such an element is known to exist.static intReturns the number of elements in the specified iterable that equal the specified object.static <T> TReturns the element at the specified position in an iterable or a default value otherwise.static <T> TReturns the element at the specified position in an iterable.static <T> TReturns the first element initerableordefaultValueif the iterable is empty.static <T> TReturns the last element ofiterableordefaultValueif the iterable is empty.static <T> TReturns the last element ofiterable.private static <T> TgetLastInNonemptyList(List<T> list) static <T> TgetOnlyElement(Iterable<? extends T> iterable, T defaultValue) Returns the single element contained initerable, ordefaultValueif the iterable is empty.static <T> TgetOnlyElement(Iterable<T> iterable) Returns the single element contained initerable.static <T> intReturns the index initerableof the first element that satisfies the providedpredicate, or-1if the Iterable has no such elements.static booleanDetermines if the given iterable contains no elements.static <T> Iterable<T>Returns a view ofiterablecontaining its firstlimitSizeelements.static <T> Iterable<T>mergeSorted(Iterable<? extends Iterable<? extends T>> iterables, Comparator<? super T> comparator) Returns an iterable over the merged contents of all giveniterables.paddedPartition(Iterable<T> iterable, int size) Divides an iterable into unmodifiable sublists of the given size, padding the final iterable with null values if necessary.Divides an iterable into unmodifiable sublists of the given size (the final iterable may be smaller).static booleanremoveAll(Iterable<?> removeFrom, Collection<?> elementsToRemove) Removes, from an iterable, every element that belongs to the provided collection.(package private) static <T> TremoveFirstMatching(Iterable<T> removeFrom, Predicate<? super T> predicate) Removes and returns the first matching element, or returnsnullif there is none.static <T> booleanRemoves, from an iterable, every element that satisfies the provided predicate.static booleanretainAll(Iterable<?> removeFrom, Collection<?> elementsToRetain) Removes, from an iterable, every element that does not belong to the provided collection.static intReturns the number of elements initerable.static <T> Iterable<T>Returns a view ofiterablethat skips its firstnumberToSkipelements.(package private) static Object[]Copies an iterable's elements into an array.static <T> T[]Copies an iterable's elements into an array.(package private) static <T> T[]static StringReturns a string representation ofiterable, with the format[e1, e2, ..., en](that is, identical toArrays.toString(Iterables.toArray(iterable))).static <F,T> Iterable<T> Returns a view containing the result of applyingfunctionto each element offromIterable.static <T> Optional<T>Returns anOptionalcontaining the first element initerablethat satisfies the given predicate, if such an element exists.static <E> Iterable<E>unmodifiableIterable(ImmutableCollection<E> iterable) Deprecated.no need to use thisstatic <T> Iterable<T>unmodifiableIterable(Iterable<? extends T> iterable) Returns an unmodifiable view ofiterable.
-
Constructor Details
-
Iterables
private Iterables()
-
-
Method Details
-
unmodifiableIterable
Returns an unmodifiable view ofiterable. -
unmodifiableIterable
Deprecated.no need to use thisSimply returns its argument.- Since:
- 10.0
-
size
Returns the number of elements initerable. -
contains
Returnstrueifiterablecontains any elementofor whichObjects.equals(o, element)would returntrue. Otherwise returnsfalse, even in cases whereCollection.contains(java.lang.Object)might throwNullPointerExceptionorClassCastException. -
removeAll
Removes, from an iterable, every element that belongs to the provided collection.This method calls
Collection.removeAll(java.util.Collection<?>)ifiterableis a collection, andIterators.removeAll(java.util.Iterator<?>, java.util.Collection<?>)otherwise.- Parameters:
removeFrom- the iterable to (potentially) remove elements fromelementsToRemove- the elements to remove- Returns:
trueif any element was removed fromiterable
-
retainAll
Removes, from an iterable, every element that does not belong to the provided collection.This method calls
Collection.retainAll(java.util.Collection<?>)ifiterableis a collection, andIterators.retainAll(java.util.Iterator<?>, java.util.Collection<?>)otherwise.- Parameters:
removeFrom- the iterable to (potentially) remove elements fromelementsToRetain- the elements to retain- Returns:
trueif any element was removed fromiterable
-
removeIf
Removes, from an iterable, every element that satisfies the provided predicate.Removals may or may not happen immediately as each element is tested against the predicate. The behavior of this method is not specified if
predicateis dependent onremoveFrom.Java 8 users: if
removeFromis aCollection, useremoveFrom.removeIf(predicate)instead.- Parameters:
removeFrom- the iterable to (potentially) remove elements frompredicate- a predicate that determines whether an element should be removed- Returns:
trueif any elements were removed from the iterable- Throws:
UnsupportedOperationException- if the iterable does not supportremove().- Since:
- 2.0
-
removeFirstMatching
@CheckForNull static <T> T removeFirstMatching(Iterable<T> removeFrom, Predicate<? super T> predicate) Removes and returns the first matching element, or returnsnullif there is none. -
elementsEqual
Determines whether two iterables contain equal elements in the same order. More specifically, this method returnstrueifiterable1anditerable2contain the same number of elements and every element ofiterable1is equal to the corresponding element ofiterable2. -
toString
Returns a string representation ofiterable, with the format[e1, e2, ..., en](that is, identical toArrays.toString(Iterables.toArray(iterable))). Note that for most implementations ofCollection,collection.toString()also gives the same result, but that behavior is not generally guaranteed. -
getOnlyElement
Returns the single element contained initerable.Java 8 users: the
Streamequivalent to this method isstream.collect(MoreCollectors.onlyElement()).- Throws:
NoSuchElementException- if the iterable is emptyIllegalArgumentException- if the iterable contains multiple elements
-
getOnlyElement
Returns the single element contained initerable, ordefaultValueif the iterable is empty.Java 8 users: the
Streamequivalent to this method isstream.collect(MoreCollectors.toOptional()).orElse(defaultValue).- Throws:
IllegalArgumentException- if the iterator contains multiple elements
-
toArray
Copies an iterable's elements into an array.- Parameters:
iterable- the iterable to copytype- the type of the elements- Returns:
- a newly-allocated array into which all the elements of the iterable have been copied
-
toArray
-
toArray
Copies an iterable's elements into an array.- Parameters:
iterable- the iterable to copy- Returns:
- a newly-allocated array into which all the elements of the iterable have been copied
-
castOrCopyToCollection
Converts an iterable into a collection. If the iterable is already a collection, it is returned. Otherwise, anArrayListis created with the contents of the iterable in the same iteration order. -
addAll
Adds all elements initerabletocollection.- Returns:
trueifcollectionwas modified as a result of this operation.
-
frequency
Returns the number of elements in the specified iterable that equal the specified object. This implementation avoids a full iteration when the iterable is aMultisetorSet.Java 8 users: In most cases, the
Streamequivalent of this method isstream.filter(element::equals).count(). Ifelementmight be null, usestream.filter(Predicate.isEqual(element)).count()instead. -
cycle
Returns an iterable whose iterators cycle indefinitely over the elements ofiterable.That iterator supports
remove()ifiterable.iterator()does. Afterremove()is called, subsequent cycles omit the removed element, which is no longer initerable. The iterator'shasNext()method returnstrueuntiliterableis empty.Warning: Typical uses of the resulting iterator may produce an infinite loop. You should use an explicit
breakor be certain that you will eventually remove all the elements.To cycle over the iterable
ntimes, use the following:Iterables.concat(Collections.nCopies(n, iterable))Java 8 users: The
Streamequivalent of this method isStream.generate(() -> iterable).flatMap(Streams::stream). -
cycle
Returns an iterable whose iterators cycle indefinitely over the provided elements.After
removeis 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 asIterables.cycle(Lists.newArrayList(elements)). The iterator'shasNextmethod returnstrueuntil 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
breakor be certain that you will eventually remove all the elements.To cycle over the elements
ntimes, use the following:Iterables.concat(Collections.nCopies(n, Arrays.asList(elements)))Java 8 users: If passing a single element
e, theStreamequivalent of this method isStream.generate(() -> e). Otherwise, put the elements in a collection and useStream.generate(() -> collection).flatMap(Collection::stream). -
concat
Combines two iterables into a single iterable. The returned iterable has an iterator that traverses the elements ina, followed by the elements inb. The source iterators are not polled until necessary.The returned iterable's iterator supports
remove()when the corresponding input iterator supports it.Java 8 users: The
Streamequivalent of this method isStream.concat(a, b). -
concat
public static <T> Iterable<T> concat(Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c) Combines three iterables into a single iterable. The returned iterable has an iterator that traverses the elements ina, followed by the elements inb, followed by the elements inc. The source iterators are not polled until necessary.The returned iterable's iterator supports
remove()when the corresponding input iterator supports it.Java 8 users: The
Streamequivalent of this method isStreams.concat(a, b, c). -
concat
public static <T> Iterable<T> concat(Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c, Iterable<? extends T> d) Combines four iterables into a single iterable. The returned iterable has an iterator that traverses the elements ina, followed by the elements inb, followed by the elements inc, followed by the elements ind. The source iterators are not polled until necessary.The returned iterable's iterator supports
remove()when the corresponding input iterator supports it.Java 8 users: The
Streamequivalent of this method isStreams.concat(a, b, c, d). -
concat
Combines multiple iterables into a single iterable. The returned iterable has an iterator that traverses the elements of each iterable ininputs. The input iterators are not polled until necessary.The returned iterable's iterator supports
remove()when the corresponding input iterator supports it.Java 8 users: The
Streamequivalent of this method isStreams.concat(...).- Throws:
NullPointerException- if any of the provided iterables is null
-
concat
Combines multiple iterables into a single iterable. The returned iterable has an iterator that traverses the elements of each iterable ininputs. The input iterators are not polled until necessary.The returned iterable's iterator supports
remove()when the corresponding input iterator supports it. The methods of the returned iterable may throwNullPointerExceptionif any of the input iterators is null.Java 8 users: The
Streamequivalent of this method isstreamOfStreams.flatMap(s -> s). -
partition
Divides an iterable into unmodifiable sublists of the given size (the final iterable may be smaller). For example, partitioning an iterable containing[a, b, c, d, e]with a partition size of 3 yields[[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
Iterator.remove()method. The returned lists implementRandomAccess, whether or not the input list does.Note: if
iterableis aList, useLists.partition(List, int)instead.- Parameters:
iterable- the iterable to return a partitioned view ofsize- the desired size of each partition (the last may be smaller)- Returns:
- an iterable of unmodifiable lists containing the elements of
iterabledivided into partitions - Throws:
IllegalArgumentException- ifsizeis nonpositive
-
paddedPartition
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[a, b, c, d, e]with a partition size of 3 yields[[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
Iterator.remove()method.- Parameters:
iterable- the iterable to return a partitioned view ofsize- the desired size of each partition- Returns:
- an iterable of unmodifiable lists containing the elements of
iterabledivided into partitions (the final iterable may have trailing null elements) - Throws:
IllegalArgumentException- ifsizeis nonpositive
-
filter
Returns a view ofunfilteredcontaining all elements that satisfy the input predicateretainIfTrue. The returned iterable's iterator does not supportremove().Streamequivalent:Stream.filter(java.util.function.Predicate<? super T>). -
filter
Returns a view ofunfilteredcontaining all elements that are of the typedesiredType. The returned iterable's iterator does not supportremove().Streamequivalent:stream.filter(type::isInstance).map(type::cast). This does perform a little more work than necessary, so another option is to insert an unchecked cast at some later point:@SuppressWarnings("unchecked") // safe because of ::isInstance check ImmutableList<NewType> result = (ImmutableList) stream.filter(NewType.class::isInstance).collect(toImmutableList()); -
any
Returnstrueif any element initerablesatisfies the predicate.Streamequivalent:Stream.anyMatch(java.util.function.Predicate<? super T>). -
all
Returnstrueif every element initerablesatisfies the predicate. Ifiterableis empty,trueis returned.Streamequivalent:Stream.allMatch(java.util.function.Predicate<? super T>). -
find
Returns the first element initerablethat 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, usetryFind(java.lang.Iterable<T>, com.google.common.base.Predicate<? super T>)orfind(Iterable, Predicate, Object)instead.Streamequivalent:stream.filter(predicate).findFirst().get()- Throws:
NoSuchElementException- if no element initerablematches the given predicate
-
find
@CheckForNull public static <T> T find(Iterable<? extends T> iterable, Predicate<? super T> predicate, @CheckForNull T defaultValue) Returns the first element initerablethat satisfies the given predicate, ordefaultValueif none found. Note that this can usually be handled more naturally usingtryFind(iterable, predicate).or(defaultValue).Streamequivalent:stream.filter(predicate).findFirst().orElse(defaultValue)- Since:
- 7.0
-
tryFind
Returns anOptionalcontaining the first element initerablethat satisfies the given predicate, if such an element exists.Warning: avoid using a
predicatethat matchesnull. Ifnullis matched initerable, a NullPointerException will be thrown.Streamequivalent:stream.filter(predicate).findFirst()- Since:
- 11.0
-
indexOf
Returns the index initerableof the first element that satisfies the providedpredicate, or-1if the Iterable has no such elements.More formally, returns the lowest index
isuch thatpredicate.apply(Iterables.get(iterable, i))returnstrue, or-1if there is no such index.- Since:
- 2.0
-
transform
public static <F,T> Iterable<T> transform(Iterable<F> fromIterable, Function<? super F, ? extends T> function) Returns a view containing the result of applyingfunctionto each element offromIterable.The returned iterable's iterator supports
remove()iffromIterable's iterator does. After a successfulremove()call,fromIterableno longer contains the corresponding element.If the input
Iterableis known to be aListor otherCollection, considerLists.transform(java.util.List<F>, com.google.common.base.Function<? super F, ? extends T>)andCollections2.transform(java.util.Collection<F>, com.google.common.base.Function<? super F, T>).Streamequivalent:Stream.map(java.util.function.Function<? super T, ? extends R>) -
get
Returns the element at the specified position in an iterable.Streamequivalent:stream.skip(position).findFirst().get()(throwsNoSuchElementExceptionif out of bounds)- Parameters:
position- position of the element to return- Returns:
- the element at the specified position in
iterable - Throws:
IndexOutOfBoundsException- ifpositionis negative or greater than or equal to the size ofiterable
-
get
Returns the element at the specified position in an iterable or a default value otherwise.Streamequivalent:stream.skip(position).findFirst().orElse(defaultValue)(returns the default value if the index is out of bounds)- Parameters:
position- position of the element to returndefaultValue- the default value to return ifpositionis greater than or equal to the size of the iterable- Returns:
- the element at the specified position in
iterableordefaultValueifiterablecontains fewer thanposition + 1elements. - Throws:
IndexOutOfBoundsException- ifpositionis negative- Since:
- 4.0
-
getFirst
Returns the first element initerableordefaultValueif the iterable is empty. TheIteratorsanalog to this method isIterators.getNext(java.util.Iterator<? extends T>, T).If no default value is desired (and the caller instead wants a
NoSuchElementExceptionto be thrown), it is recommended thatiterable.iterator().next()is used instead.To get the only element in a single-element
Iterable, consider usinggetOnlyElement(Iterable)orgetOnlyElement(Iterable, Object)instead.Streamequivalent:stream.findFirst().orElse(defaultValue)- Parameters:
defaultValue- the default value to return if the iterable is empty- Returns:
- the first element of
iterableor the default value - Since:
- 7.0
-
getLast
Returns the last element ofiterable. Ifiterableis aListwithRandomAccesssupport, then this operation is guaranteed to beO(1).Streamequivalent:Streams.findLast(stream).get()- Returns:
- the last element of
iterable - Throws:
NoSuchElementException- if the iterable is empty
-
getLast
Returns the last element ofiterableordefaultValueif the iterable is empty. Ifiterableis aListwithRandomAccesssupport, then this operation is guaranteed to beO(1).Streamequivalent:Streams.findLast(stream).orElse(defaultValue)- Parameters:
defaultValue- the value to return ifiterableis empty- Returns:
- the last element of
iterableor the default value - Since:
- 3.0
-
getLastInNonemptyList
-
skip
Returns a view ofiterablethat skips its firstnumberToSkipelements. Ifiterablecontains fewer thannumberToSkipelements, the returned iterable skips all of its elements.Modifications to the underlying
Iterablebefore a call toiterator()are reflected in the returned iterator. That is, the iterator skips the firstnumberToSkipelements that exist when theIteratoris created, not whenskip()is called.The returned iterable's iterator supports
remove()if the iterator of the underlying iterable supports it. Note that it is not possible to delete the last skipped element by immediately callingremove()on that iterator, as theIteratorcontract states that a call toremove()before a call tonext()will throw anIllegalStateException.Streamequivalent:Stream.skip(long)- Since:
- 3.0
-
limit
Returns a view ofiterablecontaining its firstlimitSizeelements. Ifiterablecontains fewer thanlimitSizeelements, the returned view contains all of its elements. The returned iterable's iterator supportsremove()ifiterable's iterator does.Streamequivalent:Stream.limit(long)- Parameters:
iterable- the iterable to limitlimitSize- the maximum number of elements in the returned iterable- Throws:
IllegalArgumentException- iflimitSizeis negative- Since:
- 3.0
-
consumingIterable
Returns a view of the supplied iterable that wraps each generatedIteratorthroughIterators.consumingIterator(Iterator).Note: If
iterableis aQueue, the returned iterable will get entries fromQueue.remove()sinceQueue's iteration order is undefined. CallingIterator.hasNext()on a generated iterator from the returned iterable may cause an item to be immediately dequeued for return on a subsequent call toIterator.next().- Parameters:
iterable- the iterable to wrap- Returns:
- a view of the supplied iterable that wraps each generated iterator through
Iterators.consumingIterator(Iterator); for queues, an iterable that generates iterators that return and consume the queue's elements in queue order - Since:
- 2.0
- See Also:
-
isEmpty
Determines if the given iterable contains no elements.There is no precise
Iteratorequivalent to this method, since one can only ask an iterator whether it has any elements remaining (which one does usingIterator.hasNext()).Streamequivalent:!stream.findAny().isPresent()- Returns:
trueif the iterable contains no elements
-
mergeSorted
public static <T> Iterable<T> mergeSorted(Iterable<? extends Iterable<? extends T>> iterables, Comparator<? super T> comparator) Returns an iterable over the merged contents of all giveniterables. Equivalent entries will not be de-duplicated.Callers must ensure that the source
iterablesare in non-descending order as this method does not sort its input.For any equivalent elements across all
iterables, it is undefined which element is returned first.- Since:
- 11.0
-
toIterator
-