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