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