libcore/luni/src/main/java/java/util/ListIterator.java

   1 /*
   2  *  Licensed to the Apache Software Foundation (ASF) under one or more
   3  *  contributor license agreements.  See the NOTICE file distributed with
   4  *  this work for additional information regarding copyright ownership.
   5  *  The ASF licenses this file to You under the Apache License, Version 2.0
   6  *  (the "License"); you may not use this file except in compliance with
   7  *  the License.  You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *  Unless required by applicable law or agreed to in writing, software
  12  *  distributed under the License is distributed on an "AS IS" BASIS,
  13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *  See the License for the specific language governing permissions and
  15  *  limitations under the License.
  16  */
  17
  18 package java.util;
  19
  20
  21 /**
  22  * An ListIterator is used to sequence over a List of objects. ListIterator can
  23  * move backwards or forwards through the list.
  24  */
  25 public interface ListIterator<E> extends Iterator<E> {
  26
  27     /**
  28      * Inserts the specified object into the list between {@code next} and
  29      * {@code previous}. The object inserted will be the previous object.
  30      *
  31      * @param object
  32      *            the object to insert.
  33      * @throws UnsupportedOperationException
  34      *             if adding is not supported by the list being iterated.
  35      * @throws ClassCastException
  36      *             if the class of the object is inappropriate for the list.
  37      * @throws IllegalArgumentException
  38      *             if the object cannot be added to the list.
  39      */
  40     void add(E object);
  41
  42     /**
  43      * Returns whether there are more elements to iterate.
  44      *
  45      * @return {@code true} if there are more elements, {@code false} otherwise.
  46      * @see #next
  47      */
  48     public boolean hasNext();
  49
  50     /**
  51      * Returns whether there are previous elements to iterate.
  52      *
  53      * @return {@code true} if there are previous elements, {@code false}
  54      *         otherwise.
  55      * @see #previous
  56      */
  57     public boolean hasPrevious();
  58
  59     /**
  60      * Returns the next object in the iteration.
  61      *
  62      * @return the next object.
  63      * @throws NoSuchElementException
  64      *             if there are no more elements.
  65      * @see #hasNext
  66      */
  67     public E next();
  68
  69     /**
  70      * Returns the index of the next object in the iteration.
  71      *
  72      * @return the index of the next object, or the size of the list if the
  73      *         iterator is at the end.
  74      * @throws NoSuchElementException
  75      *             if there are no more elements.
  76      * @see #next
  77      */
  78     public int nextIndex();
  79
  80     /**
  81      * Returns the previous object in the iteration.
  82      *
  83      * @return the previous object.
  84      * @throws NoSuchElementException
  85      *             if there are no previous elements.
  86      * @see #hasPrevious
  87      */
  88     public E previous();
  89
  90     /**
  91      * Returns the index of the previous object in the iteration.
  92      *
  93      * @return the index of the previous object, or -1 if the iterator is at the
  94      *         beginning.
  95      * @throws NoSuchElementException
  96      *             if there are no previous elements.
  97      * @see #previous
  98      */
  99     public int previousIndex();
 100
 101     /**
 102      * Removes the last object returned by {@code next} or {@code previous} from
 103      * the list.
 104      *
 105      * @throws UnsupportedOperationException
 106      *             if removing is not supported by the list being iterated.
 107      * @throws IllegalStateException
 108      *             if {@code next} or {@code previous} have not been called, or
 109      *             {@code remove} or {@code add} have already been called after
 110      *             the last call to {@code next} or {@code previous}.
 111      */
 112     public void remove();
 113
 114     /**
 115      * Replaces the last object returned by {@code next} or {@code previous}
 116      * with the specified object.
 117      *
 118      * @param object
 119      *            the object to set.
 120      * @throws UnsupportedOperationException
 121      *             if setting is not supported by the list being iterated
 122      * @throws ClassCastException
 123      *             if the class of the object is inappropriate for the list.
 124      * @throws IllegalArgumentException
 125      *             if the object cannot be added to the list.
 126      * @throws IllegalStateException
 127      *             if {@code next} or {@code previous} have not been called, or
 128      *             {@code remove} or {@code add} have already been called after
 129      *             the last call to {@code next} or {@code previous}.
 130      */
 131     void set(E object);
 132 }