• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  *  Licensed to the Apache Software Foundation (ASF) under one or more
3  *  contributor license agreements.  See the NOTICE file distributed with
4  *  this work for additional information regarding copyright ownership.
5  *  The ASF licenses this file to You under the Apache License, Version 2.0
6  *  (the "License"); you may not use this file except in compliance with
7  *  the License.  You may obtain a copy of the License at
8  *
9  *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  *  Unless required by applicable law or agreed to in writing, software
12  *  distributed under the License is distributed on an "AS IS" BASIS,
13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  *  See the License for the specific language governing permissions and
15  *  limitations under the License.
16  */
17 
18 package java.util;
19 
20 
21 /**
22  * A {@code List} is a collection which maintains an ordering for its elements. Every
23  * element in the {@code List} has an index. Each element can thus be accessed by its
24  * index, with the first index being zero. Normally, {@code List}s allow duplicate
25  * elements, as compared to Sets, where elements have to be unique.
26  */
27 public interface List<E> extends Collection<E> {
28     /**
29      * Inserts the specified object into this {@code List} at the specified location.
30      * The object is inserted before the current element at the specified
31      * location. If the location is equal to the size of this {@code List}, the object
32      * is added at the end. If the location is smaller than the size of this
33      * {@code List}, then all elements beyond the specified location are moved by one
34      * position towards the end of the {@code List}.
35      *
36      * @param location
37      *            the index at which to insert.
38      * @param object
39      *            the object to add.
40      * @throws UnsupportedOperationException
41      *                if adding to this {@code List} is not supported.
42      * @throws ClassCastException
43      *                if the class of the object is inappropriate for this
44      *                {@code List}.
45      * @throws IllegalArgumentException
46      *                if the object cannot be added to this {@code List}.
47      * @throws IndexOutOfBoundsException
48      *                if {@code location < 0 || location > size()}
49      */
add(int location, E object)50     public void add(int location, E object);
51 
52     /**
53      * Adds the specified object at the end of this {@code List}.
54      *
55      * @param object
56      *            the object to add.
57      * @return always true.
58      * @throws UnsupportedOperationException
59      *                if adding to this {@code List} is not supported.
60      * @throws ClassCastException
61      *                if the class of the object is inappropriate for this
62      *                {@code List}.
63      * @throws IllegalArgumentException
64      *                if the object cannot be added to this {@code List}.
65      */
add(E object)66     public boolean add(E object);
67 
68     /**
69      * Inserts the objects in the specified collection at the specified location
70      * in this {@code List}. The objects are added in the order they are returned from
71      * the collection's iterator.
72      *
73      * @param location
74      *            the index at which to insert.
75      * @param collection
76      *            the collection of objects to be inserted.
77      * @return true if this {@code List} has been modified through the insertion, false
78      *         otherwise (i.e. if the passed collection was empty).
79      * @throws UnsupportedOperationException
80      *                if adding to this {@code List} is not supported.
81      * @throws ClassCastException
82      *                if the class of an object is inappropriate for this
83      *                {@code List}.
84      * @throws IllegalArgumentException
85      *                if an object cannot be added to this {@code List}.
86      * @throws IndexOutOfBoundsException
87      *                if {@code location < 0 || > size()}
88      */
addAll(int location, Collection<? extends E> collection)89     public boolean addAll(int location, Collection<? extends E> collection);
90 
91     /**
92      * Adds the objects in the specified collection to the end of this {@code List}. The
93      * objects are added in the order in which they are returned from the
94      * collection's iterator.
95      *
96      * @param collection
97      *            the collection of objects.
98      * @return {@code true} if this {@code List} is modified, {@code false} otherwise
99      *         (i.e. if the passed collection was empty).
100      * @throws UnsupportedOperationException
101      *                if adding to this {@code List} is not supported.
102      * @throws ClassCastException
103      *                if the class of an object is inappropriate for this
104      *                {@code List}.
105      * @throws IllegalArgumentException
106      *                if an object cannot be added to this {@code List}.
107      */
addAll(Collection<? extends E> collection)108     public boolean addAll(Collection<? extends E> collection);
109 
110     /**
111      * Removes all elements from this {@code List}, leaving it empty.
112      *
113      * @throws UnsupportedOperationException
114      *                if removing from this {@code List} is not supported.
115      * @see #isEmpty
116      * @see #size
117      */
clear()118     public void clear();
119 
120     /**
121      * Tests whether this {@code List} contains the specified object.
122      *
123      * @param object
124      *            the object to search for.
125      * @return {@code true} if object is an element of this {@code List}, {@code false}
126      *         otherwise
127      */
contains(Object object)128     public boolean contains(Object object);
129 
130     /**
131      * Tests whether this {@code List} contains all objects contained in the
132      * specified collection.
133      *
134      * @param collection
135      *            the collection of objects
136      * @return {@code true} if all objects in the specified collection are
137      *         elements of this {@code List}, {@code false} otherwise.
138      */
containsAll(Collection<?> collection)139     public boolean containsAll(Collection<?> collection);
140 
141     /**
142      * Compares the given object with the {@code List}, and returns true if they
143      * represent the <em>same</em> object using a class specific comparison. For
144      * {@code List}s, this means that they contain the same elements in exactly the same
145      * order.
146      *
147      * @param object
148      *            the object to compare with this object.
149      * @return boolean {@code true} if the object is the same as this object,
150      *         and {@code false} if it is different from this object.
151      * @see #hashCode
152      */
equals(Object object)153     public boolean equals(Object object);
154 
155     /**
156      * Returns the element at the specified location in this {@code List}.
157      *
158      * @param location
159      *            the index of the element to return.
160      * @return the element at the specified location.
161      * @throws IndexOutOfBoundsException
162      *                if {@code location < 0 || >= size()}
163      */
get(int location)164     public E get(int location);
165 
166     /**
167      * Returns the hash code for this {@code List}. It is calculated by taking each
168      * element' hashcode and its position in the {@code List} into account.
169      *
170      * @return the hash code of the {@code List}.
171      */
hashCode()172     public int hashCode();
173 
174     /**
175      * Searches this {@code List} for the specified object and returns the index of the
176      * first occurrence.
177      *
178      * @param object
179      *            the object to search for.
180      * @return the index of the first occurrence of the object or -1 if the
181      *         object was not found.
182      */
indexOf(Object object)183     public int indexOf(Object object);
184 
185     /**
186      * Returns whether this {@code List} contains no elements.
187      *
188      * @return {@code true} if this {@code List} has no elements, {@code false}
189      *         otherwise.
190      * @see #size
191      */
isEmpty()192     public boolean isEmpty();
193 
194     /**
195      * Returns an iterator on the elements of this {@code List}. The elements are
196      * iterated in the same order as they occur in the {@code List}.
197      *
198      * @return an iterator on the elements of this {@code List}.
199      * @see Iterator
200      */
iterator()201     public Iterator<E> iterator();
202 
203     /**
204      * Searches this {@code List} for the specified object and returns the index of the
205      * last occurrence.
206      *
207      * @param object
208      *            the object to search for.
209      * @return the index of the last occurrence of the object, or -1 if the
210      *         object was not found.
211      */
lastIndexOf(Object object)212     public int lastIndexOf(Object object);
213 
214     /**
215      * Returns a {@code List} iterator on the elements of this {@code List}. The elements are
216      * iterated in the same order that they occur in the {@code List}.
217      *
218      * @return a {@code List} iterator on the elements of this {@code List}
219      *
220      * @see ListIterator
221      */
listIterator()222     public ListIterator<E> listIterator();
223 
224     /**
225      * Returns a list iterator on the elements of this {@code List}. The elements are
226      * iterated in the same order as they occur in the {@code List}. The iteration
227      * starts at the specified location.
228      *
229      * @param location
230      *            the index at which to start the iteration.
231      * @return a list iterator on the elements of this {@code List}.
232      * @throws IndexOutOfBoundsException
233      *                if {@code location < 0 || location > size()}
234      * @see ListIterator
235      */
listIterator(int location)236     public ListIterator<E> listIterator(int location);
237 
238     /**
239      * Removes the object at the specified location from this {@code List}.
240      *
241      * @param location
242      *            the index of the object to remove.
243      * @return the removed object.
244      * @throws UnsupportedOperationException
245      *                if removing from this {@code List} is not supported.
246      * @throws IndexOutOfBoundsException
247      *                if {@code location < 0 || >= size()}
248      */
remove(int location)249     public E remove(int location);
250 
251     /**
252      * Removes the first occurrence of the specified object from this {@code List}.
253      *
254      * @param object
255      *            the object to remove.
256      * @return true if this {@code List} was modified by this operation, false
257      *         otherwise.
258      * @throws UnsupportedOperationException
259      *                if removing from this {@code List} is not supported.
260      */
remove(Object object)261     public boolean remove(Object object);
262 
263     /**
264      * Removes all occurrences in this {@code List} of each object in the specified
265      * collection.
266      *
267      * @param collection
268      *            the collection of objects to remove.
269      * @return {@code true} if this {@code List} is modified, {@code false} otherwise.
270      * @throws UnsupportedOperationException
271      *                if removing from this {@code List} is not supported.
272      */
removeAll(Collection<?> collection)273     public boolean removeAll(Collection<?> collection);
274 
275     /**
276      * Removes all objects from this {@code List} that are not contained in the
277      * specified collection.
278      *
279      * @param collection
280      *            the collection of objects to retain.
281      * @return {@code true} if this {@code List} is modified, {@code false} otherwise.
282      * @throws UnsupportedOperationException
283      *                if removing from this {@code List} is not supported.
284      */
retainAll(Collection<?> collection)285     public boolean retainAll(Collection<?> collection);
286 
287     /**
288      * Replaces the element at the specified location in this {@code List} with the
289      * specified object. This operation does not change the size of the {@code List}.
290      *
291      * @param location
292      *            the index at which to put the specified object.
293      * @param object
294      *            the object to insert.
295      * @return the previous element at the index.
296      * @throws UnsupportedOperationException
297      *                if replacing elements in this {@code List} is not supported.
298      * @throws ClassCastException
299      *                if the class of an object is inappropriate for this
300      *                {@code List}.
301      * @throws IllegalArgumentException
302      *                if an object cannot be added to this {@code List}.
303      * @throws IndexOutOfBoundsException
304      *                if {@code location < 0 || >= size()}
305      */
set(int location, E object)306     public E set(int location, E object);
307 
308     /**
309      * Returns the number of elements in this {@code List}.
310      *
311      * @return the number of elements in this {@code List}.
312      */
size()313     public int size();
314 
315     /**
316      * Returns a {@code List} of the specified portion of this {@code List} from the given start
317      * index to the end index minus one. The returned {@code List} is backed by this
318      * {@code List} so changes to it are reflected by the other.
319      *
320      * @param start
321      *            the index at which to start the sublist.
322      * @param end
323      *            the index one past the end of the sublist.
324      * @return a list of a portion of this {@code List}.
325      * @throws IndexOutOfBoundsException
326      *                if {@code start < 0, start > end} or {@code end >
327      *                size()}
328      */
subList(int start, int end)329     public List<E> subList(int start, int end);
330 
331     /**
332      * Returns an array containing all elements contained in this {@code List}.
333      *
334      * @return an array of the elements from this {@code List}.
335      */
toArray()336     public Object[] toArray();
337 
338     /**
339      * Returns an array containing all elements contained in this {@code List}. If the
340      * specified array is large enough to hold the elements, the specified array
341      * is used, otherwise an array of the same type is created. If the specified
342      * array is used and is larger than this {@code List}, the array element following
343      * the collection elements is set to null.
344      *
345      * @param array
346      *            the array.
347      * @return an array of the elements from this {@code List}.
348      * @throws ArrayStoreException
349      *                if the type of an element in this {@code List} cannot be stored
350      *                in the type of the specified array.
351      */
toArray(T[] array)352     public <T> T[] toArray(T[] array);
353 }
354