    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.collections4.iterators;
    018
    019import java.util.NoSuchElementException;
    020
    021import org.apache.commons.collections4.ResettableIterator;
    022
    023/**
    024 * An {@link java.util.Iterator Iterator} over an array of objects.
    025 * <p>
    026 * This iterator does not support {@link #remove}, as the object array cannot be
    027 * structurally modified.
    028 * <p>
    029 * The iterator implements a {@link #reset} method, allowing the reset of the iterator
    030 * back to the start if required.
    031 *
    032 * @param <E> the type of elements returned by this iterator
    033 * @since 3.0
    034 */
    035public class ObjectArrayIterator<E> implements ResettableIterator<E> {
    036
    037    /** The array */
    038    final E[] array;
    039    /** The start index to loop from */
    040    final int startIndex;
    041    /** The end index to loop to */
    042    final int endIndex;
    043    /** The current iterator index */
    044    int index = 0;
    045
    046    //-------------------------------------------------------------------------
    047    /**
    048     * Constructs an ObjectArrayIterator that will iterate over the values in the
    049     * specified array.
    050     *
    051     * @param array the array to iterate over
    052     * @throws NullPointerException if <code>array</code> is <code>null</code>
    053     */
    054    public ObjectArrayIterator(final E... array) {
    055        this(array, 0, array.length);
    056    }
    057
    058    /**
    059     * Constructs an ObjectArrayIterator that will iterate over the values in the
    060     * specified array from a specific start index.
    061     *
    062     * @param array  the array to iterate over
    063     * @param start  the index to start iterating at
    064     * @throws NullPointerException if <code>array</code> is <code>null</code>
    065     * @throws IndexOutOfBoundsException if the start index is out of bounds
    066     */
    067    public ObjectArrayIterator(final E array[], final int start) {
    068        this(array, start, array.length);
    069    }
    070
    071    /**
    072     * Construct an ObjectArrayIterator that will iterate over a range of values
    073     * in the specified array.
    074     *
    075     * @param array  the array to iterate over
    076     * @param start  the index to start iterating at
    077     * @param end  the index (exclusive) to finish iterating at
    078     * @throws IndexOutOfBoundsException if the start or end index is out of bounds
    079     * @throws IllegalArgumentException if end index is before the start
    080     * @throws NullPointerException if <code>array</code> is <code>null</code>
    081     */
    082    public ObjectArrayIterator(final E array[], final int start, final int end) {
    083        super();
    084        if (start < 0) {
    085            throw new ArrayIndexOutOfBoundsException("Start index must not be less than zero");
    086        }
    087        if (end > array.length) {
    088            throw new ArrayIndexOutOfBoundsException("End index must not be greater than the array length");
    089        }
    090        if (start > array.length) {
    091            throw new ArrayIndexOutOfBoundsException("Start index must not be greater than the array length");
    092        }
    093        if (end < start) {
    094            throw new IllegalArgumentException("End index must not be less than start index");
    095        }
    096        this.array = array;
    097        this.startIndex = start;
    098        this.endIndex = end;
    099        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}