1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections4.iterators;
18
19 import java.util.NoSuchElementException;
20
21 import org.apache.commons.collections4.ResettableIterator;
22
23 /**
24 * An {@link java.util.Iterator Iterator} over an array of objects.
25 * <p>
26 * This iterator does not support {@link #remove}, as the object array cannot be
27 * structurally modified.
28 * </p>
29 * <p>
30 * The iterator implements a {@link #reset} method, allowing the reset of the iterator
31 * back to the start if required.
32 * </p>
33 *
34 * @param <E> the type of elements returned by this iterator.
35 * @since 3.0
36 */
37 public class ObjectArrayIterator<E> implements ResettableIterator<E> {
38
39 /** The array */
40 final E[] array;
41 /** The start index to loop from */
42 final int startIndex;
43 /** The end index to loop to */
44 final int endIndex;
45 /** The current iterator index */
46 int index;
47
48 /**
49 * Constructs an ObjectArrayIterator that will iterate over the values in the
50 * specified array.
51 *
52 * @param array the array to iterate over
53 * @throws NullPointerException if {@code array} is {@code null}
54 */
55 public ObjectArrayIterator(final E... array) {
56 this(array, 0, array.length);
57 }
58
59 /**
60 * Constructs an ObjectArrayIterator that will iterate over the values in the
61 * specified array from a specific start index.
62 *
63 * @param array the array to iterate over
64 * @param start the index to start iterating at
65 * @throws NullPointerException if {@code array} is {@code null}
66 * @throws IndexOutOfBoundsException if the start index is out of bounds
67 */
68 public ObjectArrayIterator(final E[] array, final int start) {
69 this(array, start, array.length);
70 }
71
72 /**
73 * Constructs an ObjectArrayIterator that will iterate over a range of values
74 * in the specified array.
75 *
76 * @param array the array to iterate over
77 * @param start the index to start iterating at
78 * @param end the index (exclusive) to finish iterating at
79 * @throws IndexOutOfBoundsException if the start or end index is out of bounds
80 * @throws IllegalArgumentException if end index is before the start
81 * @throws NullPointerException if {@code array} is {@code null}
82 */
83 public ObjectArrayIterator(final E[] array, final int start, final int end) {
84 if (start < 0) {
85 throw new ArrayIndexOutOfBoundsException("Start index must not be less than zero");
86 }
87 if (end > array.length) {
88 throw new ArrayIndexOutOfBoundsException("End index must not be greater than the array length");
89 }
90 if (start > array.length) {
91 throw new ArrayIndexOutOfBoundsException("Start index must not be greater than the array length");
92 }
93 if (end < start) {
94 throw new IllegalArgumentException("End index must not be less than start index");
95 }
96 this.array = array;
97 startIndex = start;
98 endIndex = end;
99 index = start;
100 }
101
102 /**
103 * Gets the array that this iterator is iterating over.
104 *
105 * @return the array this iterator iterates over
106 */
107 public E[] getArray() {
108 return array;
109 }
110
111 /**
112 * Gets the end index to loop to.
113 *
114 * @return the end index
115 */
116 public int getEndIndex() {
117 return endIndex;
118 }
119
120 /**
121 * Gets the start index to loop from.
122 *
123 * @return the start index
124 */
125 public int getStartIndex() {
126 return startIndex;
127 }
128
129 /**
130 * Returns true if there are more elements to return from the array.
131 *
132 * @return true if there is a next element to return
133 */
134 @Override
135 public boolean hasNext() {
136 return index < endIndex;
137 }
138
139 /**
140 * Returns the next element in the array.
141 *
142 * @return the next element in the array
143 * @throws NoSuchElementException if all the elements in the array
144 * have already been returned
145 */
146 @Override
147 public E next() {
148 if (!hasNext()) {
149 throw new NoSuchElementException();
150 }
151 return array[index++];
152 }
153
154 /**
155 * Throws {@link UnsupportedOperationException}.
156 *
157 * @throws UnsupportedOperationException always
158 */
159 @Override
160 public void remove() {
161 throw new UnsupportedOperationException("remove() method is not supported for an ObjectArrayIterator");
162 }
163
164 /**
165 * Resets the iterator back to the start index.
166 */
167 @Override
168 public void reset() {
169 index = startIndex;
170 }
171
172 }