< prev index next >

src/java.base/share/classes/java/util/List.java

Print this page
rev 54827 : 6394757: AbstractSet.removeAll semantics are surprisingly dependent on relative sizes
Reviewed-by: XXX
   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      *


< prev index next >