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