Class FluentIterable<E extends @Nullable java.lang.Object>
- java.lang.Object
-
- com.google.common.collect.FluentIterable<E>
-
- All Implemented Interfaces:
java.lang.Iterable<E>
@GwtCompatible(emulated=true) public abstract class FluentIterable<E extends @Nullable java.lang.Object> extends java.lang.Object implements java.lang.Iterable<E>
A discouraged (but not deprecated) precursor to Java's superiorStream
library.The following types of methods are provided:
- chaining methods which return a new
FluentIterable
based in some way on the contents of the current one (for exampletransform(com.google.common.base.Function<? super E, T>)
) - element extraction methods which facilitate the retrieval of certain elements (for example
last()
) - query methods which answer questions about the
FluentIterable
's contents (for exampleanyMatch(com.google.common.base.Predicate<? super E>)
) - conversion methods which copy the
FluentIterable
's contents into a new collection or array (for exampletoList()
)
Several lesser-used features are currently available only as static methods on the
Iterables
class.Comparison to streams
Stream
is similar to this class, but generally more powerful, and certainly more standard. Key differences include:- A stream is single-use; it becomes invalid as soon as any "terminal operation" such
as
findFirst()
oriterator()
is invoked. (Even thoughStream
contains all the right method signatures to implementIterable
, it does not actually do so, to avoid implying repeat-iterability.)FluentIterable
, on the other hand, is multiple-use, and does implementIterable
. - Streams offer many features not found here, including
min/max
,distinct
,reduce
,sorted
, the very powerfulcollect
, and built-in support for parallelizing stream operations. FluentIterable
contains several features not available onStream
, which are noted in the method descriptions below.- Streams include primitive-specialized variants such as
IntStream
, the use of which is strongly recommended. - Streams are standard Java, not requiring a third-party dependency.
Example
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 aList
:
The approximate stream equivalent is:ImmutableList<String> results = FluentIterable.from(database.getClientList()) .filter(Client::isActiveInLastMonth) .transform(Object::toString) .limit(10) .toList();
List<String> results = database.getClientList() .stream() .filter(Client::isActiveInLastMonth) .map(Object::toString) .limit(10) .collect(Collectors.toList());
- Since:
- 12.0
- Author:
- Marcin Mikosik
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
FluentIterable()
Constructor for use by subclasses.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description boolean
allMatch(Predicate<? super E> predicate)
Returnstrue
if every element in this fluent iterable satisfies the predicate.boolean
anyMatch(Predicate<? super E> predicate)
Returnstrue
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 byelements
.FluentIterable<E>
append(java.lang.Iterable<? extends E> other)
Returns a fluent iterable whose iterators traverse first the elements of this fluent iterable, followed by those ofother
.static <T extends @Nullable java.lang.Object>
FluentIterable<T>concat(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> inputs)
Returns a fluent iterable that combines several iterables.static <T extends @Nullable java.lang.Object>
FluentIterable<T>concat(java.lang.Iterable<? extends T>... inputs)
Returns a fluent iterable that combines several iterables.static <T extends @Nullable java.lang.Object>
FluentIterable<T>concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b)
Returns a fluent iterable that combines two iterables.static <T extends @Nullable java.lang.Object>
FluentIterable<T>concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b, java.lang.Iterable<? extends T> c)
Returns a fluent iterable that combines three iterables.static <T extends @Nullable java.lang.Object>
FluentIterable<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)
Returns a fluent iterable that combines four iterables.boolean
contains(java.lang.Object target)
Returnstrue
if this fluent iterable contains any object for whichequals(target)
is true.<C extends java.util.Collection<? super E>>
CcopyInto(C collection)
Copies all the elements from this fluent iterable tocollection
.FluentIterable<E>
cycle()
Returns a fluent iterable whoseIterator
cycles indefinitely over the elements of this fluent iterable.FluentIterable<E>
filter(Predicate<? super E> predicate)
Returns the elements from this fluent iterable that satisfy a predicate.<T> FluentIterable<T>
filter(java.lang.Class<T> type)
Returns the elements from this fluent iterable that are instances of classtype
.Optional<@NonNull E>
first()
Returns anOptional
containing the first element in this fluent iterable.Optional<@NonNull E>
firstMatch(Predicate<? super E> predicate)
Returns anOptional
containing the first element in this fluent iterable that satisfies the given predicate, if such an element exists.static <E extends @Nullable java.lang.Object>
FluentIterable<E>from(FluentIterable<E> iterable)
Deprecated.instances ofFluentIterable
don't need to be converted toFluentIterable
static <E extends @Nullable java.lang.Object>
FluentIterable<E>from(E[] elements)
Returns a fluent iterable containingelements
in the specified order.static <E extends @Nullable java.lang.Object>
FluentIterable<E>from(java.lang.Iterable<E> iterable)
Returns a fluent iterable that wrapsiterable
, oriterable
itself if it is already aFluentIterable
.E
get(int position)
Returns the element at the specified position in this fluent iterable.<K> ImmutableListMultimap<K,@NonNull E>
index(Function<? super E,K> keyFunction)
Creates an indexImmutableListMultimap
that contains the results of applying a specified function to each item in thisFluentIterable
of values.boolean
isEmpty()
Determines whether this fluent iterable is empty.java.lang.String
join(Joiner joiner)
Returns aString
containing all of the elements of this fluent iterable joined withjoiner
.Optional<@NonNull E>
last()
Returns anOptional
containing the last element in this fluent iterable.FluentIterable<E>
limit(int maxSize)
Creates a fluent iterable with the firstsize
elements of this fluent iterable.static <E extends @Nullable java.lang.Object>
FluentIterable<E>of()
Returns a fluent iterable containing no elements.static <E extends @Nullable java.lang.Object>
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 firstnumberToSkip
elements.java.util.stream.Stream<E>
stream()
Returns a stream of this fluent iterable's contents (similar to callingCollection.stream()
on a collection).@Nullable E[]
toArray(java.lang.Class<@NonNull E> type)
Returns an array containing all of the elements from this fluent iterable in iteration order.ImmutableList<@NonNull E>
toList()
Returns anImmutableList
containing all of the elements from this fluent iterable in proper sequence.<V> ImmutableMap<@NonNull E,V>
toMap(Function<? super E,V> valueFunction)
Returns an immutable map whose keys are the distinct elements of thisFluentIterable
and whose value for each key was computed byvalueFunction
.ImmutableMultiset<@NonNull E>
toMultiset()
Returns anImmutableMultiset
containing all of the elements from this fluent iterable.ImmutableSet<@NonNull E>
toSet()
Returns anImmutableSet
containing all of the elements from this fluent iterable with duplicates removed.ImmutableList<@NonNull E>
toSortedList(java.util.Comparator<? super E> comparator)
Returns anImmutableList
containing all of the elements from thisFluentIterable
in the order specified bycomparator
.ImmutableSortedSet<@NonNull E>
toSortedSet(java.util.Comparator<? super E> comparator)
Returns anImmutableSortedSet
containing all of the elements from thisFluentIterable
in the order specified bycomparator
, with duplicates (determined bycomparator.compare(x, y) == 0
) removed.java.lang.String
toString()
Returns a string representation of this fluent iterable, with the format[e1, e2, ..., en]
.<T extends @Nullable java.lang.Object>
FluentIterable<T>transform(Function<? super E,T> function)
Returns a fluent iterable that appliesfunction
to each element of this fluent iterable.<T extends @Nullable java.lang.Object>
FluentIterable<T>transformAndConcat(Function<? super E,? extends java.lang.Iterable<? extends T>> function)
Appliesfunction
to each element of this fluent iterable and returns a fluent iterable with the concatenated combination of results.<K> ImmutableMap<K,@NonNull E>
uniqueIndex(Function<? super E,K> keyFunction)
Returns a map with the contents of thisFluentIterable
as itsvalues
, indexed by keys derived from those values.
-
-
-
Constructor Detail
-
FluentIterable
protected FluentIterable()
Constructor for use by subclasses.
-
-
Method Detail
-
from
public static <E extends @Nullable java.lang.Object> FluentIterable<E> from(java.lang.Iterable<E> iterable)
Returns a fluent iterable that wrapsiterable
, oriterable
itself if it is already aFluentIterable
.Stream
equivalent:Collection.stream()
ifiterable
is aCollection
;Streams.stream(Iterable)
otherwise.
-
from
public static <E extends @Nullable java.lang.Object> FluentIterable<E> from(E[] elements)
Returns a fluent iterable containingelements
in the specified order.The returned iterable is an unmodifiable view of the input array.
Stream
equivalent:Stream.of(T...)
.- Since:
- 20.0 (since 18.0 as an overload of
of
)
-
from
@Deprecated @InlineMe(replacement="checkNotNull(iterable)", staticImports="com.google.common.base.Preconditions.checkNotNull") public static <E extends @Nullable java.lang.Object> FluentIterable<E> from(FluentIterable<E> iterable)
Deprecated.instances ofFluentIterable
don't need to be converted toFluentIterable
Construct a fluent iterable from another fluent iterable. This is obviously never necessary, but is intended to help call out cases where one migration fromIterable
toFluentIterable
has obviated the need to explicitly convert to aFluentIterable
.
-
concat
public static <T extends @Nullable java.lang.Object> FluentIterable<T> concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b)
Returns a fluent iterable that combines two iterables. 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.Stream
equivalent:Stream.concat(java.util.stream.Stream<? extends T>, java.util.stream.Stream<? extends T>)
.- Since:
- 20.0
-
concat
public static <T extends @Nullable java.lang.Object> FluentIterable<T> concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b, java.lang.Iterable<? extends T> c)
Returns a fluent iterable that combines three iterables. 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.Stream
equivalent: use nested calls toStream.concat(java.util.stream.Stream<? extends T>, java.util.stream.Stream<? extends T>)
, or see the advice inconcat(Iterable...)
.- Since:
- 20.0
-
concat
public static <T extends @Nullable java.lang.Object> FluentIterable<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)
Returns a fluent iterable that combines four iterables. 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.Stream
equivalent: use nested calls toStream.concat(java.util.stream.Stream<? extends T>, java.util.stream.Stream<? extends T>)
, or see the advice inconcat(Iterable...)
.- Since:
- 20.0
-
concat
public static <T extends @Nullable java.lang.Object> FluentIterable<T> concat(java.lang.Iterable<? extends T>... inputs)
Returns a fluent iterable that combines several iterables. 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.Stream
equivalent: to concatenate an arbitrary number of streams, useStream.of(stream1, stream2, ...).flatMap(s -> s)
. If the sources are iterables, useStream.of(iter1, iter2, ...).flatMap(Streams::stream)
.- Throws:
java.lang.NullPointerException
- if any of the provided iterables isnull
- Since:
- 20.0
-
concat
public static <T extends @Nullable java.lang.Object> FluentIterable<T> concat(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> inputs)
Returns a fluent iterable that combines several iterables. 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 isnull
.Stream
equivalent:streamOfStreams.flatMap(s -> s)
orstreamOfIterables.flatMap(Streams::stream)
. (SeeStreams.stream(java.lang.Iterable<T>)
.)- Since:
- 20.0
-
of
public static <E extends @Nullable java.lang.Object> FluentIterable<E> of()
Returns a fluent iterable containing no elements.Stream
equivalent:Stream.empty()
.- Since:
- 20.0
-
of
public static <E extends @Nullable java.lang.Object> FluentIterable<E> of(E element, E... elements)
Returns a fluent iterable containing the specified elements in order.Stream
equivalent:Stream.of(T...)
.- Since:
- 20.0
-
toString
public java.lang.String toString()
Returns a string representation of this fluent iterable, with the format[e1, e2, ..., en]
.Stream
equivalent:stream.collect(Collectors.joining(", ", "[", "]"))
or (less efficiently)stream.collect(Collectors.toList()).toString()
.- Overrides:
toString
in classjava.lang.Object
-
size
public final int size()
Returns the number of elements in this fluent iterable.Stream
equivalent:Stream.count()
.
-
contains
public final boolean contains(@CheckForNull java.lang.Object target)
Returnstrue
if this fluent iterable contains any object for whichequals(target)
is true.Stream
equivalent:stream.anyMatch(Predicate.isEqual(target))
.
-
cycle
public final FluentIterable<E> cycle()
Returns a fluent iterable whoseIterator
cycles indefinitely over the elements of this fluent iterable.That iterator supports
remove()
ifiterable.iterator()
does. Afterremove()
is called, subsequent cycles omit the removed element, which is no longer in this fluent iterable. The iterator'shasNext()
method returnstrue
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 elemente
, useStream.generate(() -> e)
. Otherwise, collect your stream into a collection and useStream.generate(() -> collection).flatMap(Collection::stream)
.
-
append
public final FluentIterable<E> append(java.lang.Iterable<? extends E> other)
Returns a fluent iterable whose iterators traverse first the elements of this fluent iterable, followed by those ofother
. The iterators are not polled until necessary.The returned iterable's
Iterator
supportsremove()
when the correspondingIterator
supports it.Stream
equivalent:Stream.concat(java.util.stream.Stream<? extends T>, java.util.stream.Stream<? extends T>)
.- Since:
- 18.0
-
append
public final FluentIterable<E> append(E... elements)
Returns a fluent iterable whose iterators traverse first the elements of this fluent iterable, followed byelements
.Stream
equivalent:Stream.concat(thisStream, Stream.of(elements))
.- Since:
- 18.0
-
filter
public final FluentIterable<E> filter(Predicate<? super E> predicate)
Returns the elements from this fluent iterable that satisfy a predicate. The resulting fluent iterable's iterator does not supportremove()
.Stream
equivalent:Stream.filter(java.util.function.Predicate<? super T>)
(same).
-
filter
@GwtIncompatible public final <T> FluentIterable<T> filter(java.lang.Class<T> type)
Returns the elements from this fluent iterable that are instances of classtype
.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());
-
anyMatch
public final boolean anyMatch(Predicate<? super E> predicate)
Returnstrue
if any element in this fluent iterable satisfies the predicate.Stream
equivalent:Stream.anyMatch(java.util.function.Predicate<? super T>)
(same).
-
allMatch
public final boolean allMatch(Predicate<? super E> predicate)
Returnstrue
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).
-
firstMatch
public final Optional<@NonNull E> firstMatch(Predicate<? super E> predicate)
Returns anOptional
containing the first element in this fluent iterable that satisfies the given predicate, if such an element exists.Warning: avoid using a
predicate
that matchesnull
. Ifnull
is matched in this fluent iterable, aNullPointerException
will be thrown.Stream
equivalent:stream.filter(predicate).findFirst()
.
-
transform
public final <T extends @Nullable java.lang.Object> FluentIterable<T> transform(Function<? super E,T> function)
Returns a fluent iterable that appliesfunction
to each element of this fluent iterable.The returned fluent iterable's iterator supports
remove()
if this iterable's iterator does. After a successfulremove()
call, this fluent iterable no longer contains the corresponding element.Stream
equivalent:Stream.map(java.util.function.Function<? super T, ? extends R>)
.
-
transformAndConcat
public <T extends @Nullable java.lang.Object> FluentIterable<T> transformAndConcat(Function<? super E,? extends java.lang.Iterable<? extends T>> function)
Appliesfunction
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 successfulremove()
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).- Since:
- 13.0 (required
Function<E, Iterable<T>>
until 14.0)
-
first
public final Optional<@NonNull E> first()
Returns anOptional
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
.- Throws:
java.lang.NullPointerException
- if the first element is null; if this is a possibility, useiterator().next()
orIterables.getFirst(java.lang.Iterable<? extends T>, T)
instead.
-
last
public final Optional<@NonNull E> last()
Returns anOptional
containing the last element in this fluent iterable. If the iterable is empty,Optional.absent()
is returned. If the underlyingiterable
is aList
withRandomAccess
support, then this operation is guaranteed to beO(1)
.Stream
equivalent:stream.reduce((a, b) -> b)
.- Throws:
java.lang.NullPointerException
- if the last element is null; if this is a possibility, useIterables.getLast(java.lang.Iterable<T>)
instead.
-
skip
public final FluentIterable<E> skip(int numberToSkip)
Returns a view of this fluent iterable that skips its firstnumberToSkip
elements. If this fluent iterable contains fewer thannumberToSkip
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 iterator skips the firstnumberToSkip
elements that exist when the iterator is created, not whenskip()
is called.The returned fluent iterable's iterator supports
remove()
if theIterator
of this fluent iterable supports it. Note that it is not possible to delete the last skipped element by immediately callingremove()
on the returned fluent iterable's iterator, as theIterator
contract states that a call to* remove()
before a call tonext()
will throw anIllegalStateException
.Stream
equivalent:Stream.skip(long)
(same).
-
limit
public final FluentIterable<E> limit(int maxSize)
Creates a fluent iterable with the firstsize
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 supportsremove()
if this fluent iterable's iterator does.Stream
equivalent:Stream.limit(long)
(same).- Parameters:
maxSize
- the maximum number of elements in the returned fluent iterable- Throws:
java.lang.IllegalArgumentException
- ifsize
is negative
-
isEmpty
public final boolean isEmpty()
Determines whether this fluent iterable is empty.Stream
equivalent:!stream.findAny().isPresent()
.
-
toList
public final ImmutableList<@NonNull E> toList()
Returns anImmutableList
containing all of the elements from this fluent iterable in proper sequence.Stream
equivalent: passImmutableList.toImmutableList()
tostream.collect()
.- Throws:
java.lang.NullPointerException
- if any element isnull
- Since:
- 14.0 (since 12.0 as
toImmutableList()
).
-
toSortedList
public final ImmutableList<@NonNull E> toSortedList(java.util.Comparator<? super E> comparator)
Returns anImmutableList
containing all of the elements from thisFluentIterable
in the order specified bycomparator
. To produce anImmutableList
sorted by its natural ordering, usetoSortedList(Ordering.natural())
.Stream
equivalent: passImmutableList.toImmutableList()
tostream.sorted(comparator).collect()
.- Parameters:
comparator
- the function by which to sort list elements- Throws:
java.lang.NullPointerException
- if any element of this iterable isnull
- Since:
- 14.0 (since 13.0 as
toSortedImmutableList()
).
-
toSet
public final ImmutableSet<@NonNull E> toSet()
Returns anImmutableSet
containing all of the elements from this fluent iterable with duplicates removed.Stream
equivalent: passImmutableSet.toImmutableSet()
tostream.collect()
.- Throws:
java.lang.NullPointerException
- if any element isnull
- Since:
- 14.0 (since 12.0 as
toImmutableSet()
).
-
toSortedSet
public final ImmutableSortedSet<@NonNull E> toSortedSet(java.util.Comparator<? super E> comparator)
Returns anImmutableSortedSet
containing all of the elements from thisFluentIterable
in the order specified bycomparator
, with duplicates (determined bycomparator.compare(x, y) == 0
) removed. To produce anImmutableSortedSet
sorted by its natural ordering, usetoSortedSet(Ordering.natural())
.Stream
equivalent: passImmutableSortedSet.toImmutableSortedSet(java.util.Comparator<? super E>)
tostream.collect()
.- Parameters:
comparator
- the function by which to sort set elements- Throws:
java.lang.NullPointerException
- if any element of this iterable isnull
- Since:
- 14.0 (since 12.0 as
toImmutableSortedSet()
).
-
toMultiset
public final ImmutableMultiset<@NonNull E> toMultiset()
Returns anImmutableMultiset
containing all of the elements from this fluent iterable.Stream
equivalent: passImmutableMultiset.toImmutableMultiset()
tostream.collect()
.- Throws:
java.lang.NullPointerException
- if any element is null- Since:
- 19.0
-
toMap
public final <V> ImmutableMap<@NonNull E,V> toMap(Function<? super E,V> valueFunction)
Returns an immutable map whose keys are the distinct elements of thisFluentIterable
and whose value for each key was computed byvalueFunction
. 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))
.- Throws:
java.lang.NullPointerException
- if any element of this iterable isnull
, or ifvalueFunction
producesnull
for any key- Since:
- 14.0
-
index
public final <K> ImmutableListMultimap<K,@NonNull E> index(Function<? super E,K> keyFunction)
Creates an indexImmutableListMultimap
that contains the results of applying a specified function to each item in thisFluentIterable
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 mutableMap<K, List<E>>
instead, and may not preserve the order of entries.- Parameters:
keyFunction
- the function used to produce the key for each value- Throws:
java.lang.NullPointerException
- if any element of this iterable isnull
, or ifkeyFunction
producesnull
for any key- Since:
- 14.0
-
uniqueIndex
public final <K> ImmutableMap<K,@NonNull E> uniqueIndex(Function<? super E,K> keyFunction)
Returns a map with the contents of thisFluentIterable
as itsvalues
, 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 applyingkeyFunction
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))
.- Parameters:
keyFunction
- the function used to produce the key for each value- Returns:
- a map mapping the result of evaluating the function
keyFunction
on each value in this fluent iterable to that value - Throws:
java.lang.IllegalArgumentException
- ifkeyFunction
produces the same key for more than one value in this fluent iterablejava.lang.NullPointerException
- if any element of this iterable isnull
, or ifkeyFunction
producesnull
for any key- Since:
- 14.0
-
toArray
@GwtIncompatible public final @Nullable E[] toArray(java.lang.Class<@NonNull E> type)
Returns an array containing all of the elements from this fluent iterable in iteration order.Stream
equivalent: if an object array is acceptable, usestream.toArray()
; iftype
is a class literal such asMyType.class
, usestream.toArray(MyType[]::new)
. Otherwise usestream.toArray( len -> (E[]) Array.newInstance(type, len))
.- Parameters:
type
- the type of the elements- Returns:
- a newly-allocated array into which all the elements of this fluent iterable have been copied
-
copyInto
@CanIgnoreReturnValue public final <C extends java.util.Collection<? super E>> C copyInto(C collection)
Copies all the elements from this fluent iterable tocollection
. This is equivalent to callingIterables.addAll(collection, this)
.Stream
equivalent:stream.forEachOrdered(collection::add)
orstream.forEach(collection::add)
.- Parameters:
collection
- the collection to copy elements to- Returns:
collection
, for convenience- Since:
- 14.0
-
join
public final java.lang.String join(Joiner joiner)
Returns aString
containing all of the elements of this fluent iterable joined withjoiner
.Stream
equivalent:joiner.join(stream.iterator())
, or, if you are not using any optionalJoiner
features,stream.collect(Collectors.joining(delimiter)
.- Since:
- 18.0
-
get
public final E get(int position)
Returns the element at the specified position in this fluent iterable.Stream
equivalent:stream.skip(position).findFirst().get()
(but note that this throws different exception types, and throws an exception ifnull
would be returned).- Parameters:
position
- position of the element to return- Returns:
- the element at the specified position in this fluent iterable
- Throws:
java.lang.IndexOutOfBoundsException
- ifposition
is negative or greater than or equal to the size of this fluent iterable
-
stream
public final java.util.stream.Stream<E> stream()
Returns a stream of this fluent iterable's contents (similar to callingCollection.stream()
on a collection).Note: the earlier in the chain you can switch to
Stream
usage (ideally not going throughFluentIterable
at all), the more performant and idiomatic your code will be. This method is a transitional aid, to be used only when really necessary.- Since:
- 21.0
-
-