    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.collections4;
    018
    019import java.util.Arrays;
    020import java.util.Collection;
    021import java.util.Comparator;
    022import java.util.Enumeration;
    023import java.util.Iterator;
    024import java.util.List;
    025import java.util.Objects;
    026
    027import org.apache.commons.collections4.iterators.SingletonIterator;
    028
    029/**
    030 * A FluentIterable provides a powerful yet simple API for manipulating
    031 * Iterable instances in a fluent manner.
    032 * <p>
    033 * A FluentIterable can be created either from an Iterable or from a set
    034 * of elements. The following types of methods are provided:
    035 * </p>
    036 * <ul>
    037 *   <li>fluent methods which return a new {@code FluentIterable} instance,
    038 *       providing a view of the original iterable (e.g. filter(Predicate));
    039 *   <li>conversion methods which copy the FluentIterable's contents into a
    040 *       new collection or array (e.g. toList());
    041 *   <li>utility methods which answer questions about the FluentIterable's
    042 *       contents (e.g. size(), anyMatch(Predicate)).
    043 *   <li>
    044 * </ul>
    045 * <p>
    046 * The following example outputs the first 3 even numbers in the range [1, 10]
    047 * into a list:
    048 * </p>
    049 * <pre>
    050 * List&lt;String&gt; result =
    051 *   FluentIterable
    052 *       .of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
    053 *       .filter(new Predicate&lt;Integer&gt;() {
    054 *                   public boolean evaluate(Integer number) {
    055 *                        return number % 2 == 0;
    056 *                   }
    057 *              )
    058 *       .transform(TransformerUtils.stringValueTransformer())
    059 *       .limit(3)
    060 *       .toList();
    061 * </pre>
    062 * The resulting list will contain the following elements:
    063 * <pre>[2, 4, 6]</pre>
    064 *
    065 * @param <E>  the element type
    066 * @since 4.1
    067 */
    068public class FluentIterable<E> implements Iterable<E> {
    069
    070    /**
    071     * Creates a new empty FluentIterable.
    072     *
    073     * @param <T>  the element type
    074     * @return a new empty FluentIterable
    075     */
    076    public static <T> FluentIterable<T> empty() {
    077        return IterableUtils.EMPTY_ITERABLE;
    078    }
    079
    080    /**
    081     * Constructs a new FluentIterable from the provided iterable. If the
    082     * iterable is already an instance of FluentIterable, the instance
    083     * will be returned instead.
    084     * <p>
    085     * The returned iterable's iterator supports {@code remove()} when the
    086     * corresponding input iterator supports it.
    087     *
    088     * @param <T>  the element type
    089     * @param iterable  the iterable to wrap into a FluentIterable, may not be null
    090     * @return a new FluentIterable wrapping the provided iterable
    091     * @throws NullPointerException if iterable is null
    092     */
    093    public static <T> FluentIterable<T> of(final Iterable<T> iterable) {
    094        IterableUtils.checkNotNull(iterable);
    095        if (iterable instanceof FluentIterable<?>) {
    096            return (FluentIterable<T>) iterable;
    097        }
    098        return new FluentIterable<>(iterable);
    099    }
    100
    101    /**
    102     * Creates a new FluentIterable of the single provided element.
    103     * <p>
    104     * The returned iterable's iterator does not support {@code remove()}.
    105     *
    106     * @param <T>  the element type
    107     * @param singleton  the singleton element
    108     * @return a new FluentIterable containing the singleton
    109     */
    110    public static <T> FluentIterable<T> of(final T singleton) {
    111        return of(IteratorUtils.asIterable(new SingletonIterator<>(singleton, false)));
    112    }
    113
    114    /**
    115     * Creates a new FluentIterable from the provided elements.
    116     * <p>
    117     * The returned iterable's iterator does not support {@code remove()}.
    118     *
    119     * @param <T>  the element type
    120     * @param elements  the elements to be contained in the FluentIterable
    121     * @return a new FluentIterable containing the provided elements
    122     */
    123    public static <T> FluentIterable<T> of(final T... elements) {
    124        return of(Arrays.asList(elements));
    125    }
    126
    127    /** A reference to the wrapped iterable. */
    128    private final Iterable<E> iterable;
    129
    130    /**
    131     * Don't allow instances.
    132     */
    133    FluentIterable() {
    134        this.iterable = this;
    135    }
    136
    137    /**
    138     * Create a new FluentIterable by wrapping the provided iterable.
    139     * @param iterable  the iterable to wrap
    140     */
    141    private FluentIterable(final Iterable<E> iterable) {
    142        this.iterable = iterable;
    143    }
    144
    145    /**
    146     * Checks if all elements contained in this iterable are matching the
    147     * provided predicate.
    148     * <p>
    149     * A {@code null} or empty iterable returns true.
    150     *
    151     * @param predicate  the predicate to use, may not be null
    152     * @return true if all elements contained in this iterable match the predicate,
    153     *   false otherwise
    154     * @throws NullPointerException if predicate is null
    155     */
    156    public boolean allMatch(final Predicate<? super E> predicate) {
    157        return IterableUtils.matchesAll(iterable, predicate);
    158    }
    159
    160    /**
    161     * Checks if this iterable contains any element matching the provided predicate.
    162     * <p>
    163     * A {@code null} or empty iterable returns false.
    164     *
    165     * @param predicate  the predicate to use, may not be null
    166     * @return true if at least one element contained in this iterable matches the predicate,
    167     *   false otherwise
    168     * @throws NullPointerException if predicate is null
    169     */
    170    public boolean anyMatch(final Predicate<? super E> predicate) {
    171        return IterableUtils.matchesAny(iterable, predicate);
    172    }
    173
    174    /**
    175     * Returns a new FluentIterable whose iterator will first traverse
    176     * the elements of the current iterable, followed by the provided
    177     * elements.
    178     *
    179     * @param elements  the elements to append to the iterable
    180     * @return a new iterable, combining this iterable with the elements
    181     */
    182    public FluentIterable<E> append(final E... elements) {
    183        return append(Arrays.asList(elements));
    184    }
    185
    186    /**
    187     * Returns a new FluentIterable whose iterator will first traverse
    188     * the elements of the current iterable, followed by the elements
    189     * of the provided iterable.
    190     *
    191     * @param other  the other iterable to combine, may not be null
    192     * @return a new iterable, combining this iterable with other
    193     * @throws NullPointerException if other is null
    194     */
    195    public FluentIterable<E> append(final Iterable<? extends E> other) {
    196        return of(IterableUtils.chainedIterable(iterable, other));
    197    }
    198
    199    /**
    200     * Returns an Enumeration that will enumerate all elements contained
    201     * in this iterable.
    202     *
    203     * @return an Enumeration over the elements of this iterable
    204     */
    205    public Enumeration<E> asEnumeration() {
    206        return IteratorUtils.asEnumeration(iterator());
    207    }
    208
    209    /**
    210     * Returns a new FluentIterable whose iterator will traverse the
    211     * elements of the current and provided iterable in natural order.
    212     * <p>
    213     * Example: natural ordering
    214     * <ul>
    215     *   <li>this contains elements [1, 3, 5, 7]
    216     *   <li>other contains elements [2, 4, 6, 8]
    217     * </ul>
    218     * <p>
    219     * The returned iterable will traverse the elements in the following
    220     * order: [1, 2, 3, 4, 5, 6, 7, 8]
    221     *
    222     * @param other  the other iterable to collate, may not be null
    223     * @return a new iterable, collating this iterable with the other in natural order
    224     * @throws NullPointerException if other is null
    225     * @see org.apache.commons.collections4.iterators.CollatingIterator
    226     */
    227    public FluentIterable<E> collate(final Iterable<? extends E> other) {
    228        return of(IterableUtils.collatedIterable(iterable, other));
    229    }
    230
    231    /**
    232     * Returns a new FluentIterable whose iterator will traverse the
    233     * elements of the current and provided iterable according to the
    234     * ordering defined by a comparator.
    235     * <p>
    236     * Example: descending order
    237     * <ul>
    238     *   <li>this contains elements [7, 5, 3, 1]
    239     *   <li>other contains elements [8, 6, 4, 2]
    240     * </ul>
    241     * <p>
    242     * The returned iterable will traverse the elements in the following
    243     * order: [8, 7, 6, 5, 4, 3, 2, 1]
    244     *
    245     * @param comparator  the comparator to define an ordering, may be null,
    246     *   in which case natural ordering will be used
    247     * @param other  the other iterable to collate, may not be null
    248     * @return a new iterable, collating this iterable with the other in natural order
    249     * @throws NullPointerException if other is null
    250     * @see org.apache.commons.collections4.iterators.CollatingIterator
    251     */
    252    public FluentIterable<E> collate(final Iterable<? extends E> other,
    253                                     final Comparator<? super E> comparator) {
    254        return of(IterableUtils.collatedIterable(comparator, iterable, other));
    255    }
    256
    257    /**
    258     * Checks if the object is contained in this iterable.
    259     *
    260     * @param object  the object to check
    261     * @return true if the object is contained in this iterable, false otherwise
    262     */
    263    public boolean contains(final Object object) {
    264        return IterableUtils.contains(iterable, object);
    265    }
    266
    267    /**
    268     * Traverses an iterator of this iterable and adds all elements
    269     * to the provided collection.
    270     *
    271     * @param collection  the collection to add the elements
    272     * @throws NullPointerException if collection is null
    273     */
    274    public void copyInto(final Collection<? super E> collection) {
    275        Objects.requireNonNull(collection, "collection");
    276        CollectionUtils.addAll(collection, iterable);
    277    }
    278
    279    /**
    280     * This method fully traverses an iterator of this iterable and returns
    281     * a new iterable with the same contents, but without any reference
    282     * to the originating iterables and/or iterators.
    283     * <p>
    284     * Calling this method is equivalent to:
    285     * <pre>
    286     *   FluentIterable&lt;E&gt; someIterable = ...;
    287     *   FluentIterable.of(someIterable.toList());
    288     * </pre>
    289     *
    290     * @return a new iterable with the same contents as this iterable
    291     */
    292    public FluentIterable<E> eval() {
    293        return of(toList());
    294    }
    295
    296    /**
    297     * Returns a new FluentIterable whose iterator will only return
    298     * elements from this iterable matching the provided predicate.
    299     *
    300     * @param predicate  the predicate used to filter elements
    301     * @return a new iterable, providing a filtered view of this iterable
    302     * @throws NullPointerException if predicate is null
    303     */
    304    public FluentIterable<E> filter(final Predicate<? super E> predicate) {
    305        return of(IterableUtils.filteredIterable(iterable, predicate));
    306    }
    307
    308    /**
    309     * Applies the closure to all elements contained in this iterable.
    310     *
    311     * @param closure  the closure to apply to each element, may not be null
    312     * @throws NullPointerException if closure is null
    313     */
    314    public void forEach(final Closure<? super E> closure) {
    315        IterableUtils.forEach(iterable, closure);
    316    }
    317
    318    /**
    319     * Returns the element at the provided position in this iterable.
    320     * In order to return the element, an iterator needs to be traversed
    321     * up to the requested position.
    322     *
    323     * @param position  the position of the element to return
    324     * @return the element
    325     * @throws IndexOutOfBoundsException if the provided position is outside the
    326     *   valid range of this iterable: [0, size)
    327     */
    328    public E get(final int position) {
    329        return IterableUtils.get(iterable, position);
    330    }
    331
    332    /**
    333     * Checks if this iterable is empty.
    334     *
    335     * @return true if this iterable does not contain any elements, false otherwise
    336     */
    337    public boolean isEmpty() {
    338        return IterableUtils.isEmpty(iterable);
    339    }
    340
    341    /** {@inheritDoc} */
    342    @Override
    343    public Iterator<E> iterator() {
    344        return iterable.iterator();
    345    }
    346
    347    /**
    348     * Returns a new FluentIterable whose iterator will return at most
    349     * the provided maximum number of elements from this iterable.
    350     *
    351     * @param maxSize  the maximum number of elements
    352     * @return a new iterable, providing a bounded view of this iterable
    353     * @throws IllegalArgumentException if maxSize is negative
    354     */
    355    public FluentIterable<E> limit(final long maxSize) {
    356        return of(IterableUtils.boundedIterable(iterable, maxSize));
    357    }
    358
    359    /**
    360     * Returns a new FluentIterable whose iterator will loop infinitely
    361     * over the elements from this iterable.
    362     *
    363     * @return a new iterable, providing a looping view of this iterable
    364     */
    365    public FluentIterable<E> loop() {
    366        return of(IterableUtils.loopingIterable(iterable));
    367    }
    368
    369    /**
    370     * Returns a new FluentIterable whose iterator will traverse the
    371     * elements from this iterable in reverse order.
    372     *
    373     * @return a new iterable, providing a reversed view of this iterable
    374     */
    375    public FluentIterable<E> reverse() {
    376        return of(IterableUtils.reversedIterable(iterable));
    377    }
    378
    379    /**
    380     * Returns the number of elements that are contained in this iterable.
    381     * In order to determine the size, an iterator needs to be traversed.
    382     *
    383     * @return the size of this iterable
    384     */
    385    public int size() {
    386        return IterableUtils.size(iterable);
    387    }
    388
    389    /**
    390     * Returns a new FluentIterable whose iterator will skip the first
    391     * N elements from this iterable.
    392     *
    393     * @param elementsToSkip  the number of elements to skip
    394     * @return a new iterable, providing a view of this iterable by skipping
    395     *   the first N elements
    396     * @throws IllegalArgumentException if elementsToSkip is negative
    397     */
    398    public FluentIterable<E> skip(final long elementsToSkip) {
    399        return of(IterableUtils.skippingIterable(iterable, elementsToSkip));
    400    }
    401
    402    /**
    403     * Returns an array containing all elements of this iterable by traversing
    404     * its iterator.
    405     *
    406     * @param arrayClass  the class of array to create
    407     * @return an array of the iterable contents
    408     * @throws ArrayStoreException if arrayClass is invalid
    409     */
    410    public E[] toArray(final Class<E> arrayClass) {
    411        return IteratorUtils.toArray(iterator(), arrayClass);
    412    }
    413
    414    /**
    415     * Returns a mutable list containing all elements of this iterable
    416     * by traversing its iterator.
    417     * <p>
    418     * The returned list is guaranteed to be mutable.
    419     *
    420     * @return a list of the iterable contents
    421     */
    422    public List<E> toList() {
    423        return IterableUtils.toList(iterable);
    424    }
    425
    426    /** {@inheritDoc} */
    427    @Override
    428    public String toString() {
    429        return IterableUtils.toString(iterable);
    430    }
    431
    432    /**
    433     * Returns a new FluentIterable whose iterator will return all elements
    434     * of this iterable transformed by the provided transformer.
    435     *
    436     * @param <O>  the output element type
    437     * @param transformer  the transformer applied to each element
    438     * @return a new iterable, providing a transformed view of this iterable
    439     * @throws NullPointerException if transformer is null
    440     */
    441    public <O> FluentIterable<O> transform(final Transformer<? super E, ? extends O> transformer) {
    442        return of(IterableUtils.transformedIterable(iterable, transformer));
    443    }
    444
    445    /**
    446     * Returns a new FluentIterable whose iterator will return a unique view
    447     * of this iterable.
    448     *
    449     * @return a new iterable, providing a unique view of this iterable
    450     */
    451    public FluentIterable<E> unique() {
    452        return of(IterableUtils.uniqueIterable(iterable));
    453    }
    454
    455    /**
    456     * Returns a new FluentIterable whose iterator will return an unmodifiable
    457     * view of this iterable.
    458     *
    459     * @return a new iterable, providing an unmodifiable view of this iterable
    460     */
    461    public FluentIterable<E> unmodifiable() {
    462        return of(IterableUtils.unmodifiableIterable(iterable));
    463    }
    464
    465    /**
    466     * Returns a new FluentIterable whose iterator will traverse
    467     * the elements of this iterable and the other iterable in
    468     * alternating order.
    469     *
    470     * @param other  the other iterable to interleave, may not be null
    471     * @return a new iterable, interleaving this iterable with others
    472     * @throws NullPointerException if other is null
    473     */
    474    public FluentIterable<E> zip(final Iterable<? extends E> other) {
    475        return of(IterableUtils.zippingIterable(iterable, other));
    476    }
    477
    478    /**
    479     * Returns a new FluentIterable whose iterator will traverse
    480     * the elements of this iterable and the other iterables in
    481     * alternating order.
    482     *
    483     * @param others  the iterables to interleave, may not be null
    484     * @return a new iterable, interleaving this iterable with others
    485     * @throws NullPointerException if either of the provided iterables is null
    486     */
    487    public FluentIterable<E> zip(final Iterable<? extends E>... others) {
    488        return of(IterableUtils.zippingIterable(iterable, others));
    489    }
    490
    491}