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 |
|
|
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 |
} |
} |