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

Javadoc and Code tidy 

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131205 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Stephen Colebourne 2003-09-29 22:37:40 +00:00
parent 22d14c1895
commit 1088244314
4 changed files with 216 additions and 220 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

136
src/java/org/apache/commons/collections/iterators/ArrayIterator.java
View File

@ -1,5 +1,5 @@
/* /*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/ArrayIterator.java,v 1.5 2003/08/31 17:25:49 scolebourne Exp $ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/ArrayIterator.java,v 1.6 2003/09/29 22:37:40 scolebourne Exp $
* ==================================================================== * ====================================================================
* *
* The Apache Software License, Version 1.1 * The Apache Software License, Version 1.1
@ -61,7 +61,7 @@ import java.lang.reflect.Array;
import java.util.NoSuchElementException; import java.util.NoSuchElementException;
/** /**
* Implements an {@link java.util.Iterator Iterator} over an array. * Implements an {@link java.util.Iterator Iterator} over any array.
* <p> * <p>
* The array can be either an array of object or of primitives. If you know * The array can be either an array of object or of primitives. If you know
* that you have an object array, the * that you have an object array, the
@ -72,17 +72,17 @@ import java.util.NoSuchElementException;
* the iterator back to the start if required. * the iterator back to the start if required.
* *
* @since Commons Collections 1.0 * @since Commons Collections 1.0
* @version $Revision: 1.5 $ $Date: 2003/08/31 17:25:49 $ * @version $Revision: 1.6 $ $Date: 2003/09/29 22:37:40 $
* *
* @author <a href="mailto:jstrachan@apache.org">James Strachan</a> * @author James Strachan
* @author Mauricio S. Moura * @author Mauricio S. Moura
* @author <a href="mailto:mas@apache.org">Michael A. Smith</a> * @author Michael A. Smith
* @author <a href="mailto:neilotoole@users.sourceforge.net">Neil O'Toole</a> * @author Neil O'Toole
* @author Stephen Colebourne * @author Stephen Colebourne
*/ */
public class ArrayIterator implements ResetableIterator { public class ArrayIterator implements ResetableIterator {
/** The array */ /** The array to iterate over */
protected Object array; protected Object array;
/** The start index to loop from */ /** The start index to loop from */
protected int startIndex = 0; protected int startIndex = 0;
@ -91,6 +91,8 @@ public class ArrayIterator implements ResetableIterator {
/** The current iterator index */ /** The current iterator index */
protected int index = 0; protected int index = 0;
// Constructors
// ----------------------------------------------------------------------
/** /**
* Constructor for use with <code>setArray</code>. * Constructor for use with <code>setArray</code>.
* <p> * <p>
@ -109,9 +111,9 @@ public class ArrayIterator implements ResetableIterator {
* @throws IllegalArgumentException if <code>array</code> is not an array. * @throws IllegalArgumentException if <code>array</code> is not an array.
* @throws NullPointerException if <code>array</code> is <code>null</code> * @throws NullPointerException if <code>array</code> is <code>null</code>
*/ */
public ArrayIterator(Object array) { public ArrayIterator(final Object array) {
super(); super();
setArray( array ); setArray(array);
} }
/** /**
@ -119,15 +121,17 @@ public class ArrayIterator implements ResetableIterator {
* specified array from a specific start index. * specified array from a specific start index.
* *
* @param array the array to iterate over. * @param array the array to iterate over.
* @param start the index to start iterating at. * @param startIndex the index to start iterating at.
* @throws IllegalArgumentException if <code>array</code> is not an array. * @throws IllegalArgumentException if <code>array</code> is not an array.
* @throws NullPointerException if <code>array</code> is <code>null</code> * @throws NullPointerException if <code>array</code> is <code>null</code>
* @throws IndexOutOfBoundsException if the index is invalid
*/ */
public ArrayIterator(Object array, int start) { public ArrayIterator(final Object array, final int startIndex) {
setArray( array ); super();
checkBound(start, "start"); setArray(array);
this.startIndex = start; checkBound(startIndex, "start");
this.index = start; this.startIndex = startIndex;
this.index = startIndex;
} }
/** /**
@ -135,80 +139,87 @@ public class ArrayIterator implements ResetableIterator {
* in the specified array. * in the specified array.
* *
* @param array the array to iterate over. * @param array the array to iterate over.
* @param start the index to start iterating at. * @param startIndex the index to start iterating at.
* @param end the index to finish iterating at. * @param endIndex the index to finish iterating at.
* @throws IllegalArgumentException if <code>array</code> is not an array. * @throws IllegalArgumentException if <code>array</code> is not an array.
* @throws NullPointerException if <code>array</code> is <code>null</code> * @throws NullPointerException if <code>array</code> is <code>null</code>
* @throws IndexOutOfBoundsException if either index is invalid
*/ */
public ArrayIterator(Object array, int start, int end) { public ArrayIterator(final Object array, final int startIndex, final int endIndex) {
setArray( array ); super();
checkBound(start, "start"); setArray(array);
checkBound(end, "end"); checkBound(startIndex, "start");
if (end < start) { checkBound(endIndex, "end");
if (endIndex < startIndex) {
throw new IllegalArgumentException("End index must not be less than start index."); throw new IllegalArgumentException("End index must not be less than start index.");
} }
this.startIndex = start; this.startIndex = startIndex;
this.endIndex = end; this.endIndex = endIndex;
this.index = start; this.index = startIndex;
} }
protected void checkBound(int bound, String type ) { /**
* Checks whether the index is valid or not.
*
* @param bound the index to check
* @param type the index type (for error messges)
* @throws IndexOutOfBoundsException if the index is invalid
*/
protected void checkBound(final int bound, final String type ) {
if (bound > this.endIndex) { if (bound > this.endIndex) {
throw new ArrayIndexOutOfBoundsException( throw new ArrayIndexOutOfBoundsException(
"Attempt to make an ArrayIterator that "+type+ "Attempt to make an ArrayIterator that " + type +
"s beyond the end of the array. " "s beyond the end of the array. "
); );
} }
if (bound < 0) { if (bound < 0) {
throw new ArrayIndexOutOfBoundsException( throw new ArrayIndexOutOfBoundsException(
"Attempt to make an ArrayIterator that "+type+ "Attempt to make an ArrayIterator that " + type +
"s before the start of the array. " "s before the start of the array. "
); );
} }
} }
// Iterator interface // Iterator interface
//------------------------------------------------------------------------- //-----------------------------------------------------------------------
/** /**
* Returns true if there are more elements to return from the array. * Returns true if there are more elements to return from the array.
* *
* @return true if there is a next element to return * @return true if there is a next element to return
*/ */
public boolean hasNext() { public boolean hasNext() {
return (index < endIndex); return (index < endIndex);
} }
/** /**
* Returns the next element in the array. * Returns the next element in the array.
* *
* @return the next element in the array * @return the next element in the array
* @throws NoSuchElementException if all the elements in the array * @throws NoSuchElementException if all the elements in the array
* have already been returned * have already been returned
*/ */
public Object next() { public Object next() {
if (hasNext() == false) { if (hasNext() == false) {
throw new NoSuchElementException(); throw new NoSuchElementException();
} }
return Array.get( array, index++ ); return Array.get(array, index++);
} }
/** /**
* Throws {@link UnsupportedOperationException}. * Throws {@link UnsupportedOperationException}.
* *
* @throws UnsupportedOperationException always * @throws UnsupportedOperationException always
*/ */
public void remove() { public void remove() {
throw new UnsupportedOperationException( "remove() method is not supported" ); throw new UnsupportedOperationException("remove() method is not supported");
} }
// Properties // Properties
//------------------------------------------------------------------------- //-----------------------------------------------------------------------
/** /**
* Retrieves the array that this iterator is iterating over. * Gets the array that this iterator is iterating over.
* *
* @return the array this iterator iterates over, or <code>null</code> if * @return the array this iterator iterates over, or <code>null</code> if
* the no-arg constructor was used and {@link #setArray(Object)} has never * the no-arg constructor was used and {@link #setArray(Object)} has never
* been called with a valid array. * been called with a valid array.
*/ */
@ -217,40 +228,25 @@ public class ArrayIterator implements ResetableIterator {
} }
/** /**
* Changes the array that the ArrayIterator should iterate over. If an * Sets the array that the ArrayIterator should iterate over.
* array has previously been set (using the single-arg constructor or this
* method), that array along with the current iterator position within
* that array is discarded in favor of the argument to this method. This
* method can be used in combination with {@link #getArray()} to "reset"
* the iterator to the beginning of the array:
*
* <pre>
* ArrayIterator iterator = ...
* ...
* iterator.setArray(iterator.getArray());
* </pre>
*
* Note: Using i.setArray(i.getArray()) may throw a NullPointerException
* if no array has ever been set for the iterator (see {@link
* #getArray()})
* <p> * <p>
* The {@link #reset()} method is a better choice for resetting the iterator. * If an array has previously been set (using the single-arg constructor
* or this method) then that array is discarded in favour of this one.
* Iteration is restarted at the start of the new array.
* Although this can be used to reset iteration, the {@link #reset()} method
* is a more effective choice.
* *
* @param array the array that the iterator should iterate over. * @param array the array that the iterator should iterate over.
* * @throws IllegalArgumentException if <code>array</code> is not an array.
* @exception IllegalArgumentException if <code>array</code> is not an * @throws NullPointerException if <code>array</code> is <code>null</code>
* array.
*
* @exception NullPointerException
* if <code>array</code> is <code>null</code>
*/ */
public void setArray( Object array ) { public void setArray(final Object array) {
// Array.getLength throws IllegalArgumentException if the object is not // Array.getLength throws IllegalArgumentException if the object is not
// an array or NullPointerException if the object is null. This call // an array or NullPointerException if the object is null. This call
// is made before saving the array and resetting the index so that the // is made before saving the array and resetting the index so that the
// array iterator remains in a consistent state if the argument is not // array iterator remains in a consistent state if the argument is not
// an array or is null. // an array or is null.
this.endIndex = Array.getLength( array ); this.endIndex = Array.getLength(array);
this.startIndex = 0; this.startIndex = 0;
this.array = array; this.array = array;
this.index = 0; this.index = 0;

34
src/java/org/apache/commons/collections/iterators/ArrayListIterator.java
View File

@ -1,5 +1,5 @@
/* /*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/ArrayListIterator.java,v 1.5 2003/09/29 03:56:12 psteitz Exp $ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/ArrayListIterator.java,v 1.6 2003/09/29 22:37:40 scolebourne Exp $
* ==================================================================== * ====================================================================
* *
* The Apache Software License, Version 1.1 * The Apache Software License, Version 1.1
@ -77,7 +77,7 @@ import java.util.NoSuchElementException;
* @see java.util.ListIterator * @see java.util.ListIterator
* *
* @since Commons Collections 2.2 * @since Commons Collections 2.2
* @version $Revision: 1.5 $ $Date: 2003/09/29 03:56:12 $ * @version $Revision: 1.6 $ $Date: 2003/09/29 22:37:40 $
* *
* @author <a href="mailto:neilotoole@users.sourceforge.net">Neil O'Toole</a> * @author <a href="mailto:neilotoole@users.sourceforge.net">Neil O'Toole</a>
* @author Stephen Colebourne * @author Stephen Colebourne
@ -86,13 +86,16 @@ import java.util.NoSuchElementException;
public class ArrayListIterator extends ArrayIterator implements ResetableListIterator { public class ArrayListIterator extends ArrayIterator implements ResetableListIterator {
/** /**
* Holds the index of the last item returned by a call to <code>next()</code> or <code>previous()</code>. This * Holds the index of the last item returned by a call to <code>next()</code>
* is set to <code>-1</code> if neither method has yet been invoked. <code>lastItemIndex</code> is used to to * or <code>previous()</code>. This is set to <code>-1</code> if neither method
* implement the {@link #set} method. * has yet been invoked. <code>lastItemIndex</code> is used to to implement
* the {@link #set} method.
* *
*/ */
protected int lastItemIndex = -1; protected int lastItemIndex = -1;
// Constructors
// ----------------------------------------------------------------------
/** /**
* Constructor for use with <code>setArray</code>. * Constructor for use with <code>setArray</code>.
* <p> * <p>
@ -120,14 +123,14 @@ public class ArrayListIterator extends ArrayIterator implements ResetableListIte
* specified array from a specific start index. * specified array from a specific start index.
* *
* @param array the array to iterate over * @param array the array to iterate over
* @param start the index to start iterating at * @param startIndex the index to start iterating at
* @throws IllegalArgumentException if <code>array</code> is not an array. * @throws IllegalArgumentException if <code>array</code> is not an array.
* @throws NullPointerException if <code>array</code> is <code>null</code> * @throws NullPointerException if <code>array</code> is <code>null</code>
* @throws IndexOutOfBoundsException if the start index is out of bounds * @throws IndexOutOfBoundsException if the start index is out of bounds
*/ */
public ArrayListIterator(Object array, int start) { public ArrayListIterator(Object array, int startIndex) {
super(array, start); super(array, startIndex);
this.startIndex = start; this.startIndex = startIndex;
} }
/** /**
@ -135,21 +138,20 @@ public class ArrayListIterator extends ArrayIterator implements ResetableListIte
* in the specified array. * in the specified array.
* *
* @param array the array to iterate over * @param array the array to iterate over
* @param start the index to start iterating at * @param startIndex the index to start iterating at
* @param end the index (exclusive) to finish iterating at * @param endIndex the index (exclusive) to finish iterating at
* @throws IllegalArgumentException if <code>array</code> is not an array. * @throws IllegalArgumentException if <code>array</code> is not an array.
* @throws IndexOutOfBoundsException if the start or end index is out of bounds * @throws IndexOutOfBoundsException if the start or end index is out of bounds
* @throws IllegalArgumentException if end index is before the start * @throws IllegalArgumentException if end index is before the start
* @throws NullPointerException if <code>array</code> is <code>null</code> * @throws NullPointerException if <code>array</code> is <code>null</code>
*/ */
public ArrayListIterator(Object array, int start, int end) { public ArrayListIterator(Object array, int startIndex, int endIndex) {
super(array, start, end); super(array, startIndex, endIndex);
this.startIndex = start; this.startIndex = startIndex;
} }
// ListIterator interface // ListIterator interface
//------------------------------------------------------------------------- //-----------------------------------------------------------------------
/** /**
* Returns true if there are previous elements to return from the array. * Returns true if there are previous elements to return from the array.
* *

184
src/java/org/apache/commons/collections/iterators/CollatingIterator.java
View File

@ -1,5 +1,5 @@
/* /*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/CollatingIterator.java,v 1.8 2003/09/29 22:02:33 scolebourne Exp $ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/CollatingIterator.java,v 1.9 2003/09/29 22:37:40 scolebourne Exp $
* ==================================================================== * ====================================================================
* *
* The Apache Software License, Version 1.1 * The Apache Software License, Version 1.1
@ -68,23 +68,24 @@ import java.util.NoSuchElementException;
/** /**
* Provides an ordered iteration over the elements contained in * Provides an ordered iteration over the elements contained in
* a collection of ordered {@link Iterator}s. In other words, * a collection of ordered {@link Iterator}s.
* given two ordered {@link Iterator}s <code>A</code> and <code>B</code>, * <p>
* my {@link #next} method will return the lesser of * Given two ordered {@link Iterator}s <code>A</code> and <code>B</code>,
* the {@link #next} method on this iterator will return the lesser of
* <code>A.next()</code> and <code>B.next()</code>. * <code>A.next()</code> and <code>B.next()</code>.
* *
* @since Commons Collections 2.1 * @since Commons Collections 2.1
* @version $Revision: 1.8 $ $Date: 2003/09/29 22:02:33 $ * @version $Revision: 1.9 $ $Date: 2003/09/29 22:37:40 $
* *
* @author Rodney Waldhoff * @author Rodney Waldhoff
* @author Stephen Colebourne * @author Stephen Colebourne
*/ */
public class CollatingIterator implements Iterator { public class CollatingIterator implements Iterator {
/** My {@link Comparator}. */ /** The {@link Comparator} used to evaluate order. */
private Comparator comparator = null; private Comparator comparator = null;
/** My list of {@link Iterator}s. */ /** The list of {@link Iterator}s to evaluate. */
private ArrayList iterators = null; private ArrayList iterators = null;
/** {@link Iterator#next Next} objects peeked from each iterator. */ /** {@link Iterator#next Next} objects peeked from each iterator. */
@ -97,8 +98,7 @@ public class CollatingIterator implements Iterator {
private int lastReturned = -1; private int lastReturned = -1;
// Constructors // Constructors
// ------------------------------------------------------------------- // ----------------------------------------------------------------------
/** /**
* Constructs a new <code>CollatingIterator</code>. Natural sort order * Constructs a new <code>CollatingIterator</code>. Natural sort order
* will be used, and child iterators will have to be manually added * will be used, and child iterators will have to be manually added
@ -113,10 +113,9 @@ public class CollatingIterator implements Iterator {
* specified comparator for ordering. Child iterators will have to be * specified comparator for ordering. Child iterators will have to be
* manually added using the {@link #addIterator(Iterator)} method. * manually added using the {@link #addIterator(Iterator)} method.
* *
* @param comp the comparator to use for ordering, or <code>null</code> * @param comp the comparator to use to sort, or null to use natural sort order
* to use natural sort order
*/ */
public CollatingIterator(Comparator comp) { public CollatingIterator(final Comparator comp) {
this(comp,2); this(comp,2);
} }
@ -126,12 +125,11 @@ public class CollatingIterator implements Iterator {
* capacity. Child iterators will have to be * capacity. Child iterators will have to be
* manually added using the {@link #addIterator(Iterator)} method. * manually added using the {@link #addIterator(Iterator)} method.
* *
* @param comp the comparator to use for ordering, or <code>null</code> * @param comp the comparator to use to sort, or null to use natural sort order
* to use natural sort order
* @param initIterCapacity the initial capacity for the internal list * @param initIterCapacity the initial capacity for the internal list
* of child iterators * of child iterators
*/ */
public CollatingIterator(Comparator comp, int initIterCapacity) { public CollatingIterator(final Comparator comp, final int initIterCapacity) {
iterators = new ArrayList(initIterCapacity); iterators = new ArrayList(initIterCapacity);
setComparator(comp); setComparator(comp);
} }
@ -141,13 +139,12 @@ public class CollatingIterator implements Iterator {
* specified comparator to provide ordered iteration over the two * specified comparator to provide ordered iteration over the two
* given iterators. * given iterators.
* *
* @param comp the comparator to use to sort, or null to use natural * @param comp the comparator to use to sort, or null to use natural sort order
* sort order
* @param a the first child ordered iterator * @param a the first child ordered iterator
* @param b the second child ordered iterator * @param b the second child ordered iterator
* @throws NullPointerException if either iterator is null * @throws NullPointerException if either iterator is null
*/ */
public CollatingIterator(Comparator comp, Iterator a, Iterator b) { public CollatingIterator(final Comparator comp, final Iterator a, final Iterator b) {
this(comp,2); this(comp,2);
addIterator(a); addIterator(a);
addIterator(b); addIterator(b);
@ -158,12 +155,11 @@ public class CollatingIterator implements Iterator {
* specified comparator to provide ordered iteration over the array * specified comparator to provide ordered iteration over the array
* of iterators. * of iterators.
* *
* @param comp the comparator to use to sort, or null to use natural * @param comp the comparator to use to sort, or null to use natural sort order
* sort order
* @param iterators the array of iterators * @param iterators the array of iterators
* @throws NullPointerException if iterators array is or contains null * @throws NullPointerException if iterators array is or contains null
*/ */
public CollatingIterator(Comparator comp, Iterator[] iterators) { public CollatingIterator(final Comparator comp, final Iterator[] iterators) {
this(comp, iterators.length); this(comp, iterators.length);
for (int i = 0; i < iterators.length; i++) { for (int i = 0; i < iterators.length; i++) {
addIterator(iterators[i]); addIterator(iterators[i]);
@ -175,14 +171,13 @@ public class CollatingIterator implements Iterator {
* specified comparator to provide ordered iteration over the collection * specified comparator to provide ordered iteration over the collection
* of iterators. * of iterators.
* *
* @param comp the comparator to use to sort, or null to use natural * @param comp the comparator to use to sort, or null to use natural sort order
* sort order
* @param iterators the collection of iterators * @param iterators the collection of iterators
* @throws NullPointerException if the iterators collection is or contains null * @throws NullPointerException if the iterators collection is or contains null
* @throws ClassCastException if the iterators collection contains an * @throws ClassCastException if the iterators collection contains an
* element that's not an {@link Iterator} * element that's not an {@link Iterator}
*/ */
public CollatingIterator(Comparator comp, Collection iterators) { public CollatingIterator(final Comparator comp, final Collection iterators) {
this(comp, iterators.size()); this(comp, iterators.size());
for (Iterator it = iterators.iterator(); it.hasNext();) { for (Iterator it = iterators.iterator(); it.hasNext();) {
Iterator item = (Iterator) it.next(); Iterator item = (Iterator) it.next();
@ -191,14 +186,15 @@ public class CollatingIterator implements Iterator {
} }
// Public Methods // Public Methods
// ------------------------------------------------------------------- // ----------------------------------------------------------------------
/** /**
* Add the given {@link Iterator} to my collection to collate. * Adds the given {@link Iterator} to the iterators being collated.
* @throws IllegalStateException if I've already started iterating *
* @param iterator the iterator to add to the collation, must not be null
* @throws IllegalStateException if iteration has started
* @throws NullPointerException if the iterator is null * @throws NullPointerException if the iterator is null
*/ */
public void addIterator(Iterator iterator) { public void addIterator(final Iterator iterator) {
checkNotStarted(); checkNotStarted();
if (iterator == null) { if (iterator == null) {
throw new NullPointerException("Iterator must not be null"); throw new NullPointerException("Iterator must not be null");
@ -207,15 +203,15 @@ public class CollatingIterator implements Iterator {
} }
/** /**
* Set the Iterator at the given index * Sets the iterator at the given index.
* *
* @param index index of the Iterator to replace * @param index index of the Iterator to replace
* @param iterator Iterator to place at the given index * @param iterator Iterator to place at the given index
* @throws IndexOutOfBoundsException if index &lt; 0 or index &gt; size() * @throws IndexOutOfBoundsException if index &lt; 0 or index &gt; size()
* @throws IllegalStateException if I've already started iterating * @throws IllegalStateException if iteration has started
* @throws NullPointerException if the iterator is null * @throws NullPointerException if the iterator is null
*/ */
public void setIterator(int index, Iterator iterator) throws IndexOutOfBoundsException { public void setIterator(final int index, final Iterator iterator) {
checkNotStarted(); checkNotStarted();
if (iterator == null) { if (iterator == null) {
throw new NullPointerException("Iterator must not be null"); throw new NullPointerException("Iterator must not be null");
@ -224,7 +220,7 @@ public class CollatingIterator implements Iterator {
} }
/** /**
* Get the list of Iterators (unmodifiable) * Gets the list of Iterators (unmodifiable).
* *
* @return the unmodifiable list of iterators added * @return the unmodifiable list of iterators added
*/ */
@ -233,28 +229,28 @@ public class CollatingIterator implements Iterator {
} }
/** /**
* Set the {@link Comparator} by which I collate. * Gets the {@link Comparator} by which collatation occurs.
* @throws IllegalStateException if I've already started iterating
*/
public void setComparator(Comparator comp) {
checkNotStarted();
comparator = comp;
}
/**
* Get the {@link Comparator} by which I collate.
*/ */
public Comparator getComparator() { public Comparator getComparator() {
return comparator; return comparator;
} }
/**
* Sets the {@link Comparator} by which collation occurs.
*
* @throws IllegalStateException if iteration has started
*/
public void setComparator(final Comparator comp) {
checkNotStarted();
comparator = comp;
}
// Iterator Methods // Iterator Methods
// ------------------------------------------------------------------- // -------------------------------------------------------------------
/** /**
* Returns <code>true</code> if any child iterator has remaining elements. * Returns <code>true</code> if any child iterator has remaining elements.
* *
* @return true if this iterator has remaining elements * @return true if this iterator has remaining elements
*/ */
public boolean hasNext() { public boolean hasNext() {
start(); start();
@ -262,53 +258,51 @@ public class CollatingIterator implements Iterator {
} }
/** /**
* Returns the next ordered element from a child iterator. * Returns the next ordered element from a child iterator.
* *
* @return the next ordered element * @return the next ordered element
* @throws NoSuchElementException if no child iterator has any more * @throws NoSuchElementException if no child iterator has any more elements
* elements
*/ */
public Object next() throws NoSuchElementException { public Object next() throws NoSuchElementException {
if(!hasNext()) { if (hasNext() == false) {
throw new NoSuchElementException();
}
int leastIndex = least();
if (leastIndex == -1) {
throw new NoSuchElementException(); throw new NoSuchElementException();
} else { } else {
int leastIndex = least(); Object val = values.get(leastIndex);
if(leastIndex == -1) { clear(leastIndex);
throw new NoSuchElementException(); lastReturned = leastIndex;
} else { return val;
Object val = values.get(leastIndex);
clear(leastIndex);
lastReturned = leastIndex;
return val;
}
} }
} }
/** /**
* Removes the last returned element from the child iterator that * Removes the last returned element from the child iterator that
* produced it. * produced it.
* *
* @throws IllegalStateException if there is no last returned element, * @throws IllegalStateException if there is no last returned element,
* or if the last returned element has already been removed * or if the last returned element has already been removed
*/ */
public void remove() { public void remove() {
if(-1 == lastReturned) { if (lastReturned == -1) {
throw new IllegalStateException("No value can be removed at present"); throw new IllegalStateException("No value can be removed at present");
} else {
Iterator iter = (Iterator)(iterators.get(lastReturned));
iter.remove();
} }
Iterator it = (Iterator) (iterators.get(lastReturned));
it.remove();
} }
// Private Methods // Private Methods
// ------------------------------------------------------------------- // -------------------------------------------------------------------
/**
/** Initialize my collating state if it hasn't been already. */ * Initializes the collating state if it hasn't been already.
*/
private void start() { private void start() {
if(null == values) { if (values == null) {
values = new ArrayList(iterators.size()); values = new ArrayList(iterators.size());
valueSet = new BitSet(iterators.size()); valueSet = new BitSet(iterators.size());
for(int i=0;i<iterators.size();i++) { for (int i = 0; i < iterators.size(); i++) {
values.add(null); values.add(null);
valueSet.clear(i); valueSet.clear(i);
} }
@ -316,7 +310,7 @@ public class CollatingIterator implements Iterator {
} }
/** /**
* Set the {@link #values} and {@link #valueSet} attributes * Sets the {@link #values} and {@link #valueSet} attributes
* at position <i>i</i> to the next value of the * at position <i>i</i> to the next value of the
* {@link #iterators iterator} at position <i>i</i>, or * {@link #iterators iterator} at position <i>i</i>, or
* clear them if the <i>i</i><sup>th</sup> iterator * clear them if the <i>i</i><sup>th</sup> iterator
@ -325,9 +319,9 @@ public class CollatingIterator implements Iterator {
* @return <tt>false</tt> iff there was no value to set * @return <tt>false</tt> iff there was no value to set
*/ */
private boolean set(int i) { private boolean set(int i) {
Iterator iter = (Iterator)(iterators.get(i)); Iterator it = (Iterator)(iterators.get(i));
if(iter.hasNext()) { if (it.hasNext()) {
values.set(i,iter.next()); values.set(i, it.next());
valueSet.set(i); valueSet.set(i);
return true; return true;
} else { } else {
@ -338,7 +332,7 @@ public class CollatingIterator implements Iterator {
} }
/** /**
* Clear the {@link #values} and {@link #valueSet} attributes * Clears the {@link #values} and {@link #valueSet} attributes
* at position <i>i</i>. * at position <i>i</i>.
*/ */
private void clear(int i) { private void clear(int i) {
@ -347,11 +341,13 @@ public class CollatingIterator implements Iterator {
} }
/** /**
* Throw {@link IllegalStateException} iff I've been {@link #start started}. * Throws {@link IllegalStateException} if iteration has started
* @throws IllegalStateException iff I've been {@link #start started} * via {@link #start}.
*
* @throws IllegalStateException if iteration started
*/ */
private void checkNotStarted() throws IllegalStateException { private void checkNotStarted() throws IllegalStateException {
if (null != values) { if (values != null) {
throw new IllegalStateException("Can't do that after next or hasNext has been called."); throw new IllegalStateException("Can't do that after next or hasNext has been called.");
} }
} }
@ -359,21 +355,23 @@ public class CollatingIterator implements Iterator {
/** /**
* Returns the index of the least element in {@link #values}, * Returns the index of the least element in {@link #values},
* {@link #set(int) setting} any uninitialized values. * {@link #set(int) setting} any uninitialized values.
*
* @throws IllegalStateException
*/ */
private int least() throws IllegalStateException { private int least() {
int leastIndex = -1; int leastIndex = -1;
Object leastObject = null; Object leastObject = null;
for(int i=0;i<values.size();i++) { for (int i = 0; i < values.size(); i++) {
if(!valueSet.get(i)) { if (valueSet.get(i) == false) {
set(i); set(i);
} }
if(valueSet.get(i)) { if (valueSet.get(i)) {
if(leastIndex == -1) { if (leastIndex == -1) {
leastIndex = i; leastIndex = i;
leastObject = values.get(i); leastObject = values.get(i);
} else { } else {
Object curObject = values.get(i); Object curObject = values.get(i);
if(comparator.compare(curObject,leastObject) < 0) { if (comparator.compare(curObject,leastObject) < 0) {
leastObject = curObject; leastObject = curObject;
leastIndex = i; leastIndex = i;
} }
@ -388,8 +386,8 @@ public class CollatingIterator implements Iterator {
* <code>true</code>. * <code>true</code>.
*/ */
private boolean anyValueSet(BitSet set) { private boolean anyValueSet(BitSet set) {
for(int i=0;i<set.size();i++) { for (int i = 0; i < set.size(); i++) {
if(set.get(i)) { if (set.get(i)) {
return true; return true;
} }
} }
@ -401,9 +399,9 @@ public class CollatingIterator implements Iterator {
* in the given list has a next value. * in the given list has a next value.
*/ */
private boolean anyHasNext(ArrayList iters) { private boolean anyHasNext(ArrayList iters) {
for(int i=0;i<iters.size();i++) { for (int i = 0; i < iters.size(); i++) {
Iterator iter = (Iterator)iters.get(i); Iterator it = (Iterator) iters.get(i);
if(iter.hasNext()) { if (it.hasNext()) {
return true; return true;
} }
} }

80
src/java/org/apache/commons/collections/iterators/EnumerationIterator.java
View File

@ -1,5 +1,5 @@
/* /*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/EnumerationIterator.java,v 1.4 2003/09/29 22:02:33 scolebourne Exp $ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/EnumerationIterator.java,v 1.5 2003/09/29 22:37:40 scolebourne Exp $
* ==================================================================== * ====================================================================
* *
* The Apache Software License, Version 1.1 * The Apache Software License, Version 1.1
@ -66,68 +66,71 @@ import java.util.Iterator;
* to be {@link Iterator Iterator} instances. * to be {@link Iterator Iterator} instances.
* *
* @since Commons Collections 1.0 * @since Commons Collections 1.0
* @version $Revision: 1.4 $ $Date: 2003/09/29 22:02:33 $ * @version $Revision: 1.5 $ $Date: 2003/09/29 22:37:40 $
* *
* @author <a href="mailto:jstrachan@apache.org">James Strachan</a> * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
* @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a> * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
*/ */
public class EnumerationIterator implements Iterator { public class EnumerationIterator implements Iterator {
/** The collection to remove elements from */
private Collection collection; private Collection collection;
/** The enumeration being converted */
private Enumeration enumeration; private Enumeration enumeration;
/** The last object retrieved */
private Object last; private Object last;
// Constructors
//-----------------------------------------------------------------------
/** /**
* Constructs a new <code>EnumerationIterator</code> that will not * Constructs a new <code>EnumerationIterator</code> that will not
* function until {@link #setEnumeration(Enumeration)} is called. * function until {@link #setEnumeration(Enumeration)} is called.
*/ */
public EnumerationIterator() { public EnumerationIterator() {
this(null, null); this(null, null);
} }
/** /**
* Constructs a new <code>EnumerationIterator</code> that provides * Constructs a new <code>EnumerationIterator</code> that provides
* an iterator view of the given enumeration. * an iterator view of the given enumeration.
* *
* @param enumeration the enumeration to use * @param enumeration the enumeration to use
*/ */
public EnumerationIterator( Enumeration enumeration ) { public EnumerationIterator(final Enumeration enumeration) {
this(enumeration, null); this(enumeration, null);
} }
/** /**
* Constructs a new <code>EnumerationIterator</code> that will remove * Constructs a new <code>EnumerationIterator</code> that will remove
* elements from the specified collection. * elements from the specified collection.
* *
* @param enum the enumeration to use * @param enum the enumeration to use
* @param collection the collection to remove elements form * @param collection the collection to remove elements form
*/ */
public EnumerationIterator( Enumeration enum, Collection collection ) { public EnumerationIterator(final Enumeration enum, final Collection collection) {
super();
this.enumeration = enum; this.enumeration = enum;
this.collection = collection; this.collection = collection;
this.last = null; this.last = null;
} }
// Iterator interface // Iterator interface
//------------------------------------------------------------------------- //-----------------------------------------------------------------------
/** /**
* Returns true if the underlying enumeration has more elements. * Returns true if the underlying enumeration has more elements.
* *
* @return true if the underlying enumeration has more elements * @return true if the underlying enumeration has more elements
* @throws NullPointerException if the underlying enumeration is null * @throws NullPointerException if the underlying enumeration is null
*/ */
public boolean hasNext() { public boolean hasNext() {
return enumeration.hasMoreElements(); return enumeration.hasMoreElements();
} }
/** /**
* Returns the next object from the enumeration. * Returns the next object from the enumeration.
* *
* @return the next object from the enumeration * @return the next object from the enumeration
* @throws NullPointerException if the enumeration is null * @throws NullPointerException if the enumeration is null
*/ */
public Object next() { public Object next() {
last = enumeration.nextElement(); last = enumeration.nextElement();
@ -135,48 +138,45 @@ public class EnumerationIterator implements Iterator {
} }
/** /**
* Removes the last retrieved element if a collection is attached.
* <p>
* Functions if an associated <code>Collection</code> is known. * Functions if an associated <code>Collection</code> is known.
* If so, the first occurrence of the last returned object from this * If so, the first occurrence of the last returned object from this
* iterator will be removed from the collection. * iterator will be removed from the collection.
* *
* @exception IllegalStateException <code>next()</code> not called. * @exception IllegalStateException <code>next()</code> not called.
* @exception UnsupportedOperationException No associated * @exception UnsupportedOperationException if no associated collection
* <code>Collection</code>.
*/ */
public void remove() { public void remove() {
if (collection != null) { if (collection != null) {
if (last != null) { if (last != null) {
collection.remove(last); collection.remove(last);
} else {
throw new IllegalStateException("next() must have been called for remove() to function");
} }
else { } else {
throw new IllegalStateException throw new UnsupportedOperationException("No Collection associated with this Iterator");
("next() must have been called for remove() to function");
}
}
else {
throw new UnsupportedOperationException
("No Collection associated with this Iterator");
} }
} }
// Properties // Properties
//------------------------------------------------------------------------- //-----------------------------------------------------------------------
/** /**
* Returns the underlying enumeration. * Returns the underlying enumeration.
* *
* @return the underlying enumeration * @return the underlying enumeration
*/ */
public Enumeration getEnumeration() { public Enumeration getEnumeration() {
return enumeration; return enumeration;
} }
/** /**
* Sets the underlying enumeration. * Sets the underlying enumeration.
* *
* @param enumeration the new underlying enumeration * @param enumeration the new underlying enumeration
*/ */
public void setEnumeration( Enumeration enumeration ) { public void setEnumeration(final Enumeration enumeration) {
this.enumeration = enumeration; this.enumeration = enumeration;
} }
} }