KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > iterators > ArrayIterator


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.collections.iterators;
17
18 import java.lang.reflect.Array JavaDoc;
19 import java.util.NoSuchElementException JavaDoc;
20
21 import org.apache.commons.collections.ResettableIterator;
22
23 /**
24  * Implements an {@link java.util.Iterator Iterator} over any array.
25  * <p>
26  * The array can be either an array of object or of primitives. If you know
27  * that you have an object array, the
28  * {@link org.apache.commons.collections.iterators.ObjectArrayIterator ObjectArrayIterator}
29  * class is a better choice, as it will perform better.
30  * <p>
31  * The iterator implements a {@link #reset} method, allowing the reset of
32  * the iterator back to the start if required.
33  *
34  * @since Commons Collections 1.0
35  * @version $Revision: 1.11 $ $Date: 2004/02/18 00:59:50 $
36  *
37  * @author James Strachan
38  * @author Mauricio S. Moura
39  * @author Michael A. Smith
40  * @author Neil O'Toole
41  * @author Stephen Colebourne
42  */
43 public class ArrayIterator implements ResettableIterator {
44
45     /** The array to iterate over */
46     protected Object JavaDoc array;
47     /** The start index to loop from */
48     protected int startIndex = 0;
49     /** The end index to loop to */
50     protected int endIndex = 0;
51     /** The current iterator index */
52     protected int index = 0;
53     
54     // Constructors
55 // ----------------------------------------------------------------------
56 /**
57      * Constructor for use with <code>setArray</code>.
58      * <p>
59      * Using this constructor, the iterator is equivalent to an empty iterator
60      * until {@link #setArray(Object)} is called to establish the array to iterate over.
61      */
62     public ArrayIterator() {
63         super();
64     }
65    
66     /**
67      * Constructs an ArrayIterator that will iterate over the values in the
68      * specified array.
69      *
70      * @param array the array to iterate over.
71      * @throws IllegalArgumentException if <code>array</code> is not an array.
72      * @throws NullPointerException if <code>array</code> is <code>null</code>
73      */
74     public ArrayIterator(final Object JavaDoc array) {
75         super();
76         setArray(array);
77     }
78
79     /**
80      * Constructs an ArrayIterator that will iterate over the values in the
81      * specified array from a specific start index.
82      *
83      * @param array the array to iterate over.
84      * @param startIndex the index to start iterating at.
85      * @throws IllegalArgumentException if <code>array</code> is not an array.
86      * @throws NullPointerException if <code>array</code> is <code>null</code>
87      * @throws IndexOutOfBoundsException if the index is invalid
88      */
89     public ArrayIterator(final Object JavaDoc array, final int startIndex) {
90         super();
91         setArray(array);
92         checkBound(startIndex, "start");
93         this.startIndex = startIndex;
94         this.index = startIndex;
95     }
96
97     /**
98      * Construct an ArrayIterator that will iterate over a range of values
99      * in the specified array.
100      *
101      * @param array the array to iterate over.
102      * @param startIndex the index to start iterating at.
103      * @param endIndex the index to finish iterating at.
104      * @throws IllegalArgumentException if <code>array</code> is not an array.
105      * @throws NullPointerException if <code>array</code> is <code>null</code>
106      * @throws IndexOutOfBoundsException if either index is invalid
107      */
108     public ArrayIterator(final Object JavaDoc array, final int startIndex, final int endIndex) {
109         super();
110         setArray(array);
111         checkBound(startIndex, "start");
112         checkBound(endIndex, "end");
113         if (endIndex < startIndex) {
114             throw new IllegalArgumentException JavaDoc("End index must not be less than start index.");
115         }
116         this.startIndex = startIndex;
117         this.endIndex = endIndex;
118         this.index = startIndex;
119     }
120
121     /**
122      * Checks whether the index is valid or not.
123      *
124      * @param bound the index to check
125      * @param type the index type (for error messages)
126      * @throws IndexOutOfBoundsException if the index is invalid
127      */
128     protected void checkBound(final int bound, final String JavaDoc type ) {
129         if (bound > this.endIndex) {
130             throw new ArrayIndexOutOfBoundsException JavaDoc(
131               "Attempt to make an ArrayIterator that " + type +
132               "s beyond the end of the array. "
133             );
134         }
135         if (bound < 0) {
136             throw new ArrayIndexOutOfBoundsException JavaDoc(
137               "Attempt to make an ArrayIterator that " + type +
138               "s before the start of the array. "
139             );
140         }
141     }
142
143     // Iterator interface
144 //-----------------------------------------------------------------------
145 /**
146      * Returns true if there are more elements to return from the array.
147      *
148      * @return true if there is a next element to return
149      */
150     public boolean hasNext() {
151         return (index < endIndex);
152     }
153
154     /**
155      * Returns the next element in the array.
156      *
157      * @return the next element in the array
158      * @throws NoSuchElementException if all the elements in the array
159      * have already been returned
160      */
161     public Object JavaDoc next() {
162         if (hasNext() == false) {
163             throw new NoSuchElementException JavaDoc();
164         }
165         return Array.get(array, index++);
166     }
167
168     /**
169      * Throws {@link UnsupportedOperationException}.
170      *
171      * @throws UnsupportedOperationException always
172      */
173     public void remove() {
174         throw new UnsupportedOperationException JavaDoc("remove() method is not supported");
175     }
176
177     // Properties
178 //-----------------------------------------------------------------------
179 /**
180      * Gets the array that this iterator is iterating over.
181      *
182      * @return the array this iterator iterates over, or <code>null</code> if
183      * the no-arg constructor was used and {@link #setArray(Object)} has never
184      * been called with a valid array.
185      */
186     public Object JavaDoc getArray() {
187         return array;
188     }
189     
190     /**
191      * Sets the array that the ArrayIterator should iterate over.
192      * <p>
193      * If an array has previously been set (using the single-arg constructor
194      * or this method) then that array is discarded in favour of this one.
195      * Iteration is restarted at the start of the new array.
196      * Although this can be used to reset iteration, the {@link #reset()} method
197      * is a more effective choice.
198      *
199      * @param array the array that the iterator should iterate over.
200      * @throws IllegalArgumentException if <code>array</code> is not an array.
201      * @throws NullPointerException if <code>array</code> is <code>null</code>
202      */
203     public void setArray(final Object JavaDoc array) {
204         // Array.getLength throws IllegalArgumentException if the object is not
205 // an array or NullPointerException if the object is null. This call
206 // is made before saving the array and resetting the index so that the
207 // array iterator remains in a consistent state if the argument is not
208 // an array or is null.
209 this.endIndex = Array.getLength(array);
210         this.startIndex = 0;
211         this.array = array;
212         this.index = 0;
213     }
214     
215     /**
216      * Resets the iterator back to the start index.
217      */
218     public void reset() {
219         this.index = this.startIndex;
220     }
221
222 }
223
Popular Tags