Apache
/
commons-collections
mirror of https://github.com/apache/commons-collections.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Complete javadoc, minor formatting. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1436360 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas Neidhart 2013-01-21 14:14:46 +00:00
parent 9b11d27cd3
commit f99ac98da4
1 changed files with 85 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
src/main/java/org/apache/commons/collections/CollectionUtils.java
View File

@ -453,6 +453,7 @@ public class CollectionUtils {
* If the input collection or predicate is null, or no element of the collection * If the input collection or predicate is null, or no element of the collection
* matches the predicate, null is returned. * matches the predicate, null is returned.
* *
* @param <T> the type of object the {@link Collection} contains
* @param collection the collection to search, may be null * @param collection the collection to search, may be null
* @param predicate the predicate to use, may be null * @param predicate the predicate to use, may be null
* @return the first element of the collection which matches the predicate or null if none could be found * @return the first element of the collection which matches the predicate or null if none could be found
@ -473,10 +474,10 @@ public class CollectionUtils {
* <p> * <p>
* If the input collection or closure is null, there is no change made. * If the input collection or closure is null, there is no change made.
* *
* @param collection * @param <T> the type of object the {@link Collection} contains
* the collection to get the input from, may be null * @param <C> the closure type
* @param closure * @param collection the collection to get the input from, may be null
* the closure to perform, may be null * @param closure the closure to perform, may be null
* @return closure * @return closure
*/ */
public static <T, C extends Closure<? super T>> C forAllDo(final Collection<T> collection, final C closure) { public static <T, C extends Closure<? super T>> C forAllDo(final Collection<T> collection, final C closure) {
@ -493,10 +494,10 @@ public class CollectionUtils {
* <p> * <p>
* If the input collection or closure is null, there is no change made. * If the input collection or closure is null, there is no change made.
* *
* @param iterator * @param <T> the type of object the {@link Iterator} contains
* the iterator to get the input from, may be null * @param <C> the closure type
* @param closure * @param iterator the iterator to get the input from, may be null
* the closure to perform, may be null * @param closure the closure to perform, may be null
* @return closure * @return closure
* @since 4.0 * @since 4.0
*/ */
@ -515,10 +516,9 @@ public class CollectionUtils {
* <p> * <p>
* If the input collection or predicate is null, there is no change made. * If the input collection or predicate is null, there is no change made.
* *
* @param collection * @param <T> the type of object the {@link Iterable} contains
* the collection to get the input from, may be null * @param collection the collection to get the input from, may be null
* @param predicate * @param predicate the predicate to use as a filter, may be null
* the predicate to use as a filter, may be null
* @return true if the collection is modified by this call, false otherwise. * @return true if the collection is modified by this call, false otherwise.
*/ */
public static <T> boolean filter(final Iterable<T> collection, final Predicate<? super T> predicate) { public static <T> boolean filter(final Iterable<T> collection, final Predicate<? super T> predicate) {
@ -547,13 +547,13 @@ public class CollectionUtils {
* Transformer creates duplicates (or are otherwise invalid), the collection * Transformer creates duplicates (or are otherwise invalid), the collection
* may reduce in size due to calling this method. * may reduce in size due to calling this method.
* *
* @param collection * @param <C> the type of object the {@link Collection} contains
* the {@link Iterable} to get the input from, may be null * @param collection the {@link Iterable} to get the input from, may be null
* @param transformer * @param transformer the transformer to perform, may be null
* the transformer to perform, may be null
*/ */
public static <C> void transform(final Collection<C> collection, public static <C> void transform(final Collection<C> collection,
final Transformer<? super C, ? extends C> transformer) { final Transformer<? super C, ? extends C> transformer) {
if (collection != null && transformer != null) { if (collection != null && transformer != null) {
if (collection instanceof List<?>) { if (collection instanceof List<?>) {
final List<C> list = (List<C>) collection; final List<C> list = (List<C>) collection;
@ -574,10 +574,9 @@ public class CollectionUtils {
* <p> * <p>
* A <code>null</code> collection or predicate matches no elements. * A <code>null</code> collection or predicate matches no elements.
* *
* @param input * @param <C> the type of object the {@link Iterable} contains
* the {@link Iterable} to get the input from, may be null * @param input the {@link Iterable} to get the input from, may be null
* @param predicate * @param predicate the predicate to use, may be null
* the predicate to use, may be null
* @return the number of matches for the predicate in the collection * @return the number of matches for the predicate in the collection
*/ */
public static <C> int countMatches(final Iterable<C> input, final Predicate<? super C> predicate) { public static <C> int countMatches(final Iterable<C> input, final Predicate<? super C> predicate) {
@ -598,12 +597,10 @@ public class CollectionUtils {
* <p> * <p>
* A <code>null</code> collection or predicate returns false. * A <code>null</code> collection or predicate returns false.
* *
* @param input * @param <C> the type of object the {@link Iterable} contains
* the {@link Iterable} to get the input from, may be null * @param input the {@link Iterable} to get the input from, may be null
* @param predicate * @param predicate the predicate to use, may be null
* the predicate to use, may be null * @return true if at least one element of the collection matches the predicate
* @return true if at least one element of the collection matches the
* predicate
*/ */
public static <C> boolean exists(final Iterable<C> input, final Predicate<? super C> predicate) { public static <C> boolean exists(final Iterable<C> input, final Predicate<? super C> predicate) {
if (input != null && predicate != null) { if (input != null && predicate != null) {
@ -622,13 +619,11 @@ public class CollectionUtils {
* <p> * <p>
* A <code>null</code> predicate matches no elements. * A <code>null</code> predicate matches no elements.
* *
* @param inputCollection * @param <O> the type of object the {@link Collection} contains
* the collection to get the input from, may not be null * @param inputCollection the collection to get the input from, may not be null
* @param predicate * @param predicate the predicate to use, may be null
* the predicate to use, may be null
* @return the elements matching the predicate (new list) * @return the elements matching the predicate (new list)
* @throws NullPointerException * @throws NullPointerException if the input collection is null
* if the input collection is null
*/ */
public static <O> Collection<O> select(final Collection<? extends O> inputCollection, public static <O> Collection<O> select(final Collection<? extends O> inputCollection,
final Predicate<? super O> predicate) { final Predicate<? super O> predicate) {
@ -642,17 +637,17 @@ public class CollectionUtils {
* If the input collection or predicate is null, there is no change to the * If the input collection or predicate is null, there is no change to the
* output collection. * output collection.
* *
* @param inputCollection * @param <O> the type of object the {@link Collection} contains
* the collection to get the input from, may be null * @param <R> the type of the output {@link Collection}
* @param predicate * @param inputCollection the collection to get the input from, may be null
* the predicate to use, may be null * @param predicate the predicate to use, may be null
* @param outputCollection * @param outputCollection the collection to output into, may not be null if the inputCollection
* the collection to output into, may not be null if the inputCollection * and predicate or not null
* and predicate or not null
* @return the outputCollection * @return the outputCollection
*/ */
public static <O, R extends Collection<? super O>> R select(final Collection<? extends O> inputCollection, public static <O, R extends Collection<? super O>> R select(final Collection<? extends O> inputCollection,
final Predicate<? super O> predicate, final R outputCollection) { final Predicate<? super O> predicate, final R outputCollection) {
if (inputCollection != null && predicate != null) { if (inputCollection != null && predicate != null) {
for (final O item : inputCollection) { for (final O item : inputCollection) {
if (predicate.evaluate(item)) { if (predicate.evaluate(item)) {
@ -670,13 +665,11 @@ public class CollectionUtils {
* If the input predicate is <code>null</code>, the result is an empty * If the input predicate is <code>null</code>, the result is an empty
* list. * list.
* *
* @param inputCollection * @param <O> the type of object the {@link Collection} contains
* the collection to get the input from, may not be null * @param inputCollection the collection to get the input from, may not be null
* @param predicate * @param predicate the predicate to use, may be null
* the predicate to use, may be null
* @return the elements <b>not</b> matching the predicate (new list) * @return the elements <b>not</b> matching the predicate (new list)
* @throws NullPointerException * @throws NullPointerException if the input collection is null
* if the input collection is null
*/ */
public static <O> Collection<O> selectRejected(final Collection<? extends O> inputCollection, public static <O> Collection<O> selectRejected(final Collection<? extends O> inputCollection,
final Predicate<? super O> predicate) { final Predicate<? super O> predicate) {
@ -690,13 +683,12 @@ public class CollectionUtils {
* If the input predicate is <code>null</code>, no elements are added to * If the input predicate is <code>null</code>, no elements are added to
* <code>outputCollection</code>. * <code>outputCollection</code>.
* *
* @param inputCollection * @param <O> the type of object the {@link Collection} contains
* the collection to get the input from, may be null * @param <R> the type of the output {@link Collection}
* @param predicate * @param inputCollection the collection to get the input from, may be null
* the predicate to use, may be null * @param predicate the predicate to use, may be null
* @param outputCollection * @param outputCollection the collection to output into, may not be null if the inputCollection
* the collection to output into, may not be null if the inputCollection * and predicate or not null
* and predicate or not null
* @return outputCollection * @return outputCollection
*/ */
public static <O, R extends Collection<? super O>> R selectRejected(final Collection<? extends O> inputCollection, public static <O, R extends Collection<? super O>> R selectRejected(final Collection<? extends O> inputCollection,
@ -718,15 +710,12 @@ public class CollectionUtils {
* <p> * <p>
* If the input transformer is null, the result is an empty list. * If the input transformer is null, the result is an empty list.
* *
* @param inputCollection * @param inputCollection the collection to get the input from, may not be null
* the collection to get the input from, may not be null * @param transformer the transformer to use, may be null
* @param transformer
* the transformer to use, may be null
* @param <I> the type of object in the input collection * @param <I> the type of object in the input collection
* @param <O> the type of object in the output collection * @param <O> the type of object in the output collection
* @return the transformed result (new list) * @return the transformed result (new list)
* @throws NullPointerException * @throws NullPointerException if the input collection is null
* if the input collection is null
*/ */
public static <I, O> Collection<O> collect(final Iterable<I> inputCollection, public static <I, O> Collection<O> collect(final Iterable<I> inputCollection,
final Transformer<? super I, ? extends O> transformer) { final Transformer<? super I, ? extends O> transformer) {
@ -742,10 +731,8 @@ public class CollectionUtils {
* If the input iterator or transformer is null, the result is an empty * If the input iterator or transformer is null, the result is an empty
* list. * list.
* *
* @param inputIterator * @param inputIterator the iterator to get the input from, may be null
* the iterator to get the input from, may be null * @param transformer the transformer to use, may be null
* @param transformer
* the transformer to use, may be null
* @param <I> the type of object in the input collection * @param <I> the type of object in the input collection
* @param <O> the type of object in the output collection * @param <O> the type of object in the output collection
* @return the transformed result (new list) * @return the transformed result (new list)
@ -818,6 +805,7 @@ public class CollectionUtils {
/** /**
* Adds an element to the collection unless the element is null. * Adds an element to the collection unless the element is null.
* *
* @param <T> the type of object the {@link Collection} contains
* @param collection the collection to add to, must not be null * @param collection the collection to add to, must not be null
* @param object the object to add, if null it will not be added * @param object the object to add, if null it will not be added
* @return true if the collection changed * @return true if the collection changed
@ -836,13 +824,11 @@ public class CollectionUtils {
* {@link Iterable} is a {@link Collection} then it is cast and will be * {@link Iterable} is a {@link Collection} then it is cast and will be
* added using {@link Collection#addAll(Collection)} instead of iterating. * added using {@link Collection#addAll(Collection)} instead of iterating.
* *
* @param collection * @param <C> the type of object the {@link Collection} contains
* the collection to add to, must not be null * @param collection the collection to add to, must not be null
* @param iterable * @param iterable the iterable of elements to add, must not be null
* the iterable of elements to add, must not be null
* @return a boolean indicating whether the collection has changed or not. * @return a boolean indicating whether the collection has changed or not.
* @throws NullPointerException * @throws NullPointerException if the collection or iterator is null
* if the collection or iterator is null
*/ */
public static <C> boolean addAll(final Collection<C> collection, final Iterable<? extends C> iterable) { public static <C> boolean addAll(final Collection<C> collection, final Iterable<? extends C> iterable) {
if (iterable instanceof Collection<?>) { if (iterable instanceof Collection<?>) {
@ -854,13 +840,11 @@ public class CollectionUtils {
/** /**
* Adds all elements in the iteration to the given collection. * Adds all elements in the iteration to the given collection.
* *
* @param collection * @param <C> the type of object the {@link Collection} contains
* the collection to add to, must not be null * @param collection the collection to add to, must not be null
* @param iterator * @param iterator the iterator of elements to add, must not be null
* the iterator of elements to add, must not be null
* @return a boolean indicating whether the collection has changed or not. * @return a boolean indicating whether the collection has changed or not.
* @throws NullPointerException * @throws NullPointerException if the collection or iterator is null
* if the collection or iterator is null
*/ */
public static <C> boolean addAll(final Collection<C> collection, final Iterator<? extends C> iterator) { public static <C> boolean addAll(final Collection<C> collection, final Iterator<? extends C> iterator) {
boolean changed = false; boolean changed = false;
@ -873,8 +857,10 @@ public class CollectionUtils {
/** /**
* Adds all elements in the enumeration to the given collection. * Adds all elements in the enumeration to the given collection.
* *
* @param <C> the type of object the {@link Collection} contains
* @param collection the collection to add to, must not be null * @param collection the collection to add to, must not be null
* @param enumeration the enumeration of elements to add, must not be null * @param enumeration the enumeration of elements to add, must not be null
* @return {@code true} if the collections was changed, {@code false} otherwise
* @throws NullPointerException if the collection or enumeration is null * @throws NullPointerException if the collection or enumeration is null
*/ */
public static <C> boolean addAll(final Collection<C> collection, final Enumeration<? extends C> enumeration) { public static <C> boolean addAll(final Collection<C> collection, final Enumeration<? extends C> enumeration) {
@ -888,12 +874,11 @@ public class CollectionUtils {
/** /**
* Adds all elements in the array to the given collection. * Adds all elements in the array to the given collection.
* *
* @param collection * @param <C> the type of object the {@link Collection} contains
* the collection to add to, must not be null * @param collection the collection to add to, must not be null
* @param elements * @param elements the array of elements to add, must not be null
* the array of elements to add, must not be null * @return {@code true} if the collection was changed, {@code false} otherwise
* @throws NullPointerException * @throws NullPointerException if the collection or array is null
* if the collection or array is null
*/ */
public static <C> boolean addAll(final Collection<C> collection, final C[] elements) { public static <C> boolean addAll(final Collection<C> collection, final C[] elements) {
boolean changed = false; boolean changed = false;
@ -906,9 +891,9 @@ public class CollectionUtils {
/** /**
* Returns the <code>index</code>-th value in {@link Iterator}, throwing * Returns the <code>index</code>-th value in {@link Iterator}, throwing
* <code>IndexOutOfBoundsException</code> if there is no such element. * <code>IndexOutOfBoundsException</code> if there is no such element.
* The Iterator is advanced to * <p>
* <code>index</code> (or to the end, if <code>index</code> exceeds the * The Iterator is advanced to <code>index</code> (or to the end, if
* number of entries) as a side effect of this method.</li> * <code>index</code> exceeds the number of entries) as a side effect of this method.
* *
* @param iterator the iterator to get a value from * @param iterator the iterator to get a value from
* @param index the index to get * @param index the index to get
@ -920,14 +905,14 @@ public class CollectionUtils {
public static <T> T get(final Iterator<T> iterator, final int index) { public static <T> T get(final Iterator<T> iterator, final int index) {
int i = index; int i = index;
checkIndexBounds(i); checkIndexBounds(i);
while (iterator.hasNext()) { while (iterator.hasNext()) {
i--; i--;
if (i == -1) { if (i == -1) {
return iterator.next(); return iterator.next();
}
iterator.next();
} }
throw new IndexOutOfBoundsException("Entry does not exist: " + i); iterator.next();
}
throw new IndexOutOfBoundsException("Entry does not exist: " + i);
} }
/** /**
@ -1038,9 +1023,11 @@ public class CollectionUtils {
} }
/** /**
* Returns the <code>index</code>-th <code>Map.Entry</code> in the <code>map</code>'s <code>entrySet</code>, throwing * Returns the <code>index</code>-th <code>Map.Entry</code> in the <code>map</code>'s <code>entrySet</code>,
* <code>IndexOutOfBoundsException</code> if there is no such element. * throwing <code>IndexOutOfBoundsException</code> if there is no such element.
* *
* @param <K> the key type in the {@link Map}
* @param <V> the key type in the {@link Map}
* @param map the object to get a value from * @param map the object to get a value from
* @param index the index to get * @param index the index to get
* @return the object at the specified index * @return the object at the specified index
@ -1261,6 +1248,7 @@ public class CollectionUtils {
* case the cardinality is zero. This method is useful if you do not wish to modify * case the cardinality is zero. This method is useful if you do not wish to modify
* the collection <code>c</code> and thus cannot call <code>c.retainAll(retain);</code>. * the collection <code>c</code> and thus cannot call <code>c.retainAll(retain);</code>.
* *
* @param <C> the type of object the {@link Collection} contains
* @param collection the collection whose contents are the target of the #retailAll operation * @param collection the collection whose contents are the target of the #retailAll operation
* @param retain the collection containing the elements to be retained in the returned collection * @param retain the collection containing the elements to be retained in the returned collection
* @return a <code>Collection</code> containing all the elements of <code>collection</code> * @return a <code>Collection</code> containing all the elements of <code>collection</code>
@ -1281,6 +1269,7 @@ public class CollectionUtils {
* case the cardinality is zero. This method is useful if you do not wish to modify * case the cardinality is zero. This method is useful if you do not wish to modify
* the collection <code>c</code> and thus cannot call <code>collection.removeAll(remove);</code>. * the collection <code>c</code> and thus cannot call <code>collection.removeAll(remove);</code>.
* *
* @param <E> the type of object the {@link Collection} contains
* @param collection the collection from which items are removed (in the returned collection) * @param collection the collection from which items are removed (in the returned collection)
* @param remove the items to be removed from the returned <code>collection</code> * @param remove the items to be removed from the returned <code>collection</code>
* @return a <code>Collection</code> containing all the elements of <code>collection</code> except * @return a <code>Collection</code> containing all the elements of <code>collection</code> except
@ -1311,6 +1300,7 @@ public class CollectionUtils {
* *
* This method uses the implementation in the decorators subpackage. * This method uses the implementation in the decorators subpackage.
* *
* @param <C> the type of object the {@link Collection} contains
* @param collection the collection to synchronize, must not be null * @param collection the collection to synchronize, must not be null
* @return a synchronized collection backed by the given collection * @return a synchronized collection backed by the given collection
* @throws IllegalArgumentException if the collection is null * @throws IllegalArgumentException if the collection is null
@ -1324,6 +1314,7 @@ public class CollectionUtils {
* <p> * <p>
* This method uses the implementation in the decorators subpackage. * This method uses the implementation in the decorators subpackage.
* *
* @param <C> the type of object the {@link Collection} contains
* @param collection the collection to make unmodifiable, must not be null * @param collection the collection to make unmodifiable, must not be null
* @return an unmodifiable collection backed by the given collection * @return an unmodifiable collection backed by the given collection
* @throws IllegalArgumentException if the collection is null * @throws IllegalArgumentException if the collection is null
@ -1361,6 +1352,7 @@ public class CollectionUtils {
* Existing entries in the specified collection will not be transformed. * Existing entries in the specified collection will not be transformed.
* If you want that behaviour, see {@link TransformedCollection#transformedCollection}. * If you want that behaviour, see {@link TransformedCollection#transformedCollection}.
* *
* @param <E> the type of object the {@link Collection} contains
* @param collection the collection to predicate, must not be null * @param collection the collection to predicate, must not be null
* @param transformer the transformer for the collection, must not be null * @param transformer the transformer for the collection, must not be null
* @return a transformed collection backed by the given collection * @return a transformed collection backed by the given collection