ObjectArrayIterator


1   /*
2    *  Copyright 1999-2004 The Apache Software Foundation
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   */
16  package org.apache.commons.collections.iterators;
17  
18  import java.util.Iterator  ;
19  import java.util.NoSuchElementException  ;
20  
21  import org.apache.commons.collections.ResettableIterator;
22  
23  /** 
24   * An {@link 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   * @since Commons Collections 3.0
33   * @version $Revision: 1.12 $ $Date: 2004/02/18 00:59:50 $
34   * 
35   * @author James Strachan
36   * @author Mauricio S. Moura
37   * @author Michael A. Smith
38   * @author Neil O'Toole
39   * @author Stephen Colebourne
40   * @author Phil Steitz
41   */
42  public class ObjectArrayIterator
43          implements Iterator  , ResettableIterator {
44  
45      /** The array */
46      protected Object  [] array = null;
47      /** The start index to loop from */
48      protected int startIndex = 0;
49      /** The end index to loop to */
50      protected int endIndex = 0;
51      /** The current iterator index */
52      protected int index = 0;
53  
54      /**
55       * Constructor for use with <code>setArray</code>.
56       * <p>
57       * Using this constructor, the iterator is equivalent to an empty iterator
58       * until {@link #setArray} is  called to establish the array to iterate over.
59       */
60      public ObjectArrayIterator() {
61          super();
62      }
63  
64      /**
65       * Constructs an ObjectArrayIterator that will iterate over the values in the
66       * specified array.
67       *
68       * @param array the array to iterate over
69       * @throws NullPointerException if <code>array</code> is <code>null</code>
70       */
71      public ObjectArrayIterator(Object  [] array) {
72          this(array, 0, array.length);
73      }
74  
75      /**
76       * Constructs an ObjectArrayIterator that will iterate over the values in the
77       * specified array from a specific start index.
78       *
79       * @param array  the array to iterate over
80       * @param start  the index to start iterating at
81       * @throws NullPointerException if <code>array</code> is <code>null</code>
82       * @throws IndexOutOfBoundsException if the start index is out of bounds
83       */
84      public ObjectArrayIterator(Object   array[], int start) {
85          this(array, start, array.length);
86      }
87  
88      /**
89       * Construct an ObjectArrayIterator that will iterate over a range of values 
90       * in the specified array.
91       *
92       * @param array  the array to iterate over
93       * @param start  the index to start iterating at
94       * @param end  the index (exclusive) to finish iterating at
95       * @throws IndexOutOfBoundsException if the start or end index is out of bounds
96       * @throws IllegalArgumentException if end index is before the start
97       * @throws NullPointerException if <code>array</code> is <code>null</code>
98       */
99      public ObjectArrayIterator(Object   array[], int start, int end) {
100         super();
101         if (start < 0) {
102             throw new ArrayIndexOutOfBoundsException  ("Start index must not be less than zero");
103         }
104         if (end > array.length) {
105             throw new ArrayIndexOutOfBoundsException  ("End index must not be greater than the array length");
106         }
107         if (start > array.length) {
108             throw new ArrayIndexOutOfBoundsException  ("Start index must not be greater than the array length");
109         }
110         if (end < start) {
111             throw new IllegalArgumentException  ("End index must not be less than start index");
112         }
113         this.array = array;
114         this.startIndex = start;
115         this.endIndex = end;
116         this.index = start;
117     }
118 
119     // Iterator interface
120     //-------------------------------------------------------------------------
121 
122     /**
123      * Returns true if there are more elements to return from the array.
124      *
125      * @return true if there is a next element to return
126      */
127     public boolean hasNext() {
128         return (this.index < this.endIndex);
129     }
130 
131     /**
132      * Returns the next element in the array.
133      *
134      * @return the next element in the array
135      * @throws NoSuchElementException if all the elements in the array
136      *    have already been returned
137      */
138     public Object   next() {
139         if (hasNext() == false) {
140             throw new NoSuchElementException  ();
141         }
142         return this.array[this.index++];
143     }
144 
145     /**
146      * Throws {@link UnsupportedOperationException}.
147      *
148      * @throws UnsupportedOperationException always
149      */
150     public void remove() {
151         throw new UnsupportedOperationException  ("remove() method is not supported for an ObjectArrayIterator");
152     }
153 
154     // Properties
155     //-------------------------------------------------------------------------
156 
157     /**
158      * Gets the array that this iterator is iterating over. 
159      *
160      * @return the array this iterator iterates over, or <code>null</code> if
161      * the no-arg constructor was used and {@link #setArray} has never
162      * been called with a valid array.
163      */
164     public Object  [] getArray() {
165         return this.array;
166     }
167 
168     /**
169      * Sets the array that the ArrayIterator should iterate over.
170      * <p>
171      * This method may only be called once, otherwise an IllegalStateException
172      * will occur.
173      * <p>
174      * The {@link #reset} method can be used to reset the iterator if required.
175      *
176      * @param array  the array that the iterator should iterate over
177      * @throws IllegalStateException if the <code>array</code> was set in the constructor
178      * @throws NullPointerException if <code>array</code> is <code>null</code>
179      */
180     public void setArray(Object  [] array) {
181         if (this.array != null) {
182             throw new IllegalStateException  ("The array to iterate over has already been set");
183         }
184         this.array = array;
185         this.startIndex = 0;
186         this.endIndex = array.length;
187         this.index = 0;
188     }
189 
190     /**
191      * Gets the start index to loop from.
192      * 
193      * @return the start index
194      */
195     public int getStartIndex() {
196         return this.startIndex;
197     }
198 
199     /**
200      * Gets the end index to loop to.
201      * 
202      * @return the end index
203      */
204     public int getEndIndex() {
205         return this.endIndex;
206     }
207 
208     /**
209      * Resets the iterator back to the start index.
210      */
211     public void reset() {
212         this.index = this.startIndex;
213     }
214 
215 }
216
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags