1 /* 2 * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.util; 27 28 /** 29 * An iterator for lists that allows the programmer 30 * to traverse the list in either direction, modify 31 * the list during iteration, and obtain the iterator's 32 * current position in the list. A {@code ListIterator} 33 * has no current element; its <I>cursor position</I> always 34 * lies between the element that would be returned by a call 35 * to {@code previous()} and the element that would be 36 * returned by a call to {@code next()}. 37 * An iterator for a list of length {@code n} has {@code n+1} possible 38 * cursor positions, as illustrated by the carets ({@code ^}) below: 39 * <PRE> 40 * Element(0) Element(1) Element(2) ... Element(n-1) 41 * cursor positions: ^ ^ ^ ^ ^ 42 * </PRE> 43 * Note that the {@link #remove} and {@link #set(Object)} methods are 44 * <i>not</i> defined in terms of the cursor position; they are defined to 45 * operate on the last element returned by a call to {@link #next} or 46 * {@link #previous()}. 47 * 48 * <p>This interface is a member of the 49 * <a href="{@docRoot}/../technotes/guides/collections/index.html"> 50 * Java Collections Framework</a>. 51 * 52 * @author Josh Bloch 53 * @see Collection 54 * @see List 55 * @see Iterator 56 * @see Enumeration 57 * @see List#listIterator() 58 * @since 1.2 59 */ 60 public interface ListIterator<E> extends Iterator<E> { 61 // Query Operations 62 63 /** 64 * Returns {@code true} if this list iterator has more elements when 65 * traversing the list in the forward direction. (In other words, 66 * returns {@code true} if {@link #next} would return an element rather 67 * than throwing an exception.) 68 * 69 * @return {@code true} if the list iterator has more elements when 70 * traversing the list in the forward direction 71 */ hasNext()72 boolean hasNext(); 73 74 /** 75 * Returns the next element in the list and advances the cursor position. 76 * This method may be called repeatedly to iterate through the list, 77 * or intermixed with calls to {@link #previous} to go back and forth. 78 * (Note that alternating calls to {@code next} and {@code previous} 79 * will return the same element repeatedly.) 80 * 81 * @return the next element in the list 82 * @throws NoSuchElementException if the iteration has no next element 83 */ next()84 E next(); 85 86 /** 87 * Returns {@code true} if this list iterator has more elements when 88 * traversing the list in the reverse direction. (In other words, 89 * returns {@code true} if {@link #previous} would return an element 90 * rather than throwing an exception.) 91 * 92 * @return {@code true} if the list iterator has more elements when 93 * traversing the list in the reverse direction 94 */ hasPrevious()95 boolean hasPrevious(); 96 97 /** 98 * Returns the previous element in the list and moves the cursor 99 * position backwards. This method may be called repeatedly to 100 * iterate through the list backwards, or intermixed with calls to 101 * {@link #next} to go back and forth. (Note that alternating calls 102 * to {@code next} and {@code previous} will return the same 103 * element repeatedly.) 104 * 105 * @return the previous element in the list 106 * @throws NoSuchElementException if the iteration has no previous 107 * element 108 */ previous()109 E previous(); 110 111 /** 112 * Returns the index of the element that would be returned by a 113 * subsequent call to {@link #next}. (Returns list size if the list 114 * iterator is at the end of the list.) 115 * 116 * @return the index of the element that would be returned by a 117 * subsequent call to {@code next}, or list size if the list 118 * iterator is at the end of the list 119 */ nextIndex()120 int nextIndex(); 121 122 /** 123 * Returns the index of the element that would be returned by a 124 * subsequent call to {@link #previous}. (Returns -1 if the list 125 * iterator is at the beginning of the list.) 126 * 127 * @return the index of the element that would be returned by a 128 * subsequent call to {@code previous}, or -1 if the list 129 * iterator is at the beginning of the list 130 */ previousIndex()131 int previousIndex(); 132 133 134 // Modification Operations 135 136 /** 137 * Removes from the list the last element that was returned by {@link 138 * #next} or {@link #previous} (optional operation). This call can 139 * only be made once per call to {@code next} or {@code previous}. 140 * It can be made only if {@link #add} has not been 141 * called after the last call to {@code next} or {@code previous}. 142 * 143 * @throws UnsupportedOperationException if the {@code remove} 144 * operation is not supported by this list iterator 145 * @throws IllegalStateException if neither {@code next} nor 146 * {@code previous} have been called, or {@code remove} or 147 * {@code add} have been called after the last call to 148 * {@code next} or {@code previous} 149 */ remove()150 void remove(); 151 152 /** 153 * Replaces the last element returned by {@link #next} or 154 * {@link #previous} with the specified element (optional operation). 155 * This call can be made only if neither {@link #remove} nor {@link 156 * #add} have been called after the last call to {@code next} or 157 * {@code previous}. 158 * 159 * @param e the element with which to replace the last element returned by 160 * {@code next} or {@code previous} 161 * @throws UnsupportedOperationException if the {@code set} operation 162 * is not supported by this list iterator 163 * @throws ClassCastException if the class of the specified element 164 * prevents it from being added to this list 165 * @throws IllegalArgumentException if some aspect of the specified 166 * element prevents it from being added to this list 167 * @throws IllegalStateException if neither {@code next} nor 168 * {@code previous} have been called, or {@code remove} or 169 * {@code add} have been called after the last call to 170 * {@code next} or {@code previous} 171 */ set(E e)172 void set(E e); 173 174 /** 175 * Inserts the specified element into the list (optional operation). 176 * The element is inserted immediately before the element that 177 * would be returned by {@link #next}, if any, and after the element 178 * that would be returned by {@link #previous}, if any. (If the 179 * list contains no elements, the new element becomes the sole element 180 * on the list.) The new element is inserted before the implicit 181 * cursor: a subsequent call to {@code next} would be unaffected, and a 182 * subsequent call to {@code previous} would return the new element. 183 * (This call increases by one the value that would be returned by a 184 * call to {@code nextIndex} or {@code previousIndex}.) 185 * 186 * @param e the element to insert 187 * @throws UnsupportedOperationException if the {@code add} method is 188 * not supported by this list iterator 189 * @throws ClassCastException if the class of the specified element 190 * prevents it from being added to this list 191 * @throws IllegalArgumentException if some aspect of this element 192 * prevents it from being added to this list 193 */ add(E e)194 void add(E e); 195 } 196