1 /*
2 * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util;
27
28 import java.util.function.UnaryOperator;
29
30 /**
31 * An ordered collection (also known as a <i>sequence</i>). The user of this
32 * interface has precise control over where in the list each element is
33 * inserted. The user can access elements by their integer index (position in
34 * the list), and search for elements in the list.<p>
35 *
36 * Unlike sets, lists typically allow duplicate elements. More formally,
37 * lists typically allow pairs of elements {@code e1} and {@code e2}
38 * such that {@code e1.equals(e2)}, and they typically allow multiple
39 * null elements if they allow null elements at all. It is not inconceivable
40 * that someone might wish to implement a list that prohibits duplicates, by
41 * throwing runtime exceptions when the user attempts to insert them, but we
42 * expect this usage to be rare.<p>
43 *
44 * The {@code List} interface places additional stipulations, beyond those
45 * specified in the {@code Collection} interface, on the contracts of the
46 * {@code iterator}, {@code add}, {@code remove}, {@code equals}, and
47 * {@code hashCode} methods. Declarations for other inherited methods are
48 * also included here for convenience.<p>
49 *
50 * The {@code List} interface provides four methods for positional (indexed)
51 * access to list elements. Lists (like Java arrays) are zero based. Note
52 * that these operations may execute in time proportional to the index value
53 * for some implementations (the {@code LinkedList} class, for
54 * example). Thus, iterating over the elements in a list is typically
55 * preferable to indexing through it if the caller does not know the
56 * implementation.<p>
57 *
58 * The {@code List} interface provides a special iterator, called a
59 * {@code ListIterator}, that allows element insertion and replacement, and
60 * bidirectional access in addition to the normal operations that the
61 * {@code Iterator} interface provides. A method is provided to obtain a
62 * list iterator that starts at a specified position in the list.<p>
63 *
64 * The {@code List} interface provides two methods to search for a specified
65 * object. From a performance standpoint, these methods should be used with
66 * caution. In many implementations they will perform costly linear
67 * searches.<p>
68 *
69 * The {@code List} interface provides two methods to efficiently insert and
70 * remove multiple elements at an arbitrary point in the list.<p>
71 *
72 * Note: While it is permissible for lists to contain themselves as elements,
73 * extreme caution is advised: the {@code equals} and {@code hashCode}
74 * methods are no longer well defined on such a list.
75 *
76 * <p>Some list implementations have restrictions on the elements that
77 * they may contain. For example, some implementations prohibit null elements,
78 * and some have restrictions on the types of their elements. Attempting to
79 * add an ineligible element throws an unchecked exception, typically
80 * {@code NullPointerException} or {@code ClassCastException}. Attempting
81 * to query the presence of an ineligible element may throw an exception,
82 * or it may simply return false; some implementations will exhibit the former
83 * behavior and some will exhibit the latter. More generally, attempting an
84 * operation on an ineligible element whose completion would not result in
85 * the insertion of an ineligible element into the list may throw an
86 * exception or it may succeed, at the option of the implementation.
87 * Such exceptions are marked as "optional" in the specification for this
88 * interface.
89 *
90 * <h2><a name="immutable">Immutable List Static Factory Methods</a></h2>
91 * <p>The {@link List#of(Object...) List.of()} static factory methods
92 * provide a convenient way to create immutable lists. The {@code List}
93 * instances created by these methods have the following characteristics:
94 *
95 * <ul>
96 * <li>They cannot be modified. Attempts to modify them result in
97 * an {@code UnsupportedOperationException}.
98 * <li>They are truly immutable only if the contained elements are themselves
99 * immutable. If an element is mutated, it will affect the result of the
100 * containing list's {@code equals()} and {@code hashCode()} methods.
101 * <li>They disallow null elements. Attempts to create them with
102 * null elements result in {@code NullPointerException}.
103 * <li>They are serializable if all elements are serializable.
104 * </ul>
105 *
106 * <p>This interface is a member of the
107 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
108 * Java Collections Framework</a>.
109 *
110 * @param <E> the type of elements in this list
111 *
112 * @author Josh Bloch
113 * @author Neal Gafter
114 * @see Collection
115 * @see Set
116 * @see ArrayList
117 * @see LinkedList
118 * @see Vector
119 * @see Arrays#asList(Object[])
120 * @see Collections#nCopies(int, Object)
121 * @see Collections#EMPTY_LIST
122 * @see AbstractList
123 * @see AbstractSequentialList
124 * @since 1.2
125 */
126
127 public interface List<E> extends Collection<E> {
128 // Query Operations
129
130 /**
131 * Returns the number of elements in this list. If this list contains
132 * more than {@code Integer.MAX_VALUE} elements, returns
133 * {@code Integer.MAX_VALUE}.
134 *
135 * @return the number of elements in this list
136 */
137 int size();
138
139 /**
140 * Returns {@code true} if this list contains no elements.
141 *
142 * @return {@code true} if this list contains no elements
143 */
144 boolean isEmpty();
145
146 /**
147 * Returns {@code true} if this list contains the specified element.
148 * More formally, returns {@code true} if and only if this list contains
149 * at least one element {@code e} such that
150 * {@code Objects.equals(o, e)}.
151 *
152 * @param o element whose presence in this list is to be tested
153 * @return {@code true} if this list contains the specified element
154 * @throws ClassCastException if the type of the specified element
155 * is incompatible with this list
156 * (<a href="Collection.html#optional-restrictions">optional</a>)
157 * @throws NullPointerException if the specified element is null and this
158 * list does not permit null elements
159 * (<a href="Collection.html#optional-restrictions">optional</a>)
160 */
161 boolean contains(Object o);
162
163 /**
164 * Returns an iterator over the elements in this list in proper sequence.
165 *
166 * @return an iterator over the elements in this list in proper sequence
167 */
168 Iterator<E> iterator();
169
170 /**
171 * Returns an array containing all of the elements in this list in proper
172 * sequence (from first to last element).
173 *
174 * <p>The returned array will be "safe" in that no references to it are
175 * maintained by this list. (In other words, this method must
176 * allocate a new array even if this list is backed by an array).
177 * The caller is thus free to modify the returned array.
178 *
179 * <p>This method acts as bridge between array-based and collection-based
180 * APIs.
181 *
182 * @return an array containing all of the elements in this list in proper
183 * sequence
184 * @see Arrays#asList(Object[])
185 */
186 Object[] toArray();
187
188 /**
189 * Returns an array containing all of the elements in this list in
190 * proper sequence (from first to last element); the runtime type of
191 * the returned array is that of the specified array. If the list fits
192 * in the specified array, it is returned therein. Otherwise, a new
193 * array is allocated with the runtime type of the specified array and
194 * the size of this list.
195 *
196 * <p>If the list fits in the specified array with room to spare (i.e.,
197 * the array has more elements than the list), the element in the array
198 * immediately following the end of the list is set to {@code null}.
199 * (This is useful in determining the length of the list <i>only</i> if
200 * the caller knows that the list does not contain any null elements.)
201 *
202 * <p>Like the {@link #toArray()} method, this method acts as bridge between
203 * array-based and collection-based APIs. Further, this method allows
204 * precise control over the runtime type of the output array, and may,
205 * under certain circumstances, be used to save allocation costs.
206 *
207 * <p>Suppose {@code x} is a list known to contain only strings.
208 * The following code can be used to dump the list into a newly
209 * allocated array of {@code String}:
210 *
211 * <pre>{@code
212 * String[] y = x.toArray(new String[0]);
213 * }</pre>
214 *
215 * Note that {@code toArray(new Object[0])} is identical in function to
216 * {@code toArray()}.
217 *
218 * @param a the array into which the elements of this list are to
219 * be stored, if it is big enough; otherwise, a new array of the
220 * same runtime type is allocated for this purpose.
221 * @return an array containing the elements of this list
222 * @throws ArrayStoreException if the runtime type of the specified array
223 * is not a supertype of the runtime type of every element in
224 * this list
225 * @throws NullPointerException if the specified array is null
226 */
227 <T> T[] toArray(T[] a);
228
229
230 // Modification Operations
231
232 /**
233 * Appends the specified element to the end of this list (optional
234 * operation).
235 *
236 * <p>Lists that support this operation may place limitations on what
237 * elements may be added to this list. In particular, some
238 * lists will refuse to add null elements, and others will impose
239 * restrictions on the type of elements that may be added. List
240 * classes should clearly specify in their documentation any restrictions
241 * on what elements may be added.
242 *
243 * @param e element to be appended to this list
244 * @return {@code true} (as specified by {@link Collection#add})
245 * @throws UnsupportedOperationException if the {@code add} operation
246 * is not supported by this list
247 * @throws ClassCastException if the class of the specified element
248 * prevents it from being added to this list
249 * @throws NullPointerException if the specified element is null and this
250 * list does not permit null elements
251 * @throws IllegalArgumentException if some property of this element
252 * prevents it from being added to this list
253 */
254 boolean add(E e);
255
256 /**
257 * Removes the first occurrence of the specified element from this list,
258 * if it is present (optional operation). If this list does not contain
259 * the element, it is unchanged. More formally, removes the element with
260 * the lowest index {@code i} such that
261 * {@code Objects.equals(o, get(i))}
262 * (if such an element exists). Returns {@code true} if this list
263 * contained the specified element (or equivalently, if this list changed
264 * as a result of the call).
265 *
266 * @param o element to be removed from this list, if present
267 * @return {@code true} if this list contained the specified element
268 * @throws ClassCastException if the type of the specified element
269 * is incompatible with this list
270 * (<a href="Collection.html#optional-restrictions">optional</a>)
271 * @throws NullPointerException if the specified element is null and this
272 * list does not permit null elements
273 * (<a href="Collection.html#optional-restrictions">optional</a>)
274 * @throws UnsupportedOperationException if the {@code remove} operation
275 * is not supported by this list
276 */
277 boolean remove(Object o);
278
279
280 // Bulk Modification Operations
281
282 /**
283 * Returns {@code true} if this list contains all of the elements of the
284 * specified collection.
285 *
286 * @param c collection to be checked for containment in this list
287 * @return {@code true} if this list contains all of the elements of the
288 * specified collection
289 * @throws ClassCastException if the types of one or more elements
290 * in the specified collection are incompatible with this
291 * list
292 * (<a href="Collection.html#optional-restrictions">optional</a>)
293 * @throws NullPointerException if the specified collection contains one
294 * or more null elements and this list does not permit null
295 * elements
296 * (<a href="Collection.html#optional-restrictions">optional</a>),
297 * or if the specified collection is null
298 * @see #contains(Object)
299 */
300 boolean containsAll(Collection<?> c);
301
302 /**
303 * Appends all of the elements in the specified collection to the end of
304 * this list, in the order that they are returned by the specified
305 * collection's iterator (optional operation). The behavior of this
306 * operation is undefined if the specified collection is modified while
307 * the operation is in progress. (Note that this will occur if the
308 * specified collection is this list, and it's nonempty.)
309 *
310 * @param c collection containing elements to be added to this list
311 * @return {@code true} if this list changed as a result of the call
312 * @throws UnsupportedOperationException if the {@code addAll} operation
313 * is not supported by this list
314 * @throws ClassCastException if the class of an element of the specified
315 * collection prevents it from being added to this list
316 * @throws NullPointerException if the specified collection contains one
317 * or more null elements and this list does not permit null
318 * elements, or if the specified collection is null
319 * @throws IllegalArgumentException if some property of an element of the
320 * specified collection prevents it from being added to this list
321 * @see #add(Object)
322 */
323 boolean addAll(Collection<? extends E> c);
324
325 /**
326 * Inserts all of the elements in the specified collection into this
327 * list at the specified position (optional operation). Shifts the
328 * element currently at that position (if any) and any subsequent
329 * elements to the right (increases their indices). The new elements
330 * will appear in this list in the order that they are returned by the
331 * specified collection's iterator. The behavior of this operation is
332 * undefined if the specified collection is modified while the
333 * operation is in progress. (Note that this will occur if the specified
334 * collection is this list, and it's nonempty.)
335 *
336 * @param index index at which to insert the first element from the
337 * specified collection
338 * @param c collection containing elements to be added to this list
339 * @return {@code true} if this list changed as a result of the call
340 * @throws UnsupportedOperationException if the {@code addAll} operation
341 * is not supported by this list
342 * @throws ClassCastException if the class of an element of the specified
343 * collection prevents it from being added to this list
344 * @throws NullPointerException if the specified collection contains one
345 * or more null elements and this list does not permit null
346 * elements, or if the specified collection is null
347 * @throws IllegalArgumentException if some property of an element of the
348 * specified collection prevents it from being added to this list
349 * @throws IndexOutOfBoundsException if the index is out of range
350 * ({@code index < 0 || index > size()})
351 */
352 boolean addAll(int index, Collection<? extends E> c);
353
354 /**
355 * Removes from this list all of its elements that are contained in the
356 * specified collection (optional operation).
357 *
358 * @param c collection containing elements to be removed from this list
359 * @return {@code true} if this list changed as a result of the call
360 * @throws UnsupportedOperationException if the {@code removeAll} operation
361 * is not supported by this list
362 * @throws ClassCastException if the class of an element of this list
363 * is incompatible with the specified collection
364 * (<a href="Collection.html#optional-restrictions">optional</a>)
365 * @throws NullPointerException if this list contains a null element and the
366 * specified collection does not permit null elements
367 * (<a href="Collection.html#optional-restrictions">optional</a>),
368 * or if the specified collection is null
369 * @see #remove(Object)
370 * @see #contains(Object)
371 */
372 boolean removeAll(Collection<?> c);
373
374 /**
375 * Retains only the elements in this list that are contained in the
376 * specified collection (optional operation). In other words, removes
377 * from this list all of its elements that are not contained in the
378 * specified collection.
379 *
380 * @param c collection containing elements to be retained in this list
381 * @return {@code true} if this list changed as a result of the call
382 * @throws UnsupportedOperationException if the {@code retainAll} operation
383 * is not supported by this list
384 * @throws ClassCastException if the class of an element of this list
385 * is incompatible with the specified collection
386 * (<a href="Collection.html#optional-restrictions">optional</a>)
387 * @throws NullPointerException if this list contains a null element and the
388 * specified collection does not permit null elements
389 * (<a href="Collection.html#optional-restrictions">optional</a>),
390 * or if the specified collection is null
391 * @see #remove(Object)
392 * @see #contains(Object)
393 */
394 boolean retainAll(Collection<?> c);
395
396 /**
397 * Replaces each element of this list with the result of applying the
398 * operator to that element. Errors or runtime exceptions thrown by
399 * the operator are relayed to the caller.
400 *
401 * @implSpec
402 * The default implementation is equivalent to, for this {@code list}:
403 * <pre>{@code
404 * final ListIterator<E> li = list.listIterator();
405 * while (li.hasNext()) {
406 * li.set(operator.apply(li.next()));
407 * }
408 * }</pre>
409 *
410 * If the list's list-iterator does not support the {@code set} operation
411 * then an {@code UnsupportedOperationException} will be thrown when
412 * replacing the first element.
413 *
414 * @param operator the operator to apply to each element
415 * @throws UnsupportedOperationException if this list is unmodifiable.
416 * Implementations may throw this exception if an element
417 * cannot be replaced or if, in general, modification is not
418 * supported
419 * @throws NullPointerException if the specified operator is null or
420 * if the operator result is a null value and this list does
421 * not permit null elements
422 * (<a href="Collection.html#optional-restrictions">optional</a>)
423 * @since 1.8
424 */
425 default void replaceAll(UnaryOperator<E> operator) {
426 Objects.requireNonNull(operator);
427 final ListIterator<E> li = this.listIterator();
428 while (li.hasNext()) {
429 li.set(operator.apply(li.next()));
430 }
431 }
432
433 /**
434 * Sorts this list according to the order induced by the specified
435 * {@link Comparator}.
436 *
437 * <p>All elements in this list must be <i>mutually comparable</i> using the
438 * specified comparator (that is, {@code c.compare(e1, e2)} must not throw
439 * a {@code ClassCastException} for any elements {@code e1} and {@code e2}
440 * in the list).
441 *
442 * <p>If the specified comparator is {@code null} then all elements in this
443 * list must implement the {@link Comparable} interface and the elements'
444 * {@linkplain Comparable natural ordering} should be used.
445 *
446 * <p>This list must be modifiable, but need not be resizable.
447 *
448 * @implSpec
449 * The default implementation obtains an array containing all elements in
450 * this list, sorts the array, and iterates over this list resetting each
451 * element from the corresponding position in the array. (This avoids the
452 * n<sup>2</sup> log(n) performance that would result from attempting
453 * to sort a linked list in place.)
454 *
455 * @implNote
456 * This implementation is a stable, adaptive, iterative mergesort that
457 * requires far fewer than n lg(n) comparisons when the input array is
458 * partially sorted, while offering the performance of a traditional
459 * mergesort when the input array is randomly ordered. If the input array
460 * is nearly sorted, the implementation requires approximately n
461 * comparisons. Temporary storage requirements vary from a small constant
462 * for nearly sorted input arrays to n/2 object references for randomly
463 * ordered input arrays.
464 *
465 * <p>The implementation takes equal advantage of ascending and
466 * descending order in its input array, and can take advantage of
467 * ascending and descending order in different parts of the same
468 * input array. It is well-suited to merging two or more sorted arrays:
469 * simply concatenate the arrays and sort the resulting array.
470 *
471 * <p>The implementation was adapted from Tim Peters's list sort for Python
472 * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
473 * TimSort</a>). It uses techniques from Peter McIlroy's "Optimistic
474 * Sorting and Information Theoretic Complexity", in Proceedings of the
475 * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
476 * January 1993.
477 *
478 * @param c the {@code Comparator} used to compare list elements.
479 * A {@code null} value indicates that the elements'
480 * {@linkplain Comparable natural ordering} should be used
481 * @throws ClassCastException if the list contains elements that are not
482 * <i>mutually comparable</i> using the specified comparator
483 * @throws UnsupportedOperationException if the list's list-iterator does
484 * not support the {@code set} operation
485 * @throws IllegalArgumentException
486 * (<a href="Collection.html#optional-restrictions">optional</a>)
487 * if the comparator is found to violate the {@link Comparator}
488 * contract
489 * @since 1.8
490 */
491 @SuppressWarnings({"unchecked", "rawtypes"})
492 default void sort(Comparator<? super E> c) {
493 Object[] a = this.toArray();
494 Arrays.sort(a, (Comparator) c);
495 ListIterator<E> i = this.listIterator();
496 for (Object e : a) {
497 i.next();
498 i.set((E) e);
499 }
500 }
501
502 /**
503 * Removes all of the elements from this list (optional operation).
504 * The list will be empty after this call returns.
505 *
506 * @throws UnsupportedOperationException if the {@code clear} operation
507 * is not supported by this list
508 */
509 void clear();
510
511
512 // Comparison and hashing
513
514 /**
515 * Compares the specified object with this list for equality. Returns
516 * {@code true} if and only if the specified object is also a list, both
517 * lists have the same size, and all corresponding pairs of elements in
518 * the two lists are <i>equal</i>. (Two elements {@code e1} and
519 * {@code e2} are <i>equal</i> if {@code Objects.equals(e1, e2)}.)
520 * In other words, two lists are defined to be
521 * equal if they contain the same elements in the same order. This
522 * definition ensures that the equals method works properly across
523 * different implementations of the {@code List} interface.
524 *
525 * @param o the object to be compared for equality with this list
526 * @return {@code true} if the specified object is equal to this list
527 */
528 boolean equals(Object o);
529
530 /**
531 * Returns the hash code value for this list. The hash code of a list
532 * is defined to be the result of the following calculation:
533 * <pre>{@code
534 * int hashCode = 1;
535 * for (E e : list)
536 * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
537 * }</pre>
538 * This ensures that {@code list1.equals(list2)} implies that
539 * {@code list1.hashCode()==list2.hashCode()} for any two lists,
540 * {@code list1} and {@code list2}, as required by the general
541 * contract of {@link Object#hashCode}.
542 *
543 * @return the hash code value for this list
544 * @see Object#equals(Object)
545 * @see #equals(Object)
546 */
547 int hashCode();
548
549
550 // Positional Access Operations
551
552 /**
553 * Returns the element at the specified position in this list.
554 *
555 * @param index index of the element to return
556 * @return the element at the specified position in this list
557 * @throws IndexOutOfBoundsException if the index is out of range
558 * ({@code index < 0 || index >= size()})
559 */
560 E get(int index);
561
562 /**
563 * Replaces the element at the specified position in this list with the
564 * specified element (optional operation).
565 *
566 * @param index index of the element to replace
567 * @param element element to be stored at the specified position
568 * @return the element previously at the specified position
569 * @throws UnsupportedOperationException if the {@code set} operation
570 * is not supported by this list
571 * @throws ClassCastException if the class of the specified element
572 * prevents it from being added to this list
573 * @throws NullPointerException if the specified element is null and
574 * this list does not permit null elements
575 * @throws IllegalArgumentException if some property of the specified
576 * element prevents it from being added to this list
577 * @throws IndexOutOfBoundsException if the index is out of range
578 * ({@code index < 0 || index >= size()})
579 */
580 E set(int index, E element);
581
582 /**
583 * Inserts the specified element at the specified position in this list
584 * (optional operation). Shifts the element currently at that position
585 * (if any) and any subsequent elements to the right (adds one to their
586 * indices).
587 *
588 * @param index index at which the specified element is to be inserted
589 * @param element element to be inserted
590 * @throws UnsupportedOperationException if the {@code add} operation
591 * is not supported by this list
592 * @throws ClassCastException if the class of the specified element
593 * prevents it from being added to this list
594 * @throws NullPointerException if the specified element is null and
595 * this list does not permit null elements
596 * @throws IllegalArgumentException if some property of the specified
597 * element prevents it from being added to this list
598 * @throws IndexOutOfBoundsException if the index is out of range
599 * ({@code index < 0 || index > size()})
600 */
601 void add(int index, E element);
602
603 /**
604 * Removes the element at the specified position in this list (optional
605 * operation). Shifts any subsequent elements to the left (subtracts one
606 * from their indices). Returns the element that was removed from the
607 * list.
608 *
609 * @param index the index of the element to be removed
610 * @return the element previously at the specified position
611 * @throws UnsupportedOperationException if the {@code remove} operation
612 * is not supported by this list
613 * @throws IndexOutOfBoundsException if the index is out of range
614 * ({@code index < 0 || index >= size()})
615 */
616 E remove(int index);
617
618
619 // Search Operations
620
621 /**
622 * Returns the index of the first occurrence of the specified element
623 * in this list, or -1 if this list does not contain the element.
624 * More formally, returns the lowest index {@code i} such that
625 * {@code Objects.equals(o, get(i))},
626 * or -1 if there is no such index.
627 *
628 * @param o element to search for
629 * @return the index of the first occurrence of the specified element in
630 * this list, or -1 if this list does not contain the element
631 * @throws ClassCastException if the type of the specified element
632 * is incompatible with this list
633 * (<a href="Collection.html#optional-restrictions">optional</a>)
634 * @throws NullPointerException if the specified element is null and this
635 * list does not permit null elements
636 * (<a href="Collection.html#optional-restrictions">optional</a>)
637 */
638 int indexOf(Object o);
639
640 /**
641 * Returns the index of the last occurrence of the specified element
642 * in this list, or -1 if this list does not contain the element.
643 * More formally, returns the highest index {@code i} such that
644 * {@code Objects.equals(o, get(i))},
645 * or -1 if there is no such index.
646 *
647 * @param o element to search for
648 * @return the index of the last occurrence of the specified element in
649 * this list, or -1 if this list does not contain the element
650 * @throws ClassCastException if the type of the specified element
651 * is incompatible with this list
652 * (<a href="Collection.html#optional-restrictions">optional</a>)
653 * @throws NullPointerException if the specified element is null and this
654 * list does not permit null elements
655 * (<a href="Collection.html#optional-restrictions">optional</a>)
656 */
657 int lastIndexOf(Object o);
658
659
660 // List Iterators
661
662 /**
663 * Returns a list iterator over the elements in this list (in proper
664 * sequence).
665 *
666 * @return a list iterator over the elements in this list (in proper
667 * sequence)
668 */
669 ListIterator<E> listIterator();
670
671 /**
672 * Returns a list iterator over the elements in this list (in proper
673 * sequence), starting at the specified position in the list.
674 * The specified index indicates the first element that would be
675 * returned by an initial call to {@link ListIterator#next next}.
676 * An initial call to {@link ListIterator#previous previous} would
677 * return the element with the specified index minus one.
678 *
679 * @param index index of the first element to be returned from the
680 * list iterator (by a call to {@link ListIterator#next next})
681 * @return a list iterator over the elements in this list (in proper
682 * sequence), starting at the specified position in the list
683 * @throws IndexOutOfBoundsException if the index is out of range
684 * ({@code index < 0 || index > size()})
685 */
686 ListIterator<E> listIterator(int index);
687
688 // View
689
690 /**
691 * Returns a view of the portion of this list between the specified
692 * {@code fromIndex}, inclusive, and {@code toIndex}, exclusive. (If
693 * {@code fromIndex} and {@code toIndex} are equal, the returned list is
694 * empty.) The returned list is backed by this list, so non-structural
695 * changes in the returned list are reflected in this list, and vice-versa.
696 * The returned list supports all of the optional list operations supported
697 * by this list.<p>
698 *
699 * This method eliminates the need for explicit range operations (of
700 * the sort that commonly exist for arrays). Any operation that expects
701 * a list can be used as a range operation by passing a subList view
702 * instead of a whole list. For example, the following idiom
703 * removes a range of elements from a list:
704 * <pre>{@code
705 * list.subList(from, to).clear();
706 * }</pre>
707 * Similar idioms may be constructed for {@code indexOf} and
708 * {@code lastIndexOf}, and all of the algorithms in the
709 * {@code Collections} class can be applied to a subList.<p>
710 *
711 * The semantics of the list returned by this method become undefined if
712 * the backing list (i.e., this list) is <i>structurally modified</i> in
713 * any way other than via the returned list. (Structural modifications are
714 * those that change the size of this list, or otherwise perturb it in such
715 * a fashion that iterations in progress may yield incorrect results.)
716 *
717 * @param fromIndex low endpoint (inclusive) of the subList
718 * @param toIndex high endpoint (exclusive) of the subList
719 * @return a view of the specified range within this list
720 * @throws IndexOutOfBoundsException for an illegal endpoint index value
721 * ({@code fromIndex < 0 || toIndex > size ||
722 * fromIndex > toIndex})
723 */
724 List<E> subList(int fromIndex, int toIndex);
725
726 /**
727 * Creates a {@link Spliterator} over the elements in this list.
728 *
729 * <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and
730 * {@link Spliterator#ORDERED}. Implementations should document the
731 * reporting of additional characteristic values.
732 *
733 * @implSpec
734 * The default implementation creates a
735 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
736 * from the list's {@code Iterator}. The spliterator inherits the
737 * <em>fail-fast</em> properties of the list's iterator.
738 *
739 * @implNote
740 * The created {@code Spliterator} additionally reports
741 * {@link Spliterator#SUBSIZED}.
742 *
743 * @return a {@code Spliterator} over the elements in this list
744 * @since 1.8
745 */
746 @Override
747 default Spliterator<E> spliterator() {
748 return Spliterators.spliterator(this, Spliterator.ORDERED);
749 }
750
751 /**
752 * Creates an immutable list containing zero elements.
753 *
754 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
755 *
756 * @param <E> the list's element type
757 * @return the newly created list
758 *
759 * @since 9
760 */
761 static <E> List<E> of() {
762 return Collections.emptyList();
763 }
764
765 /**
766 * Creates an immutable list containing one element.
767 *
768 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
769 *
770 * @param <E> the list's element type
771 * @param e1 the single list element
772 * @return the newly created list
773 * @throws NullPointerException if the element is null
774 *
775 * @since 9
776 */
777 static <E> List<E> of(E e1) {
778 return Collections.singletonList(Objects.requireNonNull(e1));
779 }
780
781 /**
782 * Creates an immutable list containing two elements.
783 *
784 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
785 *
786 * @param <E> the list's element type
787 * @param e1 the first list element
788 * @param e2 the second list element
789 * @return the newly created list
790 * @throws NullPointerException if an element is null
791 *
792 * @since 9
793 */
794 static <E> List<E> of(E e1, E e2) {
795 return Collections.unmodifiableList(
796 Arrays.asList(Objects.requireNonNull(e1),
797 Objects.requireNonNull(e2)));
798 }
799
800 /**
801 * Creates an immutable list containing three elements.
802 *
803 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
804 *
805 * @param <E> the list's element type
806 * @param e1 the first list element
807 * @param e2 the second list element
808 * @param e3 the third list element
809 * @return the newly created list
810 * @throws NullPointerException if an element is null
811 *
812 * @since 9
813 */
814 static <E> List<E> of(E e1, E e2, E e3) {
815 return Collections.unmodifiableList(
816 Arrays.asList(Objects.requireNonNull(e1),
817 Objects.requireNonNull(e2),
818 Objects.requireNonNull(e3)));
819 }
820
821 /**
822 * Creates an immutable list containing four elements.
823 *
824 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
825 *
826 * @param <E> the list's element type
827 * @param e1 the first list element
828 * @param e2 the second list element
829 * @param e3 the third list element
830 * @param e4 the fourth list element
831 * @return the newly created list
832 * @throws NullPointerException if an element is null
833 *
834 * @since 9
835 */
836 static <E> List<E> of(E e1, E e2, E e3, E e4) {
837 return Collections.unmodifiableList(
838 Arrays.asList(Objects.requireNonNull(e1),
839 Objects.requireNonNull(e2),
840 Objects.requireNonNull(e3),
841 Objects.requireNonNull(e4)));
842 }
843
844 /**
845 * Creates an immutable list containing five elements.
846 *
847 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
848 *
849 * @param <E> the list's element type
850 * @param e1 the first list element
851 * @param e2 the second list element
852 * @param e3 the third list element
853 * @param e4 the fourth list element
854 * @param e5 the fifth list element
855 * @return the newly created list
856 * @throws NullPointerException if an element is null
857 *
858 * @since 9
859 */
860 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5) {
861 return Collections.unmodifiableList(
862 Arrays.asList(Objects.requireNonNull(e1),
863 Objects.requireNonNull(e2),
864 Objects.requireNonNull(e3),
865 Objects.requireNonNull(e4),
866 Objects.requireNonNull(e5)));
867 }
868
869 /**
870 * Creates an immutable list containing six elements.
871 *
872 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
873 *
874 * @param <E> the list's element type
875 * @param e1 the first list element
876 * @param e2 the second list element
877 * @param e3 the third list element
878 * @param e4 the fourth list element
879 * @param e5 the fifth list element
880 * @param e6 the sixth list element
881 * @return the newly created list
882 * @throws NullPointerException if an element is null
883 *
884 * @since 9
885 */
886 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
887 return Collections.unmodifiableList(
888 Arrays.asList(Objects.requireNonNull(e1),
889 Objects.requireNonNull(e2),
890 Objects.requireNonNull(e3),
891 Objects.requireNonNull(e4),
892 Objects.requireNonNull(e5),
893 Objects.requireNonNull(e6)));
894 }
895
896 /**
897 * Creates an immutable list containing seven elements.
898 *
899 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
900 *
901 * @param <E> the list's element type
902 * @param e1 the first list element
903 * @param e2 the second list element
904 * @param e3 the third list element
905 * @param e4 the fourth list element
906 * @param e5 the fifth list element
907 * @param e6 the sixth list element
908 * @param e7 the seventh list element
909 * @return the newly created list
910 * @throws NullPointerException if an element is null
911 *
912 * @since 9
913 */
914 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
915 return Collections.unmodifiableList(
916 Arrays.asList(Objects.requireNonNull(e1),
917 Objects.requireNonNull(e2),
918 Objects.requireNonNull(e3),
919 Objects.requireNonNull(e4),
920 Objects.requireNonNull(e5),
921 Objects.requireNonNull(e6),
922 Objects.requireNonNull(e7)));
923 }
924
925 /**
926 * Creates an immutable list containing eight elements.
927 *
928 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
929 *
930 * @param <E> the list's element type
931 * @param e1 the first list element
932 * @param e2 the second list element
933 * @param e3 the third list element
934 * @param e4 the fourth list element
935 * @param e5 the fifth list element
936 * @param e6 the sixth list element
937 * @param e7 the seventh list element
938 * @param e8 the eighth list element
939 * @return the newly created list
940 * @throws NullPointerException if an element is null
941 *
942 * @since 9
943 */
944 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
945 return Collections.unmodifiableList(
946 Arrays.asList(Objects.requireNonNull(e1),
947 Objects.requireNonNull(e2),
948 Objects.requireNonNull(e3),
949 Objects.requireNonNull(e4),
950 Objects.requireNonNull(e5),
951 Objects.requireNonNull(e6),
952 Objects.requireNonNull(e7),
953 Objects.requireNonNull(e8)));
954 }
955
956 /**
957 * Creates an immutable list containing nine elements.
958 *
959 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
960 *
961 * @param <E> the list's element type
962 * @param e1 the first list element
963 * @param e2 the second list element
964 * @param e3 the third list element
965 * @param e4 the fourth list element
966 * @param e5 the fifth list element
967 * @param e6 the sixth list element
968 * @param e7 the seventh list element
969 * @param e8 the eighth list element
970 * @param e9 the ninth list element
971 * @return the newly created list
972 * @throws NullPointerException if an element is null
973 *
974 * @since 9
975 */
976 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
977 return Collections.unmodifiableList(
978 Arrays.asList(Objects.requireNonNull(e1),
979 Objects.requireNonNull(e2),
980 Objects.requireNonNull(e3),
981 Objects.requireNonNull(e4),
982 Objects.requireNonNull(e5),
983 Objects.requireNonNull(e6),
984 Objects.requireNonNull(e7),
985 Objects.requireNonNull(e8),
986 Objects.requireNonNull(e9)));
987 }
988
989 /**
990 * Creates an immutable list containing ten elements.
991 *
992 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
993 *
994 * @param <E> the list's element type
995 * @param e1 the first list element
996 * @param e2 the second list element
997 * @param e3 the third list element
998 * @param e4 the fourth list element
999 * @param e5 the fifth list element
1000 * @param e6 the sixth list element
1001 * @param e7 the seventh list element
1002 * @param e8 the eighth list element
1003 * @param e9 the ninth list element
1004 * @param e10 the tenth list element
1005 * @return the newly created list
1006 * @throws NullPointerException if an element is null
1007 *
1008 * @since 9
1009 */
1010 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
1011 return Collections.unmodifiableList(
1012 Arrays.asList(Objects.requireNonNull(e1),
1013 Objects.requireNonNull(e2),
1014 Objects.requireNonNull(e3),
1015 Objects.requireNonNull(e4),
1016 Objects.requireNonNull(e5),
1017 Objects.requireNonNull(e6),
1018 Objects.requireNonNull(e7),
1019 Objects.requireNonNull(e8),
1020 Objects.requireNonNull(e9),
1021 Objects.requireNonNull(e10)));
1022 }
1023
1024 /**
1025 * Creates an immutable list containing an arbitrary number of elements.
1026 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
1027 *
1028 * @apiNote
1029 * This method also accepts a single array as an argument. The element type of
1030 * the resulting list will be the component type of the array, and the size of
1031 * the list will be equal to the length of the array. To create a list with
1032 * a single element that is an array, do the following:
1033 *
1034 * <pre>{@code
1035 * String[] array = ... ;
1036 * List<String[]> list = List.<String[]>of(array);
1037 * }</pre>
1038 *
1039 * This will cause the {@link List#of(Object) List.of(E)} method
1040 * to be invoked instead.
1041 *
1042 * @param <E> the list's element type
1043 * @param es the elements to be contained in the list
1044 * @return the newly created list
1045 * @throws NullPointerException if an element is null or if the array is null
1046 *
1047 * @since 9
1048 */
1049 @SafeVarargs
1050 @SuppressWarnings("varargs")
1051 static <E> List<E> of(E... es) {
1052 es = es.clone(); // throws NPE if es is null
1053 for (E e : es) {
1054 Objects.requireNonNull(e);
1055 }
1056 return Collections.unmodifiableList(Arrays.asList(es));
1057 }
1058 }