All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.groupbyinc.common.apache.commons.collections4.FluentIterable Maven / Gradle / Ivy

There is a newer version: 198
Show newest version
/*
 * 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.Arrays;
import java.util.Collection;
import java.util.Comparator;
import java.util.Enumeration;
import java.util.Iterator;
import java.util.List;

import org.apache.commons.collections4.iterators.SingletonIterator;

/**
 * A FluentIterable provides a powerful yet simple API for manipulating
 * Iterable instances in a fluent manner.
 * 

* A FluentIterable can be created either from an Iterable or from a set * of elements. The following types of methods are provided: *

    *
  • fluent methods which return a new {@code FluentIterable} instance, * providing a view of the original iterable (e.g. filter(Predicate)); *
  • conversion methods which copy the FluentIterable's contents into a * new collection or array (e.g. toList()); *
  • utility methods which answer questions about the FluentIterable's * contents (e.g. size(), anyMatch(Predicate)). *
  • *
*

* The following example outputs the first 3 even numbers in the range [1, 10] * into a list: *

 * List<String> result =
 *   FluentIterable
 *       .of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
 *       .filter(new Predicate() {
 *                   public boolean evaluate(Integer number) {
 *                        return number % 2 == 0;
 *                   }
 *              )
 *       .transform(TransformerUtils.stringValueTransformer())
 *       .limit(3)
 *       .toList();
 * 
* The resulting list will contain the following elements: *
[2, 4, 6]
* * @param the element type * @since 4.1 * @version $Id: FluentIterable.java 1684264 2015-06-08 20:06:29Z tn $ */ public class FluentIterable implements Iterable { /** A reference to the wrapped iterable. */ private final Iterable iterable; // Static factory methods // ---------------------------------------------------------------------- /** * Creates a new empty FluentIterable. * * @param the element type * @return a new empty FluentIterable */ @SuppressWarnings("unchecked") public static FluentIterable empty() { return IterableUtils.EMPTY_ITERABLE; } /** * Creates a new FluentIterable of the single provided element. *

* The returned iterable's iterator does not support {@code remove()}. * * @param the element type * @param singleton the singleton element * @return a new FluentIterable containing the singleton */ public static FluentIterable of(final T singleton) { return of(IteratorUtils.asIterable(new SingletonIterator(singleton, false))); } /** * Creates a new FluentIterable from the provided elements. *

* The returned iterable's iterator does not support {@code remove()}. * * @param the element type * @param elements the elements to be contained in the FluentIterable * @return a new FluentIterable containing the provided elements */ public static FluentIterable of(final T... elements) { return of(Arrays.asList(elements)); } /** * Construct a new FluentIterable from the provided iterable. If the * iterable is already an instance of FluentIterable, the instance * will be returned instead. *

* The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. * * @param the element type * @param iterable the iterable to wrap into a FluentIterable, may not be null * @return a new FluentIterable wrapping the provided iterable * @throws NullPointerException if iterable is null */ public static FluentIterable of(final Iterable iterable) { IterableUtils.checkNotNull(iterable); if (iterable instanceof FluentIterable) { return (FluentIterable) iterable; } else { return new FluentIterable(iterable); } } // Constructor // ---------------------------------------------------------------------- /** * Package-private constructor, used by IterableUtils. */ FluentIterable() { this.iterable = this; } /** * Create a new FluentIterable by wrapping the provided iterable. * @param iterable the iterable to wrap */ private FluentIterable(final Iterable iterable) { this.iterable = iterable; } // fluent construction methods // ---------------------------------------------------------------------- /** * Returns a new FluentIterable whose iterator will first traverse * the elements of the current iterable, followed by the provided * elements. * * @param elements the elements to append to the iterable * @return a new iterable, combining this iterable with the elements */ public FluentIterable append(final E... elements) { return append(Arrays.asList(elements)); } /** * Returns a new FluentIterable whose iterator will first traverse * the elements of the current iterable, followed by the elements * of the provided iterable. * * @param other the other iterable to combine, may not be null * @return a new iterable, combining this iterable with other * @throws NullPointerException if other is null */ public FluentIterable append(final Iterable other) { return of(IterableUtils.chainedIterable(iterable, other)); } /** * Returns a new FluentIterable whose iterator will traverse the * elements of the current and provided iterable in natural order. *

* Example: natural ordering *

    *
  • this contains elements [1, 3, 5, 7] *
  • other contains elements [2, 4, 6, 8] *
*

* The returned iterable will traverse the elements in the following * order: [1, 2, 3, 4, 5, 6, 7, 8] * * @param other the other iterable to collate, may not be null * @return a new iterable, collating this iterable with the other in natural order * @throws NullPointerException if other is null * @see {@link org.apache.commons.collections4.iterators.CollatingIterator CollatingIterator} */ public FluentIterable collate(final Iterable other) { return of(IterableUtils.collatedIterable(iterable, other)); } /** * Returns a new FluentIterable whose iterator will traverse the * elements of the current and provided iterable according to the * ordering defined by an comparator. *

* Example: descending order *

    *
  • this contains elements [7, 5, 3, 1] *
  • other contains elements [8, 6, 4, 2] *
*

* The returned iterable will traverse the elements in the following * order: [8, 7, 6, 5, 4, 3, 2, 1] * * @param comparator the comparator to define an ordering, may be null, * in which case natural ordering will be used * @param other the other iterable to collate, may not be null * @return a new iterable, collating this iterable with the other in natural order * @throws NullPointerException if other is null * @see {@link org.apache.commons.collections4.iterators.CollatingIterator CollatingIterator} */ public FluentIterable collate(final Iterable other, final Comparator comparator) { return of(IterableUtils.collatedIterable(comparator, iterable, other)); } /** * This method fully traverses an iterator of this iterable and returns * a new iterable with the same contents, but without any reference * to the originating iterables and/or iterators. *

* Calling this method is equivalent to: *

     *   FluentIterable someIterable = ...;
     *   FluentIterable.of(someIterable.toList());
     * 
* * @return a new iterable with the same contents as this iterable */ public FluentIterable eval() { return of(toList()); } /** * Returns a new FluentIterable whose iterator will only return * elements from this iterable matching the provided predicate. * * @param predicate the predicate used to filter elements * @return a new iterable, providing a filtered view of this iterable * @throws NullPointerException if predicate is null */ public FluentIterable filter(final Predicate predicate) { return of(IterableUtils.filteredIterable(iterable, predicate)); } /** * Returns a new FluentIterable whose iterator will return at most * the provided maximum number of elements from this iterable. * * @param maxSize the maximum number of elements * @return a new iterable, providing a bounded view of this iterable * @throws IllegalArgumentException if maxSize is negative */ public FluentIterable limit(final long maxSize) { return of(IterableUtils.boundedIterable(iterable, maxSize)); } /** * Returns a new FluentIterable whose iterator will loop infinitely * over the elements from this iterable. * * @return a new iterable, providing a looping view of this iterable */ public FluentIterable loop() { return of(IterableUtils.loopingIterable(iterable)); } /** * Returns a new FluentIterable whose iterator will traverse the * elements from this iterable in reverse order. * * @return a new iterable, providing a reversed view of this iterable */ public FluentIterable reverse() { return of(IterableUtils.reversedIterable(iterable)); } /** * Returns a new FluentIterable whose iterator will skip the first * N elements from this iterable. * * @param elementsToSkip the number of elements to skip * @return a new iterable, providing a view of this iterable by skipping * the first N elements * @throws IllegalArgumentException if elementsToSkip is negative */ public FluentIterable skip(final long elementsToSkip) { return of(IterableUtils.skippingIterable(iterable, elementsToSkip)); } /** * Returns a new FluentIterable whose iterator will return all elements * of this iterable transformed by the provided transformer. * * @param the output element type * @param transformer the transformer applied to each element * @return a new iterable, providing a transformed view of this iterable * @throws NullPointerException if transformer is null */ public FluentIterable transform(final Transformer transformer) { return of(IterableUtils.transformedIterable(iterable, transformer)); } /** * Returns a new FluentIterable whose iterator will return a unique view * of this iterable. * * @return a new iterable, providing a unique view of this iterable */ public FluentIterable unique() { return of(IterableUtils.uniqueIterable(iterable)); } /** * Returns a new FluentIterable whose iterator will return an unmodifiable * view of this iterable. * * @return a new iterable, providing an unmodifiable view of this iterable */ public FluentIterable unmodifiable() { return of(IterableUtils.unmodifiableIterable(iterable)); } /** * Returns a new FluentIterable whose iterator will traverse * the elements of this iterable and the other iterable in * alternating order. * * @param other the other iterable to interleave, may not be null * @return a new iterable, interleaving this iterable with others * @throws NullPointerException if other is null */ public FluentIterable zip(final Iterable other) { return of(IterableUtils.zippingIterable(iterable, other)); } /** * Returns a new FluentIterable whose iterator will traverse * the elements of this iterable and the other iterables in * alternating order. * * @param others the iterables to interleave, may not be null * @return a new iterable, interleaving this iterable with others * @throws NullPointerException if either of the provided iterables is null */ public FluentIterable zip(final Iterable... others) { return of(IterableUtils.zippingIterable(iterable, others)); } // convenience methods // ---------------------------------------------------------------------- /** {@inheritDoc} */ @Override public Iterator iterator() { return iterable.iterator(); } /** * Returns an Enumeration that will enumerate all elements contained * in this iterable. * * @return an Enumeration over the elements of this iterable */ public Enumeration asEnumeration() { return IteratorUtils.asEnumeration(iterator()); } /** * Checks if all elements contained in this iterable are matching the * provided predicate. *

* A null or empty iterable returns true. * * @param predicate the predicate to use, may not be null * @return true if all elements contained in this iterable match the predicate, * false otherwise * @throws NullPointerException if predicate is null */ public boolean allMatch(final Predicate predicate) { return IterableUtils.matchesAll(iterable, predicate); } /** * Checks if this iterable contains any element matching the provided predicate. *

* A null or empty iterable returns false. * * @param predicate the predicate to use, may not be null * @return true if at least one element contained in this iterable matches the predicate, * false otherwise * @throws NullPointerException if predicate is null */ public boolean anyMatch(final Predicate predicate) { return IterableUtils.matchesAny(iterable, predicate); } /** * Checks if this iterable is empty. * * @return true if this iterable does not contain any elements, false otherwise */ public boolean isEmpty() { return IterableUtils.isEmpty(iterable); } /** * Checks if the object is contained in this iterable. * * @param object the object to check * @return true if the object is contained in this iterable, false otherwise */ public boolean contains(final Object object) { return IterableUtils.contains(iterable, object); } /** * Applies the closure to all elements contained in this iterable. * * @param closure the closure to apply to each element, may not be null * @throws NullPointerException if closure is null */ public void forEach(final Closure closure) { IterableUtils.forEach(iterable, closure); } /** * Returns the element at the provided position in this iterable. * In order to return the element, an iterator needs to be traversed * up to the requested position. * * @param position the position of the element to return * @return the element * @throws IndexOutOfBoundsException if the provided position is outside the * valid range of this iterable: [0, size) */ public E get(final int position) { return IterableUtils.get(iterable, position); } /** * Returns the number of elements that are contained in this iterable. * In order to determine the size, an iterator needs to be traversed. * * @return the size of this iterable */ public int size() { return IterableUtils.size(iterable); } /** * Traverses an iterator of this iterable and adds all elements * to the provided collection. * * @param collection the collection to add the elements * @throws NullPointerException if collection is null */ public void copyInto(final Collection collection) { if (collection == null) { throw new NullPointerException("Collection must not be null"); } CollectionUtils.addAll(collection, iterable); } /** * Returns an array containing all elements of this iterable by traversing * its iterator. * * @param arrayClass the class of array to create * @return an array of the iterable contents * @throws ArrayStoreException if arrayClass is invalid */ public E[] toArray(final Class arrayClass) { return IteratorUtils.toArray(iterator(), arrayClass); } /** * Returns a mutable list containing all elements of this iterable * by traversing its iterator. *

* The returned list is guaranteed to be mutable. * * @return a list of the iterable contents */ public List toList() { return IterableUtils.toList(iterable); } /** {@inheritDoc} */ @Override public String toString() { return IterableUtils.toString(iterable); } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy