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() {
                         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
  Version:
    $Id: FluentIterable.java 1684264 2015-06-08 20:06:29Z tn $

- - ### Method Summary

    Methods
    Modifier and Type | Method and 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 an 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)` Construct a new FluentIterable from the provided iterable.
    `static <T> FluentIterable<T>` | `of(T... elements)` Creates a new FluentIterable from the provided elements.
    `static <T> FluentIterable<T>` | `of(T singleton)` Creates a new FluentIterable of the single provided element.
    `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>... others)` Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterables in alternating order.
    `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.

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

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

- - ### Method Detail

    - #### 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(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

    - #### of

          public static <T> FluentIterable<T> of(Iterable<T> iterable)

      Construct 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

    - #### 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

    - #### 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:
        `org.apache.commons.collections4.iterators.CollatingIterator 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 an 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:
        `org.apache.commons.collections4.iterators.CollatingIterator CollatingIterator}`

    - #### 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 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

    - #### 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

    - #### 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

    - #### 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

    - #### iterator

          public Iterator<E> iterator()

      Specified by:
        `iterator` in interface `Iterable<E>`

    - #### 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

    - #### 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

    - #### isEmpty

          public boolean isEmpty()

      Checks if this iterable is empty.
      Returns:
        true if this iterable does not contain any elements, false otherwise

    - #### 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

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

    - #### 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

    - #### 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

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

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.