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

Diff of /classpath/java/util/AbstractSequentialList.java

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

revision 1.12 by bryce, Thu Feb 15 06:26:31 2001 UTC revision 1.13 by ericb, Fri Oct 19 00:17:44 2001 UTC
# Line 1  Line 1 
1  /* AbstractSequentialList.java -- List implementation for sequential access  /* AbstractSequentialList.java -- List implementation for sequential access
2     Copyright (C) 1998, 1999, 2000 Free Software Foundation, Inc.     Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
3    
4  This file is part of GNU Classpath.  This file is part of GNU Classpath.
5    
# Line 25  This exception does not however invalida Line 25  This exception does not however invalida
25  executable file might be covered by the GNU General Public License. */  executable file might be covered by the GNU General Public License. */
26    
27    
 // 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.  
   
28  package java.util;  package java.util;
29    
30  /**  /**
31   * Abstract superclass to make it easier to implement the List interface when   * Abstract superclass to make it easier to implement the List interface when
32   * backed by a sequential-access store, such as a linked list.   * backed by a sequential-access store, such as a linked list. For random
33     * access data, use AbstractList. This class implements the random access
34     * methods (<code>get</code>, <code>set</code>, <code>add</code>, and
35     * <code>remove</code>) atop the list iterator, opposite of AbstractList's
36     * approach of implementing the iterator atop random access.
37     * <p>
38     *
39     * To implement a list, you need an implementation for <code>size()</code>
40     * and <code>listIterator</code>.  With just <code>hasNext</code>,
41     * <code>next</code>, <code>hasPrevious</code>, <code>previous</code>,
42     * <code>nextIndex</code>, and <code>previousIndex</code>, you have an
43     * unmodifiable list. For a modifiable one, add <code>set</code>, and for
44     * a variable-size list, add <code>add</code> and <code>remove</code>.
45     * <p>
46     *
47     * The programmer should provide a no-argument constructor, and one that
48     * accepts another Collection, as recommended by the Collection interface.
49     * Unfortunately, there is no way to enforce this in Java.
50     *
51     * @author Original author unknown
52     * @author Eric Blake <ebb9@email.byu.edu>
53     * @see Collection
54     * @see List
55     * @see AbstractList
56     * @see AbstractCollection
57     * @see ListIterator
58     * @see LinkedList
59     * @since 1.2
60     * @status updated to 1.4
61   */   */
62  public abstract class AbstractSequentialList extends AbstractList  public abstract class AbstractSequentialList extends AbstractList
63  {  {
64    /**    /**
65       * The main constructor, for use by subclasses.
66       */
67      protected AbstractSequentialList()
68      {
69      }
70    
71      /**
72     * Returns a ListIterator over the list, starting from position index.     * Returns a ListIterator over the list, starting from position index.
73     * Subclasses must provide an implementation of this method.     * Subclasses must provide an implementation of this method.
74     *     *
75     * @exception IndexOutOfBoundsException if index < 0 || index > size()     * @param index the starting position of the list
76       * @return the list iterator
77       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
78     */     */
79    public abstract ListIterator listIterator(int index);    public abstract ListIterator listIterator(int index);
80    
81    /**    /**
82     * Add an element to the list at a given index. This implementation obtains a     * Insert an element into the list at a given position (optional operation).
83     * ListIterator positioned at the specified index, and then adds the element     * This shifts all existing elements from that position to the end one
84     * using the ListIterator's add method.     * index to the right. This version of add has no return, since it is
85     *     * assumed to always succeed if there is no exception. This iteration
86     * @param index the position to add the element     * uses listIterator(index).add(o).
87     * @param o the element to insert     *
88     * @exception IndexOutOfBoundsException if index < 0 || index > size()     * @param index the location to insert the item
89     * @exception UnsupportedOperationException if the iterator returned by     * @param o the object to insert
90     *   listIterator(index) does not support the add method.     * @throws UnsupportedOperationException if this list does not support the
91       *         add operation
92       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
93       * @throws ClassCastException if o cannot be added to this list due to its
94       *         type
95       * @throws IllegalArgumentException if o cannot be added to this list for
96       *         some other reason
97     */     */
98    public void add(int index, Object o)    public void add(int index, Object o)
99    {    {
100      ListIterator i = listIterator(index);      listIterator(index).add(o);
     i.add(o);  
101    }    }
102    
103    /**    /**
104     * @specnote The spec in the JDK1.3 online docs is wrong. The implementation     * Insert the contents of a collection into the list at a given position
105     *           should not call next() to skip over new elements as they are     * (optional operation). Shift all elements at that position to the right
106     *           added, because iterator.add() should add new elements BEFORE     * by the number of elements inserted. This operation is undefined if
107     *           the cursor.     * this list is modified during the operation (for example, if you try
108       * to insert a list into itself).
109       * <p>
110       *
111       * This implementation grabs listIterator(index), then proceeds to use add
112       * for each element returned by c's iterator. Sun's online specs are wrong,
113       * claiming that this also calls next(): listIterator.add() correctly
114       * skips the added element.
115       *
116       * @param index the location to insert the collection
117       * @param c the collection to insert
118       * @return true if the list was modified by this action, that is, if c is
119       *         non-empty
120       * @throws UnsupportedOperationException if this list does not support the
121       *         addAll operation
122       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
123       * @throws ClassCastException if some element of c cannot be added to this
124       *         list due to its type
125       * @throws IllegalArgumentException if some element of c cannot be added
126       *         to this list for some other reason
127       * @throws NullPointerException if the specified collection is null
128       * @see #add(int, Object)
129     */     */
130    public boolean addAll(int index, Collection c)    public boolean addAll(int index, Collection c)
131    {    {
     boolean modified = false;  
132      Iterator ci = c.iterator();      Iterator ci = c.iterator();
133      int size = c.size();      int size = c.size();
134      ListIterator i = listIterator(index);      ListIterator i = listIterator(index);
135      for (int pos = 0; pos < size; pos++)      for (int pos = size; pos > 0; pos--)
136        {        i.add(ci.next());
137          i.add(ci.next());      return size > 0;
       }  
     return (size > 0);  
138    }    }
139    
140      /**
141       * Get the element at a given index in this list. This implementation
142       * returns listIterator(index).next().
143       *
144       * @param index the index of the element to be returned
145       * @return the element at index index in this list
146       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
147       */
148    public Object get(int index)    public Object get(int index)
149    {    {
150      ListIterator i = listIterator(index);      // This is a legal listIterator position, but an illegal get.
151      if (index < 0 || index > size())      if (index == size())
152        throw new IndexOutOfBoundsException("Index: " + index + ", Size:" +        throw new IndexOutOfBoundsException("Index: " + index + ", Size:"
153                                            size());                                            + size());
154      return i.next();      return listIterator(index).next();
155    }    }
156    
157    /**    /**
158     * Return an Iterator over this List. This implementation returns     * Obtain an Iterator over this list, whose sequence is the list order. This
159     * listIterator().     * implementation returns listIterator().
160     *     *
161     * @return an Iterator over this List     * @return an Iterator over the elements of this list, in order
162     */     */
163    public Iterator iterator()    public Iterator iterator()
164    {    {
165      return listIterator();      return listIterator();
166    }    }
167    
168      /**
169       * Remove the element at a given position in this list (optional operation).
170       * Shifts all remaining elements to the left to fill the gap. This
171       * implementation uses listIterator(index) and ListIterator.remove().
172       *
173       * @param index the position within the list of the object to remove
174       * @return the object that was removed
175       * @throws UnsupportedOperationException if this list does not support the
176       *         remove operation
177       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
178       */
179    public Object remove(int index)    public Object remove(int index)
180    {    {
181        // This is a legal listIterator position, but an illegal remove.
182        if (index == size())
183          throw new IndexOutOfBoundsException("Index: " + index + ", Size:"
184                                              + size());
185      ListIterator i = listIterator(index);      ListIterator i = listIterator(index);
     if (index < 0 || index > size())  
       throw new IndexOutOfBoundsException("Index: " + index + ", Size:" +  
                                           size());  
186      Object removed = i.next();      Object removed = i.next();
187      i.remove();      i.remove();
188      return removed;      return removed;
189    }    }
190    
191      /**
192       * Replace an element of this list with another object (optional operation).
193       * This implementation uses listIterator(index) and ListIterator.set(o).
194       *
195       * @param index the position within this list of the element to be replaced
196       * @param o the object to replace it with
197       * @return the object that was replaced
198       * @throws UnsupportedOperationException if this list does not support the
199       *         set operation
200       * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
201       * @throws ClassCastException if o cannot be added to this list due to its
202       *         type
203       * @throws IllegalArgumentException if o cannot be added to this list for
204       *         some other reason
205       */
206    public Object set(int index, Object o)    public Object set(int index, Object o)
207    {    {
208        // This is a legal listIterator position, but an illegal set.
209        if (index == size())
210          throw new IndexOutOfBoundsException("Index: " + index + ", Size:"
211                                              + size());
212      ListIterator i = listIterator(index);      ListIterator i = listIterator(index);
     if (index < 0 || index > size())  
       throw new IndexOutOfBoundsException("Index: " + index + ", Size:" +  
                                           size());  
213      Object old = i.next();      Object old = i.next();
214      i.set(o);      i.set(o);
215      return old;      return old;

Legend:
Removed from v.1.12  
changed lines
  Added in v.1.13

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