| /* |
| * 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 {@link Iterable} instances. |
| * <p> |
| * <b>Note</b>: this util class has been designed for fail-fast argument checking. |
| * <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 |
| * @version $Id$ |
| */ |
| public class IterableUtils { |
| |
| /** |
| * 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. |
| * <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. |
| * <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. |
| * <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. |
| * <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. |
| * <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(int count) { |
| if (count > iterables.length) { |
| return null; |
| } else { |
| return iterables[count - 1].iterator(); |
| } |
| } |
| }; |
| } |
| }; |
| } |
| |
| // Collated |
| // ---------------------------------------------------------------------- |
| |
| /** |
| * 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. |
| * <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. |
| * <p> |
| * The returned iterable's iterator does not support {@code remove()}. |
| * |
| * @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. |
| * <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. |
| * <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(int count) { |
| if (IterableUtils.isEmpty(iterable)) { |
| return null; |
| } else { |
| return iterable.iterator(); |
| } |
| } |
| }; |
| } |
| }; |
| } |
| |
| // Reversed |
| // ---------------------------------------------------------------------- |
| |
| /** |
| * 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<E>(list); |
| } |
| }; |
| } |
| |
| // Skipping |
| // ---------------------------------------------------------------------- |
| |
| /** |
| * 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. |
| * <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. |
| * <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 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<E>(iterable.iterator()); |
| } |
| }; |
| } |
| |
| // Unmodifiable |
| // ---------------------------------------------------------------------- |
| |
| /** |
| * 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<E>(iterable); |
| } |
| |
| /** |
| * 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. |
| * <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. |
| * <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 |
| 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. |
| * |
| * @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. |
| * |
| * @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. |
| * <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. |
| * <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. |
| * <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. |
| * <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. |
| * <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. |
| * <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. |
| * <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(); |
| } else { |
| return IteratorUtils.isEmpty(emptyIteratorIfNull(iterable)); |
| } |
| } |
| |
| /** |
| * 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); |
| } else { |
| return IteratorUtils.contains(emptyIteratorIfNull(iterable), object); |
| } |
| } |
| |
| /** |
| * 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. |
| * |
| * @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 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 <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); |
| } |
| |
| /** |
| * 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(); |
| } else { |
| return IteratorUtils.size(emptyIteratorIfNull(iterable)); |
| } |
| } |
| |
| /** |
| * 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 < 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. |
| * <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 < 3] |
| * and [x < 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. |
| * <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 < 3] |
| * and [x < 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 (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<R>(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. |
| * |
| * @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. |
| * <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. |
| * <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. |
| * <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. |
| * |
| * @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. |
| * |
| * @param iterable the iterable 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 <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(); |
| } |
| |
| } |
