/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.collections4;

import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.Iterator;
import java.util.List;
import java.util.Set;

import org.apache.commons.collections4.functors.EqualPredicate;
import org.apache.commons.collections4.iterators.LazyIteratorChain;
import org.apache.commons.collections4.iterators.ReverseListIterator;
import org.apache.commons.collections4.iterators.UniqueFilterIterator;

Provides utility methods and decorators for Iterable instances. 

Note: this util class has been designed for fail-fast argument checking.



all decorator methods are NOT null-safe wrt the provided Iterable argument, i.e. they will throw a NullPointerException if a null Iterable is passed as argument. 
 all other utility methods are null-safe wrt the provided Iterable argument, i.e. they will treat a null Iterable the same way as an empty one. Other arguments which are null, e.g. a Predicate, will result in a NullPointerException. Exception: passing a null Comparator is equivalent to a Comparator with natural ordering. 
Since:
4.1/**
 * Provides utility methods and decorators for {@link Iterable} instances.
 * <p>
 * <b>Note</b>: this util class has been designed for fail-fast argument checking.
 * </p>
 * <ul>
 * <li>
 * all decorator methods are <b>NOT</b> null-safe wrt the provided Iterable argument, i.e.
 * they will throw a {@link NullPointerException} if a null Iterable is passed as argument.
 * <li>
 * all other utility methods are null-safe wrt the provided Iterable argument, i.e. they will
 * treat a null Iterable the same way as an empty one. Other arguments which are null,
 * e.g. a {@link Predicate}, will result in a {@link NullPointerException}. Exception: passing
 * a null {@link Comparator} is equivalent to a Comparator with natural ordering.
 * </ul>
 *
 * @since 4.1
 */
public class IterableUtils {

    
An empty iterable.
/**
     * An empty iterable.
     */
    @SuppressWarnings("rawtypes")
    static final FluentIterable EMPTY_ITERABLE = new FluentIterable<Object>() {
        @Override
        public Iterator<Object> iterator() {
            return IteratorUtils.emptyIterator();
        }
    };

    // Empty
    // ----------------------------------------------------------------------

    
Gets an empty iterable.

This iterable does not contain any elements.
Type parameters:
<E> – the element type
Returns:
an empty iterable/**
     * Gets an empty iterable.
     * <p>
     * This iterable does not contain any elements.
     *
     * @param <E> the element type
     * @return an empty iterable
     */
    @SuppressWarnings("unchecked") // OK, empty collection is compatible with any type
    public static <E> Iterable<E> emptyIterable() {
        return EMPTY_ITERABLE;
    }

    // Chained
    // ----------------------------------------------------------------------

    
Combines two iterables into a single iterable.
 The returned iterable has an iterator that traverses the elements in a, followed by the elements in b. The source iterators are not polled until necessary. 
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
a –  the first iterable, may not be null
b –  the second iterable, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if either a or b is null
Returns:
a new iterable, combining the provided iterables/**
     * Combines two iterables into a single iterable.
     * <p>
     * The returned iterable has an iterator that traverses the elements in {@code a},
     * followed by the elements in {@code b}. The source iterators are not polled until
     * necessary.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the corresponding
     * input iterator supports it.
     *
     * @param <E> the element type
     * @param a  the first iterable, may not be null
     * @param b  the second iterable, may not be null
     * @return a new iterable, combining the provided iterables
     * @throws NullPointerException if either a or b is null
     */
    @SuppressWarnings("unchecked")
    public static <E> Iterable<E> chainedIterable(final Iterable<? extends E> a,
                                                  final Iterable<? extends E> b) {
        return chainedIterable(new Iterable[] {a, b});
    }

    
Combines three iterables into a single iterable.
 The returned iterable has an iterator that traverses the elements in a, followed by the elements in b and c. The source iterators are not polled until necessary. 
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
a –  the first iterable, may not be null
b –  the second iterable, may not be null
c –  the third iterable, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if either of the provided iterables is null
Returns:
a new iterable, combining the provided iterables/**
     * Combines three iterables into a single iterable.
     * <p>
     * The returned iterable has an iterator that traverses the elements in {@code a},
     * followed by the elements in {@code b} and {@code c}. The source iterators are
     * not polled until necessary.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the corresponding
     * input iterator supports it.
     *
     * @param <E> the element type
     * @param a  the first iterable, may not be null
     * @param b  the second iterable, may not be null
     * @param c  the third iterable, may not be null
     * @return a new iterable, combining the provided iterables
     * @throws NullPointerException if either of the provided iterables is null
     */
    @SuppressWarnings("unchecked")
    public static <E> Iterable<E> chainedIterable(final Iterable<? extends E> a,
                                                  final Iterable<? extends E> b,
                                                  final Iterable<? extends E> c) {
        return chainedIterable(new Iterable[] {a, b, c});
    }

    
Combines four iterables into a single iterable.
 The returned iterable has an iterator that traverses the elements in a, followed by the elements in b, c and d. The source iterators are not polled until necessary. 
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
a –  the first iterable, may not be null
b –  the second iterable, may not be null
c –  the third iterable, may not be null
d –  the fourth iterable, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if either of the provided iterables is null
Returns:
a new iterable, combining the provided iterables/**
     * Combines four iterables into a single iterable.
     * <p>
     * The returned iterable has an iterator that traverses the elements in {@code a},
     * followed by the elements in {@code b}, {@code c} and {@code d}. The source
     * iterators are not polled until necessary.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the corresponding
     * input iterator supports it.
     *
     * @param <E> the element type
     * @param a  the first iterable, may not be null
     * @param b  the second iterable, may not be null
     * @param c  the third iterable, may not be null
     * @param d  the fourth iterable, may not be null
     * @return a new iterable, combining the provided iterables
     * @throws NullPointerException if either of the provided iterables is null
     */
    @SuppressWarnings("unchecked")
    public static <E> Iterable<E> chainedIterable(final Iterable<? extends E> a,
                                                  final Iterable<? extends E> b,
                                                  final Iterable<? extends E> c,
                                                  final Iterable<? extends E> d) {
        return chainedIterable(new Iterable[] {a, b, c, d});
    }

    
Combines the provided iterables into a single iterable.

The returned iterable has an iterator that traverses the elements in the order
of the arguments, i.e. iterables[0], iterables[1], .... The source iterators
are not polled until necessary.
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
iterables –  the iterables to combine, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if either of the provided iterables is null
Returns:
a new iterable, combining the provided iterables/**
     * Combines the provided iterables into a single iterable.
     * <p>
     * The returned iterable has an iterator that traverses the elements in the order
     * of the arguments, i.e. iterables[0], iterables[1], .... The source iterators
     * are not polled until necessary.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the corresponding
     * input iterator supports it.
     *
     * @param <E> the element type
     * @param iterables  the iterables to combine, may not be null
     * @return a new iterable, combining the provided iterables
     * @throws NullPointerException if either of the provided iterables is null
     */
    public static <E> Iterable<E> chainedIterable(final Iterable<? extends E>... iterables) {
        checkNotNull(iterables);
        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                return new LazyIteratorChain<E>() {
                    @Override
                    protected Iterator<? extends E> nextIterator(final int count) {
                        if (count > iterables.length) {
                            return null;
                        }
                        return iterables[count - 1].iterator();
                    }
                };
            }
        };
    }

    // Collated
    // ----------------------------------------------------------------------

    
Combines the two provided iterables into an ordered iterable using
natural ordering.
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
a –  the first iterable, may not be null
b –  the second iterable, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if either of the provided iterables is null
Returns:
a filtered view on the specified iterable/**
     * Combines the two provided iterables into an ordered iterable using
     * natural ordering.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the
     * corresponding input iterator supports it.
     *
     * @param <E> the element type
     * @param a  the first iterable, may not be null
     * @param b  the second iterable, may not be null
     * @return a filtered view on the specified iterable
     * @throws NullPointerException if either of the provided iterables is null
     */
    public static <E> Iterable<E> collatedIterable(final Iterable<? extends E> a,
                                                   final Iterable<? extends E> b) {
        checkNotNull(a, b);
        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                return IteratorUtils.collatedIterator(null, a.iterator(), b.iterator());
            }
        };
    }

    
Combines the two provided iterables into an ordered iterable using the
provided comparator. If the comparator is null, natural ordering will be
used.
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
comparator –  the comparator defining an ordering over the elements,
  may be null, in which case natural ordering will be used
a –  the first iterable, may not be null
b –  the second iterable, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if either of the provided iterables is null
Returns:
a filtered view on the specified iterable/**
     * Combines the two provided iterables into an ordered iterable using the
     * provided comparator. If the comparator is null, natural ordering will be
     * used.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the
     * corresponding input iterator supports it.
     *
     * @param <E> the element type
     * @param comparator  the comparator defining an ordering over the elements,
     *   may be null, in which case natural ordering will be used
     * @param a  the first iterable, may not be null
     * @param b  the second iterable, may not be null
     * @return a filtered view on the specified iterable
     * @throws NullPointerException if either of the provided iterables is null
     */
    public static <E> Iterable<E> collatedIterable(final Comparator<? super E> comparator,
                                                   final Iterable<? extends E> a,
                                                   final Iterable<? extends E> b) {
        checkNotNull(a, b);
        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                return IteratorUtils.collatedIterator(comparator, a.iterator(), b.iterator());
            }
        };
    }

    // Filtered
    // ----------------------------------------------------------------------

    
Returns a view of the given iterable that only contains elements matching
the provided predicate.
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
iterable –  the iterable to filter, may not be null
predicate –  the predicate used to filter elements, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if either iterable or predicate is null
Returns:
a filtered view on the specified iterable/**
     * Returns a view of the given iterable that only contains elements matching
     * the provided predicate.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the
     * corresponding input iterator supports it.
     *
     * @param <E> the element type
     * @param iterable  the iterable to filter, may not be null
     * @param predicate  the predicate used to filter elements, may not be null
     * @return a filtered view on the specified iterable
     * @throws NullPointerException if either iterable or predicate is null
     */
    public static <E> Iterable<E> filteredIterable(final Iterable<E> iterable,
                                                   final Predicate<? super E> predicate) {
        checkNotNull(iterable);
        if (predicate == null) {
            throw new NullPointerException("Predicate must not be null.");
        }
        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                return IteratorUtils.filteredIterator(emptyIteratorIfNull(iterable), predicate);
            }
        };
    }

    // Bounded
    // ----------------------------------------------------------------------

    
Returns a view of the given iterable that contains at most the given number
of elements.
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
iterable –  the iterable to limit, may not be null
maxSize –  the maximum number of elements, must not be negative
Type parameters:
<E> – the element type
Throws:
IllegalArgumentException – if maxSize is negative
NullPointerException – if iterable is null
Returns:
a bounded view on the specified iterable/**
     * Returns a view of the given iterable that contains at most the given number
     * of elements.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the corresponding
     * input iterator supports it.
     *
     * @param <E> the element type
     * @param iterable  the iterable to limit, may not be null
     * @param maxSize  the maximum number of elements, must not be negative
     * @return a bounded view on the specified iterable
     * @throws IllegalArgumentException if maxSize is negative
     * @throws NullPointerException if iterable is null
     */
    public static <E> Iterable<E> boundedIterable(final Iterable<E> iterable, final long maxSize) {
        checkNotNull(iterable);
        if (maxSize < 0) {
            throw new IllegalArgumentException("MaxSize parameter must not be negative.");
        }

        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                return IteratorUtils.boundedIterator(iterable.iterator(), maxSize);
            }
        };
    }

    // Looping
    // ----------------------------------------------------------------------

    
Returns a view of the given iterable which will cycle infinitely over
its elements.
 The returned iterable's iterator supports remove() if iterable.iterator() does. After remove() is called, subsequent cycles omit the removed element, which is no longer in iterable. The iterator's hasNext() method returns true until iterable is empty. 
Params:
iterable –  the iterable to loop, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if iterable is null
Returns:
a view of the iterable, providing an infinite loop over its elements/**
     * Returns a view of the given iterable which will cycle infinitely over
     * its elements.
     * <p>
     * The returned iterable's iterator supports {@code remove()} if
     * {@code iterable.iterator()} does. After {@code remove()} is called, subsequent
     * cycles omit the removed element, which is no longer in {@code iterable}. The
     * iterator's {@code hasNext()} method returns {@code true} until {@code iterable}
     * is empty.
     *
     * @param <E> the element type
     * @param iterable  the iterable to loop, may not be null
     * @return a view of the iterable, providing an infinite loop over its elements
     * @throws NullPointerException if iterable is null
     */
    public static <E> Iterable<E> loopingIterable(final Iterable<E> iterable) {
        checkNotNull(iterable);
        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                return new LazyIteratorChain<E>() {
                    @Override
                    protected Iterator<? extends E> nextIterator(final int count) {
                        if (IterableUtils.isEmpty(iterable)) {
                            return null;
                        }
                        return iterable.iterator();
                    }
                };
            }
        };
    }

    // Reversed
    // ----------------------------------------------------------------------

    
Returns a reversed view of the given iterable.
 In case the provided iterable is a List instance, a ReverseListIterator will be used to reverse the traversal order, otherwise an intermediate List needs to be created. 
 The returned iterable's iterator supports remove() if the provided iterable is a List instance. 
Params:
iterable –  the iterable to use, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if iterable is null
See Also:
ReverseListIterator
Returns:
a reversed view of the specified iterable/**
     * Returns a reversed view of the given iterable.
     * <p>
     * In case the provided iterable is a {@link List} instance, a
     * {@link ReverseListIterator} will be used to reverse the traversal
     * order, otherwise an intermediate {@link List} needs to be created.
     * <p>
     * The returned iterable's iterator supports {@code remove()} if the
     * provided iterable is a {@link List} instance.
     *
     * @param <E> the element type
     * @param iterable  the iterable to use, may not be null
     * @return a reversed view of the specified iterable
     * @throws NullPointerException if iterable is null
     * @see ReverseListIterator
     */
    public static <E> Iterable<E> reversedIterable(final Iterable<E> iterable) {
        checkNotNull(iterable);
        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                final List<E> list = (iterable instanceof List<?>) ?
                        (List<E>) iterable :
                        IteratorUtils.toList(iterable.iterator());
                return new ReverseListIterator<>(list);
            }
        };
    }

    // Skipping
    // ----------------------------------------------------------------------

    
Returns a view of the given iterable that skips the first N elements.
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
iterable –  the iterable to use, may not be null
elementsToSkip –  the number of elements to skip from the start, must not be negative
Type parameters:
<E> – the element type
Throws:
IllegalArgumentException – if elementsToSkip is negative
NullPointerException – if iterable is null
Returns:
a view of the specified iterable, skipping the first N elements/**
     * Returns a view of the given iterable that skips the first N elements.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the corresponding
     * input iterator supports it.
     *
     * @param <E> the element type
     * @param iterable  the iterable to use, may not be null
     * @param elementsToSkip  the number of elements to skip from the start, must not be negative
     * @return a view of the specified iterable, skipping the first N elements
     * @throws IllegalArgumentException if elementsToSkip is negative
     * @throws NullPointerException if iterable is null
     */
    public static <E> Iterable<E> skippingIterable(final Iterable<E> iterable, final long elementsToSkip) {
        checkNotNull(iterable);
        if (elementsToSkip < 0) {
            throw new IllegalArgumentException("ElementsToSkip parameter must not be negative.");
        }

        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                return IteratorUtils.skippingIterator(iterable.iterator(), elementsToSkip);
            }
        };
    }

    // Transformed
    // ----------------------------------------------------------------------

    
Returns a transformed view of the given iterable where all of its elements
have been transformed by the provided transformer.
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
iterable –  the iterable to transform, may not be null
transformer –  the transformer, must not be null
Type parameters:
<I> –  the input element type
<O> –  the output element type
Throws:
NullPointerException – if either iterable or transformer is null
Returns:
a transformed view of the specified iterable/**
     * Returns a transformed view of the given iterable where all of its elements
     * have been transformed by the provided transformer.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the corresponding
     * input iterator supports it.
     *
     * @param <I>  the input element type
     * @param <O>  the output element type
     * @param iterable  the iterable to transform, may not be null
     * @param transformer  the transformer, must not be null
     * @return a transformed view of the specified iterable
     * @throws NullPointerException if either iterable or transformer is null
     */
    public static <I, O> Iterable<O> transformedIterable(final Iterable<I> iterable,
                                                         final Transformer<? super I, ? extends O> transformer) {
        checkNotNull(iterable);
        if (transformer == null) {
            throw new NullPointerException("Transformer must not be null.");
        }
        return new FluentIterable<O>() {
            @Override
            public Iterator<O> iterator() {
                return IteratorUtils.transformedIterator(iterable.iterator(), transformer);
            }
        };
    }

    // Unique
    // ----------------------------------------------------------------------

    
Returns a unique view of the given iterable.
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. Calling remove() will only remove a single element from the underlying iterator. 
Params:
iterable –  the iterable to use, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if iterable is null
Returns:
a unique view of the specified iterable/**
     * Returns a unique view of the given iterable.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the
     * corresponding input iterator supports it. Calling {@code remove()}
     * will only remove a single element from the underlying iterator.
     *
     * @param <E> the element type
     * @param iterable  the iterable to use, may not be null
     * @return a unique view of the specified iterable
     * @throws NullPointerException if iterable is null
     */
    public static <E> Iterable<E> uniqueIterable(final Iterable<E> iterable) {
        checkNotNull(iterable);
        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                return new UniqueFilterIterator<>(iterable.iterator());
            }
        };
    }

    // Unmodifiable
    // ----------------------------------------------------------------------

    
Returns an unmodifiable view of the given iterable.
 The returned iterable's iterator does not support remove(). 
Params:
iterable –  the iterable to use, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if iterable is null
Returns:
an unmodifiable view of the specified iterable/**
     * Returns an unmodifiable view of the given iterable.
     * <p>
     * The returned iterable's iterator does not support {@code remove()}.
     *
     * @param <E> the element type
     * @param iterable  the iterable to use, may not be null
     * @return an unmodifiable view of the specified iterable
     * @throws NullPointerException if iterable is null
     */
    public static <E> Iterable<E> unmodifiableIterable(final Iterable<E> iterable) {
        checkNotNull(iterable);
        if (iterable instanceof UnmodifiableIterable<?>) {
            return iterable;
        }
        return new UnmodifiableIterable<>(iterable);
    }

    
Inner class to distinguish unmodifiable instances.
/**
     * Inner class to distinguish unmodifiable instances.
     */
    private static final class UnmodifiableIterable<E> extends FluentIterable<E> {
        private final Iterable<E> unmodifiable;

        public UnmodifiableIterable(final Iterable<E> iterable) {
            super();
            this.unmodifiable = iterable;
        }

        @Override
        public Iterator<E> iterator() {
            return IteratorUtils.unmodifiableIterator(unmodifiable.iterator());
        }
    }

    // Zipping
    // ----------------------------------------------------------------------

    
Interleaves two iterables into a single iterable.
 The returned iterable has an iterator that traverses the elements in a and b in alternating order. The source iterators are not polled until necessary. 
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
a –  the first iterable, may not be null
b –  the second iterable, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if either a or b is null
Returns:
a new iterable, interleaving the provided iterables/**
     * Interleaves two iterables into a single iterable.
     * <p>
     * The returned iterable has an iterator that traverses the elements in {@code a}
     * and {@code b} in alternating order. The source iterators are not polled until
     * necessary.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the corresponding
     * input iterator supports it.
     *
     * @param <E> the element type
     * @param a  the first iterable, may not be null
     * @param b  the second iterable, may not be null
     * @return a new iterable, interleaving the provided iterables
     * @throws NullPointerException if either a or b is null
     */
    public static <E> Iterable<E> zippingIterable(final Iterable<? extends E> a,
                                                  final Iterable<? extends E> b) {
        checkNotNull(a);
        checkNotNull(b);
        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                return IteratorUtils.zippingIterator(a.iterator(), b.iterator());
            }
        };
    }

    
Interleaves two iterables into a single iterable.
 The returned iterable has an iterator that traverses the elements in a and b in alternating order. The source iterators are not polled until necessary. 
 The returned iterable's iterator supports remove() when the corresponding input iterator supports it. 
Params:
first –  the first iterable, may not be null
others –  the array of iterables to interleave, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if either of the provided iterables is null
Returns:
a new iterable, interleaving the provided iterables/**
     * Interleaves two iterables into a single iterable.
     * <p>
     * The returned iterable has an iterator that traverses the elements in {@code a}
     * and {@code b} in alternating order. The source iterators are not polled until
     * necessary.
     * <p>
     * The returned iterable's iterator supports {@code remove()} when the corresponding
     * input iterator supports it.
     *
     * @param <E> the element type
     * @param first  the first iterable, may not be null
     * @param others  the array of iterables to interleave, may not be null
     * @return a new iterable, interleaving the provided iterables
     * @throws NullPointerException if either of the provided iterables is null
     */
    public static <E> Iterable<E> zippingIterable(final Iterable<? extends E> first,
                                                  final Iterable<? extends E>... others) {
        checkNotNull(first);
        checkNotNull(others);
        return new FluentIterable<E>() {
            @Override
            public Iterator<E> iterator() {
                @SuppressWarnings("unchecked") // safe
                final
                Iterator<? extends E>[] iterators = new Iterator[others.length + 1];
                iterators[0] = first.iterator();
                for (int i = 0; i < others.length; i++) {
                    iterators[i + 1] = others[i].iterator();
                }
                return IteratorUtils.zippingIterator(iterators);
            }
        };
    }

    // Utility methods
    // ----------------------------------------------------------------------

    
Returns an immutable empty iterable if the argument is null,
or the argument itself otherwise.
Params:
iterable –  the iterable, may be null
Type parameters:
<E> – the element type
Returns:
an empty iterable if the argument is null/**
     * Returns an immutable empty iterable if the argument is null,
     * or the argument itself otherwise.
     *
     * @param <E> the element type
     * @param iterable  the iterable, may be null
     * @return an empty iterable if the argument is null
     */
    public static <E> Iterable<E> emptyIfNull(final Iterable<E> iterable) {
        return iterable == null ? IterableUtils.<E>emptyIterable() : iterable;
    }

    
Applies the closure to each element of the provided iterable.
Params:
iterable –  the iterator to use, may be null
closure –  the closure to apply to each element, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if closure is null/**
     * Applies the closure to each element of the provided iterable.
     *
     * @param <E> the element type
     * @param iterable  the iterator to use, may be null
     * @param closure  the closure to apply to each element, may not be null
     * @throws NullPointerException if closure is null
     */
    public static <E> void forEach(final Iterable<E> iterable, final Closure<? super E> closure) {
        IteratorUtils.forEach(emptyIteratorIfNull(iterable), closure);
    }

    
Executes the given closure on each but the last element in the iterable.

If the input iterable is null no change is made.
Params:
iterable –  the iterable to get the input from, may be null
closure –  the closure to perform, may not be null
Type parameters:
<E> – the type of object the Iterable contains
Returns:
the last element in the iterable, or null if iterable is null or empty/**
     * Executes the given closure on each but the last element in the iterable.
     * <p>
     * If the input iterable is null no change is made.
     *
     * @param <E> the type of object the {@link Iterable} contains
     * @param iterable  the iterable to get the input from, may be null
     * @param closure  the closure to perform, may not be null
     * @return the last element in the iterable, or null if iterable is null or empty
     */
    public static <E> E forEachButLast(final Iterable<E> iterable, final Closure<? super E> closure) {
        return IteratorUtils.forEachButLast(emptyIteratorIfNull(iterable), closure);
    }

    
Finds the first element in the given iterable which matches the given predicate.

A null or empty iterator returns null.
Params:
iterable –  the iterable to search, may be null
predicate –  the predicate to use, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if predicate is null
Returns:
the first element of the iterable which matches the predicate or null if none could be found/**
     * Finds the first element in the given iterable which matches the given predicate.
     * <p>
     * A <code>null</code> or empty iterator returns null.
     *
     * @param <E> the element type
     * @param iterable  the iterable to search, may be null
     * @param predicate  the predicate to use, may not be null
     * @return the first element of the iterable which matches the predicate or null if none could be found
     * @throws NullPointerException if predicate is null
     */
    public static <E> E find(final Iterable<E> iterable, final Predicate<? super E> predicate) {
        return IteratorUtils.find(emptyIteratorIfNull(iterable), predicate);
    }

    
Returns the index of the first element in the specified iterable that
matches the given predicate.

A null or empty iterable returns -1.
Params:
iterable –  the iterable to search, may be null
predicate –  the predicate to use, may not be null
Type parameters:
<E> – the element type
Throws:
NullPointerException – if predicate is null
Returns:
the index of the first element which matches the predicate or -1 if none matches/**
     * Returns the index of the first element in the specified iterable that
     * matches the given predicate.
     * <p>
     * A <code>null</code> or empty iterable returns -1.
     *
     * @param <E> the element type
     * @param iterable  the iterable to search, may be null
     * @param predicate  the predicate to use, may not be null
     * @return the index of the first element which matches the predicate or -1 if none matches
     * @throws NullPointerException if predicate is null
     */
    public static <E> int indexOf(final Iterable<E> iterable, final Predicate<? super E> predicate) {
        return IteratorUtils.indexOf(emptyIteratorIfNull(iterable), predicate);
    }

    
Answers true if a predicate is true for every element of an iterable.

A null or empty iterable returns true.
Params:
iterable –  the Iterable to use, may be null
predicate –  the predicate to use, may not be null
Type parameters:
<E> – the type of object the Iterable contains
Throws:
NullPointerException – if predicate is null
Returns:
true if every element of the collection matches the predicate or if the
  collection is empty, false otherwise/**
     * Answers true if a predicate is true for every element of an iterable.
     * <p>
     * A <code>null</code> or empty iterable returns true.
     *
     * @param <E> the type of object the {@link Iterable} contains
     * @param iterable  the {@link Iterable} to use, may be null
     * @param predicate  the predicate to use, may not be null
     * @return true if every element of the collection matches the predicate or if the
     *   collection is empty, false otherwise
     * @throws NullPointerException if predicate is null
     */
    public static <E> boolean matchesAll(final Iterable<E> iterable, final Predicate<? super E> predicate) {
        return IteratorUtils.matchesAll(emptyIteratorIfNull(iterable), predicate);
    }

    
Answers true if a predicate is true for any element of the iterable.

A null or empty iterable returns false.
Params:
iterable –  the Iterable to use, may be null
predicate –  the predicate to use, may not be null
Type parameters:
<E> – the type of object the Iterable contains
Throws:
NullPointerException – if predicate is null
Returns:
true if any element of the collection matches the predicate, false otherwise/**
     * Answers true if a predicate is true for any element of the iterable.
     * <p>
     * A <code>null</code> or empty iterable returns false.
     *
     * @param <E> the type of object the {@link Iterable} contains
     * @param iterable  the {@link Iterable} to use, may be null
     * @param predicate  the predicate to use, may not be null
     * @return true if any element of the collection matches the predicate, false otherwise
     * @throws NullPointerException if predicate is null
     */
    public static <E> boolean matchesAny(final Iterable<E> iterable, final Predicate<? super E> predicate) {
        return IteratorUtils.matchesAny(emptyIteratorIfNull(iterable), predicate);
    }

    
Counts the number of elements in the input iterable that match the predicate.

A null iterable matches no elements.
Params:
input –  the Iterable to get the input from, may be null
predicate –  the predicate to use, may not be null
Type parameters:
<E> – the type of object the Iterable contains
Throws:
NullPointerException – if predicate is null
Returns:
the number of matches for the predicate in the collection/**
     * Counts the number of elements in the input iterable that match the predicate.
     * <p>
     * A <code>null</code> iterable matches no elements.
     *
     * @param <E> the type of object the {@link Iterable} contains
     * @param input  the {@link Iterable} to get the input from, may be null
     * @param predicate  the predicate to use, may not be null
     * @return the number of matches for the predicate in the collection
     * @throws NullPointerException if predicate is null
     */
    public static <E> long countMatches(final Iterable<E> input, final Predicate<? super E> predicate) {
        if (predicate == null) {
            throw new NullPointerException("Predicate must not be null.");
        }
        return size(filteredIterable(emptyIfNull(input), predicate));
    }

    
Answers true if the provided iterable is empty.

A null iterable returns true.
Params:
iterable –  the to use, may be null
Returns:
true if the iterable is null or empty, false otherwise/**
     * Answers true if the provided iterable is empty.
     * <p>
     * A <code>null</code> iterable returns true.
     *
     * @param iterable  the {@link Iterable to use}, may be null
     * @return true if the iterable is null or empty, false otherwise
     */
    public static boolean isEmpty(final Iterable<?> iterable) {
        if (iterable instanceof Collection<?>) {
            return ((Collection<?>) iterable).isEmpty();
        }
        return IteratorUtils.isEmpty(emptyIteratorIfNull(iterable));
    }

    
Checks if the object is contained in the given iterable.

A null or empty iterable returns false.
Params:
iterable –  the iterable to check, may be null
object –  the object to check
Type parameters:
<E> – the type of object the Iterable contains
Returns:
true if the object is contained in the iterable, false otherwise/**
     * Checks if the object is contained in the given iterable.
     * <p>
     * A <code>null</code> or empty iterable returns false.
     *
     * @param <E> the type of object the {@link Iterable} contains
     * @param iterable  the iterable to check, may be null
     * @param object  the object to check
     * @return true if the object is contained in the iterable, false otherwise
     */
    public static <E> boolean contains(final Iterable<E> iterable, final Object object) {
        if (iterable instanceof Collection<?>) {
            return ((Collection<E>) iterable).contains(object);
        }
        return IteratorUtils.contains(emptyIteratorIfNull(iterable), object);
    }

    
Checks if the object is contained in the given iterable. Object equality is tested with an equator unlike contains(Iterable<Object>, Object) which uses Object.equals(Object). 

A null or empty iterable returns false.
A null object will not be passed to the equator, instead a NullPredicate will be used. 
Params:
iterable –  the iterable to check, may be null
object –  the object to check
equator –  the equator to use to check, may not be null
Type parameters:
<E> – the type of object the Iterable contains
Throws:
NullPointerException – if equator is null
Returns:
true if the object is contained in the iterable, false otherwise/**
     * Checks if the object is contained in the given iterable. Object equality
     * is tested with an {@code equator} unlike {@link #contains(Iterable, Object)}
     * which uses {@link Object#equals(Object)}.
     * <p>
     * A <code>null</code> or empty iterable returns false.
     * A <code>null</code> object will not be passed to the equator, instead a
     * {@link org.apache.commons.collections4.functors.NullPredicate NullPredicate}
     * will be used.
     *
     * @param <E> the type of object the {@link Iterable} contains
     * @param iterable  the iterable to check, may be null
     * @param object  the object to check
     * @param equator  the equator to use to check, may not be null
     * @return true if the object is contained in the iterable, false otherwise
     * @throws NullPointerException if equator is null
     */
    public static <E> boolean contains(final Iterable<? extends E> iterable, final E object,
                                       final Equator<? super E> equator) {
        if (equator == null) {
            throw new NullPointerException("Equator must not be null.");
        }
        return matchesAny(iterable, EqualPredicate.equalPredicate(object, equator));
    }

    
Returns the number of occurrences of the provided object in the iterable.
Params:
iterable –  the Iterable to search
obj –  the object to find the cardinality of
Type parameters:
<E> – the element type that the Iterable may contain
<T> – the element type of the object to find
Returns:
the number of occurrences of obj in iterable/**
     * Returns the number of occurrences of the provided object in the iterable.
     *
     * @param <E> the element type that the {@link Iterable} may contain
     * @param <T> the element type of the object to find
     * @param iterable  the {@link Iterable} to search
     * @param obj  the object to find the cardinality of
     * @return the number of occurrences of obj in iterable
     */
    public static <E, T extends E> int frequency(final Iterable<E> iterable, final T obj) {
        if (iterable instanceof Set<?>) {
            return ((Set<E>) iterable).contains(obj) ? 1 : 0;
        }
        if (iterable instanceof Bag<?>) {
            return ((Bag<E>) iterable).getCount(obj);
        }
        return size(filteredIterable(emptyIfNull(iterable), EqualPredicate.<E>equalPredicate(obj)));
    }

    
Returns the index-th value in the iterable's Iterator, throwing IndexOutOfBoundsException if there is no such element.
 If the Iterable is a List, then it will use List.get(int). 
Params:
iterable –  the Iterable to get a value from, may be null
index –  the index to get
Type parameters:
<T> – the type of object in the Iterable.
Throws:
IndexOutOfBoundsException – if the index is invalid
Returns:
the object at the specified index/**
     * Returns the <code>index</code>-th value in the <code>iterable</code>'s {@link Iterator}, throwing
     * <code>IndexOutOfBoundsException</code> if there is no such element.
     * <p>
     * If the {@link Iterable} is a {@link List}, then it will use {@link List#get(int)}.
     *
     * @param <T> the type of object in the {@link Iterable}.
     * @param iterable  the {@link Iterable} to get a value from, may be null
     * @param index  the index to get
     * @return the object at the specified index
     * @throws IndexOutOfBoundsException if the index is invalid
     */
    public static <T> T get(final Iterable<T> iterable, final int index) {
        CollectionUtils.checkIndexBounds(index);
        if (iterable instanceof List<?>) {
            return ((List<T>) iterable).get(index);
        }
        return IteratorUtils.get(emptyIteratorIfNull(iterable), index);
    }

    
Shortcut for get(iterator, 0). 

Returns the first value in the iterable's Iterator, throwing IndexOutOfBoundsException if there is no such element.

 If the Iterable is a List, then it will use List.get(int). 
Params:
iterable –  the Iterable to get a value from, may be null
Type parameters:
<T> – the type of object in the Iterable.
Throws:
IndexOutOfBoundsException – if the request  is invalid
Returns:
the first object
Since:
4.2/**
     * Shortcut for {@code get(iterator, 0)}.
     * <p>
     * Returns the <code>first</code> value in the <code>iterable</code>'s {@link Iterator}, throwing
     * <code>IndexOutOfBoundsException</code> if there is no such element.
     * </p>
     * <p>
     * If the {@link Iterable} is a {@link List}, then it will use {@link List#get(int)}.
     * </p>
     *
     * @param <T> the type of object in the {@link Iterable}.
     * @param iterable  the {@link Iterable} to get a value from, may be null
     * @return the first object
     * @throws IndexOutOfBoundsException if the request  is invalid
     * @since 4.2
     */
    public static <T> T first(final Iterable<T> iterable) {
        return get(iterable, 0);
    }

    
Returns the number of elements contained in the given iterator.

A null or empty iterator returns 0. 
Params:
iterable –  the iterable to check, may be null
Returns:
the number of elements contained in the iterable/**
     * Returns the number of elements contained in the given iterator.
     * <p>
     * A <code>null</code> or empty iterator returns {@code 0}.
     *
     * @param iterable  the iterable to check, may be null
     * @return the number of elements contained in the iterable
     */
    public static int size(final Iterable<?> iterable) {
        if (iterable instanceof Collection<?>) {
            return ((Collection<?>) iterable).size();
        }
        return IteratorUtils.size(emptyIteratorIfNull(iterable));
    }

    
Partitions all elements from iterable into separate output collections,
based on the evaluation of the given predicate.

For each predicate, the result will contain a list holding all elements of the
input iterable matching the predicate. The last list will hold all elements
which didn't match any predicate:
 [C1, R] = partition(I, P1) with
 I = input
 P1 = first predicate
 C1 = collection of elements matching P1
 R = collection of elements rejected by all predicates


If the input iterable is null, the same is returned as for an
empty iterable.

Example: for an input list [1, 2, 3, 4, 5] calling partition with a predicate [x < 3]
will result in the following output: [[1, 2], [3, 4, 5]].
Params:
iterable –  the iterable to partition, may be null
predicate –  the predicate to use, may not be null
Type parameters:
<O> –  the type of object the Iterable contains
Throws:
NullPointerException – if predicate is null
Returns:
a list containing the output collections/**
     * Partitions all elements from iterable into separate output collections,
     * based on the evaluation of the given predicate.
     * <p>
     * For each predicate, the result will contain a list holding all elements of the
     * input iterable matching the predicate. The last list will hold all elements
     * which didn't match any predicate:
     * <pre>
     *  [C1, R] = partition(I, P1) with
     *  I = input
     *  P1 = first predicate
     *  C1 = collection of elements matching P1
     *  R = collection of elements rejected by all predicates
     * </pre>
     * <p>
     * If the input iterable is <code>null</code>, the same is returned as for an
     * empty iterable.
     * <p>
     * Example: for an input list [1, 2, 3, 4, 5] calling partition with a predicate [x &lt; 3]
     * will result in the following output: [[1, 2], [3, 4, 5]].
     *
     * @param <O>  the type of object the {@link Iterable} contains
     * @param iterable  the iterable to partition, may be null
     * @param predicate  the predicate to use, may not be null
     * @return a list containing the output collections
     * @throws NullPointerException if predicate is null
     */
    public static <O> List<List<O>> partition(final Iterable<? extends O> iterable,
                                              final Predicate<? super O> predicate) {
        if (predicate == null) {
            throw new NullPointerException("Predicate must not be null.");
        }
        @SuppressWarnings({ "unchecked", "rawtypes" }) // safe
        final Factory<List<O>> factory = FactoryUtils.instantiateFactory((Class) ArrayList.class);
        @SuppressWarnings("unchecked") // safe
        final Predicate<? super O>[] predicates = new Predicate[] { predicate };
        return partition(iterable, factory, predicates);
    }

    
Partitions all elements from iterable into separate output collections,
based on the evaluation of the given predicates.

For each predicate, the result will contain a list holding all elements of the
input iterable matching the predicate. The last list will hold all elements
which didn't match any predicate:
 [C1, C2, R] = partition(I, P1, P2) with
 I = input
 P1 = first predicate
 P2 = second predicate
 C1 = collection of elements matching P1
 C2 = collection of elements matching P2
 R = collection of elements rejected by all predicates


Note: elements are only added to the output collection of the first matching
predicate, determined by the order of arguments.

If the input iterable is null, the same is returned as for an
empty iterable.

Example: for an input list [1, 2, 3, 4, 5] calling partition with predicates [x < 3]
and [x < 5] will result in the following output: [[1, 2], [3, 4], [5]].
Params:
iterable –  the collection to get the input from, may be null
predicates –  the predicates to use, may not be null
Type parameters:
<O> –  the type of object the Iterable contains
Throws:
NullPointerException – if any predicate is null
Returns:
a list containing the output collections/**
     * Partitions all elements from iterable into separate output collections,
     * based on the evaluation of the given predicates.
     * <p>
     * For each predicate, the result will contain a list holding all elements of the
     * input iterable matching the predicate. The last list will hold all elements
     * which didn't match any predicate:
     * <pre>
     *  [C1, C2, R] = partition(I, P1, P2) with
     *  I = input
     *  P1 = first predicate
     *  P2 = second predicate
     *  C1 = collection of elements matching P1
     *  C2 = collection of elements matching P2
     *  R = collection of elements rejected by all predicates
     * </pre>
     * <p>
     * <b>Note</b>: elements are only added to the output collection of the first matching
     * predicate, determined by the order of arguments.
     * <p>
     * If the input iterable is <code>null</code>, the same is returned as for an
     * empty iterable.
     * <p>
     * Example: for an input list [1, 2, 3, 4, 5] calling partition with predicates [x &lt; 3]
     * and [x &lt; 5] will result in the following output: [[1, 2], [3, 4], [5]].
     *
     * @param <O>  the type of object the {@link Iterable} contains
     * @param iterable  the collection to get the input from, may be null
     * @param predicates  the predicates to use, may not be null
     * @return a list containing the output collections
     * @throws NullPointerException if any predicate is null
     */
    public static <O> List<List<O>> partition(final Iterable<? extends O> iterable,
                                              final Predicate<? super O>... predicates) {

        @SuppressWarnings({ "unchecked", "rawtypes" }) // safe
        final Factory<List<O>> factory = FactoryUtils.instantiateFactory((Class) ArrayList.class);
        return partition(iterable, factory, predicates);
    }

    
Partitions all elements from iterable into separate output collections,
based on the evaluation of the given predicates.

For each predicate, the returned list will contain a collection holding
all elements of the input iterable matching the predicate. The last collection
contained in the list will hold all elements which didn't match any predicate:
 [C1, C2, R] = partition(I, P1, P2) with
 I = input
 P1 = first predicate
 P2 = second predicate
 C1 = collection of elements matching P1
 C2 = collection of elements matching P2
 R = collection of elements rejected by all predicates


Note: elements are only added to the output collection of the first matching
predicate, determined by the order of arguments.

If the input iterable is null, the same is returned as for an
empty iterable.
If no predicates have been provided, all elements of the input collection
will be added to the rejected collection.

Example: for an input list [1, 2, 3, 4, 5] calling partition with predicates [x < 3]
and [x < 5] will result in the following output: [[1, 2], [3, 4], [5]].
Params:
iterable –  the collection to get the input from, may be null
partitionFactory –  the factory used to create the output collections
predicates –  the predicates to use, may not be null
Type parameters:
<O> –  the type of object the Iterable contains
<R> –  the type of the output Collection
Throws:
NullPointerException – if any predicate is null
Returns:
a list containing the output collections/**
     * Partitions all elements from iterable into separate output collections,
     * based on the evaluation of the given predicates.
     * <p>
     * For each predicate, the returned list will contain a collection holding
     * all elements of the input iterable matching the predicate. The last collection
     * contained in the list will hold all elements which didn't match any predicate:
     * <pre>
     *  [C1, C2, R] = partition(I, P1, P2) with
     *  I = input
     *  P1 = first predicate
     *  P2 = second predicate
     *  C1 = collection of elements matching P1
     *  C2 = collection of elements matching P2
     *  R = collection of elements rejected by all predicates
     * </pre>
     * <p>
     * <b>Note</b>: elements are only added to the output collection of the first matching
     * predicate, determined by the order of arguments.
     * <p>
     * If the input iterable is <code>null</code>, the same is returned as for an
     * empty iterable.
     * If no predicates have been provided, all elements of the input collection
     * will be added to the rejected collection.
     * <p>
     * Example: for an input list [1, 2, 3, 4, 5] calling partition with predicates [x &lt; 3]
     * and [x &lt; 5] will result in the following output: [[1, 2], [3, 4], [5]].
     *
     * @param <O>  the type of object the {@link Iterable} contains
     * @param <R>  the type of the output {@link Collection}
     * @param iterable  the collection to get the input from, may be null
     * @param partitionFactory  the factory used to create the output collections
     * @param predicates  the predicates to use, may not be null
     * @return a list containing the output collections
     * @throws NullPointerException if any predicate is null
     */
    public static <O, R extends Collection<O>> List<R> partition(final Iterable<? extends O> iterable,
            final Factory<R> partitionFactory, final Predicate<? super O>... predicates) {

        if (iterable == null) {
            final Iterable<O> empty = emptyIterable();
            return partition(empty, partitionFactory, predicates);
        }

        if (predicates == null) {
            throw new NullPointerException("Predicates must not be null.");
        }

        for (final Predicate<?> p : predicates) {
            if (p == null) {
                throw new NullPointerException("Predicate must not be null.");
            }
        }

        if (predicates.length < 1) {
            // return the entire input collection as a single partition
            final R singlePartition = partitionFactory.create();
            CollectionUtils.addAll(singlePartition, iterable);
            return Collections.singletonList(singlePartition);
        }

        // create the empty partitions
        final int numberOfPredicates = predicates.length;
        final int numberOfPartitions = numberOfPredicates + 1;
        final List<R> partitions = new ArrayList<>(numberOfPartitions);
        for (int i = 0; i < numberOfPartitions; ++i) {
            partitions.add(partitionFactory.create());
        }

        // for each element in inputCollection:
        // find the first predicate that evaluates to true.
        // if there is a predicate, add the element to the corresponding partition.
        // if there is no predicate, add it to the last, catch-all partition.
        for (final O element : iterable) {
            boolean elementAssigned = false;
            for (int i = 0; i < numberOfPredicates; ++i) {
                if (predicates[i].evaluate(element)) {
                    partitions.get(i).add(element);
                    elementAssigned = true;
                    break;
                }
            }

            if (!elementAssigned) {
                // no predicates evaluated to true
                // add element to last partition
                partitions.get(numberOfPredicates).add(element);
            }
        }

        return partitions;
    }

    
Gets a new list with the contents of the provided iterable.
Params:
iterable –  the iterable to use, may be null
Type parameters:
<E> – the element type
Returns:
a list of the iterator contents/**
     * Gets a new list with the contents of the provided iterable.
     *
     * @param <E> the element type
     * @param iterable  the iterable to use, may be null
     * @return a list of the iterator contents
     */
    public static <E> List<E> toList(final Iterable<E> iterable) {
        return IteratorUtils.toList(emptyIteratorIfNull(iterable));
    }

    
Returns a string representation of the elements of the specified iterable.
 The string representation consists of a list of the iterable's elements, enclosed in square brackets ("[]"). Adjacent elements are separated by the characters ", " (a comma followed by a space). Elements are converted to strings as by String.valueOf(Object). 
Params:
iterable –  the iterable to convert to a string, may be null
Type parameters:
<E> – the element type
Returns:
a string representation of iterable/**
     * Returns a string representation of the elements of the specified iterable.
     * <p>
     * The string representation consists of a list of the iterable's elements,
     * enclosed in square brackets ({@code "[]"}). Adjacent elements are separated
     * by the characters {@code ", "} (a comma followed by a space). Elements are
     * converted to strings as by {@code String.valueOf(Object)}.
     *
     * @param <E> the element type
     * @param iterable  the iterable to convert to a string, may be null
     * @return a string representation of {@code iterable}
     */
    public static <E> String toString(final Iterable<E> iterable) {
        return IteratorUtils.toString(emptyIteratorIfNull(iterable));
    }

    
Returns a string representation of the elements of the specified iterable.
 The string representation consists of a list of the iterable's elements, enclosed in square brackets ("[]"). Adjacent elements are separated by the characters ", " (a comma followed by a space). Elements are converted to strings as by using the provided transformer. 
Params:
iterable –  the iterable to convert to a string, may be null
transformer –  the transformer used to get a string representation of an element
Type parameters:
<E> – the element type
Throws:
NullPointerException – if transformer is null
Returns:
a string representation of iterable/**
     * Returns a string representation of the elements of the specified iterable.
     * <p>
     * The string representation consists of a list of the iterable's elements,
     * enclosed in square brackets ({@code "[]"}). Adjacent elements are separated
     * by the characters {@code ", "} (a comma followed by a space). Elements are
     * converted to strings as by using the provided {@code transformer}.
     *
     * @param <E> the element type
     * @param iterable  the iterable to convert to a string, may be null
     * @param transformer  the transformer used to get a string representation of an element
     * @return a string representation of {@code iterable}
     * @throws NullPointerException if {@code transformer} is null
     */
    public static <E> String toString(final Iterable<E> iterable,
                                      final Transformer<? super E, String> transformer) {
        if (transformer == null) {
            throw new NullPointerException("Transformer must not be null.");
        }
        return IteratorUtils.toString(emptyIteratorIfNull(iterable), transformer);
    }

    
Returns a string representation of the elements of the specified iterable.
 The string representation consists of a list of the iterable's elements, enclosed by the provided prefix and suffix. Adjacent elements are separated by the provided delimiter. Elements are converted to strings as by using the provided transformer. 
Params:
iterable –  the iterable to convert to a string, may be null
transformer –  the transformer used to get a string representation of an element
delimiter –  the string to delimit elements
prefix –  the prefix, prepended to the string representation
suffix –  the suffix, appended to the string representation
Type parameters:
<E> – the element type
Throws:
NullPointerException – if either transformer, delimiter, prefix or suffix is null
Returns:
a string representation of iterable/**
     * Returns a string representation of the elements of the specified iterable.
     * <p>
     * The string representation consists of a list of the iterable's elements,
     * enclosed by the provided {@code prefix} and {@code suffix}. Adjacent elements
     * are separated by the provided {@code delimiter}. Elements are converted to
     * strings as by using the provided {@code transformer}.
     *
     * @param <E> the element type
     * @param iterable  the iterable to convert to a string, may be null
     * @param transformer  the transformer used to get a string representation of an element
     * @param delimiter  the string to delimit elements
     * @param prefix  the prefix, prepended to the string representation
     * @param suffix  the suffix, appended to the string representation
     * @return a string representation of {@code iterable}
     * @throws NullPointerException if either transformer, delimiter, prefix or suffix is null
     */
    public static <E> String toString(final Iterable<E> iterable,
                                      final Transformer<? super E, String> transformer,
                                      final String delimiter,
                                      final String prefix,
                                      final String suffix) {
        return IteratorUtils.toString(emptyIteratorIfNull(iterable),
                                      transformer, delimiter, prefix, suffix);
    }

    // Helper methods
    // ----------------------------------------------------------------------

    
Fail-fast check for null arguments.
Params:
iterable –  the iterable to check
Throws:
NullPointerException – if iterable is null/**
     * Fail-fast check for null arguments.
     *
     * @param iterable  the iterable to check
     * @throws NullPointerException if iterable is null
     */
    static void checkNotNull(final Iterable<?> iterable) {
        if (iterable == null) {
            throw new NullPointerException("Iterable must not be null.");
        }
    }

    
Fail-fast check for null arguments.
Params:
iterables –  the iterables to check
Throws:
NullPointerException – if the argument or any of its contents is null/**
     * Fail-fast check for null arguments.
     *
     * @param iterables  the iterables to check
     * @throws NullPointerException if the argument or any of its contents is null
     */
    static void checkNotNull(final Iterable<?>... iterables) {
        if (iterables == null) {
            throw new NullPointerException("Iterables must not be null.");
        }
        for (final Iterable<?> iterable : iterables) {
            checkNotNull(iterable);
        }
    }

    
Returns an empty iterator if the argument is null, or iterable.iterator() otherwise. 
Params:
iterable –  the iterable, possibly null
Type parameters:
<E> – the element type
Returns:
an empty iterator if the argument is null/**
     * Returns an empty iterator if the argument is <code>null</code>,
     * or {@code iterable.iterator()} otherwise.
     *
     * @param <E> the element type
     * @param iterable  the iterable, possibly <code>null</code>
     * @return an empty iterator if the argument is <code>null</code>
     */
    private static <E> Iterator<E> emptyIteratorIfNull(final Iterable<E> iterable) {
        return iterable != null ? iterable.iterator() : IteratorUtils.<E>emptyIterator();
    }

}