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

Diff of /classpath/java/util/List.java

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

revision 1.6 by bryce, Sun Nov 26 22:37:22 2000 UTC revision 1.7 by ericb, Mon Oct 15 14:53:51 2001 UTC
# Line 1  Line 1 
1  /* List.java -- An ordered collection which allows indexed access  /* List.java -- An ordered collection which allows indexed access
2     Copyright (C) 1998 Free Software Foundation, Inc.     Copyright (C) 1998, 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:  
 // ~ Doc comment for the interface itself needs to be put into english.  
 // ~ Some more @see clauses might be nice.  
   
28  package java.util;  package java.util;
29    
30  /**  /**
31   * [This is what this doc comment will mention:   * An ordered collection (also known as a list). This collection allows
32   * ~ Additional restrictions on some methods. Others included for completeness.   * access to elements by position, as well as control on where elements
33   * ~ ListIterator and what it can do   * are inserted. Unlike sets, duplicate elements are permitted by this
34   * ~ Positional and iterated access   * general contract (if a subclass forbids duplicates, this should be
35   * ~ search (but linear time)   * documented).
36   * ~ be careful when containing self as an element, because equals and hashCode   * <p>
37   *   loop.]   *
38     * List places additional requirements on <code>iterator</code>,
39     * <code>add</code>, <code>remove</code>, <code>equals</code>, and
40     * <code>hashCode</code>, in addition to requiring more methods. List
41     * indexing is 0-based (like arrays), although some implementations may
42     * require time proportional to the index to obtain an arbitrary element.
43     * The List interface is incompatible with Set; you cannot implement both
44     * simultaneously.
45     * <p>
46     *
47     * Lists also provide a <code>ListIterator</code> which allows bidirectional
48     * traversal and other features atop regular iterators. Lists can be
49     * searched for arbitrary elements, and allow easy insertion and removal
50     * of multiple elements in one method call.
51     * <p>
52     *
53     * Note: While lists may contain themselves as elements, this leads to
54     * undefined (usually infinite recursive) behavior for some methods like
55     * hashCode or equals.
56     *
57     * @author Original author unknown
58     * @author Eric Blake <ebb9@email.byu.edu>
59     * @see Collection
60     * @see Set
61     * @see ArrayList
62     * @see LinkedList
63     * @see Vector
64     * @see Arrays#asList(Object[])
65     * @see Collections#nCopies(int, Object)
66     * @see Collections#EMPTY_LIST
67     * @see AbstractList
68     * @see AbstractSequentialList
69     * @since 1.2
70     * @status updated to 1.4
71   */   */
72  public interface List extends Collection  public interface List extends Collection
73  {  {
74    /**    /**
75     * Insert an element into the list at a given position.     * Insert an element into the list at a given position (optional operation).
76     *     * This shifts all existing elements from that position to the end one
77     * @param index the location to insert the item.     * index to the right. This version of add has no return, since it is
78     * @param o the object to insert.     * assumed to always succeed if there is no exception.
79     * @exception UnsupportedOperationException if this list does not support the     *
80     *   add operation.     * @param index the location to insert the item
81     * @exception IndexOutOfBoundsException if index < 0 || index > size()     * @param o the object to insert
82     * @exception ClassCastException if o cannot be added to this list due to its     * @throws UnsupportedOperationException if this list does not support the
83     *   type.     *         add operation
84     * @exception IllegalArgumentException if o cannot be added to this list for     * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
85     *   some other reason.     * @throws ClassCastException if o cannot be added to this list due to its
86       *         type
87       * @throws IllegalArgumentException if o cannot be added to this list for
88       *         some other reason
89     */     */
90    void add(int index, Object o);    void add(int index, Object o);
91    
92    /**    /**
93     * Add an element to the end of the list.     * Add an element to the end of the list (optional operation). If the list
94     *     * imposes restraints on what can be inserted, such as no null elements,
95     * @param o the object to add.     * this should be documented.
96     * @returns true, as Collection defines this method as returning true if the     *
97     *   list was modified as a result of this action, and it always is for a     * @param o the object to add
98     *   list.     * @return true, as defined by Collection for a modified list
99     * @exception UnsupportedOperationException if this list does not support the     * @throws UnsupportedOperationException if this list does not support the
100     *   add operation.     *         add operation
101     * @exception ClassCastException if o cannot be added to this list due to its     * @throws ClassCastException if o cannot be added to this list due to its
102     *   type.     *         type
103     * @exception IllegalArgumentException if o cannot be added to this list for     * @throws IllegalArgumentException if o cannot be added to this list for
104     *   some other reason.     *         some other reason
105     */     */
106    boolean add(Object o);    boolean add(Object o);
107    
108    /**    /**
109     * Insert the contents of a collection into the list at a given position.     * Insert the contents of a collection into the list at a given position
110     *     * (optional operation). Shift all elements at that position to the right
111     * @param index the location to insert the collection.     * by the number of elements inserted. This operation is undefined if
112     * @param c the collection to insert.     * this list is modified during the operation (for example, if you try
113     * @returns true if the list was modified by this action, that is, if c is     * to insert a list into itself).
114     *   non-empty.     *
115     * @exception UnsupportedOperationException if this list does not support the     * @param index the location to insert the collection
116     *   addAll operation.     * @param c the collection to insert
117     * @exception IndexOutOfBoundsException if index < 0 || index > size()     * @return true if the list was modified by this action, that is, if c is
118     * @exception ClassCastException if some element of c cannot be added to this     *         non-empty
119     *   list due to its type.     * @throws UnsupportedOperationException if this list does not support the
120     * @exception IllegalArgumentException if some element of c cannot be added     *         addAll operation
121     *   to this list for some other reason.     * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
122       * @throws ClassCastException if some element of c cannot be added to this
123       *         list due to its type
124       * @throws IllegalArgumentException if some element of c cannot be added
125       *         to this list for some other reason
126       * @throws NullPointerException if the specified collection is null
127       * @see #add(int, Object)
128     */     */
129    boolean addAll(int index, Collection c);    boolean addAll(int index, Collection c);
130    
131    /**    /**
132     * Add the contents of a collection to the end of the list.     * Add the contents of a collection to the end of the list (optional
133     *     * operation).  This operation is undefined if this list is modified
134     * @param c the collection to add.     * during the operation (for example, if you try to insert a list into
135     * @returns true if the list was modified by this action, that is, if c is     * itself).
136     *   non-empty.     *
137     * @exception UnsupportedOperationException if this list does not support the     * @param c the collection to add
138     *   addAll operation.     * @return true if the list was modified by this action, that is, if c is
139     * @exception ClassCastException if some element of c cannot be added to this     *         non-empty
140     *   list due to its type.     * @throws UnsupportedOperationException if this list does not support the
141     * @exception IllegalArgumentException if some element of c cannot be added     *         addAll operation
142     *   to this list for some other reason.     * @throws ClassCastException if some element of c cannot be added to this
143       *         list due to its type
144       * @throws IllegalArgumentException if some element of c cannot be added
145       *         to this list for some other reason
146       * @throws NullPointerException if the specified collection is null
147       * @see #add(Object)
148     */     */
149    boolean addAll(Collection c);    boolean addAll(Collection c);
150    
151    /**    /**
152     * Clear the list, such that a subsequent call to isEmpty() would return     * Clear the list, such that a subsequent call to isEmpty() would return
153     * true.     * true (optional operation).
154     *     *
155     * @exception UnsupportedOperationException if this list does not support the     * @throws UnsupportedOperationException if this list does not support the
156     *   clear operation.     *         clear operation
157     */     */
158    void clear();    void clear();
159    
160    /**    /**
161     * Test whether this list contains a given object as one of its elements.     * Test whether this list contains a given object as one of its elements.
162       * This is defined as the existence of an element e such that
163       * <code>o == null ? e == null : o.equals(e)</code>.
164     *     *
165     * @param o the element to look for.     * @param o the element to look for
166     * @returns true if this list contains an element e such that <code>o ==     * @return true if this list contains the element
    *   null ? e == null : o.equals(e)</code>.  
167     */     */
168    boolean contains(Object o);    boolean contains(Object o);
169    
170    /**    /**
171     * Test whether this list contains every element in a given collection.     * Test whether this list contains every element in a given collection.
172     *     *
173     * @param c the collection to test for.     * @param c the collection to test for
174     * @returns true if for every element o in c, contains(o) would return true.     * @return true if for every element o in c, contains(o) would return true
175       * @throws NullPointerException if the collection is null
176       * @see #contains(Object)
177     */     */
178    boolean containsAll(Collection c);    boolean containsAll(Collection c);
179    
180    /**    /**
181     * Test whether this list is equal to another object. A List is defined to be     * Test whether this list is equal to another object. A List is defined to be
182     * equal to an object if and only if that object is also a List, and the two     * equal to an object if and only if that object is also a List, and the two
183     * lists are equal. Two lists l1 and l2 are defined to be equal if and only     * lists have the same sequence. Two lists l1 and l2 are equal if and only
184     * if <code>l1.size() == l2.size()</code>, and for every integer n between 0     * if <code>l1.size() == l2.size()</code>, and for every integer n between 0
185     * and <code>l1.size() - 1</code> inclusive, <code>l1.get(n) == null ?     * and <code>l1.size() - 1</code> inclusive, <code>l1.get(n) == null ?
186     * l2.get(n) == null : l1.get(n).equals(l2.get(n))</code>.     * l2.get(n) == null : l1.get(n).equals(l2.get(n))</code>.
187     *     *
188     * @param o the object to test for equality with this list.     * @param o the object to test for equality with this list
189     * @returns true if o is equal to this list.     * @return true if o is equal to this list
190       * @see Object#equals(Object)
191       * @see #hashCode()
192     */     */
193    boolean equals(Object o);    boolean equals(Object o);
194    
195    /**    /**
196     * Get the element at a given index in this list.     * Get the element at a given index in this list.
197     *     *
198     * @param index the index of the element to be returned.     * @param index the index of the element to be returned
199     * @returns the element at index index in this list.     * @return the element at index index in this list
200     * @exception IndexOutOfBoundsException if index < 0 || index >= size()     * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
201     */     */
202    Object get(int index);    Object get(int index);
203    
# Line 159  public interface List extends Collection Line 207  public interface List extends Collection
207     * <pre>     * <pre>
208     *   hashCode = 1;     *   hashCode = 1;
209     *   Iterator i = list.iterator();     *   Iterator i = list.iterator();
210     *   while (i.hasNext()) {     *   while (i.hasNext())
211     *     Object obj = i.next();     *     {
212     *     hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode());     *       Object obj = i.next();
213     *   }     *       hashCode = 31 * hashCode + (obj == null ? 0 : obj.hashCode());
214       *     }
215     * </pre>     * </pre>
216     * This ensures that the general contract of Object.hashCode() is adhered to.     * This ensures that the general contract of Object.hashCode() is adhered to.
217     *     *
218     * @returns the hash code of this list.     * @return the hash code of this list
219       * @see Object#hashCode()
220       * @see #equals(Object)
221     */     */
222    int hashCode();    int hashCode();
223    
# Line 174  public interface List extends Collection Line 225  public interface List extends Collection
225     * Obtain the first index at which a given object is to be found in this     * Obtain the first index at which a given object is to be found in this
226     * list.     * list.
227     *     *
228     * @returns the least integer n such that <code>o == null ? get(n) == null :     * @param o the object to search for
229     *   o.equals(get(n))</code>, or -1 if there is no such index.     * @return the least integer n such that <code>o == null ? get(n) == null :
230       *         o.equals(get(n))</code>, or -1 if there is no such index
231     */     */
232    int indexOf(Object o);    int indexOf(Object o);
233    
234    /**    /**
235     * Test whether this list is empty, that is, if size() == 0.     * Test whether this list is empty, that is, if size() == 0.
236     *     *
237     * @returns true if this list contains no elements.     * @return true if this list contains no elements
238     */     */
239    boolean isEmpty();    boolean isEmpty();
240    
241    /**    /**
242     * Obtain an Iterator over this list.     * Obtain an Iterator over this list, whose sequence is the list order.
243     *     *
244     * @returns an Iterator over the elements of this list, in order.     * @return an Iterator over the elements of this list, in order
245     */     */
246    Iterator iterator();    Iterator iterator();
247    
# Line 197  public interface List extends Collection Line 249  public interface List extends Collection
249     * Obtain the last index at which a given object is to be found in this     * Obtain the last index at which a given object is to be found in this
250     * list.     * list.
251     *     *
252     * @returns the greatest integer n such that <code>o == null ? get(n) == null     * @return the greatest integer n such that <code>o == null ? get(n) == null
253     *   : o.equals(get(n))</code>.     *         : o.equals(get(n))</code>, or -1 if there is no such index
254     */     */
255    int lastIndexOf(Object o);    int lastIndexOf(Object o);
256    
257    /**    /**
258     * Obtain a ListIterator over this list, starting at the beginning.     * Obtain a ListIterator over this list, starting at the beginning.
259     *     *
260     * @returns a ListIterator over the elements of this list, in order, starting     * @return a ListIterator over the elements of this list, in order, starting
261     *   at the beginning.     *         at the beginning
262     */     */
263    ListIterator listIterator();    ListIterator listIterator();
264    
265    /**    /**
266     * Obtain a ListIterator over this list, starting at a given position.     * Obtain a ListIterator over this list, starting at a given position.
267       * A first call to next() would return the same as get(index), and a
268       * first call to previous() would return the same as get(index - 1).
269     *     *
270     * @param index the position, between 0 and size() inclusive, to begin the     * @param index the position, between 0 and size() inclusive, to begin the
271     *   iteration from.     *        iteration from
272     * @returns a ListIterator over the elements of this list, in order, starting     * @return a ListIterator over the elements of this list, in order, starting
273     *   at index.     *         at index
274     * @exception IndexOutOfBoundsException if index < 0 || index > size()     * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
275     */     */
276    ListIterator listIterator(int index);    ListIterator listIterator(int index);
277    
278    /**    /**
279     * Remove the element at a given position in this list.     * Remove the element at a given position in this list (optional operation).
280       * Shifts all remaining elements to the left to fill the gap.
281     *     *
282     * @param index the position within the list of the object to remove.     * @param index the position within the list of the object to remove
283     * @returns the object that was removed.     * @return the object that was removed
284     * @exception UnsupportedOperationException if this list does not support the     * @throws UnsupportedOperationException if this list does not support the
285     *   remove operation.     *         remove operation
286     * @exception IndexOutOfBoundsException if index < 0 || index > size()     * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
287     */     */
288    Object remove(int index);    Object remove(int index);
289    
290    /**    /**
291     * Remove the first occurence of an object from this list. That is, remove     * Remove the first occurence of an object from this list (optional
292     * the first element e such that <code>o == null ? e == null :     * operation). That is, remove the first element e such that
293     * o.equals(e)</code>.     * <code>o == null ? e == null : o.equals(e)</code>.
294     *     *
295     * @param o the object to remove.     * @param o the object to remove
296     * @returns true if the list changed as a result of this call, that is, if     * @return true if the list changed as a result of this call, that is, if
297     *   the list contained at least one occurrence of o.     *         the list contained at least one occurrence of o
298     * @exception UnsupportedOperationException if this list does not support the     * @throws UnsupportedOperationException if this list does not support the
299     *   remove operation.     *         remove operation
300     */     */
301    boolean remove(Object o);    boolean remove(Object o);
302    
303    /**    /**
304     * Remove all elements of a given collection from this list. That is, remove     * Remove all elements of a given collection from this list (optional
305     * every element e such that c.contains(e).     * operation). That is, remove every element e such that c.contains(e).
306     *     *
307     * @returns true if this list was modified as a result of this call.     * @param c the collection to filter out
308     * @exception UnsupportedOperationException if this list does not support the     * @return true if this list was modified as a result of this call
309     *   removeAll operation.     * @throws UnsupportedOperationException if this list does not support the
310       *         removeAll operation
311       * @throws NullPointerException if the collection is null
312       * @see #remove(Object)
313       * @see #contains(Object)
314     */     */
315    boolean removeAll(Collection c);    boolean removeAll(Collection c);
316    
317    /**    /**
318     * Remove all elements of this list that are not contained in a given     * Remove all elements of this list that are not contained in a given
319     * collection. That is, remove every element e such that !c.contains(e).     * collection (optional operation). That is, remove every element e such
320       * that !c.contains(e).
321     *     *
322     * @returns true if this list was modified as a result of this call.     * @param c the collection to retain
323     * @exception UnsupportedOperationException if this list does not support the     * @return true if this list was modified as a result of this call
324     *   retainAll operation.     * @throws UnsupportedOperationException if this list does not support the
325       *         retainAll operation
326       * @throws NullPointerException if the collection is null
327       * @see #remove(Object)
328       * @see #contains(Object)
329     */     */
330    boolean retainAll(Collection c);    boolean retainAll(Collection c);
331    
332    /**    /**
333     * Replace an element of this list with another object.     * Replace an element of this list with another object (optional operation).
334     *     *
335     * @param index the position within this list of the element to be replaced.     * @param index the position within this list of the element to be replaced
336     * @param o the object to replace it with.     * @param o the object to replace it with
337     * @returns the object that was replaced.     * @return the object that was replaced
338     * @exception UnsupportedOperationException if this list does not support the     * @throws UnsupportedOperationException if this list does not support the
339     *   set operation.     *         set operation
340     * @exception IndexOutOfBoundsException if index < 0 || index >= size()     * @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
341     * @exception ClassCastException if o cannot be added to this list due to its     * @throws ClassCastException if o cannot be added to this list due to its
342     *   type.     *         type
343     * @exception IllegalArgumentException if o cannot be added to this list for     * @throws IllegalArgumentException if o cannot be added to this list for
344     *   some other reason.     *         some other reason
345     */     */
346    Object set(int index, Object o);    Object set(int index, Object o);
347    
348    /**    /**
349     * Get the number of elements in this list.     * Get the number of elements in this list. If the list contains more
350       * than Integer.MAX_VALUE elements, return Integer.MAX_VALUE.
351     *     *
352     * @returns the number of elements in the list.     * @return the number of elements in the list
353     */     */
354    int size();    int size();
355    
356    /**    /**
357     * Obtain a List view of a subsection of this list, from fromIndex     * Obtain a List view of a subsection of this list, from fromIndex
358     * (inclusive) to toIndex (exclusive). The returned list should be modifiable     * (inclusive) to toIndex (exclusive). If the two indices are equal, the
359     * if and only if this list is modifiable. Changes to the returned list     * sublist is empty. The returned list should be modifiable if and only
360     * should be reflected in this list. If this list is structurally modified in     * if this list is modifiable. Changes to the returned list should be
361       * reflected in this list. If this list is structurally modified in
362     * any way other than through the returned list, the result of any subsequent     * any way other than through the returned list, the result of any subsequent
363     * operations on the returned list is undefined.     * operations on the returned list is undefined.
364     *     *
365     * @param fromIndex the index that the returned list should start from     * @param fromIndex the index that the returned list should start from
366     *    (inclusive).     *        (inclusive)
367     * @param toIndex the index that the returned list should go to (exclusive).     * @param toIndex the index that the returned list should go to (exclusive)
368     * @returns a List backed by a subsection of this list.     * @return a List backed by a subsection of this list
369     * @exception IndexOutOfBoundsException if fromIndex < 0 || toIndex > size()     * @throws IndexOutOfBoundsException if fromIndex &lt; 0
370     *   || fromIndex > toIndex.     *         || toIndex &gt; size() || fromIndex &gt; toIndex
371       * @throws IllegalArgumentException if fromIndex &gt; toIndex (according to
372       *         AbstractList). Don't you love Sun's inconsistent specifications?
373     */     */
374    List subList(int fromIndex, int toIndex);    List subList(int fromIndex, int toIndex);
375    
376    /**    /**
377     * Copy the current contents of this list into an array.     * Copy the current contents of this list into an array.
378     *     *
379     * @returns an array of type Object[] and length equal to the length of this     * @return an array of type Object[] and length equal to the length of this
380     *   list, containing the elements currently in this list, in order.     *         list, containing the elements currently in this list, in order
381     */     */
382    Object[] toArray();    Object[] toArray();
383    
# Line 323  public interface List extends Collection Line 391  public interface List extends Collection
391     * Note: The fact that the following element is set to null is only useful     * Note: The fact that the following element is set to null is only useful
392     * if it is known that this list does not contain any null elements.     * if it is known that this list does not contain any null elements.
393     *     *
394     * @param a the array to copy this list into.     * @param a the array to copy this list into
395     * @returns an array containing the elements currently in this list, in     * @return an array containing the elements currently in this list, in
396     *    order.     *         order
397     * @exception ArrayStoreException if the type of any element of the     * @throws ArrayStoreException if the type of any element of the
398     *   collection is not a subtype of the element type of a.     *         collection is not a subtype of the element type of a
399       * @throws NullPointerException if the specified array is null
400     */     */
401    Object[] toArray(Object[] a);    Object[] toArray(Object[] a);
402  }  }

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.7

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