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 = 0; 45 46 //------------------------------------------------------------------------- 47 /** 48 * Constructs an ObjectArrayIterator that will iterate over the values in the 49 * specified array. 50 * 51 * @param array the array to iterate over 52 * @throws NullPointerException if <code>array</code> is <code>null</code> 53 */ 54 public ObjectArrayIterator(final E... array) { 55 this(array, 0, array.length); 56 } 57 58 /** 59 * Constructs an ObjectArrayIterator that will iterate over the values in the 60 * specified array from a specific start index. 61 * 62 * @param array the array to iterate over 63 * @param start the index to start iterating at 64 * @throws NullPointerException if <code>array</code> is <code>null</code> 65 * @throws IndexOutOfBoundsException if the start index is out of bounds 66 */ 67 public ObjectArrayIterator(final E array[], final int start) { 68 this(array, start, array.length); 69 } 70 71 /** 72 * Construct an ObjectArrayIterator that will iterate over a range of values 73 * in the specified array. 74 * 75 * @param array the array to iterate over 76 * @param start the index to start iterating at 77 * @param end the index (exclusive) to finish iterating at 78 * @throws IndexOutOfBoundsException if the start or end index is out of bounds 79 * @throws IllegalArgumentException if end index is before the start 80 * @throws NullPointerException if <code>array</code> is <code>null</code> 81 */ 82 public ObjectArrayIterator(final E array[], final int start, final int end) { 83 super(); 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 this.startIndex = start; 98 this.endIndex = end; 99 this.index = start; 100 } 101 102 // Iterator interface 103 //------------------------------------------------------------------------- 104 105 /** 106 * Returns true if there are more elements to return from the array. 107 * 108 * @return true if there is a next element to return 109 */ 110 @Override 111 public boolean hasNext() { 112 return this.index < this.endIndex; 113 } 114 115 /** 116 * Returns the next element in the array. 117 * 118 * @return the next element in the array 119 * @throws NoSuchElementException if all the elements in the array 120 * have already been returned 121 */ 122 @Override 123 public E next() { 124 if (hasNext() == false) { 125 throw new NoSuchElementException(); 126 } 127 return this.array[this.index++]; 128 } 129 130 /** 131 * Throws {@link UnsupportedOperationException}. 132 * 133 * @throws UnsupportedOperationException always 134 */ 135 @Override 136 public void remove() { 137 throw new UnsupportedOperationException("remove() method is not supported for an ObjectArrayIterator"); 138 } 139 140 // Properties 141 //------------------------------------------------------------------------- 142 143 /** 144 * Gets the array that this iterator is iterating over. 145 * 146 * @return the array this iterator iterates over 147 */ 148 public E[] getArray() { 149 return this.array; 150 } 151 152 /** 153 * Gets the start index to loop from. 154 * 155 * @return the start index 156 */ 157 public int getStartIndex() { 158 return this.startIndex; 159 } 160 161 /** 162 * Gets the end index to loop to. 163 * 164 * @return the end index 165 */ 166 public int getEndIndex() { 167 return this.endIndex; 168 } 169 170 /** 171 * Resets the iterator back to the start index. 172 */ 173 @Override 174 public void reset() { 175 this.index = this.startIndex; 176 } 177 178 }