libjava/java/util/ListIterator.java

   1 /* ListIterator.java -- Extended Iterator for iterating over ordered lists
   2    Copyright (C) 1998, 1999, 2001, 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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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 extends Iterator
  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   Object 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   Object 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(Object 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(Object o);
 170 }