/[classpath]/classpath/java/util/ListIterator.java
ViewVC logotype

Diff of /classpath/java/util/ListIterator.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.5 by bryce, Thu Oct 26 10:19:01 2000 UTC revision 1.6 by ericb, Mon Oct 15 14:53:51 2001 UTC
# Line 1  Line 1 
1  /* ListIterator.java -- Extended Iterator for iterating over ordered lists  /* ListIterator.java -- Extended Iterator for iterating over ordered lists
2     Copyright (C) 1998, 1999 Free Software Foundation, Inc.     Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
3    
4  This file is part of GNU Classpath.  This file is part of GNU Classpath.
5    
# Line 32  package java.util; Line 32  package java.util;
32   * elements may be accessed in forward or reverse order, elements may be   * elements may be accessed in forward or reverse order, elements may be
33   * replaced as well as removed, and new elements may be inserted, during the   * replaced as well as removed, and new elements may be inserted, during the
34   * traversal of the list.   * traversal of the list.
35     * <p>
36     *
37     * A list with n elements provides n+1 iterator positions (the front, the end,
38     * or between two elements). Note that <code>remove</code> and <code>set</code>
39     * operate on the last element returned, whether it was by <code>next</code>
40     * or <code>previous</code>.
41     *
42     * @author Original author unknown
43     * @author Eric Blake <ebb9@email.byu.edu>
44     * @see Collection
45     * @see List
46     * @see Iterator
47     * @see Enumeration
48     * @since 1.2
49     * @status updated to 1.4
50   */   */
51  public interface ListIterator extends Iterator  public interface ListIterator extends Iterator
52  {  {
53    /**    /**
54     * Tests whether there are elements remaining in the list in the forward     * Tests whether there are elements remaining in the list in the forward
55     * direction.     * direction. In other words, next() will not fail with a
56       * NoSuchElementException.
57     *     *
58     * @return true if there is at least one more element in the list in the     * @return true if the list continues in the forward direction
    *   forward direction, that is, if the next call to next will not throw  
    *   NoSuchElementException.  
59     */     */
60    boolean hasNext();    boolean hasNext();
61    
62    /**    /**
63     * Tests whether there are elements remaining in the list in the reverse     * Tests whether there are elements remaining in the list in the reverse
64     * direction.     * direction. In other words, previous() will not fail with a
65       * NoSuchElementException.
66     *     *
67     * @return true if there is at least one more element in the list in the     * @return true if the list continues in the reverse direction
    *   reverse direction, that is, if the next call to previous will not throw  
    *   NoSuchElementException.  
68     */     */
69    boolean hasPrevious();    boolean hasPrevious();
70    
71    /**    /**
72     * Obtain the next element in the list in the forward direction. Repeated     * Obtain the next element in the list in the forward direction. Repeated
73     * calls to next may be used to iterate over the entire list, or calls to next     * calls to next may be used to iterate over the entire list, or calls to
74     * and previous may be used together to go forwards and backwards. Alternating     * next and previous may be used together to go forwards and backwards.
75     * calls to next and previous will return the same element.     * Alternating calls to next and previous will return the same element.
76     *     *
77     * @return the next element in the list in the forward direction     * @return the next element in the list in the forward direction
78     * @exception NoSuchElementException if there are no more elements     * @throws NoSuchElementException if there are no more elements
79     */     */
80    Object next();    Object next();
81    
82    /**    /**
83     * Obtain the next element in the list in the reverse direction. Repeated     * Obtain the next element in the list in the reverse direction. Repeated
84     * calls to previous may be used to iterate backwards over the entire list, or     * calls to previous may be used to iterate backwards over the entire list,
85     * calls to next and previous may be used together to go forwards and     * or calls to next and previous may be used together to go forwards and
86     * backwards. Alternating calls to next and previous will return the same     * backwards. Alternating calls to next and previous will return the same
87     * element.     * element.
88     *     *
89     * @return the next element in the list in the reverse direction     * @return the next element in the list in the reverse direction
90     * @exception NoSuchElementException if there are no more elements     * @throws NoSuchElementException if there are no more elements
91     */     */
92    Object previous();    Object previous();
93    
94    /**    /**
95     * Find the index of the element that would be returned by a call to next.     * Find the index of the element that would be returned by a call to next.
96       * If hasNext() returns false, this returns the list size.
97     *     *
98     * @return the index of the element that would be returned by a call to next,     * @return the index of the element that would be returned by next()
    *   or list.size() if the iterator is at the end of the list.  
99     */     */
100    int nextIndex();    int nextIndex();
101    
102    /**    /**
103     * Find the index of the element that would be returned by a call to previous.     * Find the index of the element that would be returned by a call to
104       * previous. If hasPrevious() returns false, this returns -1.
105     *     *
106     * @return the index of the element that would be returned by a call to     * @return the index of the element that would be returned by previous()
    *   previous, or -1 if the iterator is at the beginning of the list.  
107     */     */
108    int previousIndex();    int previousIndex();
109    
110    /**    /**
111     * Insert an element into the list at the current position of the iterator.     * Insert an element into the list at the current position of the iterator
112     * The element is inserted in between the element that would be returned by     * (optional operation). The element is inserted in between the element that
113     * previous and the element that would be returned by next. After the     * would be returned by previous and the element that would be returned by
114     * insertion, a subsequent call to next is unaffected, but a call to     * next. After the insertion, a subsequent call to next is unaffected, but
115     * previous returns the item that was added. This operation is optional, it     * a call to previous returns the item that was added. The values returned
116     * may throw an UnsupportedOperationException.     * by nextIndex() and previousIndex() are incremented.
117     *     *
118     * @param o the object to insert into the list     * @param o the object to insert into the list
119     * @exception ClassCastException the object is of a type which cannot be added     * @throws ClassCastException the object is of a type which cannot be added
120     *   to this list     *         to this list
121     * @exception IllegalArgumentException some other aspect of the object stops     * @throws IllegalArgumentException some other aspect of the object stops
122     *   it being added to this list     *         it being added to this list
123     * @exception UnsupportedOperationException if this ListIterator does not     * @throws UnsupportedOperationException if this ListIterator does not
124     *   support the add operation     *         support the add operation
125     */     */
126    void add(Object o);    void add(Object o);
127    
128    /**    /**
129     * Remove from the list the element last returned by a call to next or     * Remove from the list the element last returned by a call to next or
130     * previous. This method may only be called if neither add nor remove have     * previous (optional operation). This method may only be called if neither
131     * been called since the last call to next or previous. This operation is     * add nor remove have been called since the last call to next or previous.
132     * optional, it may throw an UnsupportedOperationException.     *
133     *     * @throws IllegalStateException if neither next or previous have been
134     * @exception IllegalStateException if neither next or previous have been     *         called, or if add or remove has been called since the last call
135     *   called, or if add or remove has been called since the last call to next     *         to next or previous
136     *   or previous.     * @throws UnsupportedOperationException if this ListIterator does not
137     * @exception UnsupportedOperationException if this ListIterator does not     *         support the remove operation
    *   support the remove operation.  
138     */     */
139    void remove();    void remove();
140    
141    /**    /**
142     * Replace the element last returned by a call to next or previous with a     * Replace the element last returned by a call to next or previous with a
143     * given object. This method may only be called if neither add nor remove have     * given object (optional operation). This method may only be called if
144     * been called since the last call to next or previous. This operation is     * neither add nor remove have been called since the last call to next or
145     * optional, it may throw an UnsupportedOperationException.     * previous.
146     *     *
147     * @param o the object to replace the element with     * @param o the object to replace the element with
148     * @exception ClassCastException the object is of a type which cannot be added     * @throws ClassCastException the object is of a type which cannot be added
149     *   to this list     *         to this list
150     * @exception IllegalArgumentException some other aspect of the object stops     * @throws IllegalArgumentException some other aspect of the object stops
151     *   it being added to this list     *         it being added to this list
152     * @exception IllegalStateException if neither next or previous have been     * @throws IllegalStateException if neither next or previous have been
153     *   called, or if add or remove has been called since the last call to next     *         called, or if add or remove has been called since the last call
154     *   or previous.     *         to next or previous
155     * @exception UnsupportedOperationException if this ListIterator does not     * @throws UnsupportedOperationException if this ListIterator does not
156     *   support the set operation.     *         support the set operation
157     */     */
158    void set(Object o);    void set(Object o);
159  }  }

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.6

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26