1 /*
2 * Copyright (c) 1997, 2018, 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
275 * as a result of the call).
276 *
277 * @param o element to be removed from this list, if present
278 * @return {@code true} if this list contained the specified element
279 * @throws ClassCastException if the type of the specified element
280 * is incompatible with this list
281 * (<a href="Collection.html#optional-restrictions">optional</a>)
282 * @throws NullPointerException if the specified element is null and this
283 * list does not permit null elements
284 * (<a href="Collection.html#optional-restrictions">optional</a>)
285 * @throws UnsupportedOperationException if the {@code remove} operation
286 * is not supported by this list
287 */
288 boolean remove(Object o);
289
290
291 // Bulk Modification Operations
292
293 /**
294 * Returns {@code true} if this list contains all of the elements of the
295 * specified collection.
296 *
297 * @param c collection to be checked for containment in this list
298 * @return {@code true} if this list contains all of the elements of the
299 * specified collection
300 * @throws ClassCastException if the types of one or more elements
301 * in the specified collection are incompatible with this
302 * list
303 * (<a href="Collection.html#optional-restrictions">optional</a>)
304 * @throws NullPointerException if the specified collection contains one
305 * or more null elements and this list does not permit null
306 * elements
307 * (<a href="Collection.html#optional-restrictions">optional</a>),
308 * or if the specified collection is null
309 * @see #contains(Object)
310 */
311 boolean containsAll(Collection<?> c);
312
313 /**
314 * Appends all of the elements in the specified collection to the end of
315 * this list, in the order that they are returned by the specified
347 * @param index index at which to insert the first element from the
348 * specified collection
349 * @param c collection containing elements to be added to this list
350 * @return {@code true} if this list changed as a result of the call
351 * @throws UnsupportedOperationException if the {@code addAll} operation
352 * is not supported by this list
353 * @throws ClassCastException if the class of an element of the specified
354 * collection prevents it from being added to this list
355 * @throws NullPointerException if the specified collection contains one
356 * or more null elements and this list does not permit null
357 * elements, or if the specified collection is null
358 * @throws IllegalArgumentException if some property of an element of the
359 * specified collection prevents it from being added to this list
360 * @throws IndexOutOfBoundsException if the index is out of range
361 * ({@code index < 0 || index > size()})
362 */
363 boolean addAll(int index, Collection<? extends E> c);
364
365 /**
366 * Removes from this list all of its elements that are contained in the
367 * specified collection (optional operation).
368 *
369 * @param c collection containing elements to be removed from this list
370 * @return {@code true} if this list changed as a result of the call
371 * @throws UnsupportedOperationException if the {@code removeAll} operation
372 * is not supported by this list
373 * @throws ClassCastException if the class of an element of this list
374 * is incompatible with the specified collection
375 * (<a href="Collection.html#optional-restrictions">optional</a>)
376 * @throws NullPointerException if this list contains a null element and the
377 * specified collection does not permit null elements
378 * (<a href="Collection.html#optional-restrictions">optional</a>),
379 * or if the specified collection is null
380 * @see #remove(Object)
381 * @see #contains(Object)
382 */
383 boolean removeAll(Collection<?> c);
384
385 /**
386 * Retains only the elements in this list that are contained in the
387 * specified collection (optional operation). In other words, removes
388 * from this list all of its elements that are not contained in the
389 * specified collection.
390 *
391 * @param c collection containing elements to be retained in this list
392 * @return {@code true} if this list changed as a result of the call
393 * @throws UnsupportedOperationException if the {@code retainAll} operation
394 * is not supported by this list
395 * @throws ClassCastException if the class of an element of this list
396 * is incompatible with the specified collection
397 * (<a href="Collection.html#optional-restrictions">optional</a>)
398 * @throws NullPointerException if this list contains a null element and the
399 * specified collection does not permit null elements
400 * (<a href="Collection.html#optional-restrictions">optional</a>),
401 * or if the specified collection is null
402 * @see #remove(Object)
403 * @see #contains(Object)
404 */
405 boolean retainAll(Collection<?> c);
406
407 /**
408 * Replaces each element of this list with the result of applying the
409 * operator to that element. Errors or runtime exceptions thrown by
511 }
512 }
513
514 /**
515 * Removes all of the elements from this list (optional operation).
516 * The list will be empty after this call returns.
517 *
518 * @throws UnsupportedOperationException if the {@code clear} operation
519 * is not supported by this list
520 */
521 void clear();
522
523
524 // Comparison and hashing
525
526 /**
527 * Compares the specified object with this list for equality. Returns
528 * {@code true} if and only if the specified object is also a list, both
529 * lists have the same size, and all corresponding pairs of elements in
530 * the two lists are <i>equal</i>. (Two elements {@code e1} and
531 * {@code e2} are <i>equal</i> if {@code Objects.equals(e1, e2)}.)
532 * In other words, two lists are defined to be
533 * equal if they contain the same elements in the same order. This
534 * definition ensures that the equals method works properly across
535 * different implementations of the {@code List} interface.
536 *
537 * @param o the object to be compared for equality with this list
538 * @return {@code true} if the specified object is equal to this list
539 */
540 boolean equals(Object o);
541
542 /**
543 * Returns the hash code value for this list. The hash code of a list
544 * is defined to be the result of the following calculation:
545 * <pre>{@code
546 * int hashCode = 1;
547 * for (E e : list)
548 * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
549 * }</pre>
550 * This ensures that {@code list1.equals(list2)} implies that
551 * {@code list1.hashCode()==list2.hashCode()} for any two lists,
552 * {@code list1} and {@code list2}, as required by the general
553 * contract of {@link Object#hashCode}.
554 *
|
1 /*
2 * Copyright (c) 1997, 2019, 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
275 * as a result of the call).
276 *
277 * @param o element to be removed from this list, if present
278 * @return {@code true} if this list contained the specified element
279 * @throws ClassCastException if the type of the specified element
280 * is incompatible with this list
281 * (<a href="Collection.html#optional-restrictions">optional</a>)
282 * @throws NullPointerException if the specified element is null and this
283 * list does not permit null elements
284 * (<a href="Collection.html#optional-restrictions">optional</a>)
285 * @throws UnsupportedOperationException if the {@code remove} operation
286 * is not supported by this list
287 */
288 boolean remove(Object o);
289
290
291 // Bulk Modification Operations
292
293 /**
294 * Returns {@code true} if this list contains all of the elements of the
295 * specified collection. This operation uses the membership semantics
296 * of this list.
297 *
298 * @param c collection to be checked for containment in this list
299 * @return {@code true} if this list contains all of the elements of the
300 * specified collection
301 * @throws ClassCastException if the types of one or more elements
302 * in the specified collection are incompatible with this
303 * list
304 * (<a href="Collection.html#optional-restrictions">optional</a>)
305 * @throws NullPointerException if the specified collection contains one
306 * or more null elements and this list does not permit null
307 * elements
308 * (<a href="Collection.html#optional-restrictions">optional</a>),
309 * or if the specified collection is null
310 * @see #contains(Object)
311 */
312 boolean containsAll(Collection<?> c);
313
314 /**
315 * Appends all of the elements in the specified collection to the end of
316 * this list, in the order that they are returned by the specified
348 * @param index index at which to insert the first element from the
349 * specified collection
350 * @param c collection containing elements to be added to this list
351 * @return {@code true} if this list changed as a result of the call
352 * @throws UnsupportedOperationException if the {@code addAll} operation
353 * is not supported by this list
354 * @throws ClassCastException if the class of an element of the specified
355 * collection prevents it from being added to this list
356 * @throws NullPointerException if the specified collection contains one
357 * or more null elements and this list does not permit null
358 * elements, or if the specified collection is null
359 * @throws IllegalArgumentException if some property of an element of the
360 * specified collection prevents it from being added to this list
361 * @throws IndexOutOfBoundsException if the index is out of range
362 * ({@code index < 0 || index > size()})
363 */
364 boolean addAll(int index, Collection<? extends E> c);
365
366 /**
367 * Removes from this list all of its elements that are contained in the
368 * specified collection (optional operation). This operation uses the
369 * membership semantics of the specified collection.
370 *
371 * @implNote
372 * {@inheritDoc}
373 *
374 * @param c collection containing elements to be removed from this list
375 * @return {@code true} if this list changed as a result of the call
376 * @throws UnsupportedOperationException if the {@code removeAll} operation
377 * is not supported by this list
378 * @throws ClassCastException if the class of an element of this list
379 * is incompatible with the specified collection
380 * (<a href="Collection.html#optional-restrictions">optional</a>)
381 * @throws NullPointerException if this list contains a null element and the
382 * specified collection does not permit null elements
383 * (<a href="Collection.html#optional-restrictions">optional</a>),
384 * or if the specified collection is null
385 * @see #remove(Object)
386 * @see #contains(Object)
387 */
388 boolean removeAll(Collection<?> c);
389
390 /**
391 * Retains only the elements in this list that are contained in the
392 * specified collection (optional operation). In other words, removes
393 * from this list all of its elements that are not contained in the
394 * specified collection. This operation uses the membership semantics of
395 * the specified collection.
396 *
397 * @implNote
398 * {@inheritDoc}
399 *
400 * @param c collection containing elements to be retained in this list
401 * @return {@code true} if this list changed as a result of the call
402 * @throws UnsupportedOperationException if the {@code retainAll} operation
403 * is not supported by this list
404 * @throws ClassCastException if the class of an element of this list
405 * is incompatible with the specified collection
406 * (<a href="Collection.html#optional-restrictions">optional</a>)
407 * @throws NullPointerException if this list contains a null element and the
408 * specified collection does not permit null elements
409 * (<a href="Collection.html#optional-restrictions">optional</a>),
410 * or if the specified collection is null
411 * @see #remove(Object)
412 * @see #contains(Object)
413 */
414 boolean retainAll(Collection<?> c);
415
416 /**
417 * Replaces each element of this list with the result of applying the
418 * operator to that element. Errors or runtime exceptions thrown by
520 }
521 }
522
523 /**
524 * Removes all of the elements from this list (optional operation).
525 * The list will be empty after this call returns.
526 *
527 * @throws UnsupportedOperationException if the {@code clear} operation
528 * is not supported by this list
529 */
530 void clear();
531
532
533 // Comparison and hashing
534
535 /**
536 * Compares the specified object with this list for equality. Returns
537 * {@code true} if and only if the specified object is also a list, both
538 * lists have the same size, and all corresponding pairs of elements in
539 * the two lists are <i>equal</i>. (Two elements {@code e1} and
540 * {@code e2} are <i>equal</i> if {@code (e1==null ? e2==null :
541 * e1.equals(e2))}.) In other words, two lists are defined to be
542 * equal if they contain the same elements in the same order. This
543 * definition ensures that the {@code equals} method works properly across
544 * different implementations of the {@code List} interface.
545 *
546 * @param o the object to be compared for equality with this list
547 * @return {@code true} if the specified object is equal to this list
548 */
549 boolean equals(Object o);
550
551 /**
552 * Returns the hash code value for this list. The hash code of a list
553 * is defined to be the result of the following calculation:
554 * <pre>{@code
555 * int hashCode = 1;
556 * for (E e : list)
557 * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
558 * }</pre>
559 * This ensures that {@code list1.equals(list2)} implies that
560 * {@code list1.hashCode()==list2.hashCode()} for any two lists,
561 * {@code list1} and {@code list2}, as required by the general
562 * contract of {@link Object#hashCode}.
563 *
|