Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.common.collect
Class FluentIterable<E>

    java.lang.Object
      com.google.common.collect.FluentIterable<E>

All Implemented Interfaces:
  Iterable<E>

    @Beta
    @GwtCompatible(emulated=true)
    public abstract class FluentIterable<E>

extends Object
implements Iterable<E>

`FluentIterable` provides a rich interface for manipulating `Iterable`s in a chained fashion. A `FluentIterable` can be created from an `Iterable`, or from a set of elements. The following types of methods are provided on `FluentIterable`:

- chained methods which return a new `FluentIterable` based in some way on the contents of the current one (for example `transform(com.google.common.base.Function)`)
- conversion methods which copy the `FluentIterable`'s contents into a new collection or array (for example `toImmutableList()`)
- element extraction methods which facilitate the retrieval of certain elements (for example `last()`)
- query methods which answer questions about the `FluentIterable`'s contents (for example `anyMatch(com.google.common.base.Predicate)`)

Here is an example that merges the lists returned by two separate database calls, transforms it by invoking `toString()` on each element, and returns the first 10 elements as an `ImmutableList`:

       FluentIterable
           .from(database.getClientList())
           .filter(activeInLastMonth())
           .transform(Functions.toStringFunction())
           .limit(10)
           .toImmutableList();

Anything which can be done using `FluentIterable` could be done in a different fashion (often with `Iterables`), however the use of `FluentIterable` makes many sets of operations significantly more concise.

Since:
  12.0
Author:
  Marcin Mikosik

Constructor Summary
`protected` | `FluentIterable()` Constructor for use by subclasses.

Method Summary
`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.
`boolean` | `contains(Object element)` Returns `true` if this fluent iterable contains any object for which `equals(element)` is true.
`FluentIterable<E>` | `cycle()` Returns a fluent iterable whose `Iterator` cycles indefinitely over the elements of this fluent iterable.
`
`<T> FluentIterable<T>`
` | `filter(Class<T> type)` Returns the elements from this fluent iterable that are instances of class `type`.
`FluentIterable<E>` | `filter(Predicate<? super E> predicate)` Returns the elements from this fluent iterable that satisfy a predicate.
`Optional<E>` | `first()` Returns an `Optional` containing the first element in this fluent iterable.
`Optional<E>` | `firstMatch(Predicate<? super E> predicate)` Returns an `Optional` containing the first element in this fluent iterable that satisfies the given predicate, if such an element exists.
`static
`<E> FluentIterable<E>`
` | `from(FluentIterable<E> iterable)` Deprecated. instances of `FluentIterable` don't need to be converted to `FluentIterable`
`static
`<E> FluentIterable<E>`
` | `from(Iterable<E> iterable)` Returns a fluent iterable that wraps `iterable`, or `iterable` itself if it is already a `FluentIterable`.
`E` | `get(int position)` Returns the element at the specified position in this fluent iterable.
`boolean` | `isEmpty()` Determines whether this fluent iterable is empty.
`Optional<E>` | `last()` Returns an `Optional` containing the last element in this fluent iterable.
`FluentIterable<E>` | `limit(int size)` Creates a fluent iterable with the first `size` elements of this fluent iterable.
`int` | `size()` Returns the number of elements in this fluent iterable.
`FluentIterable<E>` | `skip(int numberToSkip)` Returns a view of this fluent iterable that skips its first `numberToSkip` elements.
`E[]` | `toArray(Class<E> type)` Returns an array containing all of the elements from this fluent iterable in iteration order.
`ImmutableList<E>` | `toImmutableList()` Returns an `ImmutableList` containing all of the elements from this fluent iterable in proper sequence.
`ImmutableSet<E>` | `toImmutableSet()` Returns an `ImmutableSet` containing all of the elements from this fluent iterable with duplicates removed.
`ImmutableSortedSet<E>` | `toImmutableSortedSet(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 `comaprator.compare(x, y) == 0`) removed.
`ImmutableList<E>` | `toSortedImmutableList(Comparator<? super E> comparator)` Returns an `ImmutableList` containing all of the elements from this `FluentIterable` in the order specified by `comparator`.
`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<T>> function)` Applies `function` to each element of this fluent iterable and returns a fluent iterable with the concatenated combination of results.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface java.lang.Iterable
`iterator`

Constructor Detail

### FluentIterable

    protected FluentIterable()

  Constructor for use by subclasses.

Method Detail

### from

    public static <E> FluentIterable<E> from(Iterable<E> iterable)

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

### from

    @Deprecated
    public static <E> 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`.

### toString

    public String toString()

  Returns a string representation of this fluent iterable, with the format `[e1, e2, ..., en]`.

  Overrides:
    `toString` in class `Object`

### size

    public final int size()

  Returns the number of elements in this fluent iterable.

### contains

    public final boolean contains(@Nullable
                                  Object element)

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

### cycle

    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.

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

### filter

    @GwtIncompatible(value="Class.isInstance")
    public final <T> FluentIterable<T> filter(Class<T> type)

  Returns the elements from this fluent iterable that are instances of class `type`.

  Parameters:
    `type` - the type of elements desired

### anyMatch

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

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

### allMatch

    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.

### firstMatch

    public final 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.

  Warning: avoid using a `predicate` that matches `null`. If `null` is matched in this fluent iterable, a `NullPointerException` will be thrown.

### transform

    public final <T> 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.

### transformAndConcat

    public <T> FluentIterable<T> transformAndConcat(Function<? super E,? extends Iterable<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.

  Since:
    13.0

### first

    public final Optional<E> first()

  Returns an `Optional` containing the first element in this fluent iterable. If the iterable is empty, `Optional.absent()` is returned.

  Throws:
    `NullPointerException` - if the first element is null; if this is a possibility, use `iterator().next()` or `Iterables.getFirst(java.lang.Iterable, T)` instead.

### last

    public final Optional<E> last()

  Returns an `Optional` containing the last element in this fluent iterable. If the iterable is empty, `Optional.absent()` is returned.

  Throws:
    `NullPointerException` - if the last element is null; if this is a possibility, use `Iterables.getLast(java.lang.Iterable)` instead.

### skip

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

### limit

    public final FluentIterable<E> limit(int size)

  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.

  Parameters:
    `size` - the maximum number of elements in the returned fluent iterable
  Throws:
    `IllegalArgumentException` - if `size` is negative

### isEmpty

    public final boolean isEmpty()

  Determines whether this fluent iterable is empty.

### toImmutableList

    public final ImmutableList<E> toImmutableList()

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

### toSortedImmutableList

    public final ImmutableList<E> toSortedImmutableList(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 `toSortedImmutableList(Ordering.natural())`.

  Parameters:
    `comparator` - the function by which to sort list elements
  Throws:
    `NullPointerException` - if any element is null
  Since:
    13.0

### toImmutableSet

    public final ImmutableSet<E> toImmutableSet()

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

### toImmutableSortedSet

    public final ImmutableSortedSet<E> toImmutableSortedSet(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 `comaprator.compare(x, y) == 0`) removed. To produce an `ImmutableSortedSet` sorted by its natural ordering, use `toImmutableSortedSet(Ordering.natural())`.

  Parameters:
    `comparator` - the function by which to sort set elements
  Throws:
    `NullPointerException` - if any element is null

### toArray

    @GwtIncompatible(value="Array.newArray(Class, int)")
    public final E[] toArray(Class<E> type)

  Returns an array containing all of the elements from this fluent iterable in iteration order.

  Parameters:
    `type` - the type of the elements
  Returns:
    a newly-allocated array into which all the elements of this fluent iterable have been copied

### get

    public final E get(int position)

  Returns the element at the specified position in this fluent iterable.

  Parameters:
    `position` - position of the element to return
  Returns:
    the element at the specified position in this fluent iterable
  Throws:
    `IndexOutOfBoundsException` - if `position` is negative or greater than or equal to the size of this fluent iterable

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010-2012. All Rights Reserved.