1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/util/List.java Tue Feb 26 16:54:16 2013 +0100
1.3 @@ -0,0 +1,600 @@
1.4 +/*
1.5 + * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package java.util;
1.30 +
1.31 +/**
1.32 + * An ordered collection (also known as a <i>sequence</i>). The user of this
1.33 + * interface has precise control over where in the list each element is
1.34 + * inserted. The user can access elements by their integer index (position in
1.35 + * the list), and search for elements in the list.<p>
1.36 + *
1.37 + * Unlike sets, lists typically allow duplicate elements. More formally,
1.38 + * lists typically allow pairs of elements <tt>e1</tt> and <tt>e2</tt>
1.39 + * such that <tt>e1.equals(e2)</tt>, and they typically allow multiple
1.40 + * null elements if they allow null elements at all. It is not inconceivable
1.41 + * that someone might wish to implement a list that prohibits duplicates, by
1.42 + * throwing runtime exceptions when the user attempts to insert them, but we
1.43 + * expect this usage to be rare.<p>
1.44 + *
1.45 + * The <tt>List</tt> interface places additional stipulations, beyond those
1.46 + * specified in the <tt>Collection</tt> interface, on the contracts of the
1.47 + * <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and
1.48 + * <tt>hashCode</tt> methods. Declarations for other inherited methods are
1.49 + * also included here for convenience.<p>
1.50 + *
1.51 + * The <tt>List</tt> interface provides four methods for positional (indexed)
1.52 + * access to list elements. Lists (like Java arrays) are zero based. Note
1.53 + * that these operations may execute in time proportional to the index value
1.54 + * for some implementations (the <tt>LinkedList</tt> class, for
1.55 + * example). Thus, iterating over the elements in a list is typically
1.56 + * preferable to indexing through it if the caller does not know the
1.57 + * implementation.<p>
1.58 + *
1.59 + * The <tt>List</tt> interface provides a special iterator, called a
1.60 + * <tt>ListIterator</tt>, that allows element insertion and replacement, and
1.61 + * bidirectional access in addition to the normal operations that the
1.62 + * <tt>Iterator</tt> interface provides. A method is provided to obtain a
1.63 + * list iterator that starts at a specified position in the list.<p>
1.64 + *
1.65 + * The <tt>List</tt> interface provides two methods to search for a specified
1.66 + * object. From a performance standpoint, these methods should be used with
1.67 + * caution. In many implementations they will perform costly linear
1.68 + * searches.<p>
1.69 + *
1.70 + * The <tt>List</tt> interface provides two methods to efficiently insert and
1.71 + * remove multiple elements at an arbitrary point in the list.<p>
1.72 + *
1.73 + * Note: While it is permissible for lists to contain themselves as elements,
1.74 + * extreme caution is advised: the <tt>equals</tt> and <tt>hashCode</tt>
1.75 + * methods are no longer well defined on such a list.
1.76 + *
1.77 + * <p>Some list implementations have restrictions on the elements that
1.78 + * they may contain. For example, some implementations prohibit null elements,
1.79 + * and some have restrictions on the types of their elements. Attempting to
1.80 + * add an ineligible element throws an unchecked exception, typically
1.81 + * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. Attempting
1.82 + * to query the presence of an ineligible element may throw an exception,
1.83 + * or it may simply return false; some implementations will exhibit the former
1.84 + * behavior and some will exhibit the latter. More generally, attempting an
1.85 + * operation on an ineligible element whose completion would not result in
1.86 + * the insertion of an ineligible element into the list may throw an
1.87 + * exception or it may succeed, at the option of the implementation.
1.88 + * Such exceptions are marked as "optional" in the specification for this
1.89 + * interface.
1.90 + *
1.91 + * <p>This interface is a member of the
1.92 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
1.93 + * Java Collections Framework</a>.
1.94 + *
1.95 + * @param <E> the type of elements in this list
1.96 + *
1.97 + * @author Josh Bloch
1.98 + * @author Neal Gafter
1.99 + * @see Collection
1.100 + * @see Set
1.101 + * @see ArrayList
1.102 + * @see LinkedList
1.103 + * @see Vector
1.104 + * @see Arrays#asList(Object[])
1.105 + * @see Collections#nCopies(int, Object)
1.106 + * @see Collections#EMPTY_LIST
1.107 + * @see AbstractList
1.108 + * @see AbstractSequentialList
1.109 + * @since 1.2
1.110 + */
1.111 +
1.112 +public interface List<E> extends Collection<E> {
1.113 + // Query Operations
1.114 +
1.115 + /**
1.116 + * Returns the number of elements in this list. If this list contains
1.117 + * more than <tt>Integer.MAX_VALUE</tt> elements, returns
1.118 + * <tt>Integer.MAX_VALUE</tt>.
1.119 + *
1.120 + * @return the number of elements in this list
1.121 + */
1.122 + int size();
1.123 +
1.124 + /**
1.125 + * Returns <tt>true</tt> if this list contains no elements.
1.126 + *
1.127 + * @return <tt>true</tt> if this list contains no elements
1.128 + */
1.129 + boolean isEmpty();
1.130 +
1.131 + /**
1.132 + * Returns <tt>true</tt> if this list contains the specified element.
1.133 + * More formally, returns <tt>true</tt> if and only if this list contains
1.134 + * at least one element <tt>e</tt> such that
1.135 + * <tt>(o==null ? e==null : o.equals(e))</tt>.
1.136 + *
1.137 + * @param o element whose presence in this list is to be tested
1.138 + * @return <tt>true</tt> if this list contains the specified element
1.139 + * @throws ClassCastException if the type of the specified element
1.140 + * is incompatible with this list
1.141 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.142 + * @throws NullPointerException if the specified element is null and this
1.143 + * list does not permit null elements
1.144 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.145 + */
1.146 + boolean contains(Object o);
1.147 +
1.148 + /**
1.149 + * Returns an iterator over the elements in this list in proper sequence.
1.150 + *
1.151 + * @return an iterator over the elements in this list in proper sequence
1.152 + */
1.153 + Iterator<E> iterator();
1.154 +
1.155 + /**
1.156 + * Returns an array containing all of the elements in this list in proper
1.157 + * sequence (from first to last element).
1.158 + *
1.159 + * <p>The returned array will be "safe" in that no references to it are
1.160 + * maintained by this list. (In other words, this method must
1.161 + * allocate a new array even if this list is backed by an array).
1.162 + * The caller is thus free to modify the returned array.
1.163 + *
1.164 + * <p>This method acts as bridge between array-based and collection-based
1.165 + * APIs.
1.166 + *
1.167 + * @return an array containing all of the elements in this list in proper
1.168 + * sequence
1.169 + * @see Arrays#asList(Object[])
1.170 + */
1.171 + Object[] toArray();
1.172 +
1.173 + /**
1.174 + * Returns an array containing all of the elements in this list in
1.175 + * proper sequence (from first to last element); the runtime type of
1.176 + * the returned array is that of the specified array. If the list fits
1.177 + * in the specified array, it is returned therein. Otherwise, a new
1.178 + * array is allocated with the runtime type of the specified array and
1.179 + * the size of this list.
1.180 + *
1.181 + * <p>If the list fits in the specified array with room to spare (i.e.,
1.182 + * the array has more elements than the list), the element in the array
1.183 + * immediately following the end of the list is set to <tt>null</tt>.
1.184 + * (This is useful in determining the length of the list <i>only</i> if
1.185 + * the caller knows that the list does not contain any null elements.)
1.186 + *
1.187 + * <p>Like the {@link #toArray()} method, this method acts as bridge between
1.188 + * array-based and collection-based APIs. Further, this method allows
1.189 + * precise control over the runtime type of the output array, and may,
1.190 + * under certain circumstances, be used to save allocation costs.
1.191 + *
1.192 + * <p>Suppose <tt>x</tt> is a list known to contain only strings.
1.193 + * The following code can be used to dump the list into a newly
1.194 + * allocated array of <tt>String</tt>:
1.195 + *
1.196 + * <pre>
1.197 + * String[] y = x.toArray(new String[0]);</pre>
1.198 + *
1.199 + * Note that <tt>toArray(new Object[0])</tt> is identical in function to
1.200 + * <tt>toArray()</tt>.
1.201 + *
1.202 + * @param a the array into which the elements of this list are to
1.203 + * be stored, if it is big enough; otherwise, a new array of the
1.204 + * same runtime type is allocated for this purpose.
1.205 + * @return an array containing the elements of this list
1.206 + * @throws ArrayStoreException if the runtime type of the specified array
1.207 + * is not a supertype of the runtime type of every element in
1.208 + * this list
1.209 + * @throws NullPointerException if the specified array is null
1.210 + */
1.211 + <T> T[] toArray(T[] a);
1.212 +
1.213 +
1.214 + // Modification Operations
1.215 +
1.216 + /**
1.217 + * Appends the specified element to the end of this list (optional
1.218 + * operation).
1.219 + *
1.220 + * <p>Lists that support this operation may place limitations on what
1.221 + * elements may be added to this list. In particular, some
1.222 + * lists will refuse to add null elements, and others will impose
1.223 + * restrictions on the type of elements that may be added. List
1.224 + * classes should clearly specify in their documentation any restrictions
1.225 + * on what elements may be added.
1.226 + *
1.227 + * @param e element to be appended to this list
1.228 + * @return <tt>true</tt> (as specified by {@link Collection#add})
1.229 + * @throws UnsupportedOperationException if the <tt>add</tt> operation
1.230 + * is not supported by this list
1.231 + * @throws ClassCastException if the class of the specified element
1.232 + * prevents it from being added to this list
1.233 + * @throws NullPointerException if the specified element is null and this
1.234 + * list does not permit null elements
1.235 + * @throws IllegalArgumentException if some property of this element
1.236 + * prevents it from being added to this list
1.237 + */
1.238 + boolean add(E e);
1.239 +
1.240 + /**
1.241 + * Removes the first occurrence of the specified element from this list,
1.242 + * if it is present (optional operation). If this list does not contain
1.243 + * the element, it is unchanged. More formally, removes the element with
1.244 + * the lowest index <tt>i</tt> such that
1.245 + * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>
1.246 + * (if such an element exists). Returns <tt>true</tt> if this list
1.247 + * contained the specified element (or equivalently, if this list changed
1.248 + * as a result of the call).
1.249 + *
1.250 + * @param o element to be removed from this list, if present
1.251 + * @return <tt>true</tt> if this list contained the specified element
1.252 + * @throws ClassCastException if the type of the specified element
1.253 + * is incompatible with this list
1.254 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.255 + * @throws NullPointerException if the specified element is null and this
1.256 + * list does not permit null elements
1.257 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.258 + * @throws UnsupportedOperationException if the <tt>remove</tt> operation
1.259 + * is not supported by this list
1.260 + */
1.261 + boolean remove(Object o);
1.262 +
1.263 +
1.264 + // Bulk Modification Operations
1.265 +
1.266 + /**
1.267 + * Returns <tt>true</tt> if this list contains all of the elements of the
1.268 + * specified collection.
1.269 + *
1.270 + * @param c collection to be checked for containment in this list
1.271 + * @return <tt>true</tt> if this list contains all of the elements of the
1.272 + * specified collection
1.273 + * @throws ClassCastException if the types of one or more elements
1.274 + * in the specified collection are incompatible with this
1.275 + * list
1.276 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.277 + * @throws NullPointerException if the specified collection contains one
1.278 + * or more null elements and this list does not permit null
1.279 + * elements
1.280 + * (<a href="Collection.html#optional-restrictions">optional</a>),
1.281 + * or if the specified collection is null
1.282 + * @see #contains(Object)
1.283 + */
1.284 + boolean containsAll(Collection<?> c);
1.285 +
1.286 + /**
1.287 + * Appends all of the elements in the specified collection to the end of
1.288 + * this list, in the order that they are returned by the specified
1.289 + * collection's iterator (optional operation). The behavior of this
1.290 + * operation is undefined if the specified collection is modified while
1.291 + * the operation is in progress. (Note that this will occur if the
1.292 + * specified collection is this list, and it's nonempty.)
1.293 + *
1.294 + * @param c collection containing elements to be added to this list
1.295 + * @return <tt>true</tt> if this list changed as a result of the call
1.296 + * @throws UnsupportedOperationException if the <tt>addAll</tt> operation
1.297 + * is not supported by this list
1.298 + * @throws ClassCastException if the class of an element of the specified
1.299 + * collection prevents it from being added to this list
1.300 + * @throws NullPointerException if the specified collection contains one
1.301 + * or more null elements and this list does not permit null
1.302 + * elements, or if the specified collection is null
1.303 + * @throws IllegalArgumentException if some property of an element of the
1.304 + * specified collection prevents it from being added to this list
1.305 + * @see #add(Object)
1.306 + */
1.307 + boolean addAll(Collection<? extends E> c);
1.308 +
1.309 + /**
1.310 + * Inserts all of the elements in the specified collection into this
1.311 + * list at the specified position (optional operation). Shifts the
1.312 + * element currently at that position (if any) and any subsequent
1.313 + * elements to the right (increases their indices). The new elements
1.314 + * will appear in this list in the order that they are returned by the
1.315 + * specified collection's iterator. The behavior of this operation is
1.316 + * undefined if the specified collection is modified while the
1.317 + * operation is in progress. (Note that this will occur if the specified
1.318 + * collection is this list, and it's nonempty.)
1.319 + *
1.320 + * @param index index at which to insert the first element from the
1.321 + * specified collection
1.322 + * @param c collection containing elements to be added to this list
1.323 + * @return <tt>true</tt> if this list changed as a result of the call
1.324 + * @throws UnsupportedOperationException if the <tt>addAll</tt> operation
1.325 + * is not supported by this list
1.326 + * @throws ClassCastException if the class of an element of the specified
1.327 + * collection prevents it from being added to this list
1.328 + * @throws NullPointerException if the specified collection contains one
1.329 + * or more null elements and this list does not permit null
1.330 + * elements, or if the specified collection is null
1.331 + * @throws IllegalArgumentException if some property of an element of the
1.332 + * specified collection prevents it from being added to this list
1.333 + * @throws IndexOutOfBoundsException if the index is out of range
1.334 + * (<tt>index < 0 || index > size()</tt>)
1.335 + */
1.336 + boolean addAll(int index, Collection<? extends E> c);
1.337 +
1.338 + /**
1.339 + * Removes from this list all of its elements that are contained in the
1.340 + * specified collection (optional operation).
1.341 + *
1.342 + * @param c collection containing elements to be removed from this list
1.343 + * @return <tt>true</tt> if this list changed as a result of the call
1.344 + * @throws UnsupportedOperationException if the <tt>removeAll</tt> operation
1.345 + * is not supported by this list
1.346 + * @throws ClassCastException if the class of an element of this list
1.347 + * is incompatible with the specified collection
1.348 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.349 + * @throws NullPointerException if this list contains a null element and the
1.350 + * specified collection does not permit null elements
1.351 + * (<a href="Collection.html#optional-restrictions">optional</a>),
1.352 + * or if the specified collection is null
1.353 + * @see #remove(Object)
1.354 + * @see #contains(Object)
1.355 + */
1.356 + boolean removeAll(Collection<?> c);
1.357 +
1.358 + /**
1.359 + * Retains only the elements in this list that are contained in the
1.360 + * specified collection (optional operation). In other words, removes
1.361 + * from this list all of its elements that are not contained in the
1.362 + * specified collection.
1.363 + *
1.364 + * @param c collection containing elements to be retained in this list
1.365 + * @return <tt>true</tt> if this list changed as a result of the call
1.366 + * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
1.367 + * is not supported by this list
1.368 + * @throws ClassCastException if the class of an element of this list
1.369 + * is incompatible with the specified collection
1.370 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.371 + * @throws NullPointerException if this list contains a null element and the
1.372 + * specified collection does not permit null elements
1.373 + * (<a href="Collection.html#optional-restrictions">optional</a>),
1.374 + * or if the specified collection is null
1.375 + * @see #remove(Object)
1.376 + * @see #contains(Object)
1.377 + */
1.378 + boolean retainAll(Collection<?> c);
1.379 +
1.380 + /**
1.381 + * Removes all of the elements from this list (optional operation).
1.382 + * The list will be empty after this call returns.
1.383 + *
1.384 + * @throws UnsupportedOperationException if the <tt>clear</tt> operation
1.385 + * is not supported by this list
1.386 + */
1.387 + void clear();
1.388 +
1.389 +
1.390 + // Comparison and hashing
1.391 +
1.392 + /**
1.393 + * Compares the specified object with this list for equality. Returns
1.394 + * <tt>true</tt> if and only if the specified object is also a list, both
1.395 + * lists have the same size, and all corresponding pairs of elements in
1.396 + * the two lists are <i>equal</i>. (Two elements <tt>e1</tt> and
1.397 + * <tt>e2</tt> are <i>equal</i> if <tt>(e1==null ? e2==null :
1.398 + * e1.equals(e2))</tt>.) In other words, two lists are defined to be
1.399 + * equal if they contain the same elements in the same order. This
1.400 + * definition ensures that the equals method works properly across
1.401 + * different implementations of the <tt>List</tt> interface.
1.402 + *
1.403 + * @param o the object to be compared for equality with this list
1.404 + * @return <tt>true</tt> if the specified object is equal to this list
1.405 + */
1.406 + boolean equals(Object o);
1.407 +
1.408 + /**
1.409 + * Returns the hash code value for this list. The hash code of a list
1.410 + * is defined to be the result of the following calculation:
1.411 + * <pre>
1.412 + * int hashCode = 1;
1.413 + * for (E e : list)
1.414 + * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
1.415 + * </pre>
1.416 + * This ensures that <tt>list1.equals(list2)</tt> implies that
1.417 + * <tt>list1.hashCode()==list2.hashCode()</tt> for any two lists,
1.418 + * <tt>list1</tt> and <tt>list2</tt>, as required by the general
1.419 + * contract of {@link Object#hashCode}.
1.420 + *
1.421 + * @return the hash code value for this list
1.422 + * @see Object#equals(Object)
1.423 + * @see #equals(Object)
1.424 + */
1.425 + int hashCode();
1.426 +
1.427 +
1.428 + // Positional Access Operations
1.429 +
1.430 + /**
1.431 + * Returns the element at the specified position in this list.
1.432 + *
1.433 + * @param index index of the element to return
1.434 + * @return the element at the specified position in this list
1.435 + * @throws IndexOutOfBoundsException if the index is out of range
1.436 + * (<tt>index < 0 || index >= size()</tt>)
1.437 + */
1.438 + E get(int index);
1.439 +
1.440 + /**
1.441 + * Replaces the element at the specified position in this list with the
1.442 + * specified element (optional operation).
1.443 + *
1.444 + * @param index index of the element to replace
1.445 + * @param element element to be stored at the specified position
1.446 + * @return the element previously at the specified position
1.447 + * @throws UnsupportedOperationException if the <tt>set</tt> operation
1.448 + * is not supported by this list
1.449 + * @throws ClassCastException if the class of the specified element
1.450 + * prevents it from being added to this list
1.451 + * @throws NullPointerException if the specified element is null and
1.452 + * this list does not permit null elements
1.453 + * @throws IllegalArgumentException if some property of the specified
1.454 + * element prevents it from being added to this list
1.455 + * @throws IndexOutOfBoundsException if the index is out of range
1.456 + * (<tt>index < 0 || index >= size()</tt>)
1.457 + */
1.458 + E set(int index, E element);
1.459 +
1.460 + /**
1.461 + * Inserts the specified element at the specified position in this list
1.462 + * (optional operation). Shifts the element currently at that position
1.463 + * (if any) and any subsequent elements to the right (adds one to their
1.464 + * indices).
1.465 + *
1.466 + * @param index index at which the specified element is to be inserted
1.467 + * @param element element to be inserted
1.468 + * @throws UnsupportedOperationException if the <tt>add</tt> operation
1.469 + * is not supported by this list
1.470 + * @throws ClassCastException if the class of the specified element
1.471 + * prevents it from being added to this list
1.472 + * @throws NullPointerException if the specified element is null and
1.473 + * this list does not permit null elements
1.474 + * @throws IllegalArgumentException if some property of the specified
1.475 + * element prevents it from being added to this list
1.476 + * @throws IndexOutOfBoundsException if the index is out of range
1.477 + * (<tt>index < 0 || index > size()</tt>)
1.478 + */
1.479 + void add(int index, E element);
1.480 +
1.481 + /**
1.482 + * Removes the element at the specified position in this list (optional
1.483 + * operation). Shifts any subsequent elements to the left (subtracts one
1.484 + * from their indices). Returns the element that was removed from the
1.485 + * list.
1.486 + *
1.487 + * @param index the index of the element to be removed
1.488 + * @return the element previously at the specified position
1.489 + * @throws UnsupportedOperationException if the <tt>remove</tt> operation
1.490 + * is not supported by this list
1.491 + * @throws IndexOutOfBoundsException if the index is out of range
1.492 + * (<tt>index < 0 || index >= size()</tt>)
1.493 + */
1.494 + E remove(int index);
1.495 +
1.496 +
1.497 + // Search Operations
1.498 +
1.499 + /**
1.500 + * Returns the index of the first occurrence of the specified element
1.501 + * in this list, or -1 if this list does not contain the element.
1.502 + * More formally, returns the lowest index <tt>i</tt> such that
1.503 + * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
1.504 + * or -1 if there is no such index.
1.505 + *
1.506 + * @param o element to search for
1.507 + * @return the index of the first occurrence of the specified element in
1.508 + * this list, or -1 if this list does not contain the element
1.509 + * @throws ClassCastException if the type of the specified element
1.510 + * is incompatible with this list
1.511 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.512 + * @throws NullPointerException if the specified element is null and this
1.513 + * list does not permit null elements
1.514 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.515 + */
1.516 + int indexOf(Object o);
1.517 +
1.518 + /**
1.519 + * Returns the index of the last occurrence of the specified element
1.520 + * in this list, or -1 if this list does not contain the element.
1.521 + * More formally, returns the highest index <tt>i</tt> such that
1.522 + * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
1.523 + * or -1 if there is no such index.
1.524 + *
1.525 + * @param o element to search for
1.526 + * @return the index of the last occurrence of the specified element in
1.527 + * this list, or -1 if this list does not contain the element
1.528 + * @throws ClassCastException if the type of the specified element
1.529 + * is incompatible with this list
1.530 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.531 + * @throws NullPointerException if the specified element is null and this
1.532 + * list does not permit null elements
1.533 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.534 + */
1.535 + int lastIndexOf(Object o);
1.536 +
1.537 +
1.538 + // List Iterators
1.539 +
1.540 + /**
1.541 + * Returns a list iterator over the elements in this list (in proper
1.542 + * sequence).
1.543 + *
1.544 + * @return a list iterator over the elements in this list (in proper
1.545 + * sequence)
1.546 + */
1.547 + ListIterator<E> listIterator();
1.548 +
1.549 + /**
1.550 + * Returns a list iterator over the elements in this list (in proper
1.551 + * sequence), starting at the specified position in the list.
1.552 + * The specified index indicates the first element that would be
1.553 + * returned by an initial call to {@link ListIterator#next next}.
1.554 + * An initial call to {@link ListIterator#previous previous} would
1.555 + * return the element with the specified index minus one.
1.556 + *
1.557 + * @param index index of the first element to be returned from the
1.558 + * list iterator (by a call to {@link ListIterator#next next})
1.559 + * @return a list iterator over the elements in this list (in proper
1.560 + * sequence), starting at the specified position in the list
1.561 + * @throws IndexOutOfBoundsException if the index is out of range
1.562 + * ({@code index < 0 || index > size()})
1.563 + */
1.564 + ListIterator<E> listIterator(int index);
1.565 +
1.566 + // View
1.567 +
1.568 + /**
1.569 + * Returns a view of the portion of this list between the specified
1.570 + * <tt>fromIndex</tt>, inclusive, and <tt>toIndex</tt>, exclusive. (If
1.571 + * <tt>fromIndex</tt> and <tt>toIndex</tt> are equal, the returned list is
1.572 + * empty.) The returned list is backed by this list, so non-structural
1.573 + * changes in the returned list are reflected in this list, and vice-versa.
1.574 + * The returned list supports all of the optional list operations supported
1.575 + * by this list.<p>
1.576 + *
1.577 + * This method eliminates the need for explicit range operations (of
1.578 + * the sort that commonly exist for arrays). Any operation that expects
1.579 + * a list can be used as a range operation by passing a subList view
1.580 + * instead of a whole list. For example, the following idiom
1.581 + * removes a range of elements from a list:
1.582 + * <pre>
1.583 + * list.subList(from, to).clear();
1.584 + * </pre>
1.585 + * Similar idioms may be constructed for <tt>indexOf</tt> and
1.586 + * <tt>lastIndexOf</tt>, and all of the algorithms in the
1.587 + * <tt>Collections</tt> class can be applied to a subList.<p>
1.588 + *
1.589 + * The semantics of the list returned by this method become undefined if
1.590 + * the backing list (i.e., this list) is <i>structurally modified</i> in
1.591 + * any way other than via the returned list. (Structural modifications are
1.592 + * those that change the size of this list, or otherwise perturb it in such
1.593 + * a fashion that iterations in progress may yield incorrect results.)
1.594 + *
1.595 + * @param fromIndex low endpoint (inclusive) of the subList
1.596 + * @param toIndex high endpoint (exclusive) of the subList
1.597 + * @return a view of the specified range within this list
1.598 + * @throws IndexOutOfBoundsException for an illegal endpoint index value
1.599 + * (<tt>fromIndex < 0 || toIndex > size ||
1.600 + * fromIndex > toIndex</tt>)
1.601 + */
1.602 + List<E> subList(int fromIndex, int toIndex);
1.603 +}