| 20 |
|
|
| 21 |
|
/** |
| 22 |
|
* A thread-safe variant of {@link java.util.ArrayList} in which all mutative |
| 23 |
< |
* operations (<tt>add</tt>, <tt>set</tt>, and so on) are implemented by |
| 23 |
> |
* operations ({@code add}, {@code set}, and so on) are implemented by |
| 24 |
|
* making a fresh copy of the underlying array. |
| 25 |
|
* |
| 26 |
|
* <p>This is ordinarily too costly, but may be <em>more</em> efficient |
| 31 |
|
* reference to the state of the array at the point that the iterator |
| 32 |
|
* was created. This array never changes during the lifetime of the |
| 33 |
|
* iterator, so interference is impossible and the iterator is |
| 34 |
< |
* guaranteed not to throw <tt>ConcurrentModificationException</tt>. |
| 34 |
> |
* guaranteed not to throw {@code ConcurrentModificationException}. |
| 35 |
|
* The iterator will not reflect additions, removals, or changes to |
| 36 |
|
* the list since the iterator was created. Element-changing |
| 37 |
< |
* operations on iterators themselves (<tt>remove</tt>, <tt>set</tt>, and |
| 38 |
< |
* <tt>add</tt>) are not supported. These methods throw |
| 39 |
< |
* <tt>UnsupportedOperationException</tt>. |
| 37 |
> |
* operations on iterators themselves ({@code remove}, {@code set}, and |
| 38 |
> |
* {@code add}) are not supported. These methods throw |
| 39 |
> |
* {@code UnsupportedOperationException}. |
| 40 |
|
* |
| 41 |
< |
* <p>All elements are permitted, including <tt>null</tt>. |
| 41 |
> |
* <p>All elements are permitted, including {@code null}. |
| 42 |
|
* |
| 43 |
|
* <p>Memory consistency effects: As with other concurrent |
| 44 |
|
* collections, actions in a thread prior to placing an object into a |
| 124 |
|
} |
| 125 |
|
|
| 126 |
|
/** |
| 127 |
< |
* Returns <tt>true</tt> if this list contains no elements. |
| 127 |
> |
* Returns {@code true} if this list contains no elements. |
| 128 |
|
* |
| 129 |
< |
* @return <tt>true</tt> if this list contains no elements |
| 129 |
> |
* @return {@code true} if this list contains no elements |
| 130 |
|
*/ |
| 131 |
|
public boolean isEmpty() { |
| 132 |
|
return size() == 0; |
| 183 |
|
} |
| 184 |
|
|
| 185 |
|
/** |
| 186 |
< |
* Returns <tt>true</tt> if this list contains the specified element. |
| 187 |
< |
* More formally, returns <tt>true</tt> if and only if this list contains |
| 188 |
< |
* at least one element <tt>e</tt> such that |
| 186 |
> |
* Returns {@code true} if this list contains the specified element. |
| 187 |
> |
* More formally, returns {@code true} if and only if this list contains |
| 188 |
> |
* at least one element {@code e} such that |
| 189 |
|
* <tt>(o==null ? e==null : o.equals(e))</tt>. |
| 190 |
|
* |
| 191 |
|
* @param o element whose presence in this list is to be tested |
| 192 |
< |
* @return <tt>true</tt> if this list contains the specified element |
| 192 |
> |
* @return {@code true} if this list contains the specified element |
| 193 |
|
*/ |
| 194 |
|
public boolean contains(Object o) { |
| 195 |
|
Object[] elements = getArray(); |
| 206 |
|
|
| 207 |
|
/** |
| 208 |
|
* Returns the index of the first occurrence of the specified element in |
| 209 |
< |
* this list, searching forwards from <tt>index</tt>, or returns -1 if |
| 209 |
> |
* this list, searching forwards from {@code index}, or returns -1 if |
| 210 |
|
* the element is not found. |
| 211 |
< |
* More formally, returns the lowest index <tt>i</tt> such that |
| 211 |
> |
* More formally, returns the lowest index {@code i} such that |
| 212 |
|
* <tt>(i >= index && (e==null ? get(i)==null : e.equals(get(i))))</tt>, |
| 213 |
|
* or -1 if there is no such index. |
| 214 |
|
* |
| 215 |
|
* @param e element to search for |
| 216 |
|
* @param index index to start searching from |
| 217 |
|
* @return the index of the first occurrence of the element in |
| 218 |
< |
* this list at position <tt>index</tt> or later in the list; |
| 219 |
< |
* <tt>-1</tt> if the element is not found. |
| 218 |
> |
* this list at position {@code index} or later in the list; |
| 219 |
> |
* {@code -1} if the element is not found. |
| 220 |
|
* @throws IndexOutOfBoundsException if the specified index is negative |
| 221 |
|
*/ |
| 222 |
|
public int indexOf(E e, int index) { |
| 234 |
|
|
| 235 |
|
/** |
| 236 |
|
* Returns the index of the last occurrence of the specified element in |
| 237 |
< |
* this list, searching backwards from <tt>index</tt>, or returns -1 if |
| 237 |
> |
* this list, searching backwards from {@code index}, or returns -1 if |
| 238 |
|
* the element is not found. |
| 239 |
< |
* More formally, returns the highest index <tt>i</tt> such that |
| 239 |
> |
* More formally, returns the highest index {@code i} such that |
| 240 |
|
* <tt>(i <= index && (e==null ? get(i)==null : e.equals(get(i))))</tt>, |
| 241 |
|
* or -1 if there is no such index. |
| 242 |
|
* |
| 243 |
|
* @param e element to search for |
| 244 |
|
* @param index index to start searching backwards from |
| 245 |
|
* @return the index of the last occurrence of the element at position |
| 246 |
< |
* less than or equal to <tt>index</tt> in this list; |
| 246 |
> |
* less than or equal to {@code index} in this list; |
| 247 |
|
* -1 if the element is not found. |
| 248 |
|
* @throws IndexOutOfBoundsException if the specified index is greater |
| 249 |
|
* than or equal to the current size of this list |
| 301 |
|
* <p>If this list fits in the specified array with room to spare |
| 302 |
|
* (i.e., the array has more elements than this list), the element in |
| 303 |
|
* the array immediately following the end of the list is set to |
| 304 |
< |
* <tt>null</tt>. (This is useful in determining the length of this |
| 304 |
> |
* {@code null}. (This is useful in determining the length of this |
| 305 |
|
* list <i>only</i> if the caller knows that this list does not contain |
| 306 |
|
* any null elements.) |
| 307 |
|
* |
| 310 |
|
* precise control over the runtime type of the output array, and may, |
| 311 |
|
* under certain circumstances, be used to save allocation costs. |
| 312 |
|
* |
| 313 |
< |
* <p>Suppose <tt>x</tt> is a list known to contain only strings. |
| 313 |
> |
* <p>Suppose {@code x} is a list known to contain only strings. |
| 314 |
|
* The following code can be used to dump the list into a newly |
| 315 |
< |
* allocated array of <tt>String</tt>: |
| 315 |
> |
* allocated array of {@code String}: |
| 316 |
|
* |
| 317 |
|
* <pre> {@code String[] y = x.toArray(new String[0]);}</pre> |
| 318 |
|
* |
| 319 |
< |
* Note that <tt>toArray(new Object[0])</tt> is identical in function to |
| 320 |
< |
* <tt>toArray()</tt>. |
| 319 |
> |
* Note that {@code toArray(new Object[0])} is identical in function to |
| 320 |
> |
* {@code toArray()}. |
| 321 |
|
* |
| 322 |
|
* @param a the array into which the elements of the list are to |
| 323 |
|
* be stored, if it is big enough; otherwise, a new array of the |
| 390 |
|
* Appends the specified element to the end of this list. |
| 391 |
|
* |
| 392 |
|
* @param e element to be appended to this list |
| 393 |
< |
* @return <tt>true</tt> (as specified by {@link Collection#add}) |
| 393 |
> |
* @return {@code true} (as specified by {@link Collection#add}) |
| 394 |
|
*/ |
| 395 |
|
public boolean add(E e) { |
| 396 |
|
final ReentrantLock lock = this.lock; |
| 474 |
|
* Removes the first occurrence of the specified element from this list, |
| 475 |
|
* if it is present. If this list does not contain the element, it is |
| 476 |
|
* unchanged. More formally, removes the element with the lowest index |
| 477 |
< |
* <tt>i</tt> such that |
| 477 |
> |
* {@code i} such that |
| 478 |
|
* <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt> |
| 479 |
< |
* (if such an element exists). Returns <tt>true</tt> if this list |
| 479 |
> |
* (if such an element exists). Returns {@code true} if this list |
| 480 |
|
* contained the specified element (or equivalently, if this list |
| 481 |
|
* changed as a result of the call). |
| 482 |
|
* |
| 483 |
|
* @param o element to be removed from this list, if present |
| 484 |
< |
* @return <tt>true</tt> if this list contained the specified element |
| 484 |
> |
* @return {@code true} if this list contained the specified element |
| 485 |
|
*/ |
| 486 |
|
public boolean remove(Object o) { |
| 487 |
|
final ReentrantLock lock = this.lock; |
| 520 |
|
|
| 521 |
|
/** |
| 522 |
|
* Removes from this list all of the elements whose index is between |
| 523 |
< |
* <tt>fromIndex</tt>, inclusive, and <tt>toIndex</tt>, exclusive. |
| 523 |
> |
* {@code fromIndex}, inclusive, and {@code toIndex}, exclusive. |
| 524 |
|
* Shifts any succeeding elements to the left (reduces their index). |
| 525 |
< |
* This call shortens the list by <tt>(toIndex - fromIndex)</tt> elements. |
| 526 |
< |
* (If <tt>toIndex==fromIndex</tt>, this operation has no effect.) |
| 525 |
> |
* This call shortens the list by {@code (toIndex - fromIndex)} elements. |
| 526 |
> |
* (If {@code toIndex==fromIndex}, this operation has no effect.) |
| 527 |
|
* |
| 528 |
|
* @param fromIndex index of first element to be removed |
| 529 |
|
* @param toIndex index after last element to be removed |
| 559 |
|
* Appends the element, if not present. |
| 560 |
|
* |
| 561 |
|
* @param e element to be added to this list, if absent |
| 562 |
< |
* @return <tt>true</tt> if the element was added |
| 562 |
> |
* @return {@code true} if the element was added |
| 563 |
|
*/ |
| 564 |
|
public boolean addIfAbsent(E e) { |
| 565 |
|
final ReentrantLock lock = this.lock; |
| 585 |
|
} |
| 586 |
|
|
| 587 |
|
/** |
| 588 |
< |
* Returns <tt>true</tt> if this list contains all of the elements of the |
| 588 |
> |
* Returns {@code true} if this list contains all of the elements of the |
| 589 |
|
* specified collection. |
| 590 |
|
* |
| 591 |
|
* @param c collection to be checked for containment in this list |
| 592 |
< |
* @return <tt>true</tt> if this list contains all of the elements of the |
| 592 |
> |
* @return {@code true} if this list contains all of the elements of the |
| 593 |
|
* specified collection |
| 594 |
|
* @throws NullPointerException if the specified collection is null |
| 595 |
|
* @see #contains(Object) |
| 610 |
|
* in this class because of the need for an internal temporary array. |
| 611 |
|
* |
| 612 |
|
* @param c collection containing elements to be removed from this list |
| 613 |
< |
* @return <tt>true</tt> if this list changed as a result of the call |
| 613 |
> |
* @return {@code true} if this list changed as a result of the call |
| 614 |
|
* @throws ClassCastException if the class of an element of this list |
| 615 |
|
* is incompatible with the specified collection |
| 616 |
|
* (<a href="../Collection.html#optional-restrictions">optional</a>) |
| 653 |
|
* its elements that are not contained in the specified collection. |
| 654 |
|
* |
| 655 |
|
* @param c collection containing elements to be retained in this list |
| 656 |
< |
* @return <tt>true</tt> if this list changed as a result of the call |
| 656 |
> |
* @return {@code true} if this list changed as a result of the call |
| 657 |
|
* @throws ClassCastException if the class of an element of this list |
| 658 |
|
* is incompatible with the specified collection |
| 659 |
|
* (<a href="../Collection.html#optional-restrictions">optional</a>) |
| 749 |
|
* collection's iterator. |
| 750 |
|
* |
| 751 |
|
* @param c collection containing elements to be added to this list |
| 752 |
< |
* @return <tt>true</tt> if this list changed as a result of the call |
| 752 |
> |
* @return {@code true} if this list changed as a result of the call |
| 753 |
|
* @throws NullPointerException if the specified collection is null |
| 754 |
|
* @see #add(Object) |
| 755 |
|
*/ |
| 782 |
|
* @param index index at which to insert the first element |
| 783 |
|
* from the specified collection |
| 784 |
|
* @param c collection containing elements to be added to this list |
| 785 |
< |
* @return <tt>true</tt> if this list changed as a result of the call |
| 785 |
> |
* @return {@code true} if this list changed as a result of the call |
| 786 |
|
* @throws IndexOutOfBoundsException {@inheritDoc} |
| 787 |
|
* @throws NullPointerException if the specified collection is null |
| 788 |
|
* @see #add(int,Object) |
| 864 |
|
* Returns a string representation of this list. The string |
| 865 |
|
* representation consists of the string representations of the list's |
| 866 |
|
* elements in the order they are returned by its iterator, enclosed in |
| 867 |
< |
* square brackets (<tt>"[]"</tt>). Adjacent elements are separated by |
| 868 |
< |
* the characters <tt>", "</tt> (comma and space). Elements are |
| 867 |
> |
* square brackets ({@code "[]"}). Adjacent elements are separated by |
| 868 |
> |
* the characters {@code ", "} (comma and space). Elements are |
| 869 |
|
* converted to strings as by {@link String#valueOf(Object)}. |
| 870 |
|
* |
| 871 |
|
* @return a string representation of this list |
| 931 |
|
* <p>The returned iterator provides a snapshot of the state of the list |
| 932 |
|
* when the iterator was constructed. No synchronization is needed while |
| 933 |
|
* traversing the iterator. The iterator does <em>NOT</em> support the |
| 934 |
< |
* <tt>remove</tt> method. |
| 934 |
> |
* {@code remove} method. |
| 935 |
|
* |
| 936 |
|
* @return an iterator over the elements in this list in proper sequence |
| 937 |
|
*/ |
| 945 |
|
* <p>The returned iterator provides a snapshot of the state of the list |
| 946 |
|
* when the iterator was constructed. No synchronization is needed while |
| 947 |
|
* traversing the iterator. The iterator does <em>NOT</em> support the |
| 948 |
< |
* <tt>remove</tt>, <tt>set</tt> or <tt>add</tt> methods. |
| 948 |
> |
* {@code remove}, {@code set} or {@code add} methods. |
| 949 |
|
*/ |
| 950 |
|
public ListIterator<E> listIterator() { |
| 951 |
|
return new COWIterator<E>(getArray(), 0); |
| 957 |
|
* <p>The returned iterator provides a snapshot of the state of the list |
| 958 |
|
* when the iterator was constructed. No synchronization is needed while |
| 959 |
|
* traversing the iterator. The iterator does <em>NOT</em> support the |
| 960 |
< |
* <tt>remove</tt>, <tt>set</tt> or <tt>add</tt> methods. |
| 960 |
> |
* {@code remove}, {@code set} or {@code add} methods. |
| 961 |
|
* |
| 962 |
|
* @throws IndexOutOfBoundsException {@inheritDoc} |
| 963 |
|
*/ |
| 1013 |
|
|
| 1014 |
|
/** |
| 1015 |
|
* Not supported. Always throws UnsupportedOperationException. |
| 1016 |
< |
* @throws UnsupportedOperationException always; <tt>remove</tt> |
| 1016 |
> |
* @throws UnsupportedOperationException always; {@code remove} |
| 1017 |
|
* is not supported by this iterator. |
| 1018 |
|
*/ |
| 1019 |
|
public void remove() { |
| 1022 |
|
|
| 1023 |
|
/** |
| 1024 |
|
* Not supported. Always throws UnsupportedOperationException. |
| 1025 |
< |
* @throws UnsupportedOperationException always; <tt>set</tt> |
| 1025 |
> |
* @throws UnsupportedOperationException always; {@code set} |
| 1026 |
|
* is not supported by this iterator. |
| 1027 |
|
*/ |
| 1028 |
|
public void set(E e) { |
| 1031 |
|
|
| 1032 |
|
/** |
| 1033 |
|
* Not supported. Always throws UnsupportedOperationException. |
| 1034 |
< |
* @throws UnsupportedOperationException always; <tt>add</tt> |
| 1034 |
> |
* @throws UnsupportedOperationException always; {@code add} |
| 1035 |
|
* is not supported by this iterator. |
| 1036 |
|
*/ |
| 1037 |
|
public void add(E e) { |
| 1041 |
|
|
| 1042 |
|
/** |
| 1043 |
|
* Returns a view of the portion of this list between |
| 1044 |
< |
* <tt>fromIndex</tt>, inclusive, and <tt>toIndex</tt>, exclusive. |
| 1044 |
> |
* {@code fromIndex}, inclusive, and {@code toIndex}, exclusive. |
| 1045 |
|
* The returned list is backed by this list, so changes in the |
| 1046 |
|
* returned list are reflected in this list. |
| 1047 |
|
* |
