@GwtCompatible(emulated=true) public abstract class FluentIterable<E> extends Object implements Iterable<E>
FluentIterable
provides a rich interface for manipulating Iterable
instances in a
chained fashion. A FluentIterable
can be created from an Iterable
, or from a set
of elements. The following types of methods are provided on FluentIterable
:
FluentIterable
based in some way on the contents
of the current one (for example transform(com.google.common.base.Function<? super E, T>)
)
FluentIterable
's contents into a new collection or
array (for example toList()
)
last()
)
FluentIterable
's contents (for example
anyMatch(com.google.common.base.Predicate<? super E>)
)
Here is an example that accepts a list from a database call, filters it based on a predicate,
transforms it by invoking toString()
on each element, and returns the first 10 elements
as an ImmutableList
:
FluentIterable
.from(database.getClientList())
.filter(activeInLastMonth)
.transform(Functions.toStringFunction())
.limit(10)
.toList();
Anything which can be done using FluentIterable
could be done in a different fashion
(often with Iterables
), however the use of FluentIterable
makes many sets of
operations significantly more concise.
Modifier | Constructor and Description |
---|---|
protected |
FluentIterable()
Constructor for use by subclasses.
|
Modifier and Type | Method and Description |
---|---|
boolean |
allMatch(Predicate<? super E> predicate)
Returns
true if every element in this fluent iterable satisfies the predicate. |
boolean |
anyMatch(Predicate<? super E> predicate)
Returns
true if any element in this fluent iterable satisfies the predicate. |
FluentIterable<E> |
append(E... elements)
Returns a fluent iterable whose iterators traverse first the elements of this fluent iterable,
followed by
elements . |
FluentIterable<E> |
append(Iterable<? extends E> other)
Returns a fluent iterable whose iterators traverse first the elements of this fluent iterable,
followed by those of
other . |
boolean |
contains(Object element)
Returns
true if this fluent iterable contains any object for which
equals(element) is true. |
<C extends Collection<? super E>> |
copyInto(C collection)
Copies all the elements from this fluent iterable to
collection . |
FluentIterable<E> |
cycle()
Returns a fluent iterable whose
Iterator cycles indefinitely over the elements of
this fluent iterable. |
<T> FluentIterable<T> |
filter(Class<T> type)
Returns the elements from this fluent iterable that are instances of class
type . |
FluentIterable<E> |
filter(Predicate<? super E> predicate)
Returns the elements from this fluent iterable that satisfy a predicate.
|
Optional<E> |
first()
Returns an
Optional containing the first element in this fluent iterable. |
Optional<E> |
firstMatch(Predicate<? super E> predicate)
Returns an
Optional containing the first element in this fluent iterable that
satisfies the given predicate, if such an element exists. |
static <E> FluentIterable<E> |
from(FluentIterable<E> iterable)
Deprecated.
instances of
FluentIterable don't need to be converted to
FluentIterable |
static <E> FluentIterable<E> |
from(Iterable<E> iterable)
Returns a fluent iterable that wraps
iterable , or iterable itself if it
is already a FluentIterable . |
E |
get(int position)
Returns the element at the specified position in this fluent iterable.
|
<K> ImmutableListMultimap<K,E> |
index(Function<? super E,K> keyFunction)
Creates an index
ImmutableListMultimap that contains the results of applying a
specified function to each item in this FluentIterable of values. |
boolean |
isEmpty()
Determines whether this fluent iterable is empty.
|
String |
join(Joiner joiner)
Returns a
String containing all of the elements of this fluent iterable joined with
joiner . |
Optional<E> |
last()
Returns an
Optional containing the last element in this fluent iterable. |
FluentIterable<E> |
limit(int size)
Creates a fluent iterable with the first
size elements of this
fluent iterable. |
static <E> FluentIterable<E> |
of(E[] elements)
Returns a fluent iterable containing
elements in the specified order. |
int |
size()
Returns the number of elements in this fluent iterable.
|
FluentIterable<E> |
skip(int numberToSkip)
Returns a view of this fluent iterable that skips its first
numberToSkip
elements. |
E[] |
toArray(Class<E> type)
Returns an array containing all of the elements from this fluent iterable in iteration order.
|
ImmutableList<E> |
toList()
Returns an
ImmutableList containing all of the elements from this fluent iterable in
proper sequence. |
<V> ImmutableMap<E,V> |
toMap(Function<? super E,V> valueFunction)
Returns an immutable map whose keys are the distinct elements of this
FluentIterable
and whose value for each key was computed by valueFunction . |
ImmutableMultiset<E> |
toMultiset()
Returns an
ImmutableMultiset containing all of the elements from this fluent iterable. |
ImmutableSet<E> |
toSet()
Returns an
ImmutableSet containing all of the elements from this fluent iterable with
duplicates removed. |
ImmutableList<E> |
toSortedList(Comparator<? super E> comparator)
Returns an
ImmutableList containing all of the elements from this FluentIterable in the order specified by comparator . |
ImmutableSortedSet<E> |
toSortedSet(Comparator<? super E> comparator)
Returns an
ImmutableSortedSet containing all of the elements from this FluentIterable in the order specified by comparator , with duplicates (determined by
comparator.compare(x, y) == 0 ) removed. |
String |
toString()
Returns a string representation of this fluent iterable, with the format
[e1, e2, ..., en] . |
<T> FluentIterable<T> |
transform(Function<? super E,T> function)
Returns a fluent iterable that applies
function to each element of this
fluent iterable. |
<T> FluentIterable<T> |
transformAndConcat(Function<? super E,? extends Iterable<? extends T>> function)
Applies
function to each element of this fluent iterable and returns
a fluent iterable with the concatenated combination of results. |
<K> ImmutableMap<K,E> |
uniqueIndex(Function<? super E,K> keyFunction)
Returns a map with the contents of this
FluentIterable as its values , indexed
by keys derived from those values. |
protected FluentIterable()
@CheckReturnValue public static <E> FluentIterable<E> from(Iterable<E> iterable)
iterable
, or iterable
itself if it
is already a FluentIterable
.@Deprecated @CheckReturnValue public static <E> FluentIterable<E> from(FluentIterable<E> iterable)
FluentIterable
don't need to be converted to
FluentIterable
Iterable
to
FluentIterable
has obviated the need to explicitly convert to a FluentIterable
.@Beta @CheckReturnValue public static <E> FluentIterable<E> of(E[] elements)
elements
in the specified order.@CheckReturnValue public String toString()
[e1, e2, ..., en]
.@CheckReturnValue public final int size()
@CheckReturnValue public final boolean contains(@Nullable Object element)
true
if this fluent iterable contains any object for which
equals(element)
is true.@CheckReturnValue public final FluentIterable<E> cycle()
Iterator
cycles indefinitely over the elements of
this fluent iterable.
That iterator supports remove()
if iterable.iterator()
does. After
remove()
is called, subsequent cycles omit the removed element, which is no longer in
this fluent iterable. The iterator's hasNext()
method returns true
until
this fluent 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.
@Beta @CheckReturnValue public final FluentIterable<E> append(Iterable<? extends E> other)
other
. The iterators are not polled until necessary.
The returned iterable's Iterator
supports remove()
when the corresponding
Iterator
supports it.
@Beta @CheckReturnValue public final FluentIterable<E> append(E... elements)
elements
.@CheckReturnValue public final FluentIterable<E> filter(Predicate<? super E> predicate)
remove()
.@GwtIncompatible(value="Class.isInstance") @CheckReturnValue public final <T> FluentIterable<T> filter(Class<T> type)
type
.type
- the type of elements desired@CheckReturnValue public final boolean anyMatch(Predicate<? super E> predicate)
true
if any element in this fluent iterable satisfies the predicate.@CheckReturnValue public final boolean allMatch(Predicate<? super E> predicate)
true
if every element in this fluent iterable satisfies the predicate.
If this fluent iterable is empty, true
is returned.@CheckReturnValue public final Optional<E> firstMatch(Predicate<? super E> predicate)
Optional
containing the first element in this fluent iterable that
satisfies the given predicate, if such an element exists.
Warning: avoid using a predicate
that matches null
. If null
is matched in this fluent iterable, a NullPointerException
will be thrown.
@CheckReturnValue public final <T> FluentIterable<T> transform(Function<? super E,T> function)
function
to each element of this
fluent iterable.
The returned fluent iterable's iterator supports remove()
if this iterable's
iterator does. After a successful remove()
call, this fluent iterable no longer
contains the corresponding element.
@CheckReturnValue public <T> FluentIterable<T> transformAndConcat(Function<? super E,? extends Iterable<? extends T>> function)
function
to each element of this fluent iterable and returns
a fluent iterable with the concatenated combination of results. function
returns an Iterable of results.
The returned fluent iterable's iterator supports remove()
if this
function-returned iterables' iterator does. After a successful remove()
call,
the returned fluent iterable no longer contains the corresponding element.
Function<E, Iterable<T>>
until 14.0)@CheckReturnValue public final Optional<E> first()
Optional
containing the first element in this fluent iterable.
If the iterable is empty, Optional.absent()
is returned.NullPointerException
- if the first element is null; if this is a possibility, use
iterator().next()
or Iterables.getFirst(java.lang.Iterable<? extends T>, T)
instead.@CheckReturnValue public final Optional<E> last()
Optional
containing the last element in this fluent iterable.
If the iterable is empty, Optional.absent()
is returned.NullPointerException
- if the last element is null; if this is a possibility, use
Iterables.getLast(java.lang.Iterable<T>)
instead.@CheckReturnValue public final FluentIterable<E> skip(int numberToSkip)
numberToSkip
elements. If this fluent iterable contains fewer than numberToSkip
elements,
the returned fluent iterable skips all of its elements.
Modifications to this fluent iterable before a call to iterator()
are
reflected in the returned fluent iterable. That is, the its iterator skips the first
numberToSkip
elements that exist when the iterator is created, not when skip()
is called.
The returned fluent iterable's iterator supports remove()
if the
Iterator
of this fluent iterable supports it. Note that it is not
possible to delete the last skipped element by immediately calling remove()
on the
returned fluent iterable's iterator, as the Iterator
contract states that a call
to * remove()
before a call to next()
will throw an
IllegalStateException
.
@CheckReturnValue public final FluentIterable<E> limit(int size)
size
elements of this
fluent iterable. If this fluent iterable does not contain that many elements,
the returned fluent iterable will have the same behavior as this fluent iterable.
The returned fluent iterable's iterator supports remove()
if this
fluent iterable's iterator does.size
- the maximum number of elements in the returned fluent iterableIllegalArgumentException
- if size
is negative@CheckReturnValue public final boolean isEmpty()
@CheckReturnValue public final ImmutableList<E> toList()
ImmutableList
containing all of the elements from this fluent iterable in
proper sequence.toImmutableList()
).@CheckReturnValue public final ImmutableList<E> toSortedList(Comparator<? super E> comparator)
ImmutableList
containing all of the elements from this FluentIterable
in the order specified by comparator
. To produce an ImmutableList
sorted by its natural ordering, use toSortedList(Ordering.natural())
.comparator
- the function by which to sort list elementsNullPointerException
- if any element is nulltoSortedImmutableList()
).@CheckReturnValue public final ImmutableSet<E> toSet()
ImmutableSet
containing all of the elements from this fluent iterable with
duplicates removed.toImmutableSet()
).@CheckReturnValue public final ImmutableSortedSet<E> toSortedSet(Comparator<? super E> comparator)
ImmutableSortedSet
containing all of the elements from this FluentIterable
in the order specified by comparator
, with duplicates (determined by
comparator.compare(x, y) == 0
) removed. To produce an ImmutableSortedSet
sorted
by its natural ordering, use toSortedSet(Ordering.natural())
.comparator
- the function by which to sort set elementsNullPointerException
- if any element is nulltoImmutableSortedSet()
).@CheckReturnValue public final ImmutableMultiset<E> toMultiset()
ImmutableMultiset
containing all of the elements from this fluent iterable.@CheckReturnValue public final <V> ImmutableMap<E,V> toMap(Function<? super E,V> valueFunction)
FluentIterable
and whose value for each key was computed by valueFunction
. The map's iteration order
is the order of the first appearance of each key in this iterable.
When there are multiple instances of a key in this iterable, it is unspecified whether
valueFunction
will be applied to more than one instance of that key and, if it is,
which result will be mapped to that key in the returned map.
NullPointerException
- if any element of this iterable is null
, or if valueFunction
produces null
for any key@CheckReturnValue public final <K> ImmutableListMultimap<K,E> index(Function<? super E,K> keyFunction)
ImmutableListMultimap
that contains the results of applying a
specified function to each item in this FluentIterable
of values. Each element of this
iterable will be stored as a value in the resulting multimap, yielding a multimap with the same
size as this iterable. The key used to store that value in the multimap will be the result of
calling the function on that value. The resulting multimap is created as an immutable snapshot.
In the returned multimap, keys appear in the order they are first encountered, and the values
corresponding to each key appear in the same order as they are encountered.keyFunction
- the function used to produce the key for each valueNullPointerException
- if any of the following cases is true:
keyFunction
is null
keyFunction
returns null
for any element of this iterable
@CheckReturnValue public final <K> ImmutableMap<K,E> uniqueIndex(Function<? super E,K> keyFunction)
FluentIterable
as its values
, indexed
by keys derived from those values. In other words, each input value produces an entry in the
map whose key is the result of applying keyFunction
to that value. These entries appear
in the same order as they appeared in this fluent iterable. Example usage:
Color red = new Color("red", 255, 0, 0);
...
FluentIterable<Color> allColors = FluentIterable.from(ImmutableSet.of(red, green, blue));
Map<String, Color> colorForName = allColors.uniqueIndex(toStringFunction());
assertThat(colorForName).containsEntry("red", red);
If your index may associate multiple values with each key, use index
.
keyFunction
- the function used to produce the key for each valuekeyFunction
on each value in this fluent iterable to that valueIllegalArgumentException
- if keyFunction
produces the same
key for more than one value in this fluent iterableNullPointerException
- if any elements of this fluent iterable is null, or
if keyFunction
produces null
for any value@GwtIncompatible(value="Array.newArray(Class, int)") @CheckReturnValue public final E[] toArray(Class<E> type)
type
- the type of the elementspublic final <C extends Collection<? super E>> C copyInto(C collection)
collection
. This is equivalent to
calling Iterables.addAll(collection, this)
.collection
- the collection to copy elements tocollection
, for convenience@Beta @CheckReturnValue public final String join(Joiner joiner)
String
containing all of the elements of this fluent iterable joined with
joiner
.@CheckReturnValue public final E get(int position)
position
- position of the element to returnIndexOutOfBoundsException
- if position
is negative or greater than or equal to
the size of this fluent iterableCopyright © 2010-2015. All Rights Reserved.