Author: tn Date: Tue Jun 19 19:52:06 2012 New Revision: 1351821 URL: http://svn.apache.org/viewvc?rev=1351821&view=rev Log: [COLLECTIONS-409] Improve performance of ListOrderedSet#addAll, add missing javadoc. Thanks to Adrian Nistor for reporting and providing a patch.
Modified: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/set/ListOrderedSet.java Modified: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/set/ListOrderedSet.java URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/set/ListOrderedSet.java?rev=1351821&r1=1351820&r2=1351821&view=diff ============================================================================== --- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/set/ListOrderedSet.java (original) +++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/set/ListOrderedSet.java Tue Jun 19 19:52:06 2012 @@ -65,8 +65,10 @@ public class ListOrderedSet<E> extends A * <p> * The list and set must both be empty. * + * @param <E> the element type * @param set the set to decorate, must be empty and not null * @param list the list to decorate, must be empty and not null + * @return a new ordered set * @throws IllegalArgumentException if set or list is null * @throws IllegalArgumentException if either the set or list is not empty * @since Commons Collections 3.1 @@ -89,7 +91,9 @@ public class ListOrderedSet<E> extends A * <p> * An <code>ArrayList</code> is used to retain order. * + * @param <E> the element type * @param set the set to decorate, must not be null + * @return a new ordered set * @throws IllegalArgumentException if set is null */ public static <E> ListOrderedSet<E> listOrderedSet(Set<E> set) { @@ -104,7 +108,9 @@ public class ListOrderedSet<E> extends A * NOTE: If the list contains duplicates, the duplicates are removed, * altering the specified list. * + * @param <E> the element type * @param list the list to decorate, must not be null + * @return a new ordered set * @throws IllegalArgumentException if list is null */ public static <E> ListOrderedSet<E> listOrderedSet(List<E> list) { @@ -244,14 +250,41 @@ public class ListOrderedSet<E> extends A } //----------------------------------------------------------------------- + // Additional methods that comply to the {@link List} interface + //----------------------------------------------------------------------- + + /** + * Returns the element at the specified position in this ordered set. + * + * @param index the position of the element in the ordered {@link Set}. + * @return the element at position {@code index} + * @see {@link List#get(int)} + */ public E get(int index) { return setOrder.get(index); } + /** + * Returns the index of the first occurrence of the specified element in ordered set. + * + * @param object the element to search for + * @return the index of the first occurrence of the object, or {@code -1} if this + * ordered set does not contain this object + * @see {@link List#indexOf(Object)} + */ public int indexOf(Object object) { return setOrder.indexOf(object); } + /** + * Inserts the specified element at the specified position if it is not yet contained in this + * ordered set (optional operation). Shifts the element currently at this position and any + * subsequent elements to the right. + * + * @param index the index at which the element is to be inserted + * @param object the element to be inserted + * @see {@link List#add(int, Object)} + */ public void add(int index, E object) { if (!contains(object)) { collection.add(object); @@ -259,19 +292,44 @@ public class ListOrderedSet<E> extends A } } + /** + * Inserts all elements in the specified collection not yet contained in the ordered set at the specified + * position (optional operation). Shifts the element currently at the position and all subsequent + * elements to the right. + * + * @param index the position to insert the elements + * @param coll the collection containing the elements to be inserted + * @return {@code true} if this ordered set changed as a result of the call + * @see {@link List#addAll(int, Collection)} + */ public boolean addAll(int index, Collection<? extends E> coll) { boolean changed = false; + // collect all elements to be added for performance reasons + final List<E> toAdd = new ArrayList<E>(); for (E e : coll) { if (contains(e)) { continue; } collection.add(e); - setOrder.add(index++, e); + toAdd.add(e); changed = true; } + + if (changed) { + setOrder.addAll(index, toAdd); + } + return changed; } + /** + * Removes the element at the specified position from the ordered set. Shifts any subsequent + * elements to the left. + * + * @param index the index of the element to be removed + * @return the element that has been remove from the ordered set + * @see {@link List#remove(int)} + */ public Object remove(int index) { Object obj = setOrder.remove(index); remove(obj); @@ -282,6 +340,8 @@ public class ListOrderedSet<E> extends A * Uses the underlying List's toString so that order is achieved. * This means that the decorated Set's toString is not used, so * any custom toStrings will be ignored. + * + * @return a string representation of the ordered set */ // Fortunately List.toString and Set.toString look the same @Override