1. /*

  2.  * @(#)ListIterator.java	1.23 03/12/19

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.util;

  9. 

  10. /**

  11.  * 

  12.  * An iterator for lists that allows the programmer 

  13.  * to traverse the list in either direction, modify 

  14.  * the list during iteration, and obtain the iterator's 

  15.  * current position in the list. A <TT>ListIterator</TT> 

  16.  * has no current element; its <I>cursor position</I> always 

  17.  * lies between the element that would be returned by a call 

  18.  * to <TT>previous()</TT> and the element that would be 

  19.  * returned by a call to <TT>next()</TT>. In a list of 

  20.  * length <TT>n</TT>, there are <TT>n+1</TT> valid 

  21.  * index values, from <TT>0</TT> to <TT>n</TT>, inclusive. 

  22.  * <PRE>

  23.  *

  24.  *          Element(0)   Element(1)   Element(2)   ... Element(n)   

  25.  *        ^            ^            ^            ^               ^

  26.  * Index: 0            1            2            3               n+1

  27.  *

  28.  * </PRE>

  29.  * <P>

  30.  * Note that the {@link #remove} and {@link #set(Object)} methods are

  31.  * <i>not</i> defined in terms of the cursor position;  they are defined to

  32.  * operate on the last element returned by a call to {@link #next} or {@link

  33.  * #previous()}.

  34.  * <P>

  35.  * This interface is a member of the 

  36.  * <a href="{@docRoot}/../guide/collections/index.html">

  37.  * Java Collections Framework</a>.

  38.  *

  39.  * @author  Josh Bloch

  40.  * @version 1.23, 12/19/03

  41.  * @see Collection

  42.  * @see List

  43.  * @see Iterator

  44.  * @see Enumeration

  45.  * @since   1.2

  46.  */

  47. public interface ListIterator<E> extends Iterator<E> {

  48.     // Query Operations

  49. 

  50.     /**

  51.      * Returns <tt>true</tt> if this list iterator has more elements when

  52.      * traversing the list in the forward direction. (In other words, returns

  53.      * <tt>true</tt> if <tt>next</tt> would return an element rather than

  54.      * throwing an exception.)

  55.      *

  56.      * @return <tt>true</tt> if the list iterator has more elements when

  57.      *		traversing the list in the forward direction.

  58.      */

  59.     boolean hasNext();

  60. 

  61.     /**

  62.      * Returns the next element in the list.  This method may be called

  63.      * repeatedly to iterate through the list, or intermixed with calls to

  64.      * <tt>previous</tt> to go back and forth.  (Note that alternating calls

  65.      * to <tt>next</tt> and <tt>previous</tt> will return the same element

  66.      * repeatedly.)

  67.      *

  68.      * @return the next element in the list.

  69.      * @exception NoSuchElementException if the iteration has no next element.

  70.      */

  71.     E next();

  72. 

  73.     /**

  74.      * Returns <tt>true</tt> if this list iterator has more elements when

  75.      * traversing the list in the reverse direction.  (In other words, returns

  76.      * <tt>true</tt> if <tt>previous</tt> would return an element rather than

  77.      * throwing an exception.)

  78.      *

  79.      * @return <tt>true</tt> if the list iterator has more elements when

  80.      *	       traversing the list in the reverse direction.

  81.      */

  82.     boolean hasPrevious();

  83. 

  84.     /**

  85.      * Returns the previous element in the list.  This method may be called

  86.      * repeatedly to iterate through the list backwards, or intermixed with

  87.      * calls to <tt>next</tt> to go back and forth.  (Note that alternating

  88.      * calls to <tt>next</tt> and <tt>previous</tt> will return the same

  89.      * element repeatedly.)

  90.      *

  91.      * @return the previous element in the list.

  92.      * 

  93.      * @exception NoSuchElementException if the iteration has no previous

  94.      *            element.

  95.      */

  96.     E previous();

  97. 

  98.     /**

  99.      * Returns the index of the element that would be returned by a subsequent

  100.      * call to <tt>next</tt>. (Returns list size if the list iterator is at the

  101.      * end of the list.)

  102.      *

  103.      * @return the index of the element that would be returned by a subsequent

  104.      * 	       call to <tt>next</tt>, or list size if list iterator is at end

  105.      *	       of list. 

  106.      */

  107.     int nextIndex();

  108. 

  109.     /**

  110.      * Returns the index of the element that would be returned by a subsequent

  111.      * call to <tt>previous</tt>. (Returns -1 if the list iterator is at the

  112.      * beginning of the list.)

  113.      *

  114.      * @return the index of the element that would be returned by a subsequent

  115.      * 	       call to <tt>previous</tt>, or -1 if list iterator is at

  116.      *	       beginning of list.

  117.      */ 

  118.     int previousIndex();

  119. 

  120. 

  121.     // Modification Operations

  122.     

  123.     /**

  124.      * Removes from the list the last element that was returned by

  125.      * <tt>next</tt> or <tt>previous</tt> (optional operation).  This call can

  126.      * only be made once per call to <tt>next</tt> or <tt>previous</tt>.  It

  127.      * can be made only if <tt>ListIterator.add</tt> has not been called after

  128.      * the last call to <tt>next</tt> or <tt>previous</tt>.

  129.      *

  130.      * @exception UnsupportedOperationException if the <tt>remove</tt>

  131.      * 		  operation is not supported by this list iterator.

  132.      * @exception IllegalStateException neither <tt>next</tt> nor

  133.      *		  <tt>previous</tt> have been called, or <tt>remove</tt> or

  134.      *		  <tt>add</tt> have been called after the last call to *

  135.      *		  <tt>next</tt> or <tt>previous</tt>.

  136.      */

  137.     void remove();

  138. 

  139.     /**

  140.      * Replaces the last element returned by <tt>next</tt> or

  141.      * <tt>previous</tt> with the specified element (optional operation).

  142.      * This call can be made only if neither <tt>ListIterator.remove</tt> nor

  143.      * <tt>ListIterator.add</tt> have been called after the last call to

  144.      * <tt>next</tt> or <tt>previous</tt>.

  145.      *

  146.      * @param o the element with which to replace the last element returned by

  147.      *          <tt>next</tt> or <tt>previous</tt>.

  148.      * @exception UnsupportedOperationException if the <tt>set</tt> operation

  149.      * 		  is not supported by this list iterator.

  150.      * @exception ClassCastException if the class of the specified element

  151.      * 		  prevents it from being added to this list.

  152.      * @exception IllegalArgumentException if some aspect of the specified

  153.      *		  element prevents it from being added to this list.

  154.      * @exception IllegalStateException if neither <tt>next</tt> nor

  155.      *	          <tt>previous</tt> have been called, or <tt>remove</tt> or

  156.      *		  <tt>add</tt> have been called after the last call to

  157.      * 		  <tt>next</tt> or <tt>previous</tt>.

  158.      */

  159.     void set(E o);

  160. 

  161.     /**

  162.      * Inserts the specified element into the list (optional operation).  The

  163.      * element is inserted immediately before the next element that would be

  164.      * returned by <tt>next</tt>, if any, and after the next element that

  165.      * would be returned by <tt>previous</tt>, if any.  (If the list contains

  166.      * no elements, the new element becomes the sole element on the list.)

  167.      * The new element is inserted before the implicit cursor: a subsequent

  168.      * call to <tt>next</tt> would be unaffected, and a subsequent call to

  169.      * <tt>previous</tt> would return the new element.  (This call increases

  170.      * by one the value that would be returned by a call to <tt>nextIndex</tt>

  171.      * or <tt>previousIndex</tt>.)

  172.      *

  173.      * @param o the element to insert.

  174.      * @exception UnsupportedOperationException if the <tt>add</tt> method is

  175.      * 		  not supported by this list iterator.

  176.      * 

  177.      * @exception ClassCastException if the class of the specified element

  178.      * 		  prevents it from being added to this list.

  179.      * 

  180.      * @exception IllegalArgumentException if some aspect of this element

  181.      *            prevents it from being added to this list.

  182.      */

  183.     void add(E o);

  184. }