KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > util > ListIterator


1 /*
2  * @(#)ListIterator.java 1.23 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.util;
9
10 /**
11  *
12  * An iterator for lists that allows the programmer
13  * to traverse the list in either direction, modify
14  * the list during iteration, and obtain the iterator's
15  * current position in the list. A <TT>ListIterator</TT>
16  * has no current element; its <I>cursor position</I> always
17  * lies between the element that would be returned by a call
18  * to <TT>previous()</TT> and the element that would be
19  * returned by a call to <TT>next()</TT>. In a list of
20  * length <TT>n</TT>, there are <TT>n+1</TT> valid
21  * index values, from <TT>0</TT> to <TT>n</TT>, inclusive.
22  * <PRE>
23  *
24  * Element(0) Element(1) Element(2) ... Element(n)
25  * ^ ^ ^ ^ ^
26  * Index: 0 1 2 3 n+1
27  *
28  * </PRE>
29  * <P>
30  * Note that the {@link #remove} and {@link #set(Object)} methods are
31  * <i>not</i> defined in terms of the cursor position; they are defined to
32  * operate on the last element returned by a call to {@link #next} or {@link
33  * #previous()}.
34  * <P>
35  * This interface is a member of the
36  * <a HREF="{@docRoot}/../guide/collections/index.html">
37  * Java Collections Framework</a>.
38  *
39  * @author Josh Bloch
40  * @version 1.23, 12/19/03
41  * @see Collection
42  * @see List
43  * @see Iterator
44  * @see Enumeration
45  * @since 1.2
46  */
47 public interface ListIterator<E> extends Iterator JavaDoc<E> {
48     // Query Operations
49
50     /**
51      * Returns <tt>true</tt> if this list iterator has more elements when
52      * traversing the list in the forward direction. (In other words, returns
53      * <tt>true</tt> if <tt>next</tt> would return an element rather than
54      * throwing an exception.)
55      *
56      * @return <tt>true</tt> if the list iterator has more elements when
57      * traversing the list in the forward direction.
58      */
59     boolean hasNext();
60
61     /**
62      * Returns the next element in the list. This method may be called
63      * repeatedly to iterate through the list, or intermixed with calls to
64      * <tt>previous</tt> to go back and forth. (Note that alternating calls
65      * to <tt>next</tt> and <tt>previous</tt> will return the same element
66      * repeatedly.)
67      *
68      * @return the next element in the list.
69      * @exception NoSuchElementException if the iteration has no next element.
70      */
71     E next();
72
73     /**
74      * Returns <tt>true</tt> if this list iterator has more elements when
75      * traversing the list in the reverse direction. (In other words, returns
76      * <tt>true</tt> if <tt>previous</tt> would return an element rather than
77      * throwing an exception.)
78      *
79      * @return <tt>true</tt> if the list iterator has more elements when
80      * traversing the list in the reverse direction.
81      */
82     boolean hasPrevious();
83
84     /**
85      * Returns the previous element in the list. This method may be called
86      * repeatedly to iterate through the list backwards, or intermixed with
87      * calls to <tt>next</tt> to go back and forth. (Note that alternating
88      * calls to <tt>next</tt> and <tt>previous</tt> will return the same
89      * element repeatedly.)
90      *
91      * @return the previous element in the list.
92      *
93      * @exception NoSuchElementException if the iteration has no previous
94      * element.
95      */
96     E previous();
97
98     /**
99      * Returns the index of the element that would be returned by a subsequent
100      * call to <tt>next</tt>. (Returns list size if the list iterator is at the
101      * end of the list.)
102      *
103      * @return the index of the element that would be returned by a subsequent
104      * call to <tt>next</tt>, or list size if list iterator is at end
105      * of list.
106      */
107     int nextIndex();
108
109     /**
110      * Returns the index of the element that would be returned by a subsequent
111      * call to <tt>previous</tt>. (Returns -1 if the list iterator is at the
112      * beginning of the list.)
113      *
114      * @return the index of the element that would be returned by a subsequent
115      * call to <tt>previous</tt>, or -1 if list iterator is at
116      * beginning of list.
117      */
118     int previousIndex();
119
120
121     // Modification Operations
122
123     /**
124      * Removes from the list the last element that was returned by
125      * <tt>next</tt> or <tt>previous</tt> (optional operation). This call can
126      * only be made once per call to <tt>next</tt> or <tt>previous</tt>. It
127      * can be made only if <tt>ListIterator.add</tt> has not been called after
128      * the last call to <tt>next</tt> or <tt>previous</tt>.
129      *
130      * @exception UnsupportedOperationException if the <tt>remove</tt>
131      * operation is not supported by this list iterator.
132      * @exception IllegalStateException neither <tt>next</tt> nor
133      * <tt>previous</tt> have been called, or <tt>remove</tt> or
134      * <tt>add</tt> have been called after the last call to *
135      * <tt>next</tt> or <tt>previous</tt>.
136      */
137     void remove();
138
139     /**
140      * Replaces the last element returned by <tt>next</tt> or
141      * <tt>previous</tt> with the specified element (optional operation).
142      * This call can be made only if neither <tt>ListIterator.remove</tt> nor
143      * <tt>ListIterator.add</tt> have been called after the last call to
144      * <tt>next</tt> or <tt>previous</tt>.
145      *
146      * @param o the element with which to replace the last element returned by
147      * <tt>next</tt> or <tt>previous</tt>.
148      * @exception UnsupportedOperationException if the <tt>set</tt> operation
149      * is not supported by this list iterator.
150      * @exception ClassCastException if the class of the specified element
151      * prevents it from being added to this list.
152      * @exception IllegalArgumentException if some aspect of the specified
153      * element prevents it from being added to this list.
154      * @exception IllegalStateException if neither <tt>next</tt> nor
155      * <tt>previous</tt> have been called, or <tt>remove</tt> or
156      * <tt>add</tt> have been called after the last call to
157      * <tt>next</tt> or <tt>previous</tt>.
158      */
159     void set(E o);
160
161     /**
162      * Inserts the specified element into the list (optional operation). The
163      * element is inserted immediately before the next element that would be
164      * returned by <tt>next</tt>, if any, and after the next element that
165      * would be returned by <tt>previous</tt>, if any. (If the list contains
166      * no elements, the new element becomes the sole element on the list.)
167      * The new element is inserted before the implicit cursor: a subsequent
168      * call to <tt>next</tt> would be unaffected, and a subsequent call to
169      * <tt>previous</tt> would return the new element. (This call increases
170      * by one the value that would be returned by a call to <tt>nextIndex</tt>
171      * or <tt>previousIndex</tt>.)
172      *
173      * @param o the element to insert.
174      * @exception UnsupportedOperationException if the <tt>add</tt> method is
175      * not supported by this list iterator.
176      *
177      * @exception ClassCastException if the class of the specified element
178      * prevents it from being added to this list.
179      *
180      * @exception IllegalArgumentException if some aspect of this element
181      * prevents it from being added to this list.
182      */
183     void add(E o);
184 }
185
Popular Tags