| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.commons.collections4.iterators; |
| |
| import java.lang.reflect.Array; |
| import java.util.NoSuchElementException; |
| |
| import org.apache.commons.collections4.ResettableIterator; |
| |
| /** |
| * Implements an {@link java.util.Iterator Iterator} over any array. |
| * <p> |
| * The array can be either an array of object or of primitives. If you know |
| * that you have an object array, the |
| * {@link org.apache.commons.collections4.iterators.ObjectArrayIterator ObjectArrayIterator} |
| * class is a better choice, as it will perform better. |
| * <p> |
| * The iterator implements a {@link #reset} method, allowing the reset of |
| * the iterator back to the start if required. |
| * |
| * @param <E> the type of elements returned by this iterator. |
| * @since 1.0 |
| */ |
| public class ArrayIterator<E> implements ResettableIterator<E> { |
| |
| /** The array to iterate over */ |
| final Object array; |
| /** The start index to loop from */ |
| final int startIndex; |
| /** The end index to loop to */ |
| final int endIndex; |
| /** The current iterator index */ |
| int index; |
| |
| // Constructors |
| // ---------------------------------------------------------------------- |
| /** |
| * Constructs an ArrayIterator that will iterate over the values in the |
| * specified array. |
| * |
| * @param array the array to iterate over. |
| * @throws IllegalArgumentException if {@code array} is not an array. |
| * @throws NullPointerException if {@code array} is {@code null} |
| */ |
| public ArrayIterator(final Object array) { |
| this(array, 0); |
| } |
| |
| /** |
| * Constructs an ArrayIterator that will iterate over the values in the |
| * specified array from a specific start index. |
| * |
| * @param array the array to iterate over. |
| * @param startIndex the index to start iterating at. |
| * @throws IllegalArgumentException if {@code array} is not an array. |
| * @throws NullPointerException if {@code array} is {@code null} |
| * @throws IndexOutOfBoundsException if the index is invalid |
| */ |
| public ArrayIterator(final Object array, final int startIndex) { |
| this(array, startIndex, Array.getLength(array)); |
| } |
| |
| /** |
| * Construct an ArrayIterator that will iterate over a range of values |
| * in the specified array. |
| * |
| * @param array the array to iterate over. |
| * @param startIndex the index to start iterating at. |
| * @param endIndex the index to finish iterating at. |
| * @throws IllegalArgumentException if {@code array} is not an array. |
| * @throws NullPointerException if {@code array} is {@code null} |
| * @throws IndexOutOfBoundsException if either index is invalid |
| */ |
| public ArrayIterator(final Object array, final int startIndex, final int endIndex) { |
| this.array = array; |
| this.startIndex = startIndex; |
| this.endIndex = endIndex; |
| this.index = startIndex; |
| |
| final int len = Array.getLength(array); |
| checkBound(startIndex, len, "start"); |
| checkBound(endIndex, len, "end"); |
| if (endIndex < startIndex) { |
| throw new IllegalArgumentException("End index must not be less than start index."); |
| } |
| } |
| |
| /** |
| * Checks whether the index is valid or not. |
| * |
| * @param bound the index to check |
| * @param len the length of the array |
| * @param type the index type (for error messages) |
| * @throws IndexOutOfBoundsException if the index is invalid |
| */ |
| protected void checkBound(final int bound, final int len, final String type ) { |
| if (bound > len) { |
| throw new ArrayIndexOutOfBoundsException( |
| "Attempt to make an ArrayIterator that " + type + |
| "s beyond the end of the array. " |
| ); |
| } |
| if (bound < 0) { |
| throw new ArrayIndexOutOfBoundsException( |
| "Attempt to make an ArrayIterator that " + type + |
| "s before the start of the array. " |
| ); |
| } |
| } |
| |
| // Iterator interface |
| //----------------------------------------------------------------------- |
| /** |
| * Returns true if there are more elements to return from the array. |
| * |
| * @return true if there is a next element to return |
| */ |
| @Override |
| public boolean hasNext() { |
| return index < endIndex; |
| } |
| |
| /** |
| * Returns the next element in the array. |
| * |
| * @return the next element in the array |
| * @throws NoSuchElementException if all the elements in the array |
| * have already been returned |
| */ |
| @Override |
| @SuppressWarnings("unchecked") |
| public E next() { |
| if (hasNext() == false) { |
| throw new NoSuchElementException(); |
| } |
| return (E) Array.get(array, index++); |
| } |
| |
| /** |
| * Throws {@link UnsupportedOperationException}. |
| * |
| * @throws UnsupportedOperationException always |
| */ |
| @Override |
| public void remove() { |
| throw new UnsupportedOperationException("remove() method is not supported"); |
| } |
| |
| // Properties |
| //----------------------------------------------------------------------- |
| /** |
| * Gets the array that this iterator is iterating over. |
| * |
| * @return the array this iterator iterates over. |
| */ |
| public Object getArray() { |
| return array; |
| } |
| |
| /** |
| * Gets the start index to loop from. |
| * |
| * @return the start index |
| * @since 4.0 |
| */ |
| public int getStartIndex() { |
| return this.startIndex; |
| } |
| |
| /** |
| * Gets the end index to loop to. |
| * |
| * @return the end index |
| * @since 4.0 |
| */ |
| public int getEndIndex() { |
| return this.endIndex; |
| } |
| |
| /** |
| * Resets the iterator back to the start index. |
| */ |
| @Override |
| public void reset() { |
| this.index = this.startIndex; |
| } |
| |
| } |