FluentIterable (Apache Commons Collections 4.4 API)

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

All Methods Static Methods Instance Methods Concrete 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

Methods inherited from interface java.lang.Iterable
forEach, spliterator

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

Class FluentIterable<E>

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Method Detail

empty

of

of

of

append

append

collate

collate

eval

filter

limit

loop

reverse

skip

transform

unique

unmodifiable

zip

zip

iterator

asEnumeration

allMatch

anyMatch

isEmpty

contains

forEach

get

size

copyInto

toArray

toList

toString