@GwtCompatible(emulated=true) public final class Iterables extends Object
Iterable
. Except as noted, each method has a corresponding
Iterator
-based method in the
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.
See the Guava User Guide article on Iterables
.
Modifier and Type | Method and Description |
---|---|
static <T> boolean |
addAll(Collection
Adds all elements in
iterable to
collection .
|
static <T> boolean |
all(Iterable
Returns
true if every element in
iterable satisfies the predicate.
|
static <T> boolean |
any(Iterable
Returns
true if any element in
iterable satisfies the predicate.
|
static <T> Iterable |
concat(Iterable
Combines multiple iterables into a single iterable.
|
static <T> Iterable |
concat(Iterable
Combines multiple iterables into a single iterable.
|
static <T> Iterable |
concat(Iterable
Combines two iterables into a single iterable.
|
static <T> Iterable |
concat(Iterable
Combines three iterables into a single iterable.
|
static <T> Iterable |
concat(Iterable
Combines four iterables into a single iterable.
|
static <T> Iterable |
consumingIterable(Iterable
Returns a view of the supplied iterable that wraps each generated
Iterator through
Iterators .
|
static boolean |
contains(Iterable
Returns
true if
iterable contains any object for which
equals(element) is true.
|
static <T> Iterable |
cycle(Iterable
Returns an iterable whose iterators cycle indefinitely over the elements of
iterable .
|
static <T> Iterable |
cycle(T... elements)
Returns an iterable whose iterators cycle indefinitely over the provided elements.
|
static boolean |
elementsEqual(Iterable
Determines whether two iterables contain equal elements in the same order.
|
static <T> Iterable |
filter(Iterable
Returns all instances of class
type in
unfiltered .
|
static <T> Iterable |
filter(Iterable
Returns the elements of
unfiltered that satisfy a predicate.
|
static <T> T |
find(Iterable
Returns the first element in
iterable that satisfies the given predicate, or
defaultValue if none found.
|
static <T> T |
find(Iterable
Returns the first element in
iterable that satisfies the given predicate; use this method only when such an element is known to exist.
|
static int |
frequency(Iterable
Returns the number of elements in the specified iterable that equal the specified object.
|
static <T> T |
get(Iterable
Returns the element at the specified position in an iterable or a default value otherwise.
|
static <T> T |
get(Iterable
Returns the element at the specified position in an iterable.
|
static <T> T |
getFirst(Iterable
Returns the first element in
iterable or
defaultValue if the iterable is empty.
|
static <T> T |
getLast(Iterable
Returns the last element of
iterable or
defaultValue if the iterable is empty.
|
static <T> T |
getLast(Iterable
Returns the last element of
iterable .
|
static <T> T |
getOnlyElement(Iterable
Returns the single element contained in
iterable , or
defaultValue if the iterable is empty.
|
static <T> T |
getOnlyElement(Iterable
Returns the single element contained in
iterable .
|
static <T> int |
indexOf(Iterable
Returns the index in
iterable of the first element that satisfies the provided
predicate , or
-1 if the Iterable has no such elements.
|
static boolean |
isEmpty(Iterable
Determines if the given iterable contains no elements.
|
static <T> Iterable |
limit(Iterable
Creates an iterable with the first
limitSize elements of the given iterable.
|
static <T> Iterable |
mergeSorted(Iterable
Returns an iterable over the merged contents of all given
iterables .
|
static <T> Iterable |
paddedPartition(Iterable
Divides an iterable into unmodifiable sublists of the given size, padding the final iterable with null values if necessary.
|
static <T> Iterable |
partition(Iterable
Divides an iterable into unmodifiable sublists of the given size (the final iterable may be smaller).
|
static boolean |
removeAll(Iterable
Removes, from an iterable, every element that belongs to the provided collection.
|
static <T> boolean |
removeIf(Iterable
Removes, from an iterable, every element that satisfies the provided predicate.
|
static boolean |
retainAll(Iterable
Removes, from an iterable, every element that does not belong to the provided collection.
|
static int |
size(Iterable
Returns the number of elements in
iterable .
|
static <T> Iterable |
skip(Iterable
Returns a view of
iterable that skips its first
numberToSkip elements.
|
static <T> T[] |
toArray(Iterable
Copies an iterable's elements into an array.
|
static String |
toString(Iterable
Returns a string representation of
iterable , with the format
[e1, e2, ..., en] (that is, identical to
Arrays
.toString(Iterables.toArray(iterable)) ).
|
static <F |
transform(Iterable
Returns an iterable that applies
function to each element of
fromIterable .
|
static <T> Optional |
tryFind(Iterable
Returns an
Optional containing the first element in
iterable that satisfies the given predicate, if such an element exists.
|
static <E> Iterable |
unmodifiableIterable(ImmutableCollection
Deprecated.
no need to use this
|
static <T> Iterable |
unmodifiableIterable(Iterable
Returns an unmodifiable view of
iterable .
|
public static <T> Iterable<T> unmodifiableIterable(Iterable <T> iterable)
iterable
.
@Deprecated public static <E> Iterable<E> unmodifiableIterable(ImmutableCollection <E> iterable)
public static int size(Iterable<?> iterable)
iterable
.
public static boolean contains(Iterable<?> iterable, Object element)
true
if
iterable
contains any object for which
equals(element)
is true.
public static boolean removeAll(Iterable<?> removeFrom, Collection <?> elementsToRemove)
This method calls Collection
if iterable
is a collection, and Iterators
otherwise.
removeFrom
- the iterable to (potentially) remove elements from
elementsToRemove
- the elements to remove
true
if any element was removed from
iterable
public static boolean retainAll(Iterable<?> removeFrom, Collection <?> elementsToRetain)
This method calls Collection
if iterable
is a collection, and Iterators
otherwise.
removeFrom
- the iterable to (potentially) remove elements from
elementsToRetain
- the elements to retain
true
if any element was removed from
iterable
public static <T> boolean removeIf(Iterable<T> removeFrom, Predicate <? super T> predicate)
removeFrom
- the iterable to (potentially) remove elements from
predicate
- a predicate that determines whether an element should be removed
true
if any elements were removed from the iterable
UnsupportedOperationException
- if the iterable does not support
remove()
.
public static boolean elementsEqual(Iterable<?> iterable1, Iterable <?> iterable2)
true
if
iterable1
and
iterable2
contain the same number of elements and every element of
iterable1
is equal to the corresponding element of
iterable2
.
public static StringtoString(Iterable <?> iterable)
iterable
, with the format
[e1, e2, ..., en]
(that is, identical to
Arrays
.toString(Iterables.toArray(iterable))
). Note that for
most implementations of
Collection
,
collection.toString()
also gives the same result, but that behavior is not generally guaranteed.
public static <T> T getOnlyElement(Iterable<T> iterable)
iterable
.
NoSuchElementException
- if the iterable is empty
IllegalArgumentException
- if the iterable contains multiple elements
public static <T> T getOnlyElement(Iterable<? extends T> iterable, T defaultValue)
iterable
, or
defaultValue
if the iterable is empty.
IllegalArgumentException
- if the iterator contains multiple elements
@GwtIncompatible(value="Array.newInstance(Class, int)") public static <T> T[] toArray(Iterable<? extends T> iterable, Class <T> type)
iterable
- the iterable to copy
type
- the type of the elements
public static <T> boolean addAll(Collection<T> addTo, Iterable <? extends T> elementsToAdd)
iterable
to
collection
.
true
if
collection
was modified as a result of this operation.
public static <T> Iterable<T> cycle(Iterable <T> iterable)
iterable
.
That iterator supports remove()
if iterable.iterator()
does. After remove()
is called, subsequent cycles omit the removed element, which is no longer in iterable
. The iterator's hasNext()
method returns true
until iterable
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))
public static <T> Iterable<T> cycle(T... 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 as Iterables.cycle(Lists.newArrayList(elements))
. The iterator's hasNext
method returns 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 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)))
public static <T> Iterable<T> concat(Iterable <? extends T> a, Iterable <? extends T> b)
a
, followed by the elements in
b
. The source iterators are not polled until necessary.
The returned iterable's iterator supports remove()
when the corresponding input iterator supports it.
public static <T> Iterable<T> concat(Iterable <? extends T> a, Iterable <? extends T> b, Iterable <? extends T> c)
a
, followed by the elements in
b
, followed by the elements in
c
. The source iterators are not polled until necessary.
The returned iterable's iterator supports remove()
when the corresponding input iterator supports it.
public static <T> Iterable<T> concat(Iterable <? extends T> a, Iterable <? extends T> b, Iterable <? extends T> c, Iterable <? extends T> d)
a
, followed by the elements in
b
, followed by the elements in
c
, followed by the elements in
d
. The source iterators are not polled until necessary.
The returned iterable's iterator supports remove()
when the corresponding input iterator supports it.
public static <T> Iterable<T> concat(Iterable <? extends T>... inputs)
inputs
. The input iterators are not polled until necessary.
The returned iterable's iterator supports remove()
when the corresponding input iterator supports it.
NullPointerException
- if any of the provided iterables is null
public static <T> Iterable<T> concat(Iterable <? extends Iterable <? extends T>> inputs)
inputs
. 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 throw NullPointerException
if any of the input iterators is null.
public static <T> Iterable<List <T>> partition(Iterable <T> iterable, int size)
[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
method. The returned lists implement RandomAccess
, whether or not the input list does.
Note: if iterable
is a List
, use Lists
instead.
iterable
- the iterable to return a partitioned view of
size
- the desired size of each partition (the last may be smaller)
iterable
divided into partitions
IllegalArgumentException
- if
size
is nonpositive
public static <T> Iterable<List <T>> paddedPartition(Iterable <T> iterable, int size)
[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
method.
iterable
- the iterable to return a partitioned view of
size
- the desired size of each partition
iterable
divided into partitions (the final iterable may have trailing null elements)
IllegalArgumentException
- if
size
is nonpositive
public static <T> Iterable<T> filter(Iterable <T> unfiltered, Predicate <? super T> predicate)
unfiltered
that satisfy a predicate. The resulting iterable's iterator does not support
remove()
.
@GwtIncompatible(value="Class.isInstance") public static <T> Iterable<T> filter(Iterable <?> unfiltered, Class <T> type)
type
in
unfiltered
. The returned iterable has elements whose class is
type
or a subclass of
type
. The returned iterable's iterator does not support
remove()
.
unfiltered
- an iterable containing objects of any type
type
- the type of elements desired
public static <T> boolean any(Iterable<T> iterable, Predicate <? super T> predicate)
true
if any element in
iterable
satisfies the predicate.
public static <T> boolean all(Iterable<T> iterable, Predicate <? super T> predicate)
true
if every element in
iterable
satisfies the predicate. If
iterable
is empty,
true
is returned.
public static <T> T find(Iterable<T> iterable, Predicate <? super T> predicate)
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
tryFind(java.lang.Iterable<T>, com.google.common.base.Predicate<? super T>)
or
find(Iterable, Predicate, Object)
instead.
NoSuchElementException
- if no element in
iterable
matches the given predicate
public static <T> T find(Iterable<? extends T> iterable, Predicate <? super T> predicate, T defaultValue)
iterable
that satisfies the given predicate, or
defaultValue
if none found. Note that this can usually be handled more naturally using
tryFind(iterable, predicate).or(defaultValue)
.
public static <T> Optional<T> tryFind(Iterable <T> iterable, Predicate <? super T> predicate)
Optional
containing the first element in
iterable
that satisfies the given predicate, if such an element exists.
Warning: avoid using a predicate
that matches null
. If null
is matched in iterable
, a NullPointerException will be thrown.
public static <T> int indexOf(Iterable<T> iterable, Predicate <? super T> predicate)
iterable
of the first element that satisfies the provided
predicate
, or
-1
if the Iterable has no such elements.
More formally, returns the lowest index i
such that predicate.apply(Iterables.get(iterable, i))
returns true
, or -1
if there is no such index.
public static <F,T> Iterable <T> transform(Iterable <F> fromIterable, Function <? super F ,? extends T> function)
function
to each element of
fromIterable
.
The returned iterable's iterator supports remove()
if the provided iterator does. After a successful remove()
call, fromIterable
no longer contains the corresponding element.
If the input Iterable
is known to be a List
or other Collection
, consider Lists
and Collections2
.
public static <T> T get(Iterable<T> iterable, int position)
position
- position of the element to return
iterable
IndexOutOfBoundsException
- if
position
is negative or greater than or equal to the size of
iterable
public static <T> T get(Iterable<? extends T> iterable, int position, T defaultValue)
position
- position of the element to return
defaultValue
- the default value to return if
position
is greater than or equal to the size of the iterable
iterable
or
defaultValue
if
iterable
contains fewer than
position + 1
elements.
IndexOutOfBoundsException
- if
position
is negative
public static <T> T getFirst(Iterable<? extends T> iterable, T defaultValue)
iterable
or
defaultValue
if the iterable is empty. The
Iterators
analog to this method is
Iterators.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 that iterable.iterator().next()
is used instead.
defaultValue
- the default value to return if the iterable is empty
iterable
or the default value
public static <T> T getLast(Iterable<T> iterable)
iterable
.
iterable
NoSuchElementException
- if the iterable is empty
public static <T> T getLast(Iterable<? extends T> iterable, T defaultValue)
iterable
or
defaultValue
if the iterable is empty.
defaultValue
- the value to return if
iterable
is empty
iterable
or the default value
public static <T> Iterable<T> skip(Iterable <T> iterable, int numberToSkip)
iterable
that skips its first
numberToSkip
elements. If
iterable
contains fewer than
numberToSkip
elements, the returned iterable skips all of its elements.
Modifications to the underlying Iterable
before a call to iterator()
are reflected in the returned iterator. That is, the iterator skips the first numberToSkip
elements that exist when the Iterator
is created, not when skip()
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 calling remove()
on that iterator, as the Iterator
contract states that a call to remove()
before a call to next()
will throw an IllegalStateException
.
public static <T> Iterable<T> limit(Iterable <T> iterable, int limitSize)
limitSize
elements of the given iterable. If the original iterable does not contain that many elements, the returned iterable will have the same behavior as the original iterable. The returned iterable's iterator supports
remove()
if the original iterator does.
iterable
- the iterable to limit
limitSize
- the maximum number of elements in the returned iterable
IllegalArgumentException
- if
limitSize
is negative
public static <T> Iterable<T> consumingIterable(Iterable <T> iterable)
Iterator
through
Iterators.consumingIterator(Iterator)
.
Note: If iterable
is a Queue
, the returned iterable will get entries from Queue
since Queue
's iteration order is undefined. Calling Iterator
on a generated iterator from the returned iterable may cause an item to be immediately dequeued for return on a subsequent call to Iterator
.
iterable
- the iterable to wrap
Iterators.consumingIterator(Iterator)
; for queues, an iterable that generates iterators that return and consume the queue's elements in queue order
Iterators.consumingIterator(Iterator)
public static boolean isEmpty(Iterable<?> iterable)
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 using Iterator
).
true
if the iterable contains no elements
@Beta public static <T> Iterable<T> mergeSorted(Iterable <? extends Iterable <? extends T>> iterables, Comparator <? super T> comparator)
iterables
. 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.