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 * https://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.Iterator;
20 import java.util.NoSuchElementException;
21
22 import org.apache.commons.collections4.ResettableIterator;
23
24 /**
25 * An {@link Iterator Iterator} over an array of objects.
26 * <p>
27 * This iterator does not support {@link #remove}, as the object array cannot be
28 * structurally modified.
29 * </p>
30 * <p>
31 * The iterator implements a {@link #reset} method, allowing the reset of the iterator
32 * back to the start if required.
33 * </p>
34 *
35 * @param <E> The type of elements returned by this iterator.
36 * @since 3.0
37 */
38 public class ObjectArrayIterator<E> implements ResettableIterator<E> {
39
40 /** The array */
41 final E[] array;
42
43 /** The start index to loop from */
44 final int startIndex;
45
46 /** The end index to loop to */
47 final int endIndex;
48
49 /** The current iterator index */
50 int index;
51
52 /**
53 * Constructs an ObjectArrayIterator that will iterate over the values in the
54 * specified array.
55 *
56 * @param array The array to iterate over
57 * @throws NullPointerException if {@code array} is {@code null}
58 */
59 public ObjectArrayIterator(final E... array) {
60 this(array, 0, array.length);
61 }
62
63 /**
64 * Constructs an ObjectArrayIterator that will iterate over the values in the
65 * specified array from a specific start index.
66 *
67 * @param array The array to iterate over
68 * @param start The index to start iterating at
69 * @throws NullPointerException if {@code array} is {@code null}
70 * @throws IndexOutOfBoundsException if the start index is out of bounds
71 */
72 public ObjectArrayIterator(final E[] array, final int start) {
73 this(array, start, array.length);
74 }
75
76 /**
77 * Constructs an ObjectArrayIterator that will iterate over a range of values
78 * in the specified array.
79 *
80 * @param array The array to iterate over
81 * @param start The index to start iterating at
82 * @param end The index (exclusive) to finish iterating at
83 * @throws IndexOutOfBoundsException if the start or end index is out of bounds
84 * @throws IllegalArgumentException if end index is before the start
85 * @throws NullPointerException if {@code array} is {@code null}
86 */
87 public ObjectArrayIterator(final E[] array, final int start, final int end) {
88 if (start < 0) {
89 throw new ArrayIndexOutOfBoundsException("Start index must not be less than zero");
90 }
91 if (end > array.length) {
92 throw new ArrayIndexOutOfBoundsException("End index must not be greater than the array length");
93 }
94 if (start > array.length) {
95 throw new ArrayIndexOutOfBoundsException("Start index must not be greater than the array length");
96 }
97 if (end < start) {
98 throw new IllegalArgumentException("End index must not be less than start index");
99 }
100 this.array = array;
101 startIndex = start;
102 endIndex = end;
103 index = start;
104 }
105
106 /**
107 * Gets the array that this iterator is iterating over.
108 *
109 * @return The array this iterator iterates over
110 */
111 public E[] getArray() {
112 return array;
113 }
114
115 /**
116 * Gets the end index to loop to.
117 *
118 * @return The end index
119 */
120 public int getEndIndex() {
121 return endIndex;
122 }
123
124 /**
125 * Gets the start index to loop from.
126 *
127 * @return The start index
128 */
129 public int getStartIndex() {
130 return startIndex;
131 }
132
133 /**
134 * Returns true if there are more elements to return from the array.
135 *
136 * @return true if there is a next element to return
137 */
138 @Override
139 public boolean hasNext() {
140 return index < endIndex;
141 }
142
143 /**
144 * Returns the next element in the array.
145 *
146 * @return The next element in the array
147 * @throws NoSuchElementException if all the elements in the array
148 * have already been returned
149 */
150 @Override
151 public E next() {
152 if (!hasNext()) {
153 throw new NoSuchElementException();
154 }
155 return array[index++];
156 }
157
158 /**
159 * Always throws {@link UnsupportedOperationException}.
160 *
161 * @throws UnsupportedOperationException Always thrown.
162 */
163 @Override
164 public void remove() {
165 throw new UnsupportedOperationException("remove() method is not supported for an ObjectArrayIterator");
166 }
167
168 /**
169 * Resets the iterator back to the start index.
170 */
171 @Override
172 public void reset() {
173 index = startIndex;
174 }
175
176 }