mirror of
https://github.com/apache/commons-collections.git
synced 2025-02-16 15:07:17 +00:00
Javadoc
- Close HTML tags - Remove dead inline comments
This commit is contained in:
Gary Gregory
parent
91baca5864
commit
b8ff7e3e26
@ -112,7 +112,6 @@ public class IteratorUtils {
|
||||
*/
|
||||
private static final String DEFAULT_TOSTRING_DELIMITER = ", ";
|
||||
|
||||
// Arrays
|
||||
/**
|
||||
* Gets an iterator over an object array.
|
||||
*
|
||||
@ -161,6 +160,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This method will handle primitive arrays as well as object arrays.
|
||||
* The primitives will be wrapped in the appropriate wrapper class.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param array the array over which to iterate
|
||||
@ -177,6 +177,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This method will handle primitive arrays as well as object arrays.
|
||||
* The primitives will be wrapped in the appropriate wrapper class.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param array the array over which to iterate
|
||||
@ -196,6 +197,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This method will handle primitive arrays as well as object arrays.
|
||||
* The primitives will be wrapped in the appropriate wrapper class.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param array the array over which to iterate
|
||||
@ -257,6 +259,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This method will handle primitive arrays as well as object arrays.
|
||||
* The primitives will be wrapped in the appropriate wrapper class.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param array the array over which to iterate
|
||||
@ -273,6 +276,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This method will handle primitive arrays as well as object arrays.
|
||||
* The primitives will be wrapped in the appropriate wrapper class.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param array the array over which to iterate
|
||||
@ -291,6 +295,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This method will handle primitive arrays as well as object arrays.
|
||||
* The primitives will be wrapped in the appropriate wrapper class.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param array the array over which to iterate
|
||||
@ -331,7 +336,6 @@ public class IteratorUtils {
|
||||
return new IteratorIterable<>(iterator, false);
|
||||
}
|
||||
|
||||
// Views
|
||||
/**
|
||||
* Gets an iterator that provides an iterator view of the given enumeration.
|
||||
*
|
||||
@ -398,6 +402,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* The iterator is immediately advanced until it reaches the position at
|
||||
* {@code offset}, incurring O(n) time.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param iterator the iterator to decorate
|
||||
@ -485,8 +490,10 @@ public class IteratorUtils {
|
||||
* Given two ordered {@link Iterator}s {@code A} and {@code B},
|
||||
* the {@link Iterator#next()} method will return the lesser of
|
||||
* {@code A.next()} and {@code B.next()} and so on.
|
||||
* </p>
|
||||
* <p>
|
||||
* The comparator is optional. If null is specified then natural order is used.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param comparator the comparator to use, may be null for natural order
|
||||
@ -510,8 +517,10 @@ public class IteratorUtils {
|
||||
* Given two ordered {@link Iterator}s {@code A} and {@code B},
|
||||
* the {@link Iterator#next()} method will return the lesser of
|
||||
* {@code A.next()} and {@code B.next()} and so on.
|
||||
* </p>
|
||||
* <p>
|
||||
* The comparator is optional. If null is specified then natural order is used.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param comparator the comparator to use, may be null for natural order
|
||||
@ -535,8 +544,10 @@ public class IteratorUtils {
|
||||
* Given two ordered {@link Iterator}s {@code A} and {@code B},
|
||||
* the {@link Iterator#next()} method will return the lesser of
|
||||
* {@code A.next()} and {@code B.next()}.
|
||||
* </p>
|
||||
* <p>
|
||||
* The comparator is optional. If null is specified then natural order is used.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param comparator the comparator to use, may be null for natural order
|
||||
@ -554,12 +565,11 @@ public class IteratorUtils {
|
||||
return new CollatingIterator<>(comp, iterator1, iterator2);
|
||||
}
|
||||
|
||||
// Chained
|
||||
|
||||
/**
|
||||
* Checks if the object is contained in the given iterator.
|
||||
* <p>
|
||||
* A {@code null} or empty iterator returns false.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the type of object the {@link Iterator} contains
|
||||
* @param iterator the iterator to check, may be null
|
||||
@ -571,11 +581,11 @@ public class IteratorUtils {
|
||||
return matchesAny(iterator, EqualPredicate.equalPredicate(object));
|
||||
}
|
||||
|
||||
// Empty
|
||||
/**
|
||||
* Gets an empty iterator.
|
||||
* <p>
|
||||
* This iterator is a valid iterator object that will iterate over nothing.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @return an iterator over nothing
|
||||
@ -589,6 +599,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This iterator is a valid list iterator object that will iterate
|
||||
* over nothing.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @return a list iterator over nothing
|
||||
@ -602,6 +613,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This iterator is a valid map iterator object that will iterate
|
||||
* over nothing.
|
||||
* </p>
|
||||
*
|
||||
* @param <K> the key type
|
||||
* @param <V> the value type
|
||||
@ -616,6 +628,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This iterator is a valid iterator object that will iterate
|
||||
* over nothing.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @return an ordered iterator over nothing
|
||||
@ -629,6 +642,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This iterator is a valid map iterator object that will iterate
|
||||
* over nothing.
|
||||
* </p>
|
||||
*
|
||||
* @param <K> the key type
|
||||
* @param <V> the value type
|
||||
@ -638,12 +652,12 @@ public class IteratorUtils {
|
||||
return EmptyOrderedMapIterator.<K, V>emptyOrderedMapIterator();
|
||||
}
|
||||
|
||||
// Filtered
|
||||
/**
|
||||
* Gets an iterator that filters another iterator.
|
||||
* <p>
|
||||
* The returned iterator will only return objects that match the specified
|
||||
* filtering predicate.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param iterator the iterator to use, not null
|
||||
@ -663,6 +677,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* The returned iterator will only return objects that match the specified
|
||||
* filtering predicate.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param listIterator the list iterator to use, not null
|
||||
@ -763,6 +778,7 @@ public class IteratorUtils {
|
||||
* Executes the given closure on each but the last element in the iterator.
|
||||
* <p>
|
||||
* If the input iterator is null no change is made.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the type of object the {@link Iterator} contains
|
||||
* @param iterator the iterator to get the input from, may be null
|
||||
@ -835,6 +851,7 @@ public class IteratorUtils {
|
||||
* Gets a suitable Iterator for the given object.
|
||||
* <p>
|
||||
* This method can handle objects as follows
|
||||
* </p>
|
||||
* <ul>
|
||||
* <li>null - empty iterator
|
||||
* <li>Iterator - returned directly
|
||||
@ -897,13 +914,12 @@ public class IteratorUtils {
|
||||
return singletonIterator(obj);
|
||||
}
|
||||
|
||||
// Peeking
|
||||
|
||||
/**
|
||||
* Returns the index of the first element in the specified iterator that
|
||||
* matches the given predicate.
|
||||
* <p>
|
||||
* A {@code null} or empty iterator returns -1.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param iterator the iterator to search, may be null
|
||||
@ -926,12 +942,11 @@ public class IteratorUtils {
|
||||
return CollectionUtils.INDEX_NOT_FOUND;
|
||||
}
|
||||
|
||||
// Pushback
|
||||
|
||||
/**
|
||||
* Checks if the given iterator is empty.
|
||||
* <p>
|
||||
* A {@code null} or empty iterator returns true.
|
||||
* </p>
|
||||
*
|
||||
* @param iterator the {@link Iterator} to use, may be null
|
||||
* @return true if the iterator is exhausted or null, false otherwise
|
||||
@ -941,13 +956,13 @@ public class IteratorUtils {
|
||||
return iterator == null || !iterator.hasNext();
|
||||
}
|
||||
|
||||
// Looping
|
||||
/**
|
||||
* Gets an iterator that loops continuously over the supplied collection.
|
||||
* <p>
|
||||
* The iterator will only stop looping if the remove method is called
|
||||
* enough times to empty the collection, or if the collection is empty
|
||||
* to start with.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param collection the collection to iterate over, not null
|
||||
@ -963,6 +978,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* The iterator will only stop looping if the remove method is called
|
||||
* enough times to empty the list, or if the list is empty to start with.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param list the list to iterate over, not null
|
||||
@ -978,6 +994,7 @@ public class IteratorUtils {
|
||||
* Answers true if a predicate is true for every element of an iterator.
|
||||
* <p>
|
||||
* A {@code null} or empty iterator returns true.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the type of object the {@link Iterator} contains
|
||||
* @param iterator the {@link Iterator} to use, may be null
|
||||
@ -1005,6 +1022,7 @@ public class IteratorUtils {
|
||||
* Answers true if a predicate is true for any element of the iterator.
|
||||
* <p>
|
||||
* A {@code null} or empty iterator returns false.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the type of object the {@link Iterator} contains
|
||||
* @param iterator the {@link Iterator} to use, may be null
|
||||
@ -1022,6 +1040,7 @@ public class IteratorUtils {
|
||||
* The returned {@link Iterator} can be used for a single iteration.
|
||||
* <p>
|
||||
* Convenience method, allows easy iteration over NodeLists:
|
||||
* </p>
|
||||
* <pre>
|
||||
* Iterator<Node> iterator = IteratorUtils.nodeListIterator(node);
|
||||
* for (Node childNode : IteratorUtils.asIterable(iterator)) {
|
||||
@ -1038,7 +1057,6 @@ public class IteratorUtils {
|
||||
return new NodeListIterator(Objects.requireNonNull(node, "node"));
|
||||
}
|
||||
|
||||
// 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.
|
||||
@ -1060,8 +1078,10 @@ public class IteratorUtils {
|
||||
* The iteration starts from a single root object.
|
||||
* It uses a {@code Transformer} to extract the iterators and elements.
|
||||
* Its main benefit is that no intermediate {@code List} is created.
|
||||
* </p>
|
||||
* <p>
|
||||
* For example, consider an object graph:
|
||||
* </p>
|
||||
* <pre>
|
||||
* |- Branch -- Leaf
|
||||
* | \- Leaf
|
||||
@ -1073,8 +1093,10 @@ public class IteratorUtils {
|
||||
* |- Tree | /- Leaf
|
||||
* |- Branch -- Leaf
|
||||
* |- Branch -- Leaf</pre>
|
||||
* <p>
|
||||
* The following {@code Transformer}, used in this class, will extract all
|
||||
* the Leaf objects without creating a combined intermediate list:
|
||||
* </p>
|
||||
* <pre>
|
||||
* public Object transform(Object input) {
|
||||
* if (input instanceof Forest) {
|
||||
@ -1097,9 +1119,11 @@ public class IteratorUtils {
|
||||
* either an iterator or an object. If the object is an Iterator, the next element
|
||||
* from that iterator is obtained and the process repeats. If the element is an object
|
||||
* it is returned.
|
||||
* </p>
|
||||
* <p>
|
||||
* Under many circumstances, linking Iterators together in this manner is
|
||||
* more efficient (and convenient) than using nested for loops to extract a list.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param root the root object to start iterating from, null results in an empty iterator
|
||||
@ -1138,12 +1162,12 @@ public class IteratorUtils {
|
||||
return PushbackIterator.pushbackIterator(iterator);
|
||||
}
|
||||
|
||||
// Singleton
|
||||
/**
|
||||
* Gets a singleton iterator.
|
||||
* <p>
|
||||
* This iterator is a valid iterator object that will iterate over
|
||||
* the specified object.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param object the single object over which to iterate
|
||||
@ -1158,6 +1182,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* This iterator is a valid list iterator object that will iterate over
|
||||
* the specified object.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param object the single object over which to iterate
|
||||
@ -1171,6 +1196,7 @@ public class IteratorUtils {
|
||||
* Returns the number of elements contained in the given iterator.
|
||||
* <p>
|
||||
* A {@code null} or empty iterator returns {@code 0}.
|
||||
* </p>
|
||||
*
|
||||
* @param iterator the iterator to check, may be null
|
||||
* @return the number of elements contained in the iterator
|
||||
@ -1187,7 +1213,6 @@ public class IteratorUtils {
|
||||
return size;
|
||||
}
|
||||
|
||||
// Skipping
|
||||
/**
|
||||
* Decorates the specified iterator to skip the first N elements.
|
||||
*
|
||||
@ -1208,6 +1233,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* As the wrapped Iterator is traversed, an ArrayList of its values is
|
||||
* created. At the end, this is converted to an array.
|
||||
* </p>
|
||||
*
|
||||
* @param iterator the iterator to use, not null
|
||||
* @return an array of the iterator contents
|
||||
@ -1224,6 +1250,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* As the wrapped Iterator is traversed, an ArrayList of its values is
|
||||
* created. At the end, this is converted to an array.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param iterator the iterator to use, not null
|
||||
@ -1241,13 +1268,12 @@ public class IteratorUtils {
|
||||
return list.toArray(array);
|
||||
}
|
||||
|
||||
// Utility methods
|
||||
|
||||
/**
|
||||
* Gets a list based on an iterator.
|
||||
* <p>
|
||||
* As the wrapped Iterator is traversed, an ArrayList of its values is
|
||||
* created. At the end, the list is returned.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param iterator the iterator to use, not null
|
||||
@ -1263,6 +1289,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* As the wrapped Iterator is traversed, an ArrayList of its values is
|
||||
* created. At the end, the list is returned.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param iterator the iterator to use, not null
|
||||
@ -1288,6 +1315,7 @@ public class IteratorUtils {
|
||||
* <p>
|
||||
* As the wrapped Iterator is traversed, a LinkedList of its values is
|
||||
* cached, permitting all required operations of ListIterator.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param iterator the iterator to use, may not be null
|
||||
@ -1306,6 +1334,7 @@ public class IteratorUtils {
|
||||
* 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)}.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param iterator the iterator to convert to a string, may be null
|
||||
@ -1325,6 +1354,7 @@ public class IteratorUtils {
|
||||
* 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}.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param iterator the iterator to convert to a string, may be null
|
||||
@ -1346,6 +1376,7 @@ public class IteratorUtils {
|
||||
* 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}.
|
||||
* </p>
|
||||
*
|
||||
* @param <E> the element type
|
||||
* @param iterator the iterator to convert to a string, may be null
|
||||
@ -1381,12 +1412,12 @@ public class IteratorUtils {
|
||||
return stringBuilder.toString();
|
||||
}
|
||||
|
||||
// Transformed
|
||||
/**
|
||||
* Gets an iterator that transforms the elements of another iterator.
|
||||
* <p>
|
||||
* The transformation occurs during the next() method and the underlying
|
||||
* iterator is unaffected by the transformation.
|
||||
* </p>
|
||||
*
|
||||
* @param <I> the input type
|
||||
* @param <O> the output type
|
||||
@ -1403,7 +1434,6 @@ public class IteratorUtils {
|
||||
return new TransformIterator<>(iterator, transformer);
|
||||
}
|
||||
|
||||
// Unmodifiable
|
||||
/**
|
||||
* Gets an immutable version of an {@link Iterator}. The returned object
|
||||
* will always throw an {@link UnsupportedOperationException} for
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user