Class Iterables
- java.lang.Object
-
- com.google.common.collect.Iterables
-
@GwtCompatible(emulated=true) public final class Iterables extends java.lang.Object
An assortment of mainly legacy static utility methods that operate on or return objects of typeIterable
. Except as noted, each method has a correspondingIterator
-based method in theIterators
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
- Author:
- Kevin Bourrillion, Jared Levy
-
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static <T extends @Nullable java.lang.Object>
booleanaddAll(java.util.Collection<T> addTo, java.lang.Iterable<? extends T> elementsToAdd)
Adds all elements initerable
tocollection
.static <T extends @Nullable java.lang.Object>
booleanall(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
Returnstrue
if every element initerable
satisfies the predicate.static <T extends @Nullable java.lang.Object>
booleanany(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
Returnstrue
if any element initerable
satisfies the predicate.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>concat(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> inputs)
Combines multiple iterables into a single iterable.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>concat(java.lang.Iterable<? extends T>... inputs)
Combines multiple iterables into a single iterable.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b)
Combines two iterables into a single iterable.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b, java.lang.Iterable<? extends T> c)
Combines three iterables into a single iterable.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b, java.lang.Iterable<? extends T> c, java.lang.Iterable<? extends T> d)
Combines four iterables into a single iterable.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>consumingIterable(java.lang.Iterable<T> iterable)
Returns a view of the supplied iterable that wraps each generatedIterator
throughIterators.consumingIterator(Iterator)
.static boolean
contains(java.lang.Iterable<? extends @Nullable java.lang.Object> iterable, java.lang.Object element)
Returnstrue
ifiterable
contains any elemento
for whichObjects.equals(o, element)
would returntrue
.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>cycle(java.lang.Iterable<T> iterable)
Returns an iterable whose iterators cycle indefinitely over the elements ofiterable
.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>cycle(T... elements)
Returns an iterable whose iterators cycle indefinitely over the provided elements.static boolean
elementsEqual(java.lang.Iterable<?> iterable1, java.lang.Iterable<?> iterable2)
Determines whether two iterables contain equal elements in the same order.static <T> java.lang.Iterable<T>
filter(java.lang.Iterable<?> unfiltered, java.lang.Class<T> desiredType)
Returns a view ofunfiltered
containing all elements that are of the typedesiredType
.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>filter(java.lang.Iterable<T> unfiltered, Predicate<? super T> retainIfTrue)
Returns a view ofunfiltered
containing all elements that satisfy the input predicateretainIfTrue
.static <T extends @Nullable java.lang.Object>
Tfind(java.lang.Iterable<? extends T> iterable, Predicate<? super T> predicate, T defaultValue)
Returns the first element initerable
that satisfies the given predicate, ordefaultValue
if none found.static <T extends @Nullable java.lang.Object>
Tfind(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
Returns the first element initerable
that satisfies the given predicate; use this method only when such an element is known to exist.static int
frequency(java.lang.Iterable<?> iterable, java.lang.Object element)
Returns the number of elements in the specified iterable that equal the specified object.static <T extends @Nullable java.lang.Object>
Tget(java.lang.Iterable<? extends T> iterable, int position, T defaultValue)
Returns the element at the specified position in an iterable or a default value otherwise.static <T extends @Nullable java.lang.Object>
Tget(java.lang.Iterable<T> iterable, int position)
Returns the element at the specified position in an iterable.static <T extends @Nullable java.lang.Object>
TgetFirst(java.lang.Iterable<? extends T> iterable, T defaultValue)
Returns the first element initerable
ordefaultValue
if the iterable is empty.static <T extends @Nullable java.lang.Object>
TgetLast(java.lang.Iterable<? extends T> iterable, T defaultValue)
Returns the last element ofiterable
ordefaultValue
if the iterable is empty.static <T extends @Nullable java.lang.Object>
TgetLast(java.lang.Iterable<T> iterable)
Returns the last element ofiterable
.static <T extends @Nullable java.lang.Object>
TgetOnlyElement(java.lang.Iterable<? extends T> iterable, T defaultValue)
Returns the single element contained initerable
, ordefaultValue
if the iterable is empty.static <T extends @Nullable java.lang.Object>
TgetOnlyElement(java.lang.Iterable<T> iterable)
Returns the single element contained initerable
.static <T extends @Nullable java.lang.Object>
intindexOf(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
Returns the index initerable
of the first element that satisfies the providedpredicate
, or-1
if the Iterable has no such elements.static boolean
isEmpty(java.lang.Iterable<?> iterable)
Determines if the given iterable contains no elements.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>limit(java.lang.Iterable<T> iterable, int limitSize)
Returns a view ofiterable
containing its firstlimitSize
elements.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>mergeSorted(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> iterables, java.util.Comparator<? super T> comparator)
Returns an iterable over the merged contents of all giveniterables
.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<java.util.List<@Nullable T>>paddedPartition(java.lang.Iterable<T> iterable, int size)
Divides an iterable into unmodifiable sublists of the given size, padding the final iterable with null values if necessary.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<java.util.List<T>>partition(java.lang.Iterable<T> iterable, int size)
Divides an iterable into unmodifiable sublists of the given size (the final iterable may be smaller).static boolean
removeAll(java.lang.Iterable<?> removeFrom, java.util.Collection<?> elementsToRemove)
Removes, from an iterable, every element that belongs to the provided collection.static <T extends @Nullable java.lang.Object>
booleanremoveIf(java.lang.Iterable<T> removeFrom, Predicate<? super T> predicate)
Removes, from an iterable, every element that satisfies the provided predicate.static boolean
retainAll(java.lang.Iterable<?> removeFrom, java.util.Collection<?> elementsToRetain)
Removes, from an iterable, every element that does not belong to the provided collection.static int
size(java.lang.Iterable<?> iterable)
Returns the number of elements initerable
.static <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>skip(java.lang.Iterable<T> iterable, int numberToSkip)
Returns a view ofiterable
that skips its firstnumberToSkip
elements.static <T extends @Nullable java.lang.Object>
T[]toArray(java.lang.Iterable<? extends T> iterable, java.lang.Class<@NonNull T> type)
Copies an iterable's elements into an array.static java.lang.String
toString(java.lang.Iterable<?> iterable)
Returns a string representation ofiterable
, with the format[e1, e2, ..., en]
(that is, identical toArrays
.toString(Iterables.toArray(iterable))
).static <F extends @Nullable java.lang.Object,T extends @Nullable java.lang.Object>
java.lang.Iterable<T>transform(java.lang.Iterable<F> fromIterable, Function<? super F,? extends T> function)
Returns a view containing the result of applyingfunction
to each element offromIterable
.static <T> Optional<T>
tryFind(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
Returns anOptional
containing the first element initerable
that satisfies the given predicate, if such an element exists.static <E> java.lang.Iterable<E>
unmodifiableIterable(ImmutableCollection<E> iterable)
Deprecated.no need to use thisstatic <T extends @Nullable java.lang.Object>
java.lang.Iterable<T>unmodifiableIterable(java.lang.Iterable<? extends T> iterable)
Returns an unmodifiable view ofiterable
.
-
-
-
Method Detail
-
unmodifiableIterable
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> unmodifiableIterable(java.lang.Iterable<? extends T> iterable)
Returns an unmodifiable view ofiterable
.
-
unmodifiableIterable
@Deprecated public static <E> java.lang.Iterable<E> unmodifiableIterable(ImmutableCollection<E> iterable)
Deprecated.no need to use thisSimply returns its argument.- Since:
- 10.0
-
size
public static int size(java.lang.Iterable<?> iterable)
Returns the number of elements initerable
.
-
contains
public static boolean contains(java.lang.Iterable<? extends @Nullable java.lang.Object> iterable, @CheckForNull java.lang.Object element)
Returnstrue
ifiterable
contains any elemento
for whichObjects.equals(o, element)
would returntrue
. Otherwise returnsfalse
, even in cases whereCollection.contains(java.lang.Object)
might throwNullPointerException
orClassCastException
.
-
removeAll
@CanIgnoreReturnValue public static boolean removeAll(java.lang.Iterable<?> removeFrom, java.util.Collection<?> elementsToRemove)
Removes, from an iterable, every element that belongs to the provided collection.This method calls
Collection.removeAll(java.util.Collection<?>)
ifiterable
is 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:
true
if any element was removed fromiterable
-
retainAll
@CanIgnoreReturnValue public static boolean retainAll(java.lang.Iterable<?> removeFrom, java.util.Collection<?> elementsToRetain)
Removes, from an iterable, every element that does not belong to the provided collection.This method calls
Collection.retainAll(java.util.Collection<?>)
ifiterable
is 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:
true
if any element was removed fromiterable
-
removeIf
@CanIgnoreReturnValue public static <T extends @Nullable java.lang.Object> boolean removeIf(java.lang.Iterable<T> removeFrom, Predicate<? super T> predicate)
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
predicate
is dependent onremoveFrom
.Java 8 users: if
removeFrom
is 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:
true
if any elements were removed from the iterable- Throws:
java.lang.UnsupportedOperationException
- if the iterable does not supportremove()
.- Since:
- 2.0
-
elementsEqual
public static boolean elementsEqual(java.lang.Iterable<?> iterable1, java.lang.Iterable<?> iterable2)
Determines whether two iterables contain equal elements in the same order. More specifically, this method returnstrue
ifiterable1
anditerable2
contain the same number of elements and every element ofiterable1
is equal to the corresponding element ofiterable2
.
-
toString
public static java.lang.String toString(java.lang.Iterable<?> iterable)
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
public static <T extends @Nullable java.lang.Object> T getOnlyElement(java.lang.Iterable<T> iterable)
Returns the single element contained initerable
.Java 8 users: the
Stream
equivalent to this method isstream.collect(MoreCollectors.onlyElement())
.- Throws:
java.util.NoSuchElementException
- if the iterable is emptyjava.lang.IllegalArgumentException
- if the iterable contains multiple elements
-
getOnlyElement
public static <T extends @Nullable java.lang.Object> T getOnlyElement(java.lang.Iterable<? extends T> iterable, T defaultValue)
Returns the single element contained initerable
, ordefaultValue
if the iterable is empty.Java 8 users: the
Stream
equivalent to this method isstream.collect(MoreCollectors.toOptional()).orElse(defaultValue)
.- Throws:
java.lang.IllegalArgumentException
- if the iterator contains multiple elements
-
toArray
@GwtIncompatible public static <T extends @Nullable java.lang.Object> T[] toArray(java.lang.Iterable<? extends T> iterable, java.lang.Class<@NonNull T> type)
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
-
addAll
@CanIgnoreReturnValue public static <T extends @Nullable java.lang.Object> boolean addAll(java.util.Collection<T> addTo, java.lang.Iterable<? extends T> elementsToAdd)
Adds all elements initerable
tocollection
.- Returns:
true
ifcollection
was modified as a result of this operation.
-
frequency
public static int frequency(java.lang.Iterable<?> iterable, @CheckForNull java.lang.Object element)
Returns the number of elements in the specified iterable that equal the specified object. This implementation avoids a full iteration when the iterable is aMultiset
orSet
.Java 8 users: In most cases, the
Stream
equivalent of this method isstream.filter(element::equals).count()
. Ifelement
might be null, usestream.filter(Predicate.isEqual(element)).count()
instead.- See Also:
Collections.frequency(Collection, Object)
-
cycle
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> cycle(java.lang.Iterable<T> iterable)
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 returnstrue
untiliterable
is empty.Warning: Typical uses of the resulting iterator may produce an infinite loop. You should use an explicit
break
or be certain that you will eventually remove all the elements.To cycle over the iterable
n
times, use the following:Iterables.concat(Collections.nCopies(n, iterable))
Java 8 users: The
Stream
equivalent of this method isStream.generate(() -> iterable).flatMap(Streams::stream)
.
-
cycle
@SafeVarargs public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> cycle(T... elements)
Returns an iterable whose iterators cycle indefinitely over the provided elements.After
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 asIterables.cycle(Lists.newArrayList(elements))
. The iterator'shasNext
method returnstrue
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
break
or be certain that you will eventually remove all the elements.To cycle over the elements
n
times, use the following:Iterables.concat(Collections.nCopies(n, Arrays.asList(elements)))
Java 8 users: If passing a single element
e
, theStream
equivalent of this method isStream.generate(() -> e)
. Otherwise, put the elements in a collection and useStream.generate(() -> collection).flatMap(Collection::stream)
.
-
concat
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b)
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
Stream
equivalent of this method isStream.concat(a, b)
.
-
concat
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b, java.lang.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
Stream
equivalent of this method isStreams.concat(a, b, c)
.
-
concat
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b, java.lang.Iterable<? extends T> c, java.lang.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
Stream
equivalent of this method isStreams.concat(a, b, c, d)
.
-
concat
@SafeVarargs public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> concat(java.lang.Iterable<? extends T>... inputs)
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
Stream
equivalent of this method isStreams.concat(...)
.- Throws:
java.lang.NullPointerException
- if any of the provided iterables is null
-
concat
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> concat(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> inputs)
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 throwNullPointerException
if any of the input iterators is null.Java 8 users: The
Stream
equivalent of this method isstreamOfStreams.flatMap(s -> s)
.
-
partition
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<java.util.List<T>> partition(java.lang.Iterable<T> iterable, int size)
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: The current implementation eagerly allocates storage for
size
elements. As a consequence, passing values likeInteger.MAX_VALUE
can lead toOutOfMemoryError
.Note: if
iterable
is 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
iterable
divided into partitions - Throws:
java.lang.IllegalArgumentException
- ifsize
is nonpositive
-
paddedPartition
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<java.util.List<@Nullable T>> paddedPartition(java.lang.Iterable<T> iterable, int 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[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
iterable
divided into partitions (the final iterable may have trailing null elements) - Throws:
java.lang.IllegalArgumentException
- ifsize
is nonpositive
-
filter
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> filter(java.lang.Iterable<T> unfiltered, Predicate<? super T> retainIfTrue)
Returns a view ofunfiltered
containing all elements that satisfy the input predicateretainIfTrue
. The returned iterable's iterator does not supportremove()
.Stream
equivalent:Stream.filter(java.util.function.Predicate<? super T>)
.
-
filter
@GwtIncompatible public static <T> java.lang.Iterable<T> filter(java.lang.Iterable<?> unfiltered, java.lang.Class<T> desiredType)
Returns a view ofunfiltered
containing all elements that are of the typedesiredType
. The returned iterable's iterator does not supportremove()
.Stream
equivalent: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
public static <T extends @Nullable java.lang.Object> boolean any(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
Returnstrue
if any element initerable
satisfies the predicate.Stream
equivalent:Stream.anyMatch(java.util.function.Predicate<? super T>)
.
-
all
public static <T extends @Nullable java.lang.Object> boolean all(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
Returnstrue
if every element initerable
satisfies the predicate. Ifiterable
is empty,true
is returned.Stream
equivalent:Stream.allMatch(java.util.function.Predicate<? super T>)
.
-
find
public static <T extends @Nullable java.lang.Object> T find(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
Returns the first element initerable
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, usetryFind(java.lang.Iterable<T>, com.google.common.base.Predicate<? super T>)
orfind(Iterable, Predicate, Object)
instead.Stream
equivalent:stream.filter(predicate).findFirst().get()
- Throws:
java.util.NoSuchElementException
- if no element initerable
matches the given predicate
-
find
@CheckForNull public static <T extends @Nullable java.lang.Object> T find(java.lang.Iterable<? extends T> iterable, Predicate<? super T> predicate, @CheckForNull T defaultValue)
Returns the first element initerable
that satisfies the given predicate, ordefaultValue
if none found. Note that this can usually be handled more naturally usingtryFind(iterable, predicate).or(defaultValue)
.Stream
equivalent:stream.filter(predicate).findFirst().orElse(defaultValue)
- Since:
- 7.0
-
tryFind
public static <T> Optional<T> tryFind(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
Returns anOptional
containing the first element initerable
that satisfies the given predicate, if such an element exists.Warning: avoid using a
predicate
that matchesnull
. Ifnull
is matched initerable
, a NullPointerException will be thrown.Stream
equivalent:stream.filter(predicate).findFirst()
- Since:
- 11.0
-
indexOf
public static <T extends @Nullable java.lang.Object> int indexOf(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
Returns the index initerable
of the first element that satisfies the providedpredicate
, or-1
if the Iterable has no such elements.More formally, returns the lowest index
i
such thatpredicate.apply(Iterables.get(iterable, i))
returnstrue
, or-1
if there is no such index.- Since:
- 2.0
-
transform
public static <F extends @Nullable java.lang.Object,T extends @Nullable java.lang.Object> java.lang.Iterable<T> transform(java.lang.Iterable<F> fromIterable, Function<? super F,? extends T> function)
Returns a view containing the result of applyingfunction
to each element offromIterable
.The returned iterable's iterator supports
remove()
iffromIterable
's iterator does. After a successfulremove()
call,fromIterable
no longer contains the corresponding element.If the input
Iterable
is known to be aList
or 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>)
.Stream
equivalent:Stream.map(java.util.function.Function<? super T, ? extends R>)
-
get
public static <T extends @Nullable java.lang.Object> T get(java.lang.Iterable<T> iterable, int position)
Returns the element at the specified position in an iterable.Stream
equivalent:stream.skip(position).findFirst().get()
(throwsNoSuchElementException
if out of bounds)- Parameters:
position
- position of the element to return- Returns:
- the element at the specified position in
iterable
- Throws:
java.lang.IndexOutOfBoundsException
- ifposition
is negative or greater than or equal to the size ofiterable
-
get
public static <T extends @Nullable java.lang.Object> T get(java.lang.Iterable<? extends T> iterable, int position, T defaultValue)
Returns the element at the specified position in an iterable or a default value otherwise.Stream
equivalent: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 ifposition
is greater than or equal to the size of the iterable- Returns:
- the element at the specified position in
iterable
ordefaultValue
ifiterable
contains fewer thanposition + 1
elements. - Throws:
java.lang.IndexOutOfBoundsException
- ifposition
is negative- Since:
- 4.0
-
getFirst
public static <T extends @Nullable java.lang.Object> T getFirst(java.lang.Iterable<? extends T> iterable, T defaultValue)
Returns the first element initerable
ordefaultValue
if the iterable is empty. TheIterators
analog to this method isIterators.getNext(java.util.Iterator<? extends T>, T)
.If no default value is desired (and the caller instead wants a
NoSuchElementException
to 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.Stream
equivalent:stream.findFirst().orElse(defaultValue)
- Parameters:
defaultValue
- the default value to return if the iterable is empty- Returns:
- the first element of
iterable
or the default value - Since:
- 7.0
-
getLast
public static <T extends @Nullable java.lang.Object> T getLast(java.lang.Iterable<T> iterable)
Returns the last element ofiterable
. Ifiterable
is aList
withRandomAccess
support, then this operation is guaranteed to beO(1)
.Stream
equivalent:Streams.findLast(stream).get()
- Returns:
- the last element of
iterable
- Throws:
java.util.NoSuchElementException
- if the iterable is empty
-
getLast
public static <T extends @Nullable java.lang.Object> T getLast(java.lang.Iterable<? extends T> iterable, T defaultValue)
Returns the last element ofiterable
ordefaultValue
if the iterable is empty. Ifiterable
is aList
withRandomAccess
support, then this operation is guaranteed to beO(1)
.Stream
equivalent:Streams.findLast(stream).orElse(defaultValue)
- Parameters:
defaultValue
- the value to return ifiterable
is empty- Returns:
- the last element of
iterable
or the default value - Since:
- 3.0
-
skip
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> skip(java.lang.Iterable<T> iterable, int numberToSkip)
Returns a view ofiterable
that skips its firstnumberToSkip
elements. Ifiterable
contains fewer thannumberToSkip
elements, the returned iterable skips all of its elements.Modifications to the underlying
Iterable
before a call toiterator()
are reflected in the returned iterator. That is, the iterator skips the firstnumberToSkip
elements that exist when theIterator
is 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 theIterator
contract states that a call toremove()
before a call tonext()
will throw anIllegalStateException
.Stream
equivalent:Stream.skip(long)
- Since:
- 3.0
-
limit
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> limit(java.lang.Iterable<T> iterable, int limitSize)
Returns a view ofiterable
containing its firstlimitSize
elements. Ifiterable
contains fewer thanlimitSize
elements, the returned view contains all of its elements. The returned iterable's iterator supportsremove()
ifiterable
's iterator does.Stream
equivalent:Stream.limit(long)
- Parameters:
iterable
- the iterable to limitlimitSize
- the maximum number of elements in the returned iterable- Throws:
java.lang.IllegalArgumentException
- iflimitSize
is negative- Since:
- 3.0
-
consumingIterable
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> consumingIterable(java.lang.Iterable<T> iterable)
Returns a view of the supplied iterable that wraps each generatedIterator
throughIterators.consumingIterator(Iterator)
.Note: If
iterable
is aQueue
, the returned iterable will instead useCollection.isEmpty()
andQueue.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()
.Whether the input
iterable
is aQueue
or not, the returnedIterable
is not thread-safe.- 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:
Iterators.consumingIterator(Iterator)
-
isEmpty
public static boolean isEmpty(java.lang.Iterable<?> iterable)
Determines if the given iterable contains no elements.There is no precise
Iterator
equivalent to this method, since one can only ask an iterator whether it has any elements remaining (which one does usingIterator.hasNext()
).Stream
equivalent:!stream.findAny().isPresent()
- Returns:
true
if the iterable contains no elements
-
mergeSorted
public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> mergeSorted(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> iterables, java.util.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
iterables
are 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
-
-