1.1 --- a/emul/compact/src/main/java/java/util/List.java Tue Feb 26 14:55:55 2013 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,600 +0,0 @@
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 -}