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<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