Package org.apache.commons.collections4

# Class FluentIterable<E>

java.lang.Object
org.apache.commons.collections4.FluentIterable<E>

Type Parameters:
  `E` - the element type

All Implemented Interfaces:
  `Iterable<E>`

public class FluentIterable<E> extends Object implements Iterable<E>
A FluentIterable provides a powerful yet simple API for manipulating Iterable instances in a fluent manner.

A FluentIterable can be created either from an Iterable or from a set of elements. The following types of methods are provided:

- fluent methods which return a new `FluentIterable` instance, providing a view of the original iterable (e.g. filter(Predicate));
- conversion methods which copy the FluentIterable's contents into a new collection or array (e.g. toList());
- utility methods which answer questions about the FluentIterable's contents (e.g. size(), anyMatch(Predicate)).

The following example outputs the first 3 even numbers in the range [1, 10] into a list:

     List<String> result =
       FluentIterable
           .of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
           .filter(new Predicate<Integer>() {
                       public boolean evaluate(Integer number) {
                            return number % 2 == 0;
                       }
                  )
           .transform(TransformerUtils.stringValueTransformer())
           .limit(3)
           .toList();

The resulting list will contain the following elements:

    [2, 4, 6]

Since:
  4.1

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `allMatch(Predicate<? super E> predicate)`
  Checks if all elements contained in this iterable are matching the provided predicate.
  `boolean`
  `anyMatch(Predicate<? super E> predicate)`
  Checks if this iterable contains any element matching the provided predicate.
  `FluentIterable<E>`
  `append(E... elements)`
  Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the provided elements.
  `FluentIterable<E>`
  `append(Iterable<? extends E> other)`
  Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the elements of the provided iterable.
  `Enumeration<E>`
  `asEnumeration()`
  Returns an Enumeration that will enumerate all elements contained in this iterable.
  `FluentIterable<E>`
  `collate(Iterable<? extends E> other)`
  Returns a new FluentIterable whose iterator will traverse the elements of the current and provided iterable in natural order.
  `FluentIterable<E>`
  `collate(Iterable<? extends E> other, Comparator<? super E> comparator)`
  Returns a new FluentIterable whose iterator will traverse the elements of the current and provided iterable according to the ordering defined by a comparator.
  `boolean`
  `contains(Object object)`
  Checks if the object is contained in this iterable.
  `void`
  `copyInto(Collection<? super E> collection)`
  Traverses an iterator of this iterable and adds all elements to the provided collection.
  `static <T> FluentIterable<T>`
  `empty()`
  Creates a new empty FluentIterable.
  `FluentIterable<E>`
  `eval()`
  This method fully traverses an iterator of this iterable and returns a new iterable with the same contents, but without any reference to the originating iterables and/or iterators.
  `FluentIterable<E>`
  `filter(Predicate<? super E> predicate)`
  Returns a new FluentIterable whose iterator will only return elements from this iterable matching the provided predicate.
  `void`
  `forEach(Closure<? super E> closure)`
  Applies the closure to all elements contained in this iterable.
  `E`
  `get(int position)`
  Returns the element at the provided position in this iterable.
  `boolean`
  `isEmpty()`
  Checks if this iterable is empty.
  `Iterator<E>`
  `iterator()`
  `FluentIterable<E>`
  `limit(long maxSize)`
  Returns a new FluentIterable whose iterator will return at most the provided maximum number of elements from this iterable.
  `FluentIterable<E>`
  `loop()`
  Returns a new FluentIterable whose iterator will loop infinitely over the elements from this iterable.
  `static <T> FluentIterable<T>`
  `of(Iterable<T> iterable)`
  Constructs a new FluentIterable from the provided iterable.
  `static <T> FluentIterable<T>`
  `of(T singleton)`
  Creates a new FluentIterable of the single provided element.
  `static <T> FluentIterable<T>`
  `of(T... elements)`
  Creates a new FluentIterable from the provided elements.
  `FluentIterable<E>`
  `reverse()`
  Returns a new FluentIterable whose iterator will traverse the elements from this iterable in reverse order.
  `int`
  `size()`
  Returns the number of elements that are contained in this iterable.
  `FluentIterable<E>`
  `skip(long elementsToSkip)`
  Returns a new FluentIterable whose iterator will skip the first N elements from this iterable.
  `E[]`
  `toArray(Class<E> arrayClass)`
  Returns an array containing all elements of this iterable by traversing its iterator.
  `List<E>`
  `toList()`
  Returns a mutable list containing all elements of this iterable by traversing its iterator.
  `String`
  `toString()`
  `<O> FluentIterable<O>`
  `transform(Transformer<? super E,? extends O> transformer)`
  Returns a new FluentIterable whose iterator will return all elements of this iterable transformed by the provided transformer.
  `FluentIterable<E>`
  `unique()`
  Returns a new FluentIterable whose iterator will return a unique view of this iterable.
  `FluentIterable<E>`
  `unmodifiable()`
  Returns a new FluentIterable whose iterator will return an unmodifiable view of this iterable.
  `FluentIterable<E>`
  `zip(Iterable<? extends E> other)`
  Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterable in alternating order.
  `FluentIterable<E>`
  `zip(Iterable<? extends E>... others)`
  Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterables in alternating order.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

- ## Method Details

  - ### empty

    public static <T> FluentIterable<T> empty()
    Creates a new empty FluentIterable.
    Type Parameters:
      `T` - the element type
    Returns:
      a new empty FluentIterable

  - ### of

    public static <T> FluentIterable<T> of(Iterable<T> iterable)
    Constructs a new FluentIterable from the provided iterable. If the iterable is already an instance of FluentIterable, the instance will be returned instead.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `T` - the element type
    Parameters:
      `iterable` - the iterable to wrap into a FluentIterable, may not be null
    Returns:
      a new FluentIterable wrapping the provided iterable
    Throws:
      `NullPointerException` - if iterable is null

  - ### of

    public static <T> FluentIterable<T> of(T singleton)
    Creates a new FluentIterable of the single provided element.

    The returned iterable's iterator does not support `remove()`.

    Type Parameters:
      `T` - the element type
    Parameters:
      `singleton` - the singleton element
    Returns:
      a new FluentIterable containing the singleton

  - ### of

    public static <T> FluentIterable<T> of(T... elements)
    Creates a new FluentIterable from the provided elements.

    The returned iterable's iterator does not support `remove()`.

    Type Parameters:
      `T` - the element type
    Parameters:
      `elements` - the elements to be contained in the FluentIterable
    Returns:
      a new FluentIterable containing the provided elements

  - ### allMatch

    public boolean allMatch(Predicate<? super E> predicate)
    Checks if all elements contained in this iterable are matching the provided predicate.

    A `null` or empty iterable returns true.

    Parameters:
      `predicate` - the predicate to use, may not be null
    Returns:
      true if all elements contained in this iterable match the predicate, false otherwise
    Throws:
      `NullPointerException` - if predicate is null

  - ### anyMatch

    public boolean anyMatch(Predicate<? super E> predicate)
    Checks if this iterable contains any element matching the provided predicate.

    A `null` or empty iterable returns false.

    Parameters:
      `predicate` - the predicate to use, may not be null
    Returns:
      true if at least one element contained in this iterable matches the predicate, false otherwise
    Throws:
      `NullPointerException` - if predicate is null

  - ### append

    public FluentIterable<E> append(E... elements)
    Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the provided elements.
    Parameters:
      `elements` - the elements to append to the iterable
    Returns:
      a new iterable, combining this iterable with the elements

  - ### append

    public FluentIterable<E> append(Iterable<? extends E> other)
    Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the elements of the provided iterable.
    Parameters:
      `other` - the other iterable to combine, may not be null
    Returns:
      a new iterable, combining this iterable with other
    Throws:
      `NullPointerException` - if other is null

  - ### asEnumeration

    public Enumeration<E> asEnumeration()
    Returns an Enumeration that will enumerate all elements contained in this iterable.
    Returns:
      an Enumeration over the elements of this iterable

  - ### collate

    public FluentIterable<E> collate(Iterable<? extends E> other)
    Returns a new FluentIterable whose iterator will traverse the elements of the current and provided iterable in natural order.

    Example: natural ordering

    - this contains elements [1, 3, 5, 7]
    - other contains elements [2, 4, 6, 8]

    The returned iterable will traverse the elements in the following order: [1, 2, 3, 4, 5, 6, 7, 8]

    Parameters:
      `other` - the other iterable to collate, may not be null
    Returns:
      a new iterable, collating this iterable with the other in natural order
    Throws:
      `NullPointerException` - if other is null
    See Also:
      - `CollatingIterator`

  - ### collate

    public FluentIterable<E> collate(Iterable<? extends E> other, Comparator<? super E> comparator)
    Returns a new FluentIterable whose iterator will traverse the elements of the current and provided iterable according to the ordering defined by a comparator.

    Example: descending order

    - this contains elements [7, 5, 3, 1]
    - other contains elements [8, 6, 4, 2]

    The returned iterable will traverse the elements in the following order: [8, 7, 6, 5, 4, 3, 2, 1]

    Parameters:
      `comparator` - the comparator to define an ordering, may be null, in which case natural ordering will be used
      `other` - the other iterable to collate, may not be null
    Returns:
      a new iterable, collating this iterable with the other in natural order
    Throws:
      `NullPointerException` - if other is null
    See Also:
      - `CollatingIterator`

  - ### contains

    public boolean contains(Object object)
    Checks if the object is contained in this iterable.
    Parameters:
      `object` - the object to check
    Returns:
      true if the object is contained in this iterable, false otherwise

  - ### copyInto

    public void copyInto(Collection<? super E> collection)
    Traverses an iterator of this iterable and adds all elements to the provided collection.
    Parameters:
      `collection` - the collection to add the elements
    Throws:
      `NullPointerException` - if collection is null

  - ### eval

    public FluentIterable<E> eval()
    This method fully traverses an iterator of this iterable and returns a new iterable with the same contents, but without any reference to the originating iterables and/or iterators.

    Calling this method is equivalent to:

           FluentIterable<E> someIterable = ...;
           FluentIterable.of(someIterable.toList());

    Returns:
      a new iterable with the same contents as this iterable

  - ### filter

    public FluentIterable<E> filter(Predicate<? super E> predicate)
    Returns a new FluentIterable whose iterator will only return elements from this iterable matching the provided predicate.
    Parameters:
      `predicate` - the predicate used to filter elements
    Returns:
      a new iterable, providing a filtered view of this iterable
    Throws:
      `NullPointerException` - if predicate is null

  - ### forEach

    public void forEach(Closure<? super E> closure)
    Applies the closure to all elements contained in this iterable.
    Parameters:
      `closure` - the closure to apply to each element, may not be null
    Throws:
      `NullPointerException` - if closure is null

  - ### get

    public E get(int position)
    Returns the element at the provided position in this iterable. In order to return the element, an iterator needs to be traversed up to the requested position.
    Parameters:
      `position` - the position of the element to return
    Returns:
      the element
    Throws:
      `IndexOutOfBoundsException` - if the provided position is outside the valid range of this iterable: [0, size)

  - ### isEmpty

    public boolean isEmpty()
    Checks if this iterable is empty.
    Returns:
      true if this iterable does not contain any elements, false otherwise

  - ### iterator

    public Iterator<E> iterator()
    Specified by:
      `iterator` in interface `Iterable<E>`

  - ### limit

    public FluentIterable<E> limit(long maxSize)
    Returns a new FluentIterable whose iterator will return at most the provided maximum number of elements from this iterable.
    Parameters:
      `maxSize` - the maximum number of elements
    Returns:
      a new iterable, providing a bounded view of this iterable
    Throws:
      `IllegalArgumentException` - if maxSize is negative

  - ### loop

    public FluentIterable<E> loop()
    Returns a new FluentIterable whose iterator will loop infinitely over the elements from this iterable.
    Returns:
      a new iterable, providing a looping view of this iterable

  - ### reverse

    public FluentIterable<E> reverse()
    Returns a new FluentIterable whose iterator will traverse the elements from this iterable in reverse order.
    Returns:
      a new iterable, providing a reversed view of this iterable

  - ### size

    public int size()
    Returns the number of elements that are contained in this iterable. In order to determine the size, an iterator needs to be traversed.
    Returns:
      the size of this iterable

  - ### skip

    public FluentIterable<E> skip(long elementsToSkip)
    Returns a new FluentIterable whose iterator will skip the first N elements from this iterable.
    Parameters:
      `elementsToSkip` - the number of elements to skip
    Returns:
      a new iterable, providing a view of this iterable by skipping the first N elements
    Throws:
      `IllegalArgumentException` - if elementsToSkip is negative

  - ### toArray

    public E[] toArray(Class<E> arrayClass)
    Returns an array containing all elements of this iterable by traversing its iterator.
    Parameters:
      `arrayClass` - the class of array to create
    Returns:
      an array of the iterable contents
    Throws:
      `ArrayStoreException` - if arrayClass is invalid

  - ### toList

    public List<E> toList()
    Returns a mutable list containing all elements of this iterable by traversing its iterator.

    The returned list is guaranteed to be mutable.

    Returns:
      a list of the iterable contents

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### transform

    public <O> FluentIterable<O> transform(Transformer<? super E,? extends O> transformer)
    Returns a new FluentIterable whose iterator will return all elements of this iterable transformed by the provided transformer.
    Type Parameters:
      `O` - the output element type
    Parameters:
      `transformer` - the transformer applied to each element
    Returns:
      a new iterable, providing a transformed view of this iterable
    Throws:
      `NullPointerException` - if transformer is null

  - ### unique

    public FluentIterable<E> unique()
    Returns a new FluentIterable whose iterator will return a unique view of this iterable.
    Returns:
      a new iterable, providing a unique view of this iterable

  - ### unmodifiable

    public FluentIterable<E> unmodifiable()
    Returns a new FluentIterable whose iterator will return an unmodifiable view of this iterable.
    Returns:
      a new iterable, providing an unmodifiable view of this iterable

  - ### zip

    public FluentIterable<E> zip(Iterable<? extends E> other)
    Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterable in alternating order.
    Parameters:
      `other` - the other iterable to interleave, may not be null
    Returns:
      a new iterable, interleaving this iterable with others
    Throws:
      `NullPointerException` - if other is null

  - ### zip

    public FluentIterable<E> zip(Iterable<? extends E>... others)
    Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterables in alternating order.
    Parameters:
      `others` - the iterables to interleave, may not be null
    Returns:
      a new iterable, interleaving this iterable with others
    Throws:
      `NullPointerException` - if either of the provided iterables is null