| Frames | No Frames |
1: /* ListIterator.java -- Extended Iterator for iterating over ordered lists 2: Copyright (C) 1998, 1999, 2001, 2004, 2005 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.util; 40: 41: /** 42: * An extended version of Iterator to support the extra features of Lists. The 43: * elements may be accessed in forward or reverse order, elements may be 44: * replaced as well as removed, and new elements may be inserted, during the 45: * traversal of the list. 46: * <p> 47: * 48: * A list with n elements provides n+1 iterator positions (the front, the end, 49: * or between two elements). Note that <code>remove</code> and <code>set</code> 50: * operate on the last element returned, whether it was by <code>next</code> 51: * or <code>previous</code>. 52: * 53: * @author Original author unknown 54: * @author Eric Blake (ebb9@email.byu.edu) 55: * @see Collection 56: * @see List 57: * @see Iterator 58: * @see Enumeration 59: * @since 1.2 60: * @status updated to 1.4 61: */ 62: public interface ListIterator<E> extends Iterator<E> 63: { 64: /** 65: * Tests whether there are elements remaining in the list in the forward 66: * direction. In other words, next() will not fail with a 67: * NoSuchElementException. 68: * 69: * @return true if the list continues in the forward direction 70: */ 71: boolean hasNext(); 72: 73: /** 74: * Tests whether there are elements remaining in the list in the reverse 75: * direction. In other words, previous() will not fail with a 76: * NoSuchElementException. 77: * 78: * @return true if the list continues in the reverse direction 79: */ 80: boolean hasPrevious(); 81: 82: /** 83: * Obtain the next element in the list in the forward direction. Repeated 84: * calls to next may be used to iterate over the entire list, or calls to 85: * next and previous may be used together to go forwards and backwards. 86: * Alternating calls to next and previous will return the same element. 87: * 88: * @return the next element in the list in the forward direction 89: * @throws NoSuchElementException if there are no more elements 90: */ 91: E next(); 92: 93: /** 94: * Obtain the next element in the list in the reverse direction. Repeated 95: * calls to previous may be used to iterate backwards over the entire list, 96: * or calls to next and previous may be used together to go forwards and 97: * backwards. Alternating calls to next and previous will return the same 98: * element. 99: * 100: * @return the next element in the list in the reverse direction 101: * @throws NoSuchElementException if there are no more elements 102: */ 103: E previous(); 104: 105: /** 106: * Find the index of the element that would be returned by a call to next. 107: * If hasNext() returns false, this returns the list size. 108: * 109: * @return the index of the element that would be returned by next() 110: */ 111: int nextIndex(); 112: 113: /** 114: * Find the index of the element that would be returned by a call to 115: * previous. If hasPrevious() returns false, this returns -1. 116: * 117: * @return the index of the element that would be returned by previous() 118: */ 119: int previousIndex(); 120: 121: /** 122: * Insert an element into the list at the current position of the iterator 123: * (optional operation). The element is inserted in between the element that 124: * would be returned by previous and the element that would be returned by 125: * next. After the insertion, a subsequent call to next is unaffected, but 126: * a call to previous returns the item that was added. The values returned 127: * by nextIndex() and previousIndex() are incremented. 128: * 129: * @param o the object to insert into the list 130: * @throws ClassCastException if the object is of a type which cannot be added 131: * to this list. 132: * @throws IllegalArgumentException if some other aspect of the object stops 133: * it being added to this list. 134: * @throws UnsupportedOperationException if this ListIterator does not 135: * support the add operation. 136: */ 137: void add(E o); 138: 139: /** 140: * Remove from the list the element last returned by a call to next or 141: * previous (optional operation). This method may only be called if neither 142: * add nor remove have been called since the last call to next or previous. 143: * 144: * @throws IllegalStateException if neither next or previous have been 145: * called, or if add or remove has been called since the last call 146: * to next or previous 147: * @throws UnsupportedOperationException if this ListIterator does not 148: * support the remove operation 149: */ 150: void remove(); 151: 152: /** 153: * Replace the element last returned by a call to next or previous with a 154: * given object (optional operation). This method may only be called if 155: * neither add nor remove have been called since the last call to next or 156: * previous. 157: * 158: * @param o the object to replace the element with 159: * @throws ClassCastException the object is of a type which cannot be added 160: * to this list 161: * @throws IllegalArgumentException some other aspect of the object stops 162: * it being added to this list 163: * @throws IllegalStateException if neither next or previous have been 164: * called, or if add or remove has been called since the last call 165: * to next or previous 166: * @throws UnsupportedOperationException if this ListIterator does not 167: * support the set operation 168: */ 169: void set(E o); 170: }