Source for java.util.ListIterator

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