diff options
Diffstat (limited to 'java/util/ListIterator.java')
| -rw-r--r-- | java/util/ListIterator.java | 118 |
1 files changed, 65 insertions, 53 deletions
diff --git a/java/util/ListIterator.java b/java/util/ListIterator.java index 8a8d2c74e..92f49371a 100644 --- a/java/util/ListIterator.java +++ b/java/util/ListIterator.java @@ -1,5 +1,5 @@ /* ListIterator.java -- Extended Iterator for iterating over ordered lists - Copyright (C) 1998, 1999 Free Software Foundation, Inc. + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -32,116 +32,128 @@ package java.util; * elements may be accessed in forward or reverse order, elements may be * replaced as well as removed, and new elements may be inserted, during the * traversal of the list. + * <p> + * + * A list with n elements provides n+1 iterator positions (the front, the end, + * or between two elements). Note that <code>remove</code> and <code>set</code> + * operate on the last element returned, whether it was by <code>next</code> + * or <code>previous</code>. + * + * @author Original author unknown + * @author Eric Blake <ebb9@email.byu.edu> + * @see Collection + * @see List + * @see Iterator + * @see Enumeration + * @since 1.2 + * @status updated to 1.4 */ public interface ListIterator extends Iterator { /** * Tests whether there are elements remaining in the list in the forward - * direction. + * direction. In other words, next() will not fail with a + * NoSuchElementException. * - * @return true if there is at least one more element in the list in the - * forward direction, that is, if the next call to next will not throw - * NoSuchElementException. + * @return true if the list continues in the forward direction */ boolean hasNext(); /** * Tests whether there are elements remaining in the list in the reverse - * direction. + * direction. In other words, previous() will not fail with a + * NoSuchElementException. * - * @return true if there is at least one more element in the list in the - * reverse direction, that is, if the next call to previous will not throw - * NoSuchElementException. + * @return true if the list continues in the reverse direction */ boolean hasPrevious(); /** * Obtain the next element in the list in the forward direction. Repeated - * calls to next may be used to iterate over the entire list, or calls to next - * and previous may be used together to go forwards and backwards. Alternating - * calls to next and previous will return the same element. + * calls to next may be used to iterate over the entire list, or calls to + * next and previous may be used together to go forwards and backwards. + * Alternating calls to next and previous will return the same element. * * @return the next element in the list in the forward direction - * @exception NoSuchElementException if there are no more elements + * @throws NoSuchElementException if there are no more elements */ Object next(); /** * Obtain the next element in the list in the reverse direction. Repeated - * calls to previous may be used to iterate backwards over the entire list, or - * calls to next and previous may be used together to go forwards and + * calls to previous may be used to iterate backwards over the entire list, + * or calls to next and previous may be used together to go forwards and * backwards. Alternating calls to next and previous will return the same * element. * * @return the next element in the list in the reverse direction - * @exception NoSuchElementException if there are no more elements + * @throws NoSuchElementException if there are no more elements */ Object previous(); /** * Find the index of the element that would be returned by a call to next. + * If hasNext() returns false, this returns the list size. * - * @return the index of the element that would be returned by a call to next, - * or list.size() if the iterator is at the end of the list. + * @return the index of the element that would be returned by next() */ int nextIndex(); /** - * 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 + * previous. If hasPrevious() returns false, this returns -1. * - * @return the index of the element that would be returned by a call to - * previous, or -1 if the iterator is at the beginning of the list. + * @return the index of the element that would be returned by previous() */ int previousIndex(); /** - * Insert an element into the list at the current position of the iterator. - * The element is inserted in between the element that would be returned by - * previous and the element that would be returned by next. After the - * insertion, a subsequent call to next is unaffected, but a call to - * previous returns the item that was added. This operation is optional, it - * may throw an UnsupportedOperationException. + * Insert an element into the list at the current position of the iterator + * (optional operation). The element is inserted in between the element that + * would be returned by previous and the element that would be returned by + * next. After the insertion, a subsequent call to next is unaffected, but + * a call to previous returns the item that was added. The values returned + * by nextIndex() and previousIndex() are incremented. * * @param o the object to insert into the list - * @exception ClassCastException the object is of a type which cannot be added - * to this list - * @exception IllegalArgumentException some other aspect of the object stops - * it being added to this list - * @exception UnsupportedOperationException if this ListIterator does not - * support the add operation + * @throws ClassCastException the object is of a type which cannot be added + * to this list + * @throws IllegalArgumentException some other aspect of the object stops + * it being added to this list + * @throws UnsupportedOperationException if this ListIterator does not + * support the add operation */ void add(Object o); /** * Remove from the list the element last returned by a call to next or - * previous. This method may only be called if neither add nor remove have - * been called since the last call to next or previous. This operation is - * optional, it may throw an UnsupportedOperationException. + * previous (optional operation). This method may only be called if neither + * add nor remove have been called since the last call to next or previous. * - * @exception IllegalStateException if neither next or previous have been - * called, or if add or remove has been called since the last call to next - * or previous. - * @exception UnsupportedOperationException if this ListIterator does not - * support the remove operation. + * @throws IllegalStateException if neither next or previous have been + * called, or if add or remove has been called since the last call + * to next or previous + * @throws UnsupportedOperationException if this ListIterator does not + * support the remove operation */ void remove(); /** * Replace the element last returned by a call to next or previous with a - * given object. This method may only be called if neither add nor remove have - * been called since the last call to next or previous. This operation is - * optional, it may throw an UnsupportedOperationException. + * given object (optional operation). This method may only be called if + * neither add nor remove have been called since the last call to next or + * previous. * * @param o the object to replace the element with - * @exception ClassCastException the object is of a type which cannot be added - * to this list - * @exception IllegalArgumentException some other aspect of the object stops - * it being added to this list - * @exception IllegalStateException if neither next or previous have been - * called, or if add or remove has been called since the last call to next - * or previous. - * @exception UnsupportedOperationException if this ListIterator does not - * support the set operation. + * @throws ClassCastException the object is of a type which cannot be added + * to this list + * @throws IllegalArgumentException some other aspect of the object stops + * it being added to this list + * @throws IllegalStateException if neither next or previous have been + * called, or if add or remove has been called since the last call + * to next or previous + * @throws UnsupportedOperationException if this ListIterator does not + * support the set operation */ void set(Object o); } |