Home » openjdk-7 » java » util » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2007, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.util;
   27   
   28   /**
   29    * An iterator for lists that allows the programmer
   30    * to traverse the list in either direction, modify
   31    * the list during iteration, and obtain the iterator's
   32    * current position in the list. A {@code ListIterator}
   33    * has no current element; its <I>cursor position</I> always
   34    * lies between the element that would be returned by a call
   35    * to {@code previous()} and the element that would be
   36    * returned by a call to {@code next()}.
   37    * An iterator for a list of length {@code n} has {@code n+1} possible
   38    * cursor positions, as illustrated by the carets ({@code ^}) below:
   39    * <PRE>
   40    *                      Element(0)   Element(1)   Element(2)   ... Element(n-1)
   41    * cursor positions:  ^            ^            ^            ^                  ^
   42    * </PRE>
   43    * Note that the {@link #remove} and {@link #set(Object)} methods are
   44    * <i>not</i> defined in terms of the cursor position;  they are defined to
   45    * operate on the last element returned by a call to {@link #next} or
   46    * {@link #previous()}.
   47    *
   48    * <p>This interface is a member of the
   49    * <a href="{@docRoot}/../technotes/guides/collections/index.html">
   50    * Java Collections Framework</a>.
   51    *
   52    * @author  Josh Bloch
   53    * @see Collection
   54    * @see List
   55    * @see Iterator
   56    * @see Enumeration
   57    * @see List#listIterator()
   58    * @since   1.2
   59    */
   60   public interface ListIterator<E> extends Iterator<E> {
   61       // Query Operations
   62   
   63       /**
   64        * Returns {@code true} if this list iterator has more elements when
   65        * traversing the list in the forward direction. (In other words,
   66        * returns {@code true} if {@link #next} would return an element rather
   67        * than throwing an exception.)
   68        *
   69        * @return {@code true} if the list iterator has more elements when
   70        *         traversing the list in the forward direction
   71        */
   72       boolean hasNext();
   73   
   74       /**
   75        * Returns the next element in the list and advances the cursor position.
   76        * This method may be called repeatedly to iterate through the list,
   77        * or intermixed with calls to {@link #previous} to go back and forth.
   78        * (Note that alternating calls to {@code next} and {@code previous}
   79        * will return the same element repeatedly.)
   80        *
   81        * @return the next element in the list
   82        * @throws NoSuchElementException if the iteration has no next element
   83        */
   84       E next();
   85   
   86       /**
   87        * Returns {@code true} if this list iterator has more elements when
   88        * traversing the list in the reverse direction.  (In other words,
   89        * returns {@code true} if {@link #previous} would return an element
   90        * rather than throwing an exception.)
   91        *
   92        * @return {@code true} if the list iterator has more elements when
   93        *         traversing the list in the reverse direction
   94        */
   95       boolean hasPrevious();
   96   
   97       /**
   98        * Returns the previous element in the list and moves the cursor
   99        * position backwards.  This method may be called repeatedly to
  100        * iterate through the list backwards, or intermixed with calls to
  101        * {@link #next} to go back and forth.  (Note that alternating calls
  102        * to {@code next} and {@code previous} will return the same
  103        * element repeatedly.)
  104        *
  105        * @return the previous element in the list
  106        * @throws NoSuchElementException if the iteration has no previous
  107        *         element
  108        */
  109       E previous();
  110   
  111       /**
  112        * Returns the index of the element that would be returned by a
  113        * subsequent call to {@link #next}. (Returns list size if the list
  114        * iterator is at the end of the list.)
  115        *
  116        * @return the index of the element that would be returned by a
  117        *         subsequent call to {@code next}, or list size if the list
  118        *         iterator is at the end of the list
  119        */
  120       int nextIndex();
  121   
  122       /**
  123        * Returns the index of the element that would be returned by a
  124        * subsequent call to {@link #previous}. (Returns -1 if the list
  125        * iterator is at the beginning of the list.)
  126        *
  127        * @return the index of the element that would be returned by a
  128        *         subsequent call to {@code previous}, or -1 if the list
  129        *         iterator is at the beginning of the list
  130        */
  131       int previousIndex();
  132   
  133   
  134       // Modification Operations
  135   
  136       /**
  137        * Removes from the list the last element that was returned by {@link
  138        * #next} or {@link #previous} (optional operation).  This call can
  139        * only be made once per call to {@code next} or {@code previous}.
  140        * It can be made only if {@link #add} has not been
  141        * called after the last call to {@code next} or {@code previous}.
  142        *
  143        * @throws UnsupportedOperationException if the {@code remove}
  144        *         operation is not supported by this list iterator
  145        * @throws IllegalStateException if neither {@code next} nor
  146        *         {@code previous} have been called, or {@code remove} or
  147        *         {@code add} have been called after the last call to
  148        *         {@code next} or {@code previous}
  149        */
  150       void remove();
  151   
  152       /**
  153        * Replaces the last element returned by {@link #next} or
  154        * {@link #previous} with the specified element (optional operation).
  155        * This call can be made only if neither {@link #remove} nor {@link
  156        * #add} have been called after the last call to {@code next} or
  157        * {@code previous}.
  158        *
  159        * @param e the element with which to replace the last element returned by
  160        *          {@code next} or {@code previous}
  161        * @throws UnsupportedOperationException if the {@code set} operation
  162        *         is not supported by this list iterator
  163        * @throws ClassCastException if the class of the specified element
  164        *         prevents it from being added to this list
  165        * @throws IllegalArgumentException if some aspect of the specified
  166        *         element prevents it from being added to this list
  167        * @throws IllegalStateException if neither {@code next} nor
  168        *         {@code previous} have been called, or {@code remove} or
  169        *         {@code add} have been called after the last call to
  170        *         {@code next} or {@code previous}
  171        */
  172       void set(E e);
  173   
  174       /**
  175        * Inserts the specified element into the list (optional operation).
  176        * The element is inserted immediately before the element that
  177        * would be returned by {@link #next}, if any, and after the element
  178        * that would be returned by {@link #previous}, if any.  (If the
  179        * list contains no elements, the new element becomes the sole element
  180        * on the list.)  The new element is inserted before the implicit
  181        * cursor: a subsequent call to {@code next} would be unaffected, and a
  182        * subsequent call to {@code previous} would return the new element.
  183        * (This call increases by one the value that would be returned by a
  184        * call to {@code nextIndex} or {@code previousIndex}.)
  185        *
  186        * @param e the element to insert
  187        * @throws UnsupportedOperationException if the {@code add} method is
  188        *         not supported by this list iterator
  189        * @throws ClassCastException if the class of the specified element
  190        *         prevents it from being added to this list
  191        * @throws IllegalArgumentException if some aspect of this element
  192        *         prevents it from being added to this list
  193        */
  194       void add(E e);
  195   }

Home » openjdk-7 » java » util » [javadoc | source]