/*
 
* Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
 
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 
*
 
* This code is free software; you can redistribute it and/or modify it
 
* under the terms of the GNU General Public License version 2 only, as
 
* published by the Free Software Foundation.
  
Oracle designates this
 
* particular file as subject to the "Classpath" exception as provided
 
* by Oracle in the LICENSE file that accompanied this code.
 
*
 
* This code is distributed in the hope that it will be useful, but WITHOUT
 
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 
* FITNESS FOR A PARTICULAR PURPOSE.
  
See the GNU General Public License
 
* version 2 for more details (a copy is included in the LICENSE file that
 
* accompanied this code).
 
*
 
* You should have received a copy of the GNU General Public License version
 
* 2 along with this work; if not, write to the Free Software Foundation,
 
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 
*
 
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 
* or visit www.oracle.com if you need additional information or have any
 
* questions.
 
*/

package java.util;

/**
 
* An iterator for lists that allows the programmer
 
* to traverse the list in either direction, modify
 
* the list during iteration, and obtain the iterator's
 
* current position in the list. A {@code ListIterator}
 
* has no current element; its <I>cursor position</I> always
 
* lies between the element that would be returned by a call
 
* to {@code previous()} and the element that would be
 
* returned by a call to {@code next()}.
 
* An iterator for a list of length {@code n} has {@code n+1} possible
 
* cursor positions, as illustrated by the carets ({@code ^}) below:
 
* <PRE>
 
*
                      
Element(0)
   
Element(1)Element(2)... Element(n-1)
 
* cursor positions:
  
^
            
                  

 
* </PRE>
 
* Note that the {@link #remove} and {@link #set(Object)} methods are
 
* <i>not</i> defined in terms of the cursor position;
  
they are defined to
 
* operate on the last element returned by a call to {@link #next} or
 
* .
 
*
 
* <p>This interface is a member of the
 
* <a href="{@docRoot}/../technotes/guides/collections/index.html">
 
* Java Collections Framework</a>.
 
*
 
* @author
  
Josh Bloch
 
* @see Collection
 
* @see List
 
* @see Iterator
 
* @see Enumeration
 
* @see List#listIterator()
 
* @since
   
1.2
 
*/

public interface ListIterator<E> extends Iterator<E> {
    
// Query Operations

    
/**
     
* Returns {@code true} if this list iterator has more elements when
     
* traversing the list in the forward direction. (In other words,
     
* returns {@code true} if {@link #next} would return an element rather
     
* than throwing an exception.)
     
*
     
* @return {@code true} if the list iterator has more elements when
     
*
         
traversing the list in the forward direction
     
*/

    
boolean hasNext();

    
/**
     
* Returns the next element in the list and advances the cursor position.
     
* This method may be called repeatedly to iterate through the list,
     
* or intermixed with calls to {@link #previous} to go back and forth.
     
* (Note that alternating calls to {@code next} and {@code previous}
     
* will return the same element repeatedly.)
     
*
     
* @return the next element in the list
     
* @throws NoSuchElementException if the iteration has no next element
     
*/

    
E next();

    
/**
     
* Returns {@code true} if this list iterator has more elements when
     
* traversing the list in the reverse direction.
  
(In other words,
     
* returns {@code true} if {@link #previous} would return an element
     
* rather than throwing an exception.)
     
*
     
* @return {@code true} if the list iterator has more elements when
     
*
         
traversing the list in the reverse direction
     
*/

    
boolean hasPrevious();

    
/**
     
* Returns the previous element in the list and moves the cursor
     
* position backwards.
  
This method may be called repeatedly to
     
* iterate through the list backwards, or intermixed with calls to
     
* {@link #next} to go back and forth.
  
(Note that alternating calls
     
* to {@code next} and {@code previous} will return the same
     
* element repeatedly.)
     
*
     
* @return the previous element in the list
     
* @throws NoSuchElementException if the iteration has no previous
     
*
         
element
     
*/

    
E previous();

    
/**
     
* Returns the index of the element that would be returned by a
     
* subsequent call to {@link #next}. (Returns list size if the list
     
* iterator is at the end of the list.)
     
*
     
* @return the index of the element that would be returned by a
     
*
         
subsequent call to {@code next}, or list size if the list
     
*
         
iterator is at the end of the list
     
*/

    
int nextIndex();

    
/**
     
* Returns the index of the element that would be returned by a
     
* subsequent call to {@link #previous}. (Returns -1 if the list
     
* iterator is at the beginning of the list.)
     
*
     
* @return the index of the element that would be returned by a
     
*
         
subsequent call to {@code previous}, or -1 if the list
     
*
         
iterator is at the beginning of the list
     
*/

    
int previousIndex();


    
// Modification Operations

    
/**
     
* Removes from the list the last element that was returned by {@link
     
* #next} or {@link #previous} (optional operation).
  
This call can
     
* only be made once per call to {@code next} or {@code previous}.
     
* It can be made only if {@link #add} has not been
     
* called after the last call to {@code next} or {@code previous}.
     
*
     
* @throws UnsupportedOperationException if the {@code remove}
     
*
         
operation is not supported by this list iterator
     
* @throws IllegalStateException if neither {@code next} nor
     
*
         
{@code previous} have been called, or {@code remove} or
     
*
         
{@code add} have been called after the last call to
     
*
         
{@code next} or {@code previous}
     
*/

    
void remove();

    
/**
     
* Replaces the last element returned by {@link #next} or
     
* {@link #previous} with the specified element (optional operation).
     
* This call can be made only if neither {@link #remove} nor {@link
     
* #add} have been called after the last call to {@code next} or
     
* {@code previous}.
     
*
     
* @param e the element with which to replace the last element returned by
     
*
          
{@code next} or {@code previous}
     
* @throws UnsupportedOperationException if the {@code set} operation
     
*
         
is not supported by this list iterator
     
* @throws ClassCastException if the class of the specified element
     
*
         
prevents it from being added to this list
     
* @throws IllegalArgumentException if some aspect of the specified
     
*
         
element prevents it from being added to this list
     
* @throws IllegalStateException if neither {@code next} nor
     
*
         
{@code previous} have been called, or {@code remove} or
     
*
         
{@code add} have been called after the last call to
     
*
         
{@code next} or {@code previous}
     
*/

    
void set(E e);

    
/**
     
* Inserts the specified element into the list (optional operation).
     
* The element is inserted immediately before the element that
     
* would be returned by {@link #next}, if any, and after the element
     
* that would be returned by {@link #previous}, if any.
  
(If the
     
* list contains no elements, the new element becomes the sole element
     
* on the list.)
  
The new element is inserted before the implicit
     
* cursor: a subsequent call to {@code next} would be unaffected, and a
     
* subsequent call to {@code previous} would return the new element.
     
* (This call increases by one the value that would be returned by a
     
* call to {@code nextIndex} or {@code previousIndex}.)
     
*
     
* @param e the element to insert
     
* @throws UnsupportedOperationException if the {@code add} method is
     
*
         
not supported by this list iterator
     
* @throws ClassCastException if the class of the specified element
     
*
         
prevents it from being added to this list
     
* @throws IllegalArgumentException if some aspect of this element
     
*
         
prevents it from being added to this list
     
*/

    
void add(E e);
}