diff options
Diffstat (limited to 'libjava/java/util/AbstractSequentialList.java')
| -rw-r--r-- | libjava/java/util/AbstractSequentialList.java | 176 |
1 files changed, 134 insertions, 42 deletions
diff --git a/libjava/java/util/AbstractSequentialList.java b/libjava/java/util/AbstractSequentialList.java index 81481be0466..2267b02e523 100644 --- a/libjava/java/util/AbstractSequentialList.java +++ b/libjava/java/util/AbstractSequentialList.java @@ -1,5 +1,5 @@ /* AbstractSequentialList.java -- List implementation for sequential access - Copyright (C) 1998, 1999, 2000 Free Software Foundation, Inc. + Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -25,100 +25,192 @@ This exception does not however invalidate any other reasons why the executable file might be covered by the GNU General Public License. */ -// TO DO: -// ~ Lots of doc comments still missing. -// ~ The class comment should include a description of what should be overridden -// to provide what features, as should the listIterator comment. - package java.util; /** * Abstract superclass to make it easier to implement the List interface when - * backed by a sequential-access store, such as a linked list. + * backed by a sequential-access store, such as a linked list. For random + * access data, use AbstractList. This class implements the random access + * methods (<code>get</code>, <code>set</code>, <code>add</code>, and + * <code>remove</code>) atop the list iterator, opposite of AbstractList's + * approach of implementing the iterator atop random access. + * <p> + * + * To implement a list, you need an implementation for <code>size()</code> + * and <code>listIterator</code>. With just <code>hasNext</code>, + * <code>next</code>, <code>hasPrevious</code>, <code>previous</code>, + * <code>nextIndex</code>, and <code>previousIndex</code>, you have an + * unmodifiable list. For a modifiable one, add <code>set</code>, and for + * a variable-size list, add <code>add</code> and <code>remove</code>. + * <p> + * + * The programmer should provide a no-argument constructor, and one that + * accepts another Collection, as recommended by the Collection interface. + * Unfortunately, there is no way to enforce this in Java. + * + * @author Original author unknown + * @author Bryce McKinlay + * @author Eric Blake <ebb9@email.byu.edu> + * @see Collection + * @see List + * @see AbstractList + * @see AbstractCollection + * @see ListIterator + * @see LinkedList + * @since 1.2 + * @status updated to 1.4 */ public abstract class AbstractSequentialList extends AbstractList { /** + * The main constructor, for use by subclasses. + */ + protected AbstractSequentialList() + { + } + + /** * Returns a ListIterator over the list, starting from position index. * Subclasses must provide an implementation of this method. * - * @exception IndexOutOfBoundsException if index < 0 || index > size() + * @param index the starting position of the list + * @return the list iterator + * @throws IndexOutOfBoundsException if index < 0 || index > size() */ public abstract ListIterator listIterator(int index); /** - * Add an element to the list at a given index. This implementation obtains a - * ListIterator positioned at the specified index, and then adds the element - * using the ListIterator's add method. + * Insert an element into the list at a given position (optional operation). + * This shifts all existing elements from that position to the end one + * index to the right. This version of add has no return, since it is + * assumed to always succeed if there is no exception. This iteration + * uses listIterator(index).add(o). * - * @param index the position to add the element - * @param o the element to insert - * @exception IndexOutOfBoundsException if index < 0 || index > size() - * @exception UnsupportedOperationException if the iterator returned by - * listIterator(index) does not support the add method. + * @param index the location to insert the item + * @param o the object to insert + * @throws UnsupportedOperationException if this list does not support the + * add operation + * @throws IndexOutOfBoundsException if index < 0 || index > size() + * @throws ClassCastException if o cannot be added to this list due to its + * type + * @throws IllegalArgumentException if o cannot be added to this list for + * some other reason */ public void add(int index, Object o) { - ListIterator i = listIterator(index); - i.add(o); + listIterator(index).add(o); } /** - * @specnote The spec in the JDK1.3 online docs is wrong. The implementation - * should not call next() to skip over new elements as they are - * added, because iterator.add() should add new elements BEFORE - * the cursor. + * Insert the contents of a collection into the list at a given position + * (optional operation). Shift all elements at that position to the right + * by the number of elements inserted. This operation is undefined if + * this list is modified during the operation (for example, if you try + * to insert a list into itself). + * <p> + * + * This implementation grabs listIterator(index), then proceeds to use add + * for each element returned by c's iterator. Sun's online specs are wrong, + * claiming that this also calls next(): listIterator.add() correctly + * skips the added element. + * + * @param index the location to insert the collection + * @param c the collection to insert + * @return true if the list was modified by this action, that is, if c is + * non-empty + * @throws UnsupportedOperationException if this list does not support the + * addAll operation + * @throws IndexOutOfBoundsException if index < 0 || index > size() + * @throws ClassCastException if some element of c cannot be added to this + * list due to its type + * @throws IllegalArgumentException if some element of c cannot be added + * to this list for some other reason + * @throws NullPointerException if the specified collection is null + * @see #add(int, Object) */ public boolean addAll(int index, Collection c) { - boolean modified = false; Iterator ci = c.iterator(); int size = c.size(); ListIterator i = listIterator(index); - for (int pos = 0; pos < size; pos++) - { - i.add(ci.next()); - } - return (size > 0); + for (int pos = size; pos > 0; pos--) + i.add(ci.next()); + return size > 0; } + /** + * Get the element at a given index in this list. This implementation + * returns listIterator(index).next(). + * + * @param index the index of the element to be returned + * @return the element at index index in this list + * @throws IndexOutOfBoundsException if index < 0 || index >= size() + */ public Object get(int index) { - ListIterator i = listIterator(index); - if (index < 0 || index > size()) - throw new IndexOutOfBoundsException("Index: " + index + ", Size:" + - size()); - return i.next(); + // This is a legal listIterator position, but an illegal get. + if (index == size()) + throw new IndexOutOfBoundsException("Index: " + index + ", Size:" + + size()); + return listIterator(index).next(); } /** - * Return an Iterator over this List. This implementation returns - * listIterator(). + * Obtain an Iterator over this list, whose sequence is the list order. This + * implementation returns listIterator(). * - * @return an Iterator over this List + * @return an Iterator over the elements of this list, in order */ public Iterator iterator() { return listIterator(); } + /** + * Remove the element at a given position in this list (optional operation). + * Shifts all remaining elements to the left to fill the gap. This + * implementation uses listIterator(index) and ListIterator.remove(). + * + * @param index the position within the list of the object to remove + * @return the object that was removed + * @throws UnsupportedOperationException if this list does not support the + * remove operation + * @throws IndexOutOfBoundsException if index < 0 || index >= size() + */ public Object remove(int index) { + // This is a legal listIterator position, but an illegal remove. + if (index == size()) + throw new IndexOutOfBoundsException("Index: " + index + ", Size:" + + size()); ListIterator i = listIterator(index); - if (index < 0 || index > size()) - throw new IndexOutOfBoundsException("Index: " + index + ", Size:" + - size()); Object removed = i.next(); i.remove(); return removed; } + /** + * Replace an element of this list with another object (optional operation). + * This implementation uses listIterator(index) and ListIterator.set(o). + * + * @param index the position within this list of the element to be replaced + * @param o the object to replace it with + * @return the object that was replaced + * @throws UnsupportedOperationException if this list does not support the + * set operation + * @throws IndexOutOfBoundsException if index < 0 || index >= size() + * @throws ClassCastException if o cannot be added to this list due to its + * type + * @throws IllegalArgumentException if o cannot be added to this list for + * some other reason + */ public Object set(int index, Object o) { + // This is a legal listIterator position, but an illegal set. + if (index == size()) + throw new IndexOutOfBoundsException("Index: " + index + ", Size:" + + size()); ListIterator i = listIterator(index); - if (index < 0 || index > size()) - throw new IndexOutOfBoundsException("Index: " + index + ", Size:" + - size()); Object old = i.next(); i.set(o); return old; |
