View Javadoc
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 }