com.feilong.lib.collection4.IteratorUtils Maven / Gradle / Ivy
Show all versions of feilong Show documentation
/*
* 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 com.feilong.lib.collection4;
import java.lang.reflect.Array;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Dictionary;
import java.util.Enumeration;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import org.apache.commons.collections4.Closure;
import org.apache.commons.collections4.Predicate;
import org.apache.commons.collections4.ResettableIterator;
import org.apache.commons.collections4.Transformer;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
import com.feilong.lib.collection4.functors.EqualPredicate;
import com.feilong.lib.collection4.iterators.ArrayIterator;
import com.feilong.lib.collection4.iterators.EmptyIterator;
import com.feilong.lib.collection4.iterators.EnumerationIterator;
import com.feilong.lib.collection4.iterators.FilterIterator;
import com.feilong.lib.collection4.iterators.IteratorChain;
import com.feilong.lib.collection4.iterators.IteratorEnumeration;
import com.feilong.lib.collection4.iterators.NodeListIterator;
import com.feilong.lib.collection4.iterators.ObjectArrayIterator;
import com.feilong.lib.collection4.iterators.SingletonIterator;
import com.feilong.lib.collection4.iterators.TransformIterator;
/**
* Provides static utility methods and decorators for {@link Iterator}
* instances. The implementations are provided in the iterators subpackage.
*
* @since 2.1
*/
public class IteratorUtils{
// validation is done in this class in certain cases because the
// public classes allow invalid states
/**
* Default prefix used while converting an Iterator to its String representation.
*/
private static final String DEFAULT_TOSTRING_PREFIX = "[";
/**
* Default suffix used while converting an Iterator to its String representation.
*/
private static final String DEFAULT_TOSTRING_SUFFIX = "]";
/**
* Default delimiter used to delimit elements while converting an Iterator
* to its String representation.
*/
private static final String DEFAULT_TOSTRING_DELIMITER = ", ";
/**
* IteratorUtils is not normally instantiated.
*/
private IteratorUtils(){
}
// Empty
//-----------------------------------------------------------------------
/**
* Gets an empty iterator.
*
* This iterator is a valid iterator object that will iterate over nothing.
*
* @param
* the element type
* @return an iterator over nothing
*/
public static ResettableIterator emptyIterator(){
return EmptyIterator. resettableEmptyIterator();
}
// Chained
//-----------------------------------------------------------------------
/**
* Gets an iterator that iterates through two {@link Iterator}s
* one after another.
*
* @param
* the element type
* @param iterator1
* the first iterator to use, not null
* @param iterator2
* the second iterator to use, not null
* @return a combination iterator over the iterators
* @throws NullPointerException
* if either iterator is null
*/
public static Iterator chainedIterator(final Iterator iterator1,final Iterator iterator2){
// keep a version with two iterators to avoid the following warning in client code (Java 5 & 6)
// "A generic array of E is created for a varargs parameter"
return new IteratorChain<>(iterator1, iterator2);
}
/**
* Gets an iterator that iterates through an array of {@link Iterator}s
* one after another.
*
* @param
* the element type
* @param iterators
* the iterators to use, not null or empty or contain nulls
* @return a combination iterator over the iterators
* @throws NullPointerException
* if iterators array is null or contains a null
*/
@SafeVarargs
public static Iterator chainedIterator(final Iterator...iterators){
return new IteratorChain<>(iterators);
}
/**
* Gets an iterator that iterates through a collections of {@link Iterator}s
* one after another.
*
* @param
* the element type
* @param iterators
* the iterators to use, not null or empty or contain nulls
* @return a combination iterator over the iterators
* @throws NullPointerException
* if iterators collection is null or contains a null
* @throws ClassCastException
* if the iterators collection contains the wrong object type
*/
public static Iterator chainedIterator(final Collection> iterators){
return new IteratorChain<>(iterators);
}
// Object Graph
// Transformed
//-----------------------------------------------------------------------
/**
* Gets an iterator that transforms the elements of another iterator.
*
* The transformation occurs during the next() method and the underlying
* iterator is unaffected by the transformation.
*
* @param
* the input type
* @param
* the output type
* @param iterator
* the iterator to use, not null
* @param transform
* the transform to use, not null
* @return a new transforming iterator
* @throws NullPointerException
* if either parameter is null
*/
public static Iterator transformedIterator(
final Iterator iterator,
final Transformer transform){
if (iterator == null){
throw new NullPointerException("Iterator must not be null");
}
if (transform == null){
throw new NullPointerException("Transformer must not be null");
}
return new TransformIterator<>(iterator, transform);
}
// Filtered
//-----------------------------------------------------------------------
/**
* Gets an iterator that filters another iterator.
*
* The returned iterator will only return objects that match the specified
* filtering predicate.
*
* @param
* the element type
* @param iterator
* the iterator to use, not null
* @param predicate
* the predicate to use as a filter, not null
* @return a new filtered iterator
* @throws NullPointerException
* if either parameter is null
*/
public static Iterator filteredIterator(final Iterator iterator,final Predicate predicate){
if (iterator == null){
throw new NullPointerException("Iterator must not be null");
}
if (predicate == null){
throw new NullPointerException("Predicate must not be null");
}
return new FilterIterator<>(iterator, predicate);
}
// org.w3c.dom.NodeList iterators
//-----------------------------------------------------------------------
/**
* Gets an {@link Iterator} that wraps the specified {@link NodeList}.
* The returned {@link Iterator} can be used for a single iteration.
*
* @param nodeList
* the node list to use, may not be null
* @return a new, single use {@link Iterator}
* @throws NullPointerException
* if nodeList is null
* @since 4.0
*/
public static NodeListIterator nodeListIterator(final NodeList nodeList){
if (nodeList == null){
throw new NullPointerException("NodeList must not be null");
}
return new NodeListIterator(nodeList);
}
/**
* Gets an {@link Iterator} that wraps the specified node's childNodes.
* The returned {@link Iterator} can be used for a single iteration.
*
* Convenience method, allows easy iteration over NodeLists:
*
*
* Iterator<Node> iterator = IteratorUtils.nodeListIterator(node);
* for(Node childNode : IteratorUtils.asIterable(iterator)) {
* ...
* }
*
*
* @param node
* the node to use, may not be null
* @return a new, single use {@link Iterator}
* @throws NullPointerException
* if node is null
* @since 4.0
*/
public static NodeListIterator nodeListIterator(final Node node){
if (node == null){
throw new NullPointerException("Node must not be null");
}
return new NodeListIterator(node);
}
// Views
//-----------------------------------------------------------------------
/**
* Gets an iterator that provides an iterator view of the given enumeration.
*
* @param
* the element type
* @param enumeration
* the enumeration to use, may not be null
* @return a new iterator
* @throws NullPointerException
* if enumeration is null
*/
public static Iterator asIterator(final Enumeration enumeration){
if (enumeration == null){
throw new NullPointerException("Enumeration must not be null");
}
return new EnumerationIterator<>(enumeration);
}
/**
* Gets an iterator that provides an iterator view of the given enumeration
* that will remove elements from the specified collection.
*
* @param
* the element type
* @param enumeration
* the enumeration to use, may not be null
* @param removeCollection
* the collection to remove elements from, may not be null
* @return a new iterator
* @throws NullPointerException
* if enumeration or removeCollection is null
*/
public static Iterator asIterator(final Enumeration enumeration,final Collection removeCollection){
if (enumeration == null){
throw new NullPointerException("Enumeration must not be null");
}
if (removeCollection == null){
throw new NullPointerException("Collection must not be null");
}
return new EnumerationIterator<>(enumeration, removeCollection);
}
/**
* Gets an enumeration that wraps an iterator.
*
* @param
* the element type
* @param iterator
* the iterator to use, may not be null
* @return a new enumeration
* @throws NullPointerException
* if iterator is null
*/
public static Enumeration asEnumeration(final Iterator iterator){
if (iterator == null){
throw new NullPointerException("Iterator must not be null");
}
return new IteratorEnumeration<>(iterator);
}
/**
* Gets an array based on an iterator.
*
* As the wrapped Iterator is traversed, an ArrayList of its values is
* created. At the end, this is converted to an array.
*
* @param iterator
* the iterator to use, not null
* @return an array of the iterator contents
* @throws NullPointerException
* if iterator parameter is null
*/
public static Object[] toArray(final Iterator iterator){
if (iterator == null){
throw new NullPointerException("Iterator must not be null");
}
final List list = toList(iterator, 100);
return list.toArray();
}
/**
* Gets an array based on an iterator.
*
* As the wrapped Iterator is traversed, an ArrayList of its values is
* created. At the end, this is converted to an array.
*
* @param
* the element type
* @param iterator
* the iterator to use, not null
* @param arrayClass
* the class of array to create
* @return an array of the iterator contents
* @throws NullPointerException
* if iterator parameter or arrayClass is null
* @throws ArrayStoreException
* if the arrayClass is invalid
*/
public static E[] toArray(final Iterator iterator,final Class arrayClass){
if (iterator == null){
throw new NullPointerException("Iterator must not be null");
}
if (arrayClass == null){
throw new NullPointerException("Array class must not be null");
}
final List list = toList(iterator, 100);
@SuppressWarnings("unchecked")
final E[] array = (E[]) Array.newInstance(arrayClass, list.size());
return list.toArray(array);
}
/**
* Gets a list based on an iterator.
*
* As the wrapped Iterator is traversed, an ArrayList of its values is
* created. At the end, the list is returned.
*
* @param
* the element type
* @param iterator
* the iterator to use, not null
* @return a list of the iterator contents
* @throws NullPointerException
* if iterator parameter is null
*/
public static List toList(final Iterator iterator){
return toList(iterator, 10);
}
/**
* Gets a list based on an iterator.
*
* As the wrapped Iterator is traversed, an ArrayList of its values is
* created. At the end, the list is returned.
*
* @param
* the element type
* @param iterator
* the iterator to use, not null
* @param estimatedSize
* the initial size of the ArrayList
* @return a list of the iterator contents
* @throws NullPointerException
* if iterator parameter is null
* @throws IllegalArgumentException
* if the size is less than 1
*/
public static List toList(final Iterator iterator,final int estimatedSize){
if (iterator == null){
throw new NullPointerException("Iterator must not be null");
}
if (estimatedSize < 1){
throw new IllegalArgumentException("Estimated size must be greater than 0");
}
final List list = new ArrayList<>(estimatedSize);
while (iterator.hasNext()){
list.add(iterator.next());
}
return list;
}
/**
* Gets a suitable Iterator for the given object.
*
* This method can handle objects as follows
*
* - null - empty iterator
*
- Iterator - returned directly
*
- Enumeration - wrapped
*
- Collection - iterator from collection returned
*
- Map - values iterator returned
*
- Dictionary - values (elements) enumeration returned as iterator
*
- array - iterator over array returned
*
- object with iterator() public method accessed by reflection
*
- object - singleton iterator
*
- NodeList - iterator over the list
*
- Node - iterator over the child nodes
*
*
* @param obj
* the object to convert to an iterator
* @return a suitable iterator, never null
*/
public static Iterator getIterator(final Object obj){
if (obj == null){
return emptyIterator();
}
if (obj instanceof Iterator){
return (Iterator) obj;
}
if (obj instanceof Iterable){
return ((Iterable) obj).iterator();
}
if (obj instanceof Object[]){
return new ObjectArrayIterator<>((Object[]) obj);
}
if (obj instanceof Enumeration){
return new EnumerationIterator<>((Enumeration) obj);
}
if (obj instanceof Map){
return ((Map) obj).values().iterator();
}
if (obj instanceof NodeList){
return new NodeListIterator((NodeList) obj);
}
if (obj instanceof Node){
return new NodeListIterator((Node) obj);
}
if (obj instanceof Dictionary){
return new EnumerationIterator<>(((Dictionary) obj).elements());
}else if (obj.getClass().isArray()){
return new ArrayIterator<>(obj);
}
try{
final Method method = obj.getClass().getMethod("iterator", (Class[]) null);
if (Iterator.class.isAssignableFrom(method.getReturnType())){
final Iterator it = (Iterator) method.invoke(obj, (Object[]) null);
if (it != null){
return it;
}
}
}catch (final RuntimeException e){ // NOPMD
// ignore
}catch (final NoSuchMethodException e){ // NOPMD
// ignore
}catch (final IllegalAccessException e){ // NOPMD
// ignore
}catch (final InvocationTargetException e){ // NOPMD
// ignore
}
return singletonIterator(obj);
}
// Singleton
//-----------------------------------------------------------------------
/**
* Gets a singleton iterator.
*
* This iterator is a valid iterator object that will iterate over
* the specified object.
*
* @param
* the element type
* @param object
* the single object over which to iterate
* @return a singleton iterator over the object
*/
public static ResettableIterator singletonIterator(final E object){
return new SingletonIterator<>(object);
}
// Utility methods
//-----------------------------------------------------------------------
/**
* Applies the closure to each element of the provided iterator.
*
* @param
* the element type
* @param iterator
* 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
* @since 4.1
*/
public static void forEach(final Iterator iterator,final Closure closure){
if (closure == null){
throw new NullPointerException("Closure must not be null");
}
if (iterator != null){
while (iterator.hasNext()){
final E element = iterator.next();
closure.execute(element);
}
}
}
/**
* Executes the given closure on each but the last element in the iterator.
*
* If the input iterator is null no change is made.
*
* @param
* the type of object the {@link Iterator} contains
* @param iterator
* the iterator to get the input from, may be null
* @param closure
* the closure to perform, may not be null
* @return the last element in the iterator, or null if iterator is null or empty
* @throws NullPointerException
* if closure is null
* @since 4.1
*/
public static E forEachButLast(final Iterator iterator,final Closure closure){
if (closure == null){
throw new NullPointerException("Closure must not be null.");
}
if (iterator != null){
while (iterator.hasNext()){
final E element = iterator.next();
if (iterator.hasNext()){
closure.execute(element);
}else{
return element;
}
}
}
return null;
}
/**
* Finds the first element in the given iterator which matches the given predicate.
*
* A null or empty iterator returns null.
*
* @param
* the element type
* @param iterator
* the iterator to search, may be null
* @param predicate
* the predicate to use, may not be null
* @return the first element of the iterator which matches the predicate or null if none could be found
* @throws NullPointerException
* if predicate is null
* @since 4.1
*/
public static E find(final Iterator iterator,final Predicate predicate){
if (predicate == null){
throw new NullPointerException("Predicate must not be null");
}
if (iterator != null){
while (iterator.hasNext()){
final E element = iterator.next();
if (predicate.evaluate(element)){
return element;
}
}
}
return null;
}
/**
* Returns the index of the first element in the specified iterator that
* matches the given predicate.
*
* A null or empty iterator returns -1.
*
* @param
* the element type
* @param iterator
* the iterator 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
* @since 4.1
*/
public static int indexOf(final Iterator iterator,final Predicate predicate){
if (predicate == null){
throw new NullPointerException("Predicate must not be null");
}
if (iterator != null){
for (int index = 0; iterator.hasNext(); index++){
final E element = iterator.next();
if (predicate.evaluate(element)){
return index;
}
}
}
return -1;
}
/**
* Answers true if a predicate is true for any element of the iterator.
*
* A null or empty iterator returns false.
*
* @param
* the type of object the {@link Iterator} contains
* @param iterator
* the {@link Iterator} 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
* @since 4.1
*/
public static boolean matchesAny(final Iterator iterator,final Predicate predicate){
return indexOf(iterator, predicate) != -1;
}
/**
* Answers true if a predicate is true for every element of an iterator.
*
* A null or empty iterator returns true.
*
* @param
* the type of object the {@link Iterator} contains
* @param iterator
* the {@link Iterator} 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
* @since 4.1
*/
public static boolean matchesAll(final Iterator iterator,final Predicate predicate){
if (predicate == null){
throw new NullPointerException("Predicate must not be null");
}
if (iterator != null){
while (iterator.hasNext()){
final E element = iterator.next();
if (!predicate.evaluate(element)){
return false;
}
}
}
return true;
}
/**
* Checks if the given iterator is empty.
*
* A null or empty iterator returns true.
*
* @param iterator
* the {@link Iterator} to use, may be null
* @return true if the iterator is exhausted or null, false otherwise
* @since 4.1
*/
public static boolean isEmpty(final Iterator iterator){
return iterator == null || !iterator.hasNext();
}
/**
* Checks if the object is contained in the given iterator.
*
* A null or empty iterator returns false.
*
* @param
* the type of object the {@link Iterator} contains
* @param iterator
* the iterator to check, may be null
* @param object
* the object to check
* @return true if the object is contained in the iterator, false otherwise
* @since 4.1
*/
public static boolean contains(final Iterator iterator,final Object object){
return matchesAny(iterator, EqualPredicate.equalPredicate(object));
}
/**
* Returns the index-th value in {@link Iterator}, throwing
* IndexOutOfBoundsException if there is no such element.
*
* The Iterator is advanced to index (or to the end, if
* index exceeds the number of entries) as a side effect of this method.
*
* @param
* the type of object in the {@link Iterator}
* @param iterator
* the iterator to get a value from
* @param index
* the index to get
* @return the object at the specified index
* @throws IndexOutOfBoundsException
* if the index is invalid
* @since 4.1
*/
public static E get(final Iterator iterator,final int index){
int i = index;
CollectionUtils.checkIndexBounds(i);
while (iterator.hasNext()){
i--;
if (i == -1){
return iterator.next();
}
iterator.next();
}
throw new IndexOutOfBoundsException("Entry does not exist: " + i);
}
/**
* Shortcut for {@code get(iterator, 0)}.
*
* Returns the first value in {@link Iterator}, throwing
* IndexOutOfBoundsException if there is no such element.
*
*
* The Iterator is advanced to 0 (or to the end, if
* 0 exceeds the number of entries) as a side effect of this method.
*
*
* @param
* the type of object in the {@link Iterator}
* @param iterator
* the iterator to get a value from
* @return the first object
* @throws IndexOutOfBoundsException
* if the request is invalid
* @since 4.2
*/
public static E first(final Iterator iterator){
return get(iterator, 0);
}
/**
* Returns the number of elements contained in the given iterator.
*
* A null or empty iterator returns {@code 0}.
*
* @param iterator
* the iterator to check, may be null
* @return the number of elements contained in the iterator
* @since 4.1
*/
public static int size(final Iterator iterator){
int size = 0;
if (iterator != null){
while (iterator.hasNext()){
iterator.next();
size++;
}
}
return size;
}
/**
* Returns a string representation of the elements of the specified iterator.
*
* The string representation consists of a list of the iterator'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
* the element type
* @param iterator
* the iterator to convert to a string, may be null
* @return a string representation of {@code iterator}
* @since 4.1
*/
public static String toString(final Iterator iterator){
return toString(
iterator,
TransformerUtils.stringValueTransformer(),
DEFAULT_TOSTRING_DELIMITER,
DEFAULT_TOSTRING_PREFIX,
DEFAULT_TOSTRING_SUFFIX);
}
/**
* Returns a string representation of the elements of the specified iterator.
*
* 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
* the element type
* @param iterator
* the iterator 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 iterator}
* @throws NullPointerException
* if {@code transformer} is null
* @since 4.1
*/
public static String toString(final Iterator iterator,final Transformer transformer){
return toString(iterator, transformer, DEFAULT_TOSTRING_DELIMITER, DEFAULT_TOSTRING_PREFIX, DEFAULT_TOSTRING_SUFFIX);
}
/**
* Returns a string representation of the elements of the specified iterator.
*
* The string representation consists of a list of the iterator'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
* the element type
* @param iterator
* the iterator 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 iterator}
* @throws NullPointerException
* if either transformer, delimiter, prefix or suffix is null
* @since 4.1
*/
public static String toString(
final Iterator iterator,
final Transformer transformer,
final String delimiter,
final String prefix,
final String suffix){
if (transformer == null){
throw new NullPointerException("transformer may not be null");
}
if (delimiter == null){
throw new NullPointerException("delimiter may not be null");
}
if (prefix == null){
throw new NullPointerException("prefix may not be null");
}
if (suffix == null){
throw new NullPointerException("suffix may not be null");
}
final StringBuilder stringBuilder = new StringBuilder(prefix);
if (iterator != null){
while (iterator.hasNext()){
final E element = iterator.next();
stringBuilder.append(transformer.transform(element));
stringBuilder.append(delimiter);
}
if (stringBuilder.length() > prefix.length()){
stringBuilder.setLength(stringBuilder.length() - delimiter.length());
}
}
stringBuilder.append(suffix);
return stringBuilder.toString();
}
}