1 /* 2 * Copyright (c) 1997, 2022, 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}/java.base/java/util/package-summary.html#CollectionsFramework"> 50 * Java Collections Framework</a>. 51 * 52 * @param <E> the type of elements returned by this list iterator 53 * 54 * @author Josh Bloch 55 * @see Collection 56 * @see List 57 * @see Iterator 58 * @see Enumeration 59 * @see List#listIterator() 60 * @since 1.2 61 */ 62 public interface ListIterator<E> extends Iterator<E> { 63 // Query Operations 64 65 /** 66 * Returns {@code true} if this list iterator has more elements when 67 * traversing the list in the forward direction. (In other words, 68 * returns {@code true} if {@link #next} would return an element rather 69 * than throwing an exception.) 70 * 71 * @return {@code true} if the list iterator has more elements when 72 * traversing the list in the forward direction 73 */ hasNext()74 boolean hasNext(); 75 76 /** 77 * Returns the next element in the list and advances the cursor position. 78 * This method may be called repeatedly to iterate through the list, 79 * or intermixed with calls to {@link #previous} to go back and forth. 80 * (Note that alternating calls to {@code next} and {@code previous} 81 * will return the same element repeatedly.) 82 * 83 * @return the next element in the list 84 * @throws NoSuchElementException if the iteration has no next element 85 */ next()86 E next(); 87 88 /** 89 * Returns {@code true} if this list iterator has more elements when 90 * traversing the list in the reverse direction. (In other words, 91 * returns {@code true} if {@link #previous} would return an element 92 * rather than throwing an exception.) 93 * 94 * @return {@code true} if the list iterator has more elements when 95 * traversing the list in the reverse direction 96 */ hasPrevious()97 boolean hasPrevious(); 98 99 /** 100 * Returns the previous element in the list and moves the cursor 101 * position backwards. This method may be called repeatedly to 102 * iterate through the list backwards, or intermixed with calls to 103 * {@link #next} to go back and forth. (Note that alternating calls 104 * to {@code next} and {@code previous} will return the same 105 * element repeatedly.) 106 * 107 * @return the previous element in the list 108 * @throws NoSuchElementException if the iteration has no previous 109 * element 110 */ previous()111 E previous(); 112 113 /** 114 * Returns the index of the element that would be returned by a 115 * subsequent call to {@link #next}. (Returns list size if the list 116 * iterator is at the end of the list.) 117 * 118 * @return the index of the element that would be returned by a 119 * subsequent call to {@code next}, or list size if the list 120 * iterator is at the end of the list 121 */ nextIndex()122 int nextIndex(); 123 124 /** 125 * Returns the index of the element that would be returned by a 126 * subsequent call to {@link #previous}. (Returns -1 if the list 127 * iterator is at the beginning of the list.) 128 * 129 * @return the index of the element that would be returned by a 130 * subsequent call to {@code previous}, or -1 if the list 131 * iterator is at the beginning of the list 132 */ previousIndex()133 int previousIndex(); 134 135 136 // Modification Operations 137 138 /** 139 * Removes from the list the last element that was returned by {@link 140 * #next} or {@link #previous} (optional operation). This call can 141 * only be made once per call to {@code next} or {@code previous}. 142 * It can be made only if {@link #add} has not been 143 * called after the last call to {@code next} or {@code previous}. 144 * 145 * @throws UnsupportedOperationException if the {@code remove} 146 * operation is not supported by this list iterator 147 * @throws IllegalStateException if neither {@code next} nor 148 * {@code previous} have been called, or {@code remove} or 149 * {@code add} have been called after the last call to 150 * {@code next} or {@code previous} 151 */ remove()152 void remove(); 153 154 /** 155 * Replaces the last element returned by {@link #next} or 156 * {@link #previous} with the specified element (optional operation). 157 * This call can be made only if neither {@link #remove} nor {@link 158 * #add} have been called after the last call to {@code next} or 159 * {@code previous}. 160 * 161 * @param e the element with which to replace the last element returned by 162 * {@code next} or {@code previous} 163 * @throws UnsupportedOperationException if the {@code set} operation 164 * is not supported by this list iterator 165 * @throws ClassCastException if the class of the specified element 166 * prevents it from being added to this list 167 * @throws IllegalArgumentException if some aspect of the specified 168 * element prevents it from being added to this list 169 * @throws IllegalStateException if neither {@code next} nor 170 * {@code previous} have been called, or {@code remove} or 171 * {@code add} have been called after the last call to 172 * {@code next} or {@code previous} 173 */ set(E e)174 void set(E e); 175 176 /** 177 * Inserts the specified element into the list (optional operation). 178 * The element is inserted immediately before the element that 179 * would be returned by {@link #next}, if any, and after the element 180 * that would be returned by {@link #previous}, if any. (If the 181 * list contains no elements, the new element becomes the sole element 182 * on the list.) The new element is inserted before the implicit 183 * cursor: a subsequent call to {@code next} would be unaffected, and a 184 * subsequent call to {@code previous} would return the new element. 185 * (This call increases by one the value that would be returned by a 186 * call to {@code nextIndex} or {@code previousIndex}.) 187 * 188 * @param e the element to insert 189 * @throws UnsupportedOperationException if the {@code add} method is 190 * not supported by this list iterator 191 * @throws ClassCastException if the class of the specified element 192 * prevents it from being added to this list 193 * @throws IllegalArgumentException if some aspect of this element 194 * prevents it from being added to this list 195 */ add(E e)196 void add(E e); 197 } 198