Guava: Google Core Libraries for Java 33.1.0-jre · com.google.common.collect.FluentIterable

Modifier and Type	Class and Description
private static class	FluentIterable.FromIterableFunction<E extends @Nullable Object> Function that transforms `Iterable<E>` into a fluent iterable.

Modifier and Type	Field and Description
private final Optional<Iterable<E>>	iterableDelegate

Access	Constructor and Description
protected	FluentIterable() Constructor for use by subclasses.
pack-priv	FluentIterable(Iterable<E> iterable)

Method Summary

Modifier and Type	Method and Description
public final boolean	allMatch(Predicate<? super E> predicate) Returns `true` if every element in this fluent iterable satisfies the predicate.
public final boolean	anyMatch(Predicate<? super E> predicate) Returns `true` if any element in this fluent iterable satisfies the predicate.
public final 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`.
public final FluentIterable<E>	append(E... elements) Returns a fluent iterable whose iterators traverse first the elements of this fluent iterable, followed by `elements`.
public static <T extends @Nullable Object> FluentIterable<T>	concat(Iterable<? extends T> a, Iterable<? extends T> b) Returns a fluent iterable that combines two iterables.
public static <T extends @Nullable Object> FluentIterable<T>	concat(Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c) Returns a fluent iterable that combines three iterables.
public static <T extends @Nullable Object> 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.
public static <T extends @Nullable Object> FluentIterable<T>	concat(Iterable<? extends T>... inputs) Returns a fluent iterable that combines several iterables.
public static <T extends @Nullable Object> FluentIterable<T>	concat(final Iterable<? extends Iterable<? extends T>> inputs) Returns a fluent iterable that combines several iterables.
private static <T extends @Nullable Object> FluentIterable<T>	concatNoDefensiveCopy(final Iterable<? extends T>... inputs) Concatenates a varargs array of iterables without making a defensive copy of the array.
public final boolean	contains(Object target) Returns `true` if this fluent iterable contains any object for which `equals(target)` is true.
public final <C extends Collection<? super E>> C	Returns: `collection`, for convenience copyInto(C the collection to copy elements to collection) Copies all the elements from this fluent iterable to `collection`.
public final FluentIterable<E>	cycle() Returns a fluent iterable whose `Iterator` cycles indefinitely over the elements of this fluent iterable.
public final FluentIterable<E>	filter(Predicate<? super E> predicate) Returns the elements from this fluent iterable that satisfy a predicate.
public final <T> FluentIterable<T>	filter(Class<T> type) Returns the elements from this fluent iterable that are instances of class `type`.
public final Optional<@NonNull E>	first() Returns an `Optional` containing the first element in this fluent iterable.
public final Optional<@NonNull 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.
public static <E extends @Nullable Object> FluentIterable<E>	from(final Iterable<E> iterable) Returns a fluent iterable that wraps `iterable`, or `iterable` itself if it is already a `FluentIterable`.
public static <E extends @Nullable Object> FluentIterable<E>	from(E[] elements) Returns a fluent iterable containing `elements` in the specified order.
public static <E extends @Nullable Object> FluentIterable<E>	from(FluentIterable<E> iterable) Deprecated instances of `FluentIterable` don't need to be converted to `FluentIterable` Construct a fluent iterable from another fluent iterable.
public final E	Returns: the element at the specified position in this fluent iterable get(int position of the element to return position) Returns the element at the specified position in this fluent iterable.
private Iterable<E>	getDelegate()
public final <K> ImmutableListMultimap<K, @NonNull E>	index(Function<? super E, K> the function used to produce the key for each value keyFunction) Creates an index `ImmutableListMultimap` that contains the results of applying a specified function to each item in this `FluentIterable` of values.
public final boolean	isEmpty() Determines whether this fluent iterable is empty.
public final String	join(Joiner joiner) Returns a `String` containing all of the elements of this fluent iterable joined with `joiner`.
public final Optional<@NonNull E>	last() Returns an `Optional` containing the last element in this fluent iterable.
public final FluentIterable<E>	limit(int the maximum number of elements in the returned fluent iterable maxSize) Creates a fluent iterable with the first `size` elements of this fluent iterable.
public static <E extends @Nullable Object> FluentIterable<E>	of() Returns a fluent iterable containing no elements.
public static <E extends @Nullable Object> FluentIterable<E>	of(E element, E... elements) Returns a fluent iterable containing the specified elements in order.
public final int	size() Returns the number of elements in this fluent iterable.
public final FluentIterable<E>	skip(int numberToSkip) Returns a view of this fluent iterable that skips its first `numberToSkip` elements.
public final Stream<E>	stream() Returns a stream of this fluent iterable's contents (similar to calling `Collection#stream` on a collection).
public final E[]	Returns: a newly-allocated array into which all the elements of this fluent iterable have been copied toArray(Class<@NonNull E> the type of the elements type) Returns an array containing all of the elements from this fluent iterable in iteration order.
public final ImmutableList<@NonNull E>	toList() Returns an `ImmutableList` containing all of the elements from this fluent iterable in proper sequence.
public final <V> ImmutableMap<@NonNull 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`.
public final ImmutableMultiset<@NonNull E>	toMultiset() Returns an `ImmutableMultiset` containing all of the elements from this fluent iterable.
public final ImmutableSet<@NonNull E>	toSet() Returns an `ImmutableSet` containing all of the elements from this fluent iterable with duplicates removed.
public final ImmutableList<@NonNull E>	toSortedList(Comparator<? super E> the function by which to sort list elements comparator) Returns an `ImmutableList` containing all of the elements from this `FluentIterable` in the order specified by `comparator`.
public final ImmutableSortedSet<@NonNull E>	toSortedSet(Comparator<? super E> the function by which to sort set elements 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.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of this fluent iterable, with the format `[e1, e2, ..., en]`.
public final <T extends @Nullable Object> FluentIterable<T>	transform(Function<? super E, T> function) Returns a fluent iterable that applies `function` to each element of this fluent iterable.
public <T extends @Nullable Object> 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.
public final <K> ImmutableMap<K, @NonNull E>	Returns: a map mapping the result of evaluating the function `keyFunction` on each value in this fluent iterable to that value uniqueIndex(Function<? super E, K> the function used to produce the key for each value keyFunction) Returns a map with the contents of this `FluentIterable` as its `values`, indexed by keys derived from those values.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

iterableDelegate	back to summary
private final Optional<Iterable<E>> iterableDelegate

FluentIterable	back to summary
protected FluentIterable() Constructor for use by subclasses.

FluentIterable	back to summary
pack-priv FluentIterable(Iterable<E> iterable)

Method Detail

allMatch back to summary

allMatch	back to summary
public final boolean allMatch(Predicate<? super E> predicate) Returns `true` if every element in this fluent iterable satisfies the predicate. If this fluent iterable is empty, `true` is returned. `Stream` equivalent: `Stream#allMatch` (same).

public final boolean allMatch(Predicate<? super E> predicate)

Returns true if every element in this fluent iterable satisfies the predicate. If this fluent iterable is empty, true is returned.

Stream equivalent: Stream#allMatch (same).

anyMatch back to summary

anyMatch	back to summary
public final boolean anyMatch(Predicate<? super E> predicate) Returns `true` if any element in this fluent iterable satisfies the predicate. `Stream` equivalent: `Stream#anyMatch` (same).

public final boolean anyMatch(Predicate<? super E> predicate)

Returns true if any element in this fluent iterable satisfies the predicate.

Stream equivalent: Stream#anyMatch (same).

append back to summary

append	back to summary
public final 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`. The iterators are not polled until necessary. The returned iterable's `Iterator` supports `remove()` when the corresponding `Iterator` supports it. `Stream` equivalent: `Stream#concat`. Since 18.0

public final 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. The iterators are not polled until necessary.

The returned iterable's Iterator supports remove() when the corresponding Iterator supports it.

Stream equivalent: Stream#concat.

Since: 18.0

append back to summary

append	back to summary
public final FluentIterable<E> append(E... elements) Returns a fluent iterable whose iterators traverse first the elements of this fluent iterable, followed by `elements`. `Stream` equivalent: `Stream.concat(thisStream, Stream.of(elements))`. Since 18.0

public final FluentIterable<E> append(E... elements)

Returns a fluent iterable whose iterators traverse first the elements of this fluent iterable, followed by elements.

Stream equivalent: Stream.concat(thisStream, Stream.of(elements)).

Since: 18.0

concat back to summary

concat	back to summary
public static <T extends @Nullable Object> FluentIterable<T> concat(Iterable<? extends T> a, Iterable<? extends T> b) Returns a fluent iterable that combines two iterables. The returned iterable has an iterator that traverses the elements in `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`. Since 20.0

public static <T extends @Nullable Object> FluentIterable<T> concat(Iterable<? extends T> a, Iterable<? extends T> b)

Returns a fluent iterable that combines two iterables. The returned iterable has an iterator that traverses the elements in 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.

Since: 20.0

concat back to summary

concat	back to summary
public static <T extends @Nullable Object> FluentIterable<T> concat(Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c) Returns a fluent iterable that combines three iterables. The returned iterable has an iterator that traverses the elements in `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`, or see the advice in `concat(Iterable...)`. Since 20.0

public static <T extends @Nullable Object> FluentIterable<T> concat(Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c)

Returns a fluent iterable that combines three iterables. The returned iterable has an iterator that traverses the elements in 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, or see the advice in concat(Iterable...).

Since: 20.0

concat back to summary

concat	back to summary
public static <T extends @Nullable Object> 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. The returned iterable has an iterator that traverses the elements in `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`, or see the advice in `concat(Iterable...)`. Since 20.0

public static <T extends @Nullable Object> 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. The returned iterable has an iterator that traverses the elements in 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, or see the advice in concat(Iterable...).

Since: 20.0

concat back to summary

concat	back to summary
public static <T extends @Nullable Object> FluentIterable<T> concat(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 in `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)`. Annotations @SafeVarargs Exceptions NullPointerException: if any of the provided iterables is `null` Since 20.0

public static <T extends @Nullable Object> FluentIterable<T> concat(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 in 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).

Annotations

@SafeVarargs

Exceptions

NullPointerException:: if any of the provided iterables is null

Since

20.0

concat back to summary

concat	back to summary
public static <T extends @Nullable Object> FluentIterable<T> concat(final Iterable<? extends 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 in `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`.) Since 20.0

public static <T extends @Nullable Object> FluentIterable<T> concat(final Iterable<? extends Iterable<? extends T>> inputs)

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.)

Since: 20.0

concatNoDefensiveCopy	back to summary
private static <T extends @Nullable Object> FluentIterable<T> concatNoDefensiveCopy(final Iterable<? extends T>... inputs) Concatenates a varargs array of iterables without making a defensive copy of the array.

contains back to summary

contains	back to summary
public final boolean contains(Object target) Returns `true` if this fluent iterable contains any object for which `equals(target)` is true. `Stream` equivalent: `stream.anyMatch(Predicate.isEqual(target))`.

public final boolean contains(Object target)

Returns true if this fluent iterable contains any object for which equals(target) is true.

Stream equivalent: stream.anyMatch(Predicate.isEqual(target)).

copyInto back to summary

copyInto	back to summary
public final <C extends Collection<? super E>> C copyInto(C collection) Copies all the elements from this fluent iterable to `collection`. This is equivalent to calling `Iterables.addAll(collection, this)`. `Stream` equivalent: `stream.forEachOrdered(collection::add)` or `stream.forEach(collection::add)`. Parameters collection:C the collection to copy elements to Returns:C `collection`, for convenience Annotations @CanIgnoreReturnValue Since 14.0

public final <C extends Collection<? super E>> C copyInto(C collection)

Copies all the elements from this fluent iterable to collection. This is equivalent to calling Iterables.addAll(collection, this).

Stream equivalent: stream.forEachOrdered(collection::add) or stream.forEach(collection::add).

Parameters

collection:C: the collection to copy elements to

Returns:C

collection, for convenience

Annotations

@CanIgnoreReturnValue

Since

14.0

cycle back to summary

cycle	back to summary
public final FluentIterable<E> cycle() Returns a fluent iterable whose `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)`.

public final FluentIterable<E> cycle()

Returns a fluent iterable whose 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).

filter back to summary

filter	back to summary
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 support `remove()`. `Stream` equivalent: `Stream#filter` (same).

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 support remove().

Stream equivalent: Stream#filter (same).

filter back to summary

filter	back to summary
public final <T> FluentIterable<T> filter(Class<T> type) Returns the elements from this fluent iterable that are instances of class `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());` Annotations @GwtIncompatible

public final <T> FluentIterable<T> filter(Class<T> type)

Returns the elements from this fluent iterable that are instances of class 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());

Annotations

@GwtIncompatible

first back to summary

first	back to summary
public final Optional<@NonNull E> first() Returns an `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`. Annotations @SuppressWarnings:nullness Exceptions NullPointerException: if the first element is null; if this is a possibility, use `iterator().next()` or `Iterables#getFirst` instead.

public final Optional<@NonNull E> first()

Returns an 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.

Annotations

@SuppressWarnings:nullness

Exceptions

NullPointerException:: if the first element is null; if this is a possibility, use iterator().next() or Iterables#getFirst instead.

firstMatch back to summary

firstMatch	back to summary
public final Optional<@NonNull 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. 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()`. Annotations @SuppressWarnings:nullness

public final Optional<@NonNull 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.

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().

Annotations

@SuppressWarnings:nullness

from back to summary

from	back to summary
public static <E extends @Nullable Object> FluentIterable<E> from(final Iterable<E> iterable) Returns a fluent iterable that wraps `iterable`, or `iterable` itself if it is already a `FluentIterable`. `Stream` equivalent: `Collection#stream` if `iterable` is a `Collection`; `Streams#stream(Iterable)` otherwise.

public static <E extends @Nullable Object> FluentIterable<E> from(final Iterable<E> iterable)

Returns a fluent iterable that wraps iterable, or iterable itself if it is already a FluentIterable.

Stream equivalent: Collection#stream if iterable is a Collection; Streams#stream(Iterable) otherwise.

from back to summary

from	back to summary
public static <E extends @Nullable Object> FluentIterable<E> from(E[] elements) Returns a fluent iterable containing `elements` 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`)

public static <E extends @Nullable Object> FluentIterable<E> from(E[] elements)

Returns a fluent iterable containing elements 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 back to summary

from	back to summary
public static <E extends @Nullable Object> FluentIterable<E> from(FluentIterable<E> iterable) Deprecated instances of `FluentIterable` don't need to be converted to `FluentIterable` Construct a fluent iterable from another fluent iterable. This is obviously never necessary, but is intended to help call out cases where one migration from `Iterable` to `FluentIterable` has obviated the need to explicitly convert to a `FluentIterable`. Annotations @Deprecated @InlineMe replacement:checkNotNull(iterable) staticImports:checkNotNull

public static <E extends @Nullable Object> FluentIterable<E> from(FluentIterable<E> iterable)

Deprecated

instances of FluentIterable don't need to be converted to FluentIterable

Construct a fluent iterable from another fluent iterable. This is obviously never necessary, but is intended to help call out cases where one migration from Iterable to FluentIterable has obviated the need to explicitly convert to a FluentIterable.

Annotations

@Deprecated
@InlineMe
replacement:checkNotNull(iterable)
staticImports:checkNotNull

get back to summary

get	back to summary
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 if `null` would be returned). Parameters position:int position of the element to return Returns:E the element at the specified position in this fluent iterable Annotations @ParametricNullness Exceptions IndexOutOfBoundsException: if `position` is negative or greater than or equal to the size of this fluent iterable

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 if null would be returned).

Parameters

position:int: position of the element to return

Returns:E

the element at the specified position in this fluent iterable

Annotations

@ParametricNullness

Exceptions

IndexOutOfBoundsException:: if position is negative or greater than or equal to the size of this fluent iterable

getDelegate	back to summary
private Iterable<E> getDelegate()

index back to summary

index	back to summary
public final <K> ImmutableListMultimap<K, @NonNull 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. 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. Parameters keyFunction:Function<? super E, K> the function used to produce the key for each value Annotations @SuppressWarnings:nullness Exceptions NullPointerException: if any element of this iterable is `null`, or if `keyFunction` produces `null` for any key Since 14.0

public final <K> ImmutableListMultimap<K, @NonNull 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. 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.

Parameters

keyFunction:Function<? super E, K>: the function used to produce the key for each value

Annotations

@SuppressWarnings:nullness

Exceptions

NullPointerException:: if any element of this iterable is null, or if keyFunction produces null for any key

Since

14.0

isEmpty back to summary

isEmpty	back to summary
public final boolean isEmpty() Determines whether this fluent iterable is empty. `Stream` equivalent: `!stream.findAny().isPresent()`.

public final boolean isEmpty()

Determines whether this fluent iterable is empty.

Stream equivalent: !stream.findAny().isPresent().

join back to summary

join	back to summary
public final String join(Joiner joiner) Returns a `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)`. Since 18.0

public final String join(Joiner joiner)

Returns a 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).

Since: 18.0

last back to summary

last	back to summary
public final Optional<@NonNull E> last() Returns an `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 `java.util.RandomAccess` support, then this operation is guaranteed to be `O(1)`. `Stream` equivalent: `stream.reduce((a, b) -> b)`. Annotations @SuppressWarnings:nullness Exceptions NullPointerException: if the last element is null; if this is a possibility, use `Iterables#getLast` instead.

public final Optional<@NonNull E> last()

Returns an 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 java.util.RandomAccess support, then this operation is guaranteed to be O(1).

Stream equivalent: stream.reduce((a, b) -> b).

Annotations

@SuppressWarnings:nullness

Exceptions

NullPointerException:: if the last element is null; if this is a possibility, use Iterables#getLast instead.

limit back to summary

limit	back to summary
public final FluentIterable<E> limit(int maxSize) Creates a fluent iterable with the first `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` (same). Parameters maxSize:int the maximum number of elements in the returned fluent iterable Exceptions IllegalArgumentException: if `size` is negative

public final FluentIterable<E> limit(int maxSize)

Creates a fluent iterable with the first 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 (same).

Parameters

maxSize:int: the maximum number of elements in the returned fluent iterable

Exceptions

IllegalArgumentException:: if size is negative

of back to summary

of	back to summary
public static <E extends @Nullable Object> FluentIterable<E> of() Returns a fluent iterable containing no elements. `Stream` equivalent: `Stream#empty`. Since 20.0

public static <E extends @Nullable Object> FluentIterable<E> of()

Returns a fluent iterable containing no elements.

Stream equivalent: Stream#empty.

Since: 20.0

of back to summary

of	back to summary
public static <E extends @Nullable 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

public static <E extends @Nullable 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

size back to summary

size	back to summary
public final int size() Returns the number of elements in this fluent iterable. `Stream` equivalent: `Stream#count`.

public final int size()

Returns the number of elements in this fluent iterable.

Stream equivalent: Stream#count.

skip back to summary

skip	back to summary
public final FluentIterable<E> skip(int numberToSkip) Returns a view of this fluent iterable that skips its first `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 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` (same).

public final FluentIterable<E> skip(int numberToSkip)

Returns a view of this fluent iterable that skips its first 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 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 (same).

stream back to summary

stream	back to summary
public final Stream<E> stream() Returns a stream of this fluent iterable's contents (similar to calling `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. Since 21.0

public final Stream<E> stream()

Returns a stream of this fluent iterable's contents (similar to calling 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.

Since: 21.0

toArray back to summary

toArray	back to summary
public final E[] toArray(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, 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))`. Parameters type:Class<@NonNull E> the type of the elements Returns:E[] a newly-allocated array into which all the elements of this fluent iterable have been copied Annotations @GwtIncompatible

public final E[] toArray(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, 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)).

Parameters

type:Class<@NonNull E>: the type of the elements

Returns:E[]

a newly-allocated array into which all the elements of this fluent iterable have been copied

Annotations

@GwtIncompatible

toList back to summary

toList	back to summary
public final ImmutableList<@NonNull E> toList() Returns an `ImmutableList` containing all of the elements from this fluent iterable in proper sequence. `Stream` equivalent: pass `ImmutableList#toImmutableList` to `stream.collect()`. Annotations @SuppressWarnings:nullness Exceptions NullPointerException: if any element is `null` Since 14.0 (since 12.0 as `toImmutableList()`).

public final ImmutableList<@NonNull E> toList()

Returns an ImmutableList containing all of the elements from this fluent iterable in proper sequence.

Stream equivalent: pass ImmutableList#toImmutableList to stream.collect().

Annotations

@SuppressWarnings:nullness

Exceptions

NullPointerException:: if any element is null

Since

14.0 (since 12.0 as toImmutableList()).

toMap back to summary

toMap	back to summary
public final <V> ImmutableMap<@NonNull 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`. 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))`. Annotations @SuppressWarnings:nullness Exceptions NullPointerException: if any element of this iterable is `null`, or if `valueFunction` produces `null` for any key Since 14.0

public final <V> ImmutableMap<@NonNull 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. 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)).

Annotations

@SuppressWarnings:nullness

Exceptions

NullPointerException:: if any element of this iterable is null, or if valueFunction produces null for any key

Since

14.0

toMultiset back to summary

toMultiset	back to summary
public final ImmutableMultiset<@NonNull E> toMultiset() Returns an `ImmutableMultiset` containing all of the elements from this fluent iterable. `Stream` equivalent: pass `ImmutableMultiset#toImmutableMultiset` to `stream.collect()`. Annotations @SuppressWarnings:nullness Exceptions NullPointerException: if any element is null Since 19.0

public final ImmutableMultiset<@NonNull E> toMultiset()

Returns an ImmutableMultiset containing all of the elements from this fluent iterable.

Stream equivalent: pass ImmutableMultiset#toImmutableMultiset to stream.collect().

Annotations

@SuppressWarnings:nullness

Exceptions

NullPointerException:: if any element is null

Since

19.0

toSet back to summary

toSet	back to summary
public final ImmutableSet<@NonNull E> toSet() Returns an `ImmutableSet` containing all of the elements from this fluent iterable with duplicates removed. `Stream` equivalent: pass `ImmutableSet#toImmutableSet` to `stream.collect()`. Annotations @SuppressWarnings:nullness Exceptions NullPointerException: if any element is `null` Since 14.0 (since 12.0 as `toImmutableSet()`).

public final ImmutableSet<@NonNull E> toSet()

Returns an ImmutableSet containing all of the elements from this fluent iterable with duplicates removed.

Stream equivalent: pass ImmutableSet#toImmutableSet to stream.collect().

Annotations

@SuppressWarnings:nullness

Exceptions

NullPointerException:: if any element is null

Since

14.0 (since 12.0 as toImmutableSet()).

toSortedList back to summary

toSortedList	back to summary
public final ImmutableList<@NonNull E> toSortedList(Comparator<? super E> comparator) Returns an `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()`. Parameters comparator:Comparator<? super E> the function by which to sort list elements Annotations @SuppressWarnings:nullness Exceptions NullPointerException: if any element of this iterable is `null` Since 14.0 (since 13.0 as `toSortedImmutableList()`).

public final ImmutableList<@NonNull E> toSortedList(Comparator<? super E> comparator)

Returns an 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().

Parameters

comparator:Comparator<? super E>: the function by which to sort list elements

Annotations

@SuppressWarnings:nullness

Exceptions

NullPointerException:: if any element of this iterable is null

Since

14.0 (since 13.0 as toSortedImmutableList()).

toSortedSet back to summary

toSortedSet	back to summary
public final ImmutableSortedSet<@NonNull 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. To produce an `ImmutableSortedSet` sorted by its natural ordering, use `toSortedSet(Ordering.natural())`. `Stream` equivalent: pass `ImmutableSortedSet#toImmutableSortedSet` to `stream.collect()`. Parameters comparator:Comparator<? super E> the function by which to sort set elements Annotations @SuppressWarnings:nullness Exceptions NullPointerException: if any element of this iterable is `null` Since 14.0 (since 12.0 as `toImmutableSortedSet()`).

public final ImmutableSortedSet<@NonNull 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. To produce an ImmutableSortedSet sorted by its natural ordering, use toSortedSet(Ordering.natural()).

Stream equivalent: pass ImmutableSortedSet#toImmutableSortedSet to stream.collect().

Parameters

comparator:Comparator<? super E>: the function by which to sort set elements

Annotations

@SuppressWarnings:nullness

Exceptions

NullPointerException:: if any element of this iterable is null

Since

14.0 (since 12.0 as toImmutableSortedSet()).

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.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()`. Returns:String Doc from java.lang.Object.toString. a string representation of the object Annotations @Override

public String toString()

Overrides java.lang.Object.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().

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object

Annotations

@Override

transform back to summary

transform	back to summary
public final <T extends @Nullable Object> FluentIterable<T> transform(Function<? super E, T> function) Returns a fluent iterable that applies `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`.

public final <T extends @Nullable Object> FluentIterable<T> transform(Function<? super E, T> function)

Returns a fluent iterable that applies 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.

transformAndConcat back to summary

transformAndConcat	back to summary
public <T extends @Nullable Object> 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. `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` (using a function that produces streams, not iterables). Since 13.0 (required `Function<E, Iterable<T>>` until 14.0)

public <T extends @Nullable Object> 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. 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 (using a function that produces streams, not iterables).

Since: 13.0 (required Function<E, Iterable<T>> until 14.0)

uniqueIndex back to summary

uniqueIndex	back to summary
public final <K> ImmutableMap<K, @NonNull 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. 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))`. Parameters keyFunction:Function<? super E, K> the function used to produce the key for each value Returns:ImmutableMap<K, @NonNull E> a map mapping the result of evaluating the function `keyFunction` on each value in this fluent iterable to that value Annotations @SuppressWarnings:nullness Exceptions IllegalArgumentException: if `keyFunction` produces the same key for more than one value in this fluent iterable NullPointerException: if any element of this iterable is `null`, or if `keyFunction` produces `null` for any key Since 14.0

public final <K> ImmutableMap<K, @NonNull 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. 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)).

Parameters

keyFunction:Function<? super E, K>: the function used to produce the key for each value

Returns:ImmutableMap<K, @NonNull E>

a map mapping the result of evaluating the function keyFunction on each value in this fluent iterable to that value

Annotations

@SuppressWarnings:nullness

Exceptions

IllegalArgumentException:: if keyFunction produces the same key for more than one value in this fluent iterable
NullPointerException:: if any element of this iterable is null, or if keyFunction produces null for any key

Since

14.0

public abstract Class FluentIterable<E extends @Nullable Object>

Comparison to streams

Example

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class FluentIterable.FromIterableFunction<E extends @Nullable Object>

Constructor Summary

Method Summary

Constructor Detail

Method Detail