You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sc...@apache.org on 2002/12/13 13:01:36 UTC
cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections/iterators ArrayListIterator.java ObjectArrayListIterator.java ObjectArrayIterator.java ArrayIterator.java
scolebourne 2002/12/13 04:01:36
Modified: collections/src/java/org/apache/commons/collections/iterators
ArrayIterator.java
Added: collections/src/java/org/apache/commons/collections/iterators
ArrayListIterator.java ObjectArrayListIterator.java
ObjectArrayIterator.java
Log:
Rework array iterators to include Iterator and ListIterator implementations.
Also add Object array versions for better performance.
Revision Changes Path
1.2 +81 -67 jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ArrayIterator.java
Index: ArrayIterator.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ArrayIterator.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ArrayIterator.java 15 Aug 2002 23:13:51 -0000 1.1
+++ ArrayIterator.java 13 Dec 2002 12:01:35 -0000 1.2
@@ -63,100 +63,103 @@
import java.lang.reflect.Array;
import java.util.Iterator;
import java.util.NoSuchElementException;
-
-/** Implements an {@link Iterator} over an array of objects.
- *
- * @since 1.0
- * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
- * @author Mauricio S. Moura
- * @author <a href="mailto:mas@apache.org">Michael A. Smith</a>
- * @version $Revision$
- */
+/**
+ * Implements an {@link java.util.Iterator Iterator} over an array.
+ * <p>
+ * The array can be either an array of object or of primitives. If you know
+ * that you have an object array, the
+ * {@link org.apache.commons.collections.iterators.ObjectArrayIterator ObjectArrayIterator}
+ * class is a better choice, as it will perform better.
+ * <p>
+ * The iterator implements a {@link #reset} method, allowing the reset of the iterator
+ * back to the start if required.
+ *
+ * @since 1.0
+ * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
+ * @author Mauricio S. Moura
+ * @author <a href="mailto:mas@apache.org">Michael A. Smith</a>
+ * @author <a href="mailto:neilotoole@users.sourceforge.net">Neil O'Toole</a>
+ * @author Stephen Colebourne
+ * @version $Revision$
+ */
public class ArrayIterator implements Iterator {
-
- private Object array;
- private int length = 0;
- private int index = 0;
-
+
+ /** The array */
+ protected Object array;
+ /** The start index to loop from */
+ protected int startIndex = 0;
+ /** The end index to loop to */
+ protected int endIndex = 0;
+ /** The current iterator index */
+ protected int index = 0;
/**
- * Construct an ArrayIterator. Using this constructor, the iterator is
- * equivalent to an empty iterator until {@link #setArray(Object)} is
- * called to establish the array to iterate over.
- **/
+ * Constructor for use with <code>setArray</code>.
+ * <p>
+ * Using this constructor, the iterator is equivalent to an empty iterator
+ * until {@link #setArray(Object)} is called to establish the array to iterate over.
+ */
public ArrayIterator() {
}
/**
- * Construct an ArrayIterator that will iterate over the values in the
- * specified array.
- *
- * @param array the array to iterate over.
+ * Constructs an ArrayIterator that will iterate over the values in the
+ * specified array.
*
- * @exception IllegalArgumentException if <code>array</code> is not an
- * array.
- *
- * @exception NullPointerException
- * if <code>array</code> is <code>null</code>
- **/
+ * @param array the array to iterate over.
+ * @throws IllegalArgumentException if <code>array</code> is not an array.
+ * @throws NullPointerException if <code>array</code> is <code>null</code>
+ */
public ArrayIterator(Object array) {
setArray( array );
}
/**
- * Construct an ArrayIterator that will iterate over the values in the
- * specified array.
- *
- * @param array the array to iterate over.
- * @param start the index to start iterating at.
- *
- * @exception IllegalArgumentException if <code>array</code> is not an
- * array.
+ * Constructs an ArrayIterator that will iterate over the values in the
+ * specified array from a specific start index.
*
- * @exception NullPointerException
- * if <code>array</code> is <code>null</code>
- **/
+ * @param array the array to iterate over.
+ * @param start the index to start iterating at.
+ * @throws IllegalArgumentException if <code>array</code> is not an array.
+ * @throws NullPointerException if <code>array</code> is <code>null</code>
+ */
public ArrayIterator(Object array, int start) {
setArray( array );
checkBound(start, "start");
+ this.startIndex = start;
this.index = start;
}
/**
- * Construct an ArrayIterator that will iterate over the values in the
- * specified array.
- *
- * @param array the array to iterate over.
- * @param start the index to start iterating at.
- * @param end the index to finish iterating at.
- *
- * @exception IllegalArgumentException if <code>array</code> is not an
- * array.
+ * Construct an ArrayIterator that will iterate over a range of values
+ * in the specified array.
*
- * @exception NullPointerException
- * if <code>array</code> is <code>null</code>
- **/
+ * @param array the array to iterate over.
+ * @param start the index to start iterating at.
+ * @param end the index to finish iterating at.
+ * @throws IllegalArgumentException if <code>array</code> is not an array.
+ * @throws NullPointerException if <code>array</code> is <code>null</code>
+ */
public ArrayIterator(Object array, int start, int end) {
setArray( array );
checkBound(start, "start");
checkBound(end, "end");
- if(end <= start) {
- throw new IllegalArgumentException(
- "End index must be greater than start index. "
- );
+ if (end < start) {
+ throw new IllegalArgumentException("End index must not be less than start index.");
}
+ this.startIndex = start;
+ this.endIndex = end;
this.index = start;
- this.length = end;
}
- private void checkBound(int bound, String type ) {
- if(bound > this.length) {
+ protected void checkBound(int bound, String type ) {
+ if (bound > this.endIndex) {
throw new ArrayIndexOutOfBoundsException(
"Attempt to make an ArrayIterator that "+type+
"s beyond the end of the array. "
);
}
- if(bound < 0) {
+ if (bound < 0) {
throw new ArrayIndexOutOfBoundsException(
"Attempt to make an ArrayIterator that "+type+
"s before the start of the array. "
@@ -173,7 +176,7 @@
* @return true if there is a next element to return
*/
public boolean hasNext() {
- return index < length;
+ return (index < endIndex);
}
/**
@@ -184,7 +187,7 @@
* have already been returned
*/
public Object next() {
- if(!hasNext()) {
+ if (hasNext() == false) {
throw new NoSuchElementException();
}
return Array.get( array, index++ );
@@ -208,7 +211,7 @@
* @return the array this iterator iterates over, or <code>null</code> if
* the no-arg constructor was used and {@link #setArray(Object)} has never
* been called with a valid array.
- **/
+ */
public Object getArray() {
return array;
}
@@ -230,6 +233,8 @@
* Note: Using i.setArray(i.getArray()) may throw a NullPointerException
* if no array has ever been set for the iterator (see {@link
* #getArray()})
+ * <p>
+ * The {@link #reset()} method is a better choice for resetting the iterator.
*
* @param array the array that the iterator should iterate over.
*
@@ -238,15 +243,24 @@
*
* @exception NullPointerException
* if <code>array</code> is <code>null</code>
- **/
+ */
public void setArray( Object array ) {
// Array.getLength throws IllegalArgumentException if the object is not
// an array or NullPointerException if the object is null. This call
// 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
// an array or is null.
- this.length = Array.getLength( array );
+ this.endIndex = Array.getLength( array );
+ this.startIndex = 0;
this.array = array;
this.index = 0;
}
+
+ /**
+ * Resets the iterator back to the start index.
+ */
+ public void reset() {
+ this.index = this.startIndex;
+ }
+
}
1.1 jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ArrayListIterator.java
Index: ArrayListIterator.java
===================================================================
/*
* $Header: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ArrayListIterator.java,v 1.1 2002/12/13 12:01:35 scolebourne Exp $
* $Revision: 1.1 $
* $Date: 2002/12/13 12:01:35 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 1999-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
*/
package org.apache.commons.collections.iterators;
import java.lang.reflect.Array;
import java.util.ListIterator;
import java.util.NoSuchElementException;
/**
* Implements a {@link java.util.ListIterator ListIterator} over an array.
* <p>
* The array can be either an array of object or of primitives. If you know
* that you have an object array, the
* {@link org.apache.commons.collections.iterators.ObjectArrayListIterator ObjectArrayListIterator}
* class is a better choice, as it will perform better.
*
* <p>
* This iterator does not support {@link #add(Object)} or {@link #remove()}, as the array
* cannot be changed in size. The {@link #set(Object)} method is supported however.
*
* @see org.apache.commons.collections.iterators.ArrayIterator
* @see java.util.Iterator
* @see java.util.ListIterator
*
* @since 2.2
* @author <a href="mailto:neilotoole@users.sourceforge.net">Neil O'Toole</a>
* @author Stephen Colebourne
* @version $Revision: 1.1 $
*/
public class ArrayListIterator extends ArrayIterator implements ListIterator {
/**
* Holds the index of the last item returned by a call to <code>next()</code> or <code>previous()</code>. This
* is set to <code>-1</code> if neither method has yet been invoked. <code>lastItemIndex</code> is used to to
* implement the {@link #set} method.
*
*/
protected int lastItemIndex = -1;
/**
* Constructor for use with <code>setArray</code>.
* <p>
* Using this constructor, the iterator is equivalent to an empty iterator
* until {@link #setArray(Object)} is called to establish the array to iterate over.
*/
public ArrayListIterator() {
super();
}
/**
* Constructs an ArrayListIterator that will iterate over the values in the
* specified array.
*
* @param array the array to iterate over
* @throws IllegalArgumentException if <code>array</code> is not an array.
* @throws NullPointerException if <code>array</code> is <code>null</code>
*/
public ArrayListIterator(Object array) {
super(array);
}
/**
* Constructs an ArrayListIterator that will iterate over the values in the
* specified array from a specific start index.
*
* @param array the array to iterate over
* @param start the index to start iterating at
* @throws IllegalArgumentException if <code>array</code> is not an array.
* @throws NullPointerException if <code>array</code> is <code>null</code>
* @throws IndexOutOfBoundsException if the start index is out of bounds
*/
public ArrayListIterator(Object array, int start) {
super(array, start);
this.startIndex = start;
}
/**
* Construct an ArrayListIterator that will iterate over a range of values
* in the specified array.
*
* @param array the array to iterate over
* @param start the index to start iterating at
* @param end the index (exclusive) to finish iterating at
* @throws IllegalArgumentException if <code>array</code> is not an array.
* @throws IndexOutOfBoundsException if the start or end index is out of bounds
* @throws IllegalArgumentException if end index is before the start
* @throws NullPointerException if <code>array</code> is <code>null</code>
*/
public ArrayListIterator(Object array, int start, int end) {
super(array, start, end);
this.startIndex = start;
}
// ListIterator interface
//-------------------------------------------------------------------------
/**
* Returns true if there are previous elements to return from the array.
*
* @return true if there is a previous element to return
*/
public boolean hasPrevious() {
return (this.index > this.startIndex);
}
/**
* Gets the previous element from the array.
*
* @return the previous element
* @throws NoSuchElementException if there is no previous element
*/
public Object previous() {
if (hasPrevious() == false) {
throw new NoSuchElementException();
}
this.lastItemIndex = --this.index;
return Array.get(this.array, this.index);
}
/**
* Gets the next element from the array.
*
* @return the next element
* @throws NoSuchElementException if there is no next element
*/
public Object next() {
if (hasNext() == false) {
throw new NoSuchElementException();
}
this.lastItemIndex = this.index;
return Array.get(this.array, this.index++);
}
/**
* Gets the next index to be retrieved.
*
* @return the index of the item to be retrieved next
*/
public int nextIndex() {
return this.index;
}
/**
* Gets the index of the item to be retrieved if {@link #previous()} is called.
*
* @return the index of the item to be retrieved next
*/
public int previousIndex() {
return this.index - 1;
}
/**
* This iterator does not support modification of its backing collection, and so will
* always throw an {@link UnsupportedOperationException} when this method is invoked.
*
* @throws UnsupportedOperationException always thrown.
* @see java.util.ListIterator#set
*/
public void add(Object o) {
throw new UnsupportedOperationException("add() method is not supported");
}
/**
* Sets the element under the cursor.
* <p>
* This method sets the element that was returned by the last call
* to {@link #next()} of {@link #previous()}.
* <p>
* <b>Note:</b> {@link ListIterator} implementations that support
* <code>add()</code> and <code>remove()</code> only allow <code>set()</code> to be called
* once per call to <code>next()</code> or <code>previous</code> (see the {@link ListIterator}
* javadoc for more details). Since this implementation does
* not support <code>add()</code> or <code>remove()</code>, <code>set()</code> may be
* called as often as desired.
*
* @see java.util.ListIterator#set
*/
public void set(Object o) {
if (this.lastItemIndex == -1) {
throw new IllegalStateException("must call next() or previous() before a call to set()");
}
Array.set(this.array, this.lastItemIndex, o);
}
/**
* Resets the iterator back to the start index.
*/
public void reset() {
super.reset();
this.lastItemIndex = -1;
}
}
1.1 jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ObjectArrayListIterator.java
Index: ObjectArrayListIterator.java
===================================================================
/*
* $Header: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ObjectArrayListIterator.java,v 1.1 2002/12/13 12:01:35 scolebourne Exp $
* $Revision: 1.1 $
* $Date: 2002/12/13 12:01:35 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 1999-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
*/
package org.apache.commons.collections.iterators;
import java.util.ListIterator;
import java.util.NoSuchElementException;
/**
* Implements a {@link java.util.ListIterator ListIterator} over an array of objects.
* <p>
* This iterator does not support {@link #add(Object)} or {@link #remove()}, as the object array
* cannot be changed in size. The {@link #set(Object)} method is supported however.
* <p>
* The iterator implements a {@link #reset()} method, allowing the reset of the iterator
* back to the start if required.
*
* @see org.apache.commons.collections.iterators.ObjectArrayIterator
* @see java.util.Iterator
* @see java.util.ListIterator
*
* @since 2.2
* @author <a href="mailto:neilotoole@users.sourceforge.net">Neil O'Toole</a>
* @author Stephen Colebourne
* @version $Revision: 1.1 $
*/
public class ObjectArrayListIterator extends ObjectArrayIterator implements ListIterator {
/**
* Holds the index of the last item returned by a call to <code>next()</code>
* or <code>previous()</code>. This is set to <code>-1</code> if neither method
* has yet been invoked. <code>lastItemIndex</code> is used to to implement the
* {@link #set} method.
*/
protected int lastItemIndex = -1;
/**
* Constructor for use with <code>setArray</code>.
* <p>
* Using this constructor, the iterator is equivalent to an empty iterator
* until {@link #setArray(Object)} is called to establish the array to iterate over.
*/
public ObjectArrayListIterator() {
super();
}
/**
* Constructs an ObjectArrayListIterator that will iterate over the values in the
* specified array.
*
* @param array the array to iterate over
* @throws NullPointerException if <code>array</code> is <code>null</code>
*/
public ObjectArrayListIterator(Object[] array) {
super(array);
}
/**
* Constructs an ObjectArrayListIterator that will iterate over the values in the
* specified array from a specific start index.
*
* @param array the array to iterate over
* @param start the index to start iterating at
* @throws NullPointerException if <code>array</code> is <code>null</code>
* @throws IndexOutOfBoundsException if the start index is out of bounds
*/
public ObjectArrayListIterator(Object[] array, int start) {
super(array, start);
}
/**
* Construct an ObjectArrayListIterator that will iterate over a range of values
* in the specified array.
*
* @param array the array to iterate over
* @param start the index to start iterating at
* @param end the index (exclusive) to finish iterating at
* @throws IndexOutOfBoundsException if the start or end index is out of bounds
* @throws IllegalArgumentException if end index is before the start
* @throws NullPointerException if <code>array</code> is <code>null</code>
*/
public ObjectArrayListIterator(Object[] array, int start, int end) {
super(array, start, end);
}
// ListIterator interface
//-------------------------------------------------------------------------
/**
* Returns true if there are previous elements to return from the array.
*
* @return true if there is a previous element to return
*/
public boolean hasPrevious() {
return (this.index > this.startIndex);
}
/**
* Gets the previous element from the array.
*
* @return the previous element
* @throws NoSuchElementException if there is no previous element
*/
public Object previous() {
if (hasPrevious() == false) {
throw new NoSuchElementException();
}
this.lastItemIndex = --this.index;
return this.array[this.index];
}
/**
* Gets the next element from the array.
*
* @return the next element
* @throws NoSuchElementException if there is no next element
*/
public Object next() {
if (hasNext() == false) {
throw new NoSuchElementException();
}
this.lastItemIndex = this.index;
return this.array[this.index++];
}
/**
* Gets the next index to be retrieved.
*
* @return the index of the item to be retrieved next
*/
public int nextIndex() {
return this.index;
}
/**
* Gets the index of the item to be retrieved if {@link #previous()} is called.
*
* @return the index of the item to be retrieved next
*/
public int previousIndex() {
return this.index - 1;
}
/**
* This iterator does not support modification of its backing array's size, and so will
* always throw an {@link UnsupportedOperationException} when this method is invoked.
*
* @param obj the object to add
* @throws UnsupportedOperationException always thrown.
*/
public void add(Object obj) {
throw new UnsupportedOperationException("add() method is not supported");
}
/**
* Sets the element under the cursor.
* <p>
* This method sets the element that was returned by the last call
* to {@link #next()} of {@link #previous()}.
*
* <b>Note:</b> {@link ListIterator} implementations that support <code>add()</code>
* and <code>remove()</code> only allow <code>set()</code> to be called once per call
* to <code>next()</code> or <code>previous</code> (see the {@link ListIterator}
* javadoc for more details). Since this implementation does not support
* <code>add()</code> or <code>remove()</code>, <code>set()</code> may be
* called as often as desired.
*
* @param obj the object to set into the array
* @throws IllegalStateException if next() has not yet been called.
* @throws ClassCastException if the object type is unsuitable for the array
*/
public void set(Object obj) {
if (this.lastItemIndex == -1) {
throw new IllegalStateException("must call next() or previous() before a call to set()");
}
this.array[this.lastItemIndex] = obj;
}
/**
* Resets the iterator back to the start index.
*/
public void reset() {
super.reset();
this.lastItemIndex = -1;
}
}
1.1 jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ObjectArrayIterator.java
Index: ObjectArrayIterator.java
===================================================================
/*
* $Header: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ObjectArrayIterator.java,v 1.1 2002/12/13 12:01:35 scolebourne Exp $
* $Revision: 1.1 $
* $Date: 2002/12/13 12:01:35 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 1999-2002 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
*/
package org.apache.commons.collections.iterators;
import java.util.Iterator;
import java.util.NoSuchElementException;
/**
* Implements an {@link java.util.Iterator Iterator} over an array of objects.
* <p>
* This iterator does not support {@link #remove}, as the object array cannot be
* changed in size.
* <p>
* The iterator implements a {@link #reset} method, allowing the reset of the iterator
* back to the start if required.
*
* @since 2.2
* @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
* @author Mauricio S. Moura
* @author <a href="mailto:mas@apache.org">Michael A. Smith</a>
* @author <a href="mailto:neilotoole@users.sourceforge.net">Neil O'Toole</a>
* @author Stephen Colebourne
* @version $Revision: 1.1 $
*/
public class ObjectArrayIterator implements Iterator {
/** The array */
protected Object[] array = null;
/** The start index to loop from */
protected int startIndex = 0;
/** The end index to loop to */
protected int endIndex = 0;
/** The current iterator index */
protected int index = 0;
/**
* Constructor for use with <code>setArray</code>.
* <p>
* Using this constructor, the iterator is equivalent to an empty iterator
* until {@link #setArray(Object)} is called to establish the array to iterate over.
*/
public ObjectArrayIterator() {
super();
}
/**
* Constructs an ObjectArrayIterator that will iterate over the values in the
* specified array.
*
* @param array the array to iterate over
* @throws NullPointerException if <code>array</code> is <code>null</code>
*/
public ObjectArrayIterator(Object[] array) {
this(array, 0, array.length);
}
/**
* Constructs an ObjectArrayIterator that will iterate over the values in the
* specified array from a specific start index.
*
* @param array the array to iterate over
* @param start the index to start iterating at
* @throws NullPointerException if <code>array</code> is <code>null</code>
* @throws IndexOutOfBoundsException if the start index is out of bounds
*/
public ObjectArrayIterator(Object array[], int start) {
this(array, start, array.length);
}
/**
* Construct an ObjectArrayIterator that will iterate over a range of values
* in the specified array.
*
* @param array the array to iterate over
* @param start the index to start iterating at
* @param end the index (exclusive) to finish iterating at
* @throws IndexOutOfBoundsException if the start or end index is out of bounds
* @throws IllegalArgumentException if end index is before the start
* @throws NullPointerException if <code>array</code> is <code>null</code>
*/
public ObjectArrayIterator(Object array[], int start, int end) {
super();
if (start < 0) {
throw new ArrayIndexOutOfBoundsException("Start index must not be less than zero");
}
if (end > array.length) {
throw new ArrayIndexOutOfBoundsException("End index must not be greater than the array length");
}
if (end < start) {
throw new IllegalArgumentException("End index must not be less than start index");
}
this.array = array;
this.startIndex = start;
this.endIndex = end;
this.index = start;
}
// Iterator interface
//-------------------------------------------------------------------------
/**
* Returns true if there are more elements to return from the array.
*
* @return true if there is a next element to return
*/
public boolean hasNext() {
return (this.index < this.endIndex);
}
/**
* Returns the next element in the array.
*
* @return the next element in the array
* @throws NoSuchElementException if all the elements in the array
* have already been returned
*/
public Object next() {
if (hasNext() == false) {
throw new NoSuchElementException();
}
return this.array[this.index++];
}
/**
* Throws {@link UnsupportedOperationException}.
*
* @throws UnsupportedOperationException always
*/
public void remove() {
throw new UnsupportedOperationException("remove() method is not supported for an ObjectArrayIterator");
}
// Properties
//-------------------------------------------------------------------------
/**
* Gets the array that this iterator is iterating over.
*
* @return the array this iterator iterates over, or <code>null</code> if
* the no-arg constructor was used and {@link #setArray(Object)} has never
* been called with a valid array.
*/
public Object[] getArray() {
return this.array;
}
/**
* Sets the array that the ArrayIterator should iterate over.
* <p>
* This method may only be called once, otherwise an IllegalStateException
* will occur.
* <p>
* The {@link #reset} method can be used to reset the iterator if required.
*
* @param array the array that the iterator should iterate over
* @throws IllegalStateException if the <code>array</code> was set in the constructor
* @throws NullPointerException if <code>array</code> is <code>null</code>
*/
public void setArray(Object[] array) {
if (this.array != null) {
throw new IllegalStateException("The array to iterate over has already been set");
}
this.array = array;
this.startIndex = 0;
this.endIndex = array.length;
this.index = 0;
}
/**
* Gets the start index to loop from.
*
* @return the start index
*/
public int getStartIndex() {
return this.startIndex;
}
/**
* Gets the end index to loop to.
*
* @return the end index
*/
public int getEndIndex() {
return this.endIndex;
}
/**
* Resets the iterator back to the start index.
*/
public void reset() {
this.index = this.startIndex;
}
}
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>