/*
 * 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 Iterator over any array. 
 The array can be either an array of object or of primitives. If you know that you have an object array, the ObjectArrayIterator class is a better choice, as it will perform better. 
 The iterator implements a reset method, allowing the reset of the iterator back to the start if required. 
Type parameters:
<E> – the type of elements returned by this iterator
Since:
1.0/**
 * 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 /** The array to iterate over */
    final Object array;
    
The start index to loop from /** The start index to loop from */
    final int startIndex;
    
The end index to loop to /** The end index to loop to */
    final int endIndex;
    
The current iterator index /** The current iterator index */
    int index = 0;

    // Constructors
    // ----------------------------------------------------------------------
    
Constructs an ArrayIterator that will iterate over the values in the
specified array.
Params:
array – the array to iterate over.
Throws:
IllegalArgumentException – if array is not an array.
NullPointerException – if array is null/**
     * 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</code> is not an array.
     * @throws NullPointerException if <code>array</code> is <code>null</code>
     */
    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.
Params:
array –  the array to iterate over.
startIndex –  the index to start iterating at.
Throws:
IllegalArgumentException – if array is not an array.
NullPointerException – if array is null
IndexOutOfBoundsException – if the index is invalid/**
     * 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</code> is not an array.
     * @throws NullPointerException if <code>array</code> is <code>null</code>
     * @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.
Params:
array –  the array to iterate over.
startIndex –  the index to start iterating at.
endIndex –  the index to finish iterating at.
Throws:
IllegalArgumentException – if array is not an array.
NullPointerException – if array is null
IndexOutOfBoundsException – if either index is invalid/**
     * 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</code> is not an array.
     * @throws NullPointerException if <code>array</code> is <code>null</code>
     * @throws IndexOutOfBoundsException if either index is invalid
     */
    public ArrayIterator(final Object array, final int startIndex, final int endIndex) {
        super();

        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.
Params:
bound –  the index to check
len –  the length of the array
type –  the index type (for error messages)
Throws:
IndexOutOfBoundsException – if the index is invalid/**
     * 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.
Returns:
true if there is a next element to return/**
     * 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.
Throws:
NoSuchElementException – if all the elements in the array
 have already been returned
Returns:
the next element in the array/**
     * 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 UnsupportedOperationException. 
Throws:
UnsupportedOperationException – always/**
     * 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.
Returns:
the array this iterator iterates over./**
     * 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.
Returns:
the start index
Since:
4.0/**
     * 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.
Returns:
the end index
Since:
4.0/**
     * 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.
/**
     * Resets the iterator back to the start index.
     */
    @Override
    public void reset() {
        this.index = this.startIndex;
    }

}