1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package net.sf.collections15.iterators;
17
18 import java.util.NoSuchElementException;
19
20 import net.sf.collections15.ResettableIterator;
21
22 /***
23 * Implements an {@link java.util.Iterator Iterator} over any array.
24 * <p>
25 * The array can be either an array of object or of primitives. If you know
26 * that you have an object array, the
27 * {@link net.sf.collections15.iterators.ObjectArrayIterator
28 * ObjectArrayIterator} class is a better choice, as it will perform better.
29 * <p>
30 * The iterator implements a {@link #reset} method, allowing the reset of
31 * the iterator back to the start if required.
32 *
33 * @since Commons Collections 1.0
34 * @version $Revision: 1.1 $ $Date: 2005/02/27 08:04:09 $
35 *
36 * @author James Strachan
37 * @author Mauricio S. Moura
38 * @author Michael A. Smith
39 * @author Neil O'Toole
40 * @author Stephen Colebourne
41 * @author Mauro Franceschini (port to 5.0)
42 */
43 public class ArrayIterator<E> implements ResettableIterator<E> {
44
45
46
47
48 /***
49 * The array to iterate over.
50 */
51 protected E[] array;
52
53 /***
54 * The start index to loop from.
55 */
56 protected int startIndex = 0;
57
58 /***
59 * The end index to loop to.
60 */
61 protected int endIndex = 0;
62
63 /***
64 * The current iterator index.
65 */
66 protected int index = 0;
67
68
69
70
71 /***
72 * Constructor for use with <code>setArray</code>.
73 * <p>
74 * Using this constructor, the iterator is equivalent to an empty iterator
75 * until {@link #setArray(E)} is called to establish the array to iterate
76 * over.
77 */
78 public ArrayIterator() {
79 super();
80 }
81
82 /***
83 * Constructs an <code>ArrayIterator</code> that will iterate over the
84 * values in the specified array.
85 *
86 * @param array the array to iterate over.
87 * @throws IllegalArgumentException if <code>array</code> is not an array.
88 * @throws NullPointerException if <code>array</code> is <code>null</code>
89 */
90 public ArrayIterator(final E[] array) {
91 super();
92 setArray(array);
93 }
94
95 /***
96 * Constructs an <code>ArrayIterator</code> that will iterate over the
97 * values in the specified array from a specific start index.
98 *
99 * @param array the array to iterate over.
100 * @param startIndex the index to start iterating at.
101 * @throws IllegalArgumentException if <code>array</code> is not an array.
102 * @throws NullPointerException if <code>array</code> is <code>null</code>
103 * @throws IndexOutOfBoundsException if the index is invalid
104 */
105 public ArrayIterator(final E[] array, final int startIndex) {
106 super();
107 setArray(array);
108 checkBound(startIndex, "start");
109 this.startIndex = startIndex;
110 this.index = startIndex;
111 }
112
113 /***
114 * Construct an <code>ArrayIterator</code> that will iterate over a range of
115 * values in the specified array.
116 *
117 * @param array the array to iterate over.
118 * @param startIndex the index to start iterating at.
119 * @param endIndex the index to finish iterating at.
120 * @throws IllegalArgumentException if <code>array</code> is not an array.
121 * @throws NullPointerException if <code>array</code> is <code>null</code>
122 * @throws IndexOutOfBoundsException if either index is invalid
123 */
124 public ArrayIterator(final E[] array, final int startIndex,
125 final int endIndex) {
126 super();
127 setArray(array);
128 checkBound(startIndex, "start");
129 checkBound(endIndex, "end");
130 if (endIndex < startIndex) {
131 throw new IllegalArgumentException("End index must not be less " +
132 "than start index.");
133 }
134 this.startIndex = startIndex;
135 this.endIndex = endIndex;
136 this.index = startIndex;
137 }
138
139
140
141
142 /***
143 * Checks whether the index is valid or not.
144 *
145 * @param bound the index to check
146 * @param type the index type (for error messages)
147 * @throws IndexOutOfBoundsException if the index is invalid
148 */
149 protected void checkBound(final int bound, final String type ) {
150 if (bound > this.endIndex) {
151 throw new ArrayIndexOutOfBoundsException(
152 "Attempt to make an ArrayIterator that " + type +
153 "s beyond the end of the array. "
154 );
155 }
156 if (bound < 0) {
157 throw new ArrayIndexOutOfBoundsException(
158 "Attempt to make an ArrayIterator that " + type +
159 "s before the start of the array. "
160 );
161 }
162 }
163
164
165
166
167 /***
168 * Returns true if there are more elements to return from the array.
169 *
170 * @return true if there is a next element to return
171 */
172 public boolean hasNext() {
173 return (index < endIndex);
174 }
175
176 /***
177 * Returns the next element in the array.
178 *
179 * @return the next element in the array
180 * @throws NoSuchElementException if all the elements in the array
181 * have already been returned
182 */
183 public E next() {
184 if (hasNext() == false) {
185 throw new NoSuchElementException();
186 }
187 return array[index++];
188 }
189
190 /***
191 * Throws {@link UnsupportedOperationException}.
192 *
193 * @throws UnsupportedOperationException always
194 */
195 public void remove() {
196 throw new UnsupportedOperationException("remove() method is not " +
197 "supported");
198 }
199
200
201
202 /***
203 * Gets the array that this iterator is iterating over.
204 *
205 * @return the array this iterator iterates over, or <code>null</code> if
206 * the no-arg constructor was used and {@link #setArray(Object)} has never
207 * been called with a valid array.
208 */
209 public E[] getArray() {
210 return array;
211 }
212
213 /***
214 * Sets the array that the ArrayIterator should iterate over.
215 * <p>
216 * If an array has previously been set (using the single-arg constructor
217 * or this method) then that array is discarded in favour of this one.
218 * Iteration is restarted at the start of the new array.
219 * Although this can be used to reset iteration, the {@link #reset()} method
220 * is a more effective choice.
221 *
222 * @param array the array that the iterator should iterate over.
223 * @throws IllegalArgumentException if <code>array</code> is not an array.
224 * @throws NullPointerException if <code>array</code> is <code>null</code>
225 */
226 public void setArray(final E[] array) {
227
228
229
230
231
232 this.endIndex = array.length;
233 this.startIndex = 0;
234 this.array = array;
235 this.index = 0;
236 }
237
238
239
240
241 /***
242 * Resets the iterator back to the start index.
243 */
244 public void reset() {
245 this.index = this.startIndex;
246 }
247
248 }