< prev index next >

src/java.desktop/share/classes/sun/awt/util/IdentityLinkedList.java

Print this page

        

*** 33,54 **** import java.util.List; import java.util.ListIterator; import java.util.NoSuchElementException; /** ! * Linked list implementation of the <tt>List</tt> interface. Implements all * optional list operations, and permits all elements (including ! * <tt>null</tt>). In addition to implementing the <tt>List</tt> interface, ! * the <tt>IdentityLinkedList</tt> class provides uniformly named methods to ! * <tt>get</tt>, <tt>remove</tt> and <tt>insert</tt> an element at the * beginning and end of the list. These operations allow linked lists to be * used as a stack, {@linkplain java.util.Queue queue}, or {@linkplain Deque * double-ended queue}. <p> * ! * The class implements the <tt>Deque</tt> interface, providing ! * first-in-first-out queue operations for <tt>add</tt>, ! * <tt>poll</tt>, along with other stack and deque operations.<p> * * All of the operations perform as could be expected for a doubly-linked * list. Operations that index into the list will traverse the list from * the beginning or the end, whichever is closer to the specified index.<p> * --- 33,54 ---- import java.util.List; import java.util.ListIterator; import java.util.NoSuchElementException; /** ! * Linked list implementation of the {@code List} interface. Implements all * optional list operations, and permits all elements (including ! * {@code null}). In addition to implementing the {@code List} interface, ! * the {@code IdentityLinkedList} class provides uniformly named methods to ! * {@code get}, {@code remove} and {@code insert} an element at the * beginning and end of the list. These operations allow linked lists to be * used as a stack, {@linkplain java.util.Queue queue}, or {@linkplain Deque * double-ended queue}. <p> * ! * The class implements the {@code Deque} interface, providing ! * first-in-first-out queue operations for {@code add}, ! * {@code poll}, along with other stack and deque operations.<p> * * All of the operations perform as could be expected for a doubly-linked * list. Operations that index into the list will traverse the list from * the beginning or the end, whichever is closer to the specified index.<p> *
*** 65,88 **** * {@link java.util.Collections#synchronizedList Collections.synchronizedList} * method. This is best done at creation time, to prevent accidental * unsynchronized access to the list:<pre> * List list = Collections.synchronizedList(new IdentityLinkedList(...));</pre> * ! * <p>The iterators returned by this class's <tt>iterator</tt> and ! * <tt>listIterator</tt> methods are <i>fail-fast</i>: if the list is * structurally modified at any time after the iterator is created, in ! * any way except through the Iterator's own <tt>remove</tt> or ! * <tt>add</tt> methods, the iterator will throw a {@link * ConcurrentModificationException}. Thus, in the face of concurrent * modification, the iterator fails quickly and cleanly, rather than * risking arbitrary, non-deterministic behavior at an undetermined * time in the future. * * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed * as it is, generally speaking, impossible to make any hard guarantees in the * presence of unsynchronized concurrent modification. Fail-fast iterators ! * throw <tt>ConcurrentModificationException</tt> on a best-effort basis. * Therefore, it would be wrong to write a program that depended on this * exception for its correctness: <i>the fail-fast behavior of iterators * should be used only to detect bugs.</i> */ --- 65,88 ---- * {@link java.util.Collections#synchronizedList Collections.synchronizedList} * method. This is best done at creation time, to prevent accidental * unsynchronized access to the list:<pre> * List list = Collections.synchronizedList(new IdentityLinkedList(...));</pre> * ! * <p>The iterators returned by this class's {@code iterator} and ! * {@code listIterator} methods are <i>fail-fast</i>: if the list is * structurally modified at any time after the iterator is created, in ! * any way except through the Iterator's own {@code remove} or ! * {@code add} methods, the iterator will throw a {@link * ConcurrentModificationException}. Thus, in the face of concurrent * modification, the iterator fails quickly and cleanly, rather than * risking arbitrary, non-deterministic behavior at an undetermined * time in the future. * * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed * as it is, generally speaking, impossible to make any hard guarantees in the * presence of unsynchronized concurrent modification. Fail-fast iterators ! * throw {@code ConcurrentModificationException} on a best-effort basis. * Therefore, it would be wrong to write a program that depended on this * exception for its correctness: <i>the fail-fast behavior of iterators * should be used only to detect bugs.</i> */
*** 178,194 **** public void addLast(E e) { addBefore(e, header); } /** ! * Returns <tt>true</tt> if this list contains the specified element. ! * More formally, returns <tt>true</tt> if and only if this list contains ! * at least one element <tt>e</tt> such that ! * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o == e)</tt>. * * @param o element whose presence in this list is to be tested ! * @return <tt>true</tt> if this list contains the specified element */ public boolean contains(Object o) { return indexOf(o) != -1; } --- 178,194 ---- public void addLast(E e) { addBefore(e, header); } /** ! * Returns {@code true} if this list contains the specified element. ! * More formally, returns {@code true} if and only if this list contains ! * at least one element {@code e} such that ! * {@code Objects.equals(o, e)}. * * @param o element whose presence in this list is to be tested ! * @return {@code true} if this list contains the specified element */ public boolean contains(Object o) { return indexOf(o) != -1; }
*** 205,232 **** * Appends the specified element to the end of this list. * * <p>This method is equivalent to {@link #addLast}. * * @param e element to be appended to this list ! * @return <tt>true</tt> (as specified by {@link Collection#add}) */ public boolean add(E e) { addBefore(e, header); return true; } /** * Removes the first occurrence of the specified element from this list, * if it is present. If this list does not contain the element, it is * unchanged. More formally, removes the element with the lowest index ! * <tt>i</tt> such that <tt>get(i)==o</tt> ! * (if such an element exists). Returns <tt>true</tt> if this list * contained the specified element (or equivalently, if this list * changed as a result of the call). * * @param o element to be removed from this list, if present ! * @return <tt>true</tt> if this list contained the specified element */ public boolean remove(Object o) { for (Entry<E> e = header.next; e != header; e = e.next) { if (o == e.element) { remove(e); --- 205,232 ---- * Appends the specified element to the end of this list. * * <p>This method is equivalent to {@link #addLast}. * * @param e element to be appended to this list ! * @return {@code true} (as specified by {@link Collection#add}) */ public boolean add(E e) { addBefore(e, header); return true; } /** * Removes the first occurrence of the specified element from this list, * if it is present. If this list does not contain the element, it is * unchanged. More formally, removes the element with the lowest index ! * {@code i} such that {@code get(i)==o} ! * (if such an element exists). Returns {@code true} if this list * contained the specified element (or equivalently, if this list * changed as a result of the call). * * @param o element to be removed from this list, if present ! * @return {@code true} if this list contained the specified element */ public boolean remove(Object o) { for (Entry<E> e = header.next; e != header; e = e.next) { if (o == e.element) { remove(e);
*** 243,253 **** * the specified collection is modified while the operation is in * progress. (Note that this will occur if the specified collection is * this list, and it's nonempty.) * * @param c collection containing elements to be added to this list ! * @return <tt>true</tt> if this list changed as a result of the call * @throws NullPointerException if the specified collection is null */ public boolean addAll(Collection<? extends E> c) { return addAll(size, c); } --- 243,253 ---- * the specified collection is modified while the operation is in * progress. (Note that this will occur if the specified collection is * this list, and it's nonempty.) * * @param c collection containing elements to be added to this list ! * @return {@code true} if this list changed as a result of the call * @throws NullPointerException if the specified collection is null */ public boolean addAll(Collection<? extends E> c) { return addAll(size, c); }
*** 261,271 **** * specified collection's iterator. * * @param index index at which to insert the first element * from the specified collection * @param c collection containing elements to be added to this list ! * @return <tt>true</tt> if this list changed as a result of the call * @throws IndexOutOfBoundsException {@inheritDoc} * @throws NullPointerException if the specified collection is null */ public boolean addAll(int index, Collection<? extends E> c) { if (index < 0 || index > size) --- 261,271 ---- * specified collection's iterator. * * @param index index at which to insert the first element * from the specified collection * @param c collection containing elements to be added to this list ! * @return {@code true} if this list changed as a result of the call * @throws IndexOutOfBoundsException {@inheritDoc} * @throws NullPointerException if the specified collection is null */ public boolean addAll(int index, Collection<? extends E> c) { if (index < 0 || index > size)
*** 386,397 **** // Search Operations /** * Returns the index of the first occurrence of the specified element * in this list, or -1 if this list does not contain the element. ! * More formally, returns the lowest index <tt>i</tt> such that ! * <tt>get(i)==o</tt>, * or -1 if there is no such index. * * @param o element to search for * @return the index of the first occurrence of the specified element in * this list, or -1 if this list does not contain the element --- 386,397 ---- // Search Operations /** * Returns the index of the first occurrence of the specified element * in this list, or -1 if this list does not contain the element. ! * More formally, returns the lowest index {@code i} such that ! * {@code get(i)==o}, * or -1 if there is no such index. * * @param o element to search for * @return the index of the first occurrence of the specified element in * this list, or -1 if this list does not contain the element
*** 408,419 **** } /** * Returns the index of the last occurrence of the specified element * in this list, or -1 if this list does not contain the element. ! * More formally, returns the highest index <tt>i</tt> such that ! * <tt>get(i)==o</tt>, * or -1 if there is no such index. * * @param o element to search for * @return the index of the last occurrence of the specified element in * this list, or -1 if this list does not contain the element --- 408,419 ---- } /** * Returns the index of the last occurrence of the specified element * in this list, or -1 if this list does not contain the element. ! * More formally, returns the highest index {@code i} such that ! * {@code get(i)==o}, * or -1 if there is no such index. * * @param o element to search for * @return the index of the last occurrence of the specified element in * this list, or -1 if this list does not contain the element
*** 431,441 **** // Queue operations. /** * Retrieves, but does not remove, the head (first element) of this list. ! * @return the head of this list, or <tt>null</tt> if this list is empty * @since 1.5 */ public E peek() { if (size==0) return null; --- 431,441 ---- // Queue operations. /** * Retrieves, but does not remove, the head (first element) of this list. ! * @return the head of this list, or {@code null} if this list is empty * @since 1.5 */ public E peek() { if (size==0) return null;
*** 452,462 **** return getFirst(); } /** * Retrieves and removes the head (first element) of this list ! * @return the head of this list, or <tt>null</tt> if this list is empty * @since 1.5 */ public E poll() { if (size==0) return null; --- 452,462 ---- return getFirst(); } /** * Retrieves and removes the head (first element) of this list ! * @return the head of this list, or {@code null} if this list is empty * @since 1.5 */ public E poll() { if (size==0) return null;
*** 476,486 **** /** * Adds the specified element as the tail (last element) of this list. * * @param e the element to add ! * @return <tt>true</tt> (as specified by {@link java.util.Queue#offer}) * @since 1.5 */ public boolean offer(E e) { return add(e); } --- 476,486 ---- /** * Adds the specified element as the tail (last element) of this list. * * @param e the element to add ! * @return {@code true} (as specified by {@link java.util.Queue#offer}) * @since 1.5 */ public boolean offer(E e) { return add(e); }
*** 488,498 **** // Deque operations /** * Inserts the specified element at the front of this list. * * @param e the element to insert ! * @return <tt>true</tt> (as specified by {@link Deque#offerFirst}) * @since 1.6 */ public boolean offerFirst(E e) { addFirst(e); return true; --- 488,498 ---- // Deque operations /** * Inserts the specified element at the front of this list. * * @param e the element to insert ! * @return {@code true} (as specified by {@link Deque#offerFirst}) * @since 1.6 */ public boolean offerFirst(E e) { addFirst(e); return true;
*** 500,522 **** /** * Inserts the specified element at the end of this list. * * @param e the element to insert ! * @return <tt>true</tt> (as specified by {@link Deque#offerLast}) * @since 1.6 */ public boolean offerLast(E e) { addLast(e); return true; } /** * Retrieves, but does not remove, the first element of this list, ! * or returns <tt>null</tt> if this list is empty. * ! * @return the first element of this list, or <tt>null</tt> * if this list is empty * @since 1.6 */ public E peekFirst() { if (size==0) --- 500,522 ---- /** * Inserts the specified element at the end of this list. * * @param e the element to insert ! * @return {@code true} (as specified by {@link Deque#offerLast}) * @since 1.6 */ public boolean offerLast(E e) { addLast(e); return true; } /** * Retrieves, but does not remove, the first element of this list, ! * or returns {@code null} if this list is empty. * ! * @return the first element of this list, or {@code null} * if this list is empty * @since 1.6 */ public E peekFirst() { if (size==0)
*** 524,536 **** return getFirst(); } /** * Retrieves, but does not remove, the last element of this list, ! * or returns <tt>null</tt> if this list is empty. * ! * @return the last element of this list, or <tt>null</tt> * if this list is empty * @since 1.6 */ public E peekLast() { if (size==0) --- 524,536 ---- return getFirst(); } /** * Retrieves, but does not remove, the last element of this list, ! * or returns {@code null} if this list is empty. * ! * @return the last element of this list, or {@code null} * if this list is empty * @since 1.6 */ public E peekLast() { if (size==0)
*** 538,550 **** return getLast(); } /** * Retrieves and removes the first element of this list, ! * or returns <tt>null</tt> if this list is empty. * ! * @return the first element of this list, or <tt>null</tt> if * this list is empty * @since 1.6 */ public E pollFirst() { if (size==0) --- 538,550 ---- return getLast(); } /** * Retrieves and removes the first element of this list, ! * or returns {@code null} if this list is empty. * ! * @return the first element of this list, or {@code null} if * this list is empty * @since 1.6 */ public E pollFirst() { if (size==0)
*** 552,564 **** return removeFirst(); } /** * Retrieves and removes the last element of this list, ! * or returns <tt>null</tt> if this list is empty. * ! * @return the last element of this list, or <tt>null</tt> if * this list is empty * @since 1.6 */ public E pollLast() { if (size==0) --- 552,564 ---- return removeFirst(); } /** * Retrieves and removes the last element of this list, ! * or returns {@code null} if this list is empty. * ! * @return the last element of this list, or {@code null} if * this list is empty * @since 1.6 */ public E pollLast() { if (size==0)
*** 598,608 **** * Removes the first occurrence of the specified element in this * list (when traversing the list from head to tail). If the list * does not contain the element, it is unchanged. * * @param o element to be removed from this list, if present ! * @return <tt>true</tt> if the list contained the specified element * @since 1.6 */ public boolean removeFirstOccurrence(Object o) { return remove(o); } --- 598,608 ---- * Removes the first occurrence of the specified element in this * list (when traversing the list from head to tail). If the list * does not contain the element, it is unchanged. * * @param o element to be removed from this list, if present ! * @return {@code true} if the list contained the specified element * @since 1.6 */ public boolean removeFirstOccurrence(Object o) { return remove(o); }
*** 611,621 **** * Removes the last occurrence of the specified element in this * list (when traversing the list from head to tail). If the list * does not contain the element, it is unchanged. * * @param o element to be removed from this list, if present ! * @return <tt>true</tt> if the list contained the specified element * @since 1.6 */ public boolean removeLastOccurrence(Object o) { for (Entry<E> e = header.previous; e != header; e = e.previous) { if (o == e.element) { --- 611,621 ---- * Removes the last occurrence of the specified element in this * list (when traversing the list from head to tail). If the list * does not contain the element, it is unchanged. * * @param o element to be removed from this list, if present ! * @return {@code true} if the list contained the specified element * @since 1.6 */ public boolean removeLastOccurrence(Object o) { for (Entry<E> e = header.previous; e != header; e = e.previous) { if (o == e.element) {
*** 627,649 **** } /** * Returns a list-iterator of the elements in this list (in proper * sequence), starting at the specified position in the list. ! * Obeys the general contract of <tt>List.listIterator(int)</tt>.<p> * * The list-iterator is <i>fail-fast</i>: if the list is structurally * modified at any time after the Iterator is created, in any way except ! * through the list-iterator's own <tt>remove</tt> or <tt>add</tt> * methods, the list-iterator will throw a ! * <tt>ConcurrentModificationException</tt>. Thus, in the face of * concurrent modification, the iterator fails quickly and cleanly, rather * than risking arbitrary, non-deterministic behavior at an undetermined * time in the future. * * @param index index of the first element to be returned from the ! * list-iterator (by a call to <tt>next</tt>) * @return a ListIterator of the elements in this list (in proper * sequence), starting at the specified position in the list * @throws IndexOutOfBoundsException {@inheritDoc} * @see List#listIterator(int) */ --- 627,649 ---- } /** * Returns a list-iterator of the elements in this list (in proper * sequence), starting at the specified position in the list. ! * Obeys the general contract of {@code List.listIterator(int)}.<p> * * The list-iterator is <i>fail-fast</i>: if the list is structurally * modified at any time after the Iterator is created, in any way except ! * through the list-iterator's own {@code remove} or {@code add} * methods, the list-iterator will throw a ! * {@code ConcurrentModificationException}. Thus, in the face of * concurrent modification, the iterator fails quickly and cleanly, rather * than risking arbitrary, non-deterministic behavior at an undetermined * time in the future. * * @param index index of the first element to be returned from the ! * list-iterator (by a call to {@code next}) * @return a ListIterator of the elements in this list (in proper * sequence), starting at the specified position in the list * @throws IndexOutOfBoundsException {@inheritDoc} * @see List#listIterator(int) */
*** 832,859 **** * array is allocated with the runtime type of the specified array and * the size of this list. * * <p>If the list fits in the specified array with room to spare (i.e., * the array has more elements than the list), the element in the array ! * immediately following the end of the list is set to <tt>null</tt>. * (This is useful in determining the length of the list <i>only</i> if * the caller knows that the list does not contain any null elements.) * * <p>Like the {@link #toArray()} method, this method acts as bridge between * array-based and collection-based APIs. Further, this method allows * precise control over the runtime type of the output array, and may, * under certain circumstances, be used to save allocation costs. * ! * <p>Suppose <tt>x</tt> is a list known to contain only strings. * The following code can be used to dump the list into a newly ! * allocated array of <tt>String</tt>: * * <pre> * String[] y = x.toArray(new String[0]);</pre> * ! * Note that <tt>toArray(new Object[0])</tt> is identical in function to ! * <tt>toArray()</tt>. * * @param a the array into which the elements of the list are to * be stored, if it is big enough; otherwise, a new array of the * same runtime type is allocated for this purpose. * @return an array containing the elements of the list --- 832,859 ---- * array is allocated with the runtime type of the specified array and * the size of this list. * * <p>If the list fits in the specified array with room to spare (i.e., * the array has more elements than the list), the element in the array ! * immediately following the end of the list is set to {@code null}. * (This is useful in determining the length of the list <i>only</i> if * the caller knows that the list does not contain any null elements.) * * <p>Like the {@link #toArray()} method, this method acts as bridge between * array-based and collection-based APIs. Further, this method allows * precise control over the runtime type of the output array, and may, * under certain circumstances, be used to save allocation costs. * ! * <p>Suppose {@code x} is a list known to contain only strings. * The following code can be used to dump the list into a newly ! * allocated array of {@code String}: * * <pre> * String[] y = x.toArray(new String[0]);</pre> * ! * Note that {@code toArray(new Object[0])} is identical in function to ! * {@code toArray()}. * * @param a the array into which the elements of the list are to * be stored, if it is big enough; otherwise, a new array of the * same runtime type is allocated for this purpose. * @return an array containing the elements of the list
< prev index next >