@GwtCompatible(emulated=true) public abstract class FluentIterable<E> extends Object implements Iterable<E>
Stream
library.
The following types of methods are provided:
FluentIterable
based in some way on the
contents of the current one (for example transform(com.google.common.base.Function<? super E, T>)
)
last()
)
FluentIterable
's contents (for
example anyMatch(com.google.common.base.Predicate<? super E>)
)
FluentIterable
's contents into a new collection
or array (for example toList()
)
Several lesser-used features are currently available only as static methods on the Iterables
class.
Stream
is similar to this class, but generally more powerful, and certainly more
standard. Key differences include:
findFirst()
or iterator()
is invoked. (Even though Stream
contains all the right method signatures to implement Iterable
, it does not
actually do so, to avoid implying repeat-iterability.) FluentIterable
, on the other
hand, is multiple-use, and does implement Iterable
.
min/max
, distinct
,
reduce
, sorted
, the very powerful collect
, and built-in support for
parallelizing stream operations.
FluentIterable
contains several features not available on Stream
, which are
noted in the method descriptions below.
IntStream
, the use of which
is strongly recommended.
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 a List
:
ImmutableList<String> results =
FluentIterable.from(database.getClientList())
.filter(Client::isActiveInLastMonth)
.transform(Object::toString)
.limit(10)
.toList();
The approximate stream equivalent is:
List<String> results =
database.getClientList()
.stream()
.filter(Client::isActiveInLastMonth)
.map(Object::toString)
.limit(10)
.collect(Collectors.toList());
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 . |
static <T> FluentIterable<T> |
concat(Iterable<? extends Iterable<? extends T>> inputs)
Returns a fluent iterable that combines several iterables.
|
static <T> FluentIterable<T> |
concat(Iterable<? extends T>... inputs)
Returns a fluent iterable that combines several iterables.
|
static <T> FluentIterable<T> |
concat(Iterable<? extends T> a,
Iterable<? extends T> b)
Returns a fluent iterable that combines two iterables.
|
static <T> FluentIterable<T> |
concat(Iterable<? extends T> a,
Iterable<? extends T> b,
Iterable<? extends T> c)
Returns a fluent iterable that combines three iterables.
|
static <T> FluentIterable<T> |
concat(Iterable<? extends T> a,
Iterable<? extends T> b,
Iterable<? extends T> c,
Iterable<? extends T> d)
Returns a fluent iterable that combines four iterables.
|
boolean |
contains(@Nullable Object target)
Returns
true if this fluent iterable contains any object for which equals(target) 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(E[] elements)
Returns a fluent iterable containing
elements in the specified order. |
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 maxSize)
Creates a fluent iterable with the first
size elements of this fluent iterable. |
static <E> FluentIterable<E> |
of()
Returns a fluent iterable containing no elements.
|
static <E> FluentIterable<E> |
of(E element,
E... elements)
Returns a fluent iterable containing the specified elements in 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. |
Stream<E> |
stream()
Returns a stream of this fluent iterable's contents (similar to calling
Collection.stream() on a collection). |
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. |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
forEach, iterator, spliterator
protected FluentIterable()
public static <E> FluentIterable<E> from(Iterable<E> iterable)
iterable
, or iterable
itself if it is
already a FluentIterable
.
Stream
equivalent: Collection.stream()
if iterable
is a Collection
; Streams.stream(Iterable)
otherwise.
@Beta public static <E> FluentIterable<E> from(E[] elements)
elements
in the specified order.
The returned iterable is an unmodifiable view of the input array.
Stream
equivalent: Stream.of(T...)
.
of
)@Deprecated 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 public static <T> FluentIterable<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.
Stream
equivalent: Stream.concat(java.util.stream.Stream<? extends T>, java.util.stream.Stream<? extends T>)
.
@Beta public static <T> FluentIterable<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.
Stream
equivalent: use nested calls to Stream.concat(java.util.stream.Stream<? extends T>, java.util.stream.Stream<? extends T>)
, or see the
advice in concat(Iterable...)
.
@Beta public static <T> FluentIterable<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.
Stream
equivalent: use nested calls to Stream.concat(java.util.stream.Stream<? extends T>, java.util.stream.Stream<? extends T>)
, or see the
advice in concat(Iterable...)
.
@Beta public static <T> FluentIterable<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.
Stream
equivalent: to concatenate an arbitrary number of streams, use Stream.of(stream1, stream2, ...).flatMap(s -> s)
. If the sources are iterables, use Stream.of(iter1, iter2, ...).flatMap(Streams::stream)
.
NullPointerException
- if any of the provided iterables is null
@Beta public static <T> FluentIterable<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
.
Stream
equivalent: streamOfStreams.flatMap(s -> s)
or streamOfIterables.flatMap(Streams::stream)
. (See Streams.stream(java.lang.Iterable<T>)
.)
@Beta public static <E> FluentIterable<E> of()
Stream
equivalent: Stream.empty()
.
@Beta public static <E> FluentIterable<E> of(E element, E... elements)
Stream
equivalent: Stream.of(T...)
.
public String toString()
[e1, e2, ...,
en]
.
Stream
equivalent: stream.collect(Collectors.joining(", ", "[", "]"))
or (less efficiently) stream.collect(Collectors.toList()).toString()
.
public final int size()
Stream
equivalent: Stream.count()
.
public final boolean contains(@Nullable Object target)
true
if this fluent iterable contains any object for which equals(target)
is true.
Stream
equivalent: stream.anyMatch(Predicate.isEqual(target))
.
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.
Stream
equivalent: if the source iterable has only a single element e
, use Stream.generate(() -> e)
. Otherwise, collect your stream into a collection and
use Stream.generate(() -> collection).flatMap(Collection::stream)
.
@Beta 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.
Stream
equivalent: Stream.concat(java.util.stream.Stream<? extends T>, java.util.stream.Stream<? extends T>)
.
@Beta public final FluentIterable<E> append(E... elements)
elements
.
Stream
equivalent: Stream.concat(thisStream, Stream.of(elements))
.
public final FluentIterable<E> filter(Predicate<? super E> predicate)
remove()
.
Stream
equivalent: Stream.filter(java.util.function.Predicate<? super T>)
(same).
@GwtIncompatible public final <T> FluentIterable<T> filter(Class<T> type)
type
.
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());
public final boolean anyMatch(Predicate<? super E> predicate)
true
if any element in this fluent iterable satisfies the predicate.
Stream
equivalent: Stream.anyMatch(java.util.function.Predicate<? super T>)
(same).
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.
Stream
equivalent: Stream.allMatch(java.util.function.Predicate<? super T>)
(same).
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.
Stream
equivalent: stream.filter(predicate).findFirst()
.
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.
Stream
equivalent: Stream.map(java.util.function.Function<? super T, ? extends R>)
.
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.
Stream
equivalent: Stream.flatMap(java.util.function.Function<? super T, ? extends java.util.stream.Stream<? extends R>>)
(using a function that produces
streams, not iterables).
Function<E, Iterable<T>>
until 14.0)public final Optional<E> first()
Optional
containing the first element in this fluent iterable. If the
iterable is empty, Optional.absent()
is returned.
Stream
equivalent: if the goal is to obtain any element, Stream.findAny()
; if it must specifically be the first element, Stream#findFirst
.
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.public final Optional<E> last()
Optional
containing the last element in this fluent iterable. If the
iterable is empty, Optional.absent()
is returned. If the underlying iterable
is
a List
with RandomAccess
support, then this operation is guaranteed
to be O(1)
.
Stream
equivalent: stream.reduce((a, b) -> b)
.
NullPointerException
- if the last element is null; if this is a possibility, use Iterables.getLast(java.lang.Iterable<T>)
instead.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
.
Stream
equivalent: Stream.skip(long)
(same).
public final FluentIterable<E> limit(int maxSize)
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.
Stream
equivalent: Stream.limit(long)
(same).
maxSize
- the maximum number of elements in the returned fluent iterableIllegalArgumentException
- if size
is negativepublic final boolean isEmpty()
Stream
equivalent: !stream.findAny().isPresent()
.
public final ImmutableList<E> toList()
ImmutableList
containing all of the elements from this fluent iterable in
proper sequence.
Stream
equivalent: pass ImmutableList.toImmutableList()
to stream.collect()
.
NullPointerException
- if any element is null
toImmutableList()
).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())
.
Stream
equivalent: pass ImmutableList.toImmutableList()
to stream.sorted(comparator).collect()
.
comparator
- the function by which to sort list elementsNullPointerException
- if any element of this iterable is null
toSortedImmutableList()
).public final ImmutableSet<E> toSet()
ImmutableSet
containing all of the elements from this fluent iterable with
duplicates removed.
Stream
equivalent: pass ImmutableSet.toImmutableSet()
to stream.collect()
.
NullPointerException
- if any element is null
toImmutableSet()
).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())
.
Stream
equivalent: pass ImmutableSortedSet.toImmutableSortedSet(java.util.Comparator<? super E>)
to
stream.collect()
.
comparator
- the function by which to sort set elementsNullPointerException
- if any element of this iterable is null
toImmutableSortedSet()
).public final ImmutableMultiset<E> toMultiset()
ImmutableMultiset
containing all of the elements from this fluent iterable.
Stream
equivalent: pass ImmutableMultiset.toImmutableMultiset()
to
stream.collect()
.
NullPointerException
- if any element is nullpublic 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.
Stream
equivalent: stream.collect(ImmutableMap.toImmutableMap(k -> k,
valueFunction))
.
NullPointerException
- if any element of this iterable is null
, or if valueFunction
produces null
for any keypublic 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.
Stream
equivalent: stream.collect(Collectors.groupingBy(keyFunction))
behaves similarly, but returns a mutable Map<K, List<E>>
instead, and may not preserve
the order of entries).
keyFunction
- the function used to produce the key for each valueNullPointerException
- if any element of this iterable is null
, or if keyFunction
produces null
for any keypublic 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
.
Stream
equivalent: stream.collect(ImmutableMap.toImmutableMap(keyFunction, v -> v))
.
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 element of this iterable is null
, or if keyFunction
produces null
for any key@GwtIncompatible public final E[] toArray(Class<E> type)
Stream
equivalent: if an object array is acceptable, use stream.toArray()
; if type
is a class literal such as MyType.class
, use stream.toArray(MyType[]::new)
. Otherwise use stream.toArray( len -> (E[])
Array.newInstance(type, len))
.
type
- the type of the elements@CanIgnoreReturnValue public final <C extends Collection<? super E>> C copyInto(C collection)
collection
. This is equivalent to
calling Iterables.addAll(collection, this)
.
Stream
equivalent: stream.forEachOrdered(collection::add)
or stream.forEach(collection::add)
.
collection
- the collection to copy elements tocollection
, for convenience@Beta public final String join(Joiner joiner)
String
containing all of the elements of this fluent iterable joined with
joiner
.
Stream
equivalent: joiner.join(stream.iterator())
, or, if you are not
using any optional Joiner
features, stream.collect(Collectors.joining(delimiter)
.
public final E get(int position)
Stream
equivalent: stream.skip(position).findFirst().get()
(but note
that this throws different exception types, and throws an exception if null
would be
returned).
position
- position of the element to returnIndexOutOfBoundsException
- if position
is negative or greater than or equal to
the size of this fluent iterablepublic final Stream<E> stream()
Collection.stream()
on a collection).
Note: the earlier in the chain you can switch to Stream
usage (ideally not
going through FluentIterable
at all), the more performant and idiomatic your code will
be. This method is a transitional aid, to be used only when really necessary.
Copyright © 2010–2019. All rights reserved.