1 *java.util.AbstractList* *AbstractList* This class provides a skeletal implement
3 public abstract class AbstractList
4 extends |java.util.AbstractCollection|
5 implements |java.util.List|
7 |java.util.AbstractList_Description|
8 |java.util.AbstractList_Fields|
9 |java.util.AbstractList_Constructors|
10 |java.util.AbstractList_Methods|
12 ================================================================================
14 *java.util.AbstractList_Fields*
15 |int_java.util.AbstractList.modCount|
17 *java.util.AbstractList_Constructors*
18 |java.util.AbstractList()|Sole constructor.
20 *java.util.AbstractList_Methods*
21 |java.util.AbstractList.add(E)|Appends the specified element to the end of this
22 |java.util.AbstractList.add(int,E)|Inserts the specified element at the specifi
23 |java.util.AbstractList.addAll(int,Collection)|Inserts all of the elements in t
24 |java.util.AbstractList.clear()|Removes all of the elements from this collectio
25 |java.util.AbstractList.equals(Object)|Compares the specified object with this
26 |java.util.AbstractList.get(int)|Returns the element at the specified position
27 |java.util.AbstractList.hashCode()|Returns the hash code value for this list.
28 |java.util.AbstractList.indexOf(Object)|Returns the index in this list of the f
29 |java.util.AbstractList.iterator()|Returns an iterator over the elements in thi
30 |java.util.AbstractList.lastIndexOf(Object)|Returns the index in this list of t
31 |java.util.AbstractList.listIterator()|Returns an iterator of the elements in t
32 |java.util.AbstractList.listIterator(int)|Returns a list iterator of the elemen
33 |java.util.AbstractList.remove(int)|Removes the element at the specified positi
34 |java.util.AbstractList.removeRange(int,int)|Removes from this list all of the
35 |java.util.AbstractList.set(int,E)|Replaces the element at the specified positi
36 |java.util.AbstractList.subList(int,int)|Returns a view of the portion of this
38 *java.util.AbstractList_Description*
40 This class provides a skeletal implementation of the List interface to minimize
41 the effort required to implement this interface backed by a "random access"
42 data store (such as an array). For sequential access data (such as a linked
43 list), AbstractSequentialList should be used in preference to this class.
45 To implement an unmodifiable list, the programmer needs only to extend this
46 class and provide implementations for the get(int index) and size() methods.
48 To implement a modifiable list, the programmer must additionally override the
49 set(int index, Object element) method (which otherwise throws an
50 UnsupportedOperationException. If the list is variable-size the programmer must
51 additionally override the add(int index, Object element) and remove(int index)
54 The programmer should generally provide a void (no argument) and collection
55 constructor, as per the recommendation in the Collection interface
58 Unlike the other abstract collection implementations, the programmer does not
59 have to provide an iterator implementation; the iterator and list iterator are
60 implemented by this class, on top the "random access" methods: get(int index),
61 set(int index, Object element), set(int index, Object element), add(int index,
62 Object element) and remove(int index).
64 The documentation for each non-abstract methods in this class describes its
65 implementation in detail. Each of these methods may be overridden if the
66 collection being implemented admits a more efficient implementation.
68 This class is a member of the <a href="/../guide/collections/index.html"> Java
69 Collections Framework.
72 *int_java.util.AbstractList.modCount*
74 This class provides a skeletal implementation of the List interface to minimize
75 the effort required to implement this interface backed by a "random access"
76 data store (such as an array). For sequential access data (such as a linked
77 list), AbstractSequentialList should be used in preference to this class.
79 To implement an unmodifiable list, the programmer needs only to extend this
80 class and provide implementations for the get(int index) and size() methods.
82 To implement a modifiable list, the programmer must additionally override the
83 set(int index, Object element) method (which otherwise throws an
84 UnsupportedOperationException. If the list is variable-size the programmer must
85 additionally override the add(int index, Object element) and remove(int index)
88 The programmer should generally provide a void (no argument) and collection
89 constructor, as per the recommendation in the Collection interface
92 Unlike the other abstract collection implementations, the programmer does not
93 have to provide an iterator implementation; the iterator and list iterator are
94 implemented by this class, on top the "random access" methods: get(int index),
95 set(int index, Object element), set(int index, Object element), add(int index,
96 Object element) and remove(int index).
98 The documentation for each non-abstract methods in this class describes its
99 implementation in detail. Each of these methods may be overridden if the
100 collection being implemented admits a more efficient implementation.
102 This class is a member of the <a href="/../guide/collections/index.html"> Java
103 Collections Framework.
107 *java.util.AbstractList()*
109 protected AbstractList()
111 Sole constructor. (For invocation by subclass constructors, typically
115 *java.util.AbstractList.add(E)*
117 public boolean add(java.lang.Object o)
119 Appends the specified element to the end of this List (optional operation).
121 This implementation calls add(size(), o).
123 Note that this implementation throws an UnsupportedOperationException unless
124 add(int, Object) is overridden.
126 o - element to be appended to this list.
128 Returns: true (as per the general contract of Collection.add).
129 *java.util.AbstractList.add(int,E)*
133 java.lang.Object element)
135 Inserts the specified element at the specified position in this list (optional
136 operation). Shifts the element currently at that position (if any) and any
137 subsequent elements to the right (adds one to their indices).
139 This implementation always throws an UnsupportedOperationException.
141 index - index at which the specified element is to be inserted.
142 element - element to be inserted.
144 *java.util.AbstractList.addAll(int,Collection)*
146 public boolean addAll(
148 java.util.Collection c)
150 Inserts all of the elements in the specified collection into this list at the
151 specified position (optional operation). Shifts the element currently at that
152 position (if any) and any subsequent elements to the right (increases their
153 indices). The new elements will appear in the list in the order that they are
154 returned by the specified collection's iterator. The behavior of this operation
155 is unspecified if the specified collection is modified while the operation is
156 in progress. (Note that this will occur if the specified collection is this
157 list, and it's nonempty.)
159 This implementation gets an iterator over the specified collection and iterates
160 over it, inserting the elements obtained from the iterator into this list at
161 the appropriate position, one at a time, using add(int, Object). Many
162 implementations will override this method for efficiency.
164 Note that this implementation throws an UnsupportedOperationException unless
165 add(int, Object) is overridden.
167 index - index at which to insert the first element from the specified collection.
168 c - elements to be inserted into this List.
170 Returns: true if this list changed as a result of the call.
171 *java.util.AbstractList.clear()*
175 Removes all of the elements from this collection (optional operation). The
176 collection will be empty after this call returns (unless it throws an
179 This implementation calls removeRange(0, size()).
181 Note that this implementation throws an UnsupportedOperationException unless
182 remove(int index) or removeRange(int fromIndex, int toIndex) is overridden.
185 *java.util.AbstractList.equals(Object)*
187 public boolean equals(java.lang.Object o)
189 Compares the specified object with this list for equality. Returns true if and
190 only if the specified object is also a list, both lists have the same size, and
191 all corresponding pairs of elements in the two lists are equal. (Two elements
192 e1 and e2 are equal if (e1==null ? e2==null : e1.equals(e2)).) In other words,
193 two lists are defined to be equal if they contain the same elements in the same
196 This implementation first checks if the specified object is this list. If so,
197 it returns true; if not, it checks if the specified object is a list. If not,
198 it returns false; if so, it iterates over both lists, comparing corresponding
199 pairs of elements. If any comparison returns false, this method returns false.
200 If either iterator runs out of elements before the other it returns false (as
201 the lists are of unequal length); otherwise it returns true when the iterations
204 o - the object to be compared for equality with this list.
206 Returns: true if the specified object is equal to this list.
207 *java.util.AbstractList.get(int)*
209 public abstract |java.lang.Object| get(int index)
211 Returns the element at the specified position in this list.
213 index - index of element to return.
215 Returns: the element at the specified position in this list.
216 *java.util.AbstractList.hashCode()*
218 public int hashCode()
220 Returns the hash code value for this list.
222 This implementation uses exactly the code that is used to define the list hash
223 function in the documentation for the List.hashCode method.
226 Returns: the hash code value for this list.
227 *java.util.AbstractList.indexOf(Object)*
229 public int indexOf(java.lang.Object o)
231 Returns the index in this list of the first occurence of the specified element,
232 or -1 if the list does not contain this element. More formally, returns the
233 lowest index i such that (o==null ? get(i)==null : o.equals(get(i))), or -1 if
234 there is no such index.
236 This implementation first gets a list iterator (with listIterator()). Then, it
237 iterates over the list until the specified element is found or the end of the
240 o - element to search for.
242 Returns: the index in this List of the first occurence of the specified element, or -1
243 if the List does not contain this element.
244 *java.util.AbstractList.iterator()*
246 public |java.util.Iterator| iterator()
248 Returns an iterator over the elements in this list in proper sequence.
250 This implementation returns a straightforward implementation of the iterator
251 interface, relying on the backing list's size(), get(int), and remove(int)
254 Note that the iterator returned by this method will throw an
255 UnsupportedOperationException in response to its remove method unless the
256 list's remove(int) method is overridden.
258 This implementation can be made to throw runtime exceptions in the face of
259 concurrent modification, as described in the specification for the (protected)
263 Returns: an iterator over the elements in this list in proper sequence.
264 *java.util.AbstractList.lastIndexOf(Object)*
266 public int lastIndexOf(java.lang.Object o)
268 Returns the index in this list of the last occurence of the specified element,
269 or -1 if the list does not contain this element. More formally, returns the
270 highest index i such that (o==null ? get(i)==null : o.equals(get(i))), or -1 if
271 there is no such index.
273 This implementation first gets a list iterator that points to the end of the
274 list (with listIterator(size())). Then, it iterates backwards over the list
275 until the specified element is found, or the beginning of the list is reached.
277 o - element to search for.
279 Returns: the index in this list of the last occurence of the specified element, or -1 if
280 the list does not contain this element.
281 *java.util.AbstractList.listIterator()*
283 public |java.util.ListIterator| listIterator()
285 Returns an iterator of the elements in this list (in proper sequence). This
286 implementation returns listIterator(0).
289 Returns: an iterator of the elements in this list (in proper sequence).
290 *java.util.AbstractList.listIterator(int)*
292 public |java.util.ListIterator| listIterator(int index)
294 Returns a list iterator of the elements in this list (in proper sequence),
295 starting at the specified position in the list. The specified index indicates
296 the first element that would be returned by an initial call to the next method.
297 An initial call to the previous method would return the element with the
298 specified index minus one.
300 This implementation returns a straightforward implementation of the
301 ListIterator interface that extends the implementation of the Iterator
302 interface returned by the iterator() method. The ListIterator implementation
303 relies on the backing list's get(int), set(int, Object), add(int, Object) and
306 Note that the list iterator returned by this implementation will throw an
307 UnsupportedOperationException in response to its remove, set and add methods
308 unless the list's remove(int), set(int, Object), and add(int, Object) methods
311 This implementation can be made to throw runtime exceptions in the face of
312 concurrent modification, as described in the specification for the (protected)
315 index - index of the first element to be returned from the list iterator (by a call to
318 Returns: a list iterator of the elements in this list (in proper sequence), starting at
319 the specified position in the list.
320 *java.util.AbstractList.remove(int)*
322 public |java.lang.Object| remove(int index)
324 Removes the element at the specified position in this list (optional
325 operation). Shifts any subsequent elements to the left (subtracts one from
326 their indices). Returns the element that was removed from the list.
328 This implementation always throws an UnsupportedOperationException.
330 index - the index of the element to remove.
332 Returns: the element previously at the specified position.
333 *java.util.AbstractList.removeRange(int,int)*
335 protected void removeRange(
339 Removes from this list all of the elements whose index is between fromIndex,
340 inclusive, and toIndex, exclusive. Shifts any succeeding elements to the left
341 (reduces their index). This call shortens the ArrayList by (toIndex -
342 fromIndex) elements. (If toIndex==fromIndex, this operation has no effect.)
344 This method is called by the clear operation on this list and its subLists.
345 Overriding this method to take advantage of the internals of the list
346 implementation can substantially improve the performance of the clear operation
347 on this list and its subLists.
349 This implementation gets a list iterator positioned before fromIndex, and
350 repeatedly calls ListIterator.next followed by ListIterator.remove until the
351 entire range has been removed. Note: if ListIterator.remove requires linear
352 time, this implementation requires quadratic time.
354 fromIndex - index of first element to be removed.
355 toIndex - index after last element to be removed.
357 *java.util.AbstractList.set(int,E)*
359 public |java.lang.Object| set(
361 java.lang.Object element)
363 Replaces the element at the specified position in this list with the specified
364 element (optional operation).
366 This implementation always throws an UnsupportedOperationException.
368 index - index of element to replace.
369 element - element to be stored at the specified position.
371 Returns: the element previously at the specified position.
372 *java.util.AbstractList.subList(int,int)*
374 public |java.util.List| subList(
378 Returns a view of the portion of this list between fromIndex, inclusive, and
379 toIndex, exclusive. (If fromIndex and toIndex are equal, the returned list is
380 empty.) The returned list is backed by this list, so changes in the returned
381 list are reflected in this list, and vice-versa. The returned list supports all
382 of the optional list operations supported by this list.
384 This method eliminates the need for explicit range operations (of the sort that
385 commonly exist for arrays). Any operation that expects a list can be used as a
386 range operation by operating on a subList view instead of a whole list. For
387 example, the following idiom removes a range of elements from a list:
389 list.subList(from, to).clear();
391 Similar idioms may be constructed for indexOf and lastIndexOf, and all of the
392 algorithms in the Collections class can be applied to a subList.
394 The semantics of the list returned by this method become undefined if the
395 backing list (i.e., this list) is structurally modified in any way other than
396 via the returned list. (Structural modifications are those that change the size
397 of the list, or otherwise perturb it in such a fashion that iterations in
398 progress may yield incorrect results.)
400 This implementation returns a list that subclasses AbstractList. The subclass
401 stores, in private fields, the offset of the subList within the backing list,
402 the size of the subList (which can change over its lifetime), and the expected
403 modCount value of the backing list. There are two variants of the subclass, one
404 of which implements RandomAccess. If this list implements RandomAccess the
405 returned list will be an instance of the subclass that implements RandomAccess.
407 The subclass's set(int, Object), get(int), add(int, Object), remove(int),
408 addAll(int, Collection) and removeRange(int, int) methods all delegate to the
409 corresponding methods on the backing abstract list, after bounds-checking the
410 index and adjusting for the offset. The addAll(Collection c) method merely
411 returns addAll(size, c).
413 The listIterator(int) method returns a "wrapper object" over a list iterator on
414 the backing list, which is created with the corresponding method on the backing
415 list. The iterator method merely returns listIterator(), and the size method
416 merely returns the subclass's size field.
418 All methods first check to see if the actual modCount of the backing list is
419 equal to its expected value, and throw a ConcurrentModificationException if it
422 fromIndex - low endpoint (inclusive) of the subList.
423 toIndex - high endpoint (exclusive) of the subList.
425 Returns: a view of the specified range within this list.