java LinkedList

package java.util;
import java.util.function.Consumer;
/**
 * Doubly-linked list implementation of the {@code List} and {@code Deque}
 * interfaces.  Implements all optional list operations, and permits all
 * elements (including {@code null}).
 * 双向链表 实现了 List 和 Deque(双队列) 接口。实现了所有可选的List操作，并且容纳所有元素，包括空（null）。
 * 双向链表中的每个节点都包含了对前一个和后一个元素的引用。
 *
 * <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><strong>Note that this implementation is not synchronized.</strong>
 * If multiple threads access a linked list concurrently, and at least
 * one of the threads modifies the list structurally, it <i>must</i> be
 * synchronized externally.  (A structural modification is any operation
 * that adds or deletes one or more elements; merely setting the value of
 * an element is not a structural modification.)  This is typically
 * accomplished by synchronizing on some object that naturally
 * encapsulates the list.
 * 注意！这种实现不是同步的！
 * 如果多个线程同时访问链表，它们中至少一个线程要修改链表结构，那么必须必须是在外部同步的！
 * （修改链表结构指增删一个或多个元素，仅仅修改值不是修改链表结构）
 * 这通常是通过对 自然封装链表的对象 的同步完成的。
 *
 * If no such object exists, the list should be "wrapped" using the
 * {@link 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 LinkedList(...));</pre>
 *如果没有上述对象存在，该链表应该用下面的方法来包装。
 *这将会是在 创建时间 防止意外的 非同步访问链表 的最好方法。
 *List list = Collections.synchronizedList(new LinkedList(...));
 *
 * <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.
 * 用该类中iterator和listTterator类的方法 返回的迭代器 将会 fail-fast（快速失败）：
 * 在迭代器创造后的任意时间内，如果列表结构被修改，除了迭代器自身的remove和add方法外，其它方法都会抛出异常（ConcurrentModificationException）！
 * 因此，对于列表并发的修改，迭代器将会干脆利落的失效，而不是在将来某时间内去冒任意和不确定行为的风险。
 *
 * <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>
 * 注意：迭代器的fail-fast（快速失败）行为是不能被保证的，因为通常来说，在 非同步的并发修改 中是不可能做出一个强力保证的。
 * 快速失效的迭代器会力所能及（非100%）的抛出异常。
 * 因此，试图通过这种异常 设计程序的方法是错误不可取的：这种快速失效的迭代器只是用来侦测bug的。
 *
 */

public class LinkedList<E>
    extends AbstractSequentialList<E>
    implements List<E>, Deque<E>, Cloneable, java.io.Serializable
{
    /**
     * <E>是泛型！ E即列表元素的类型，有很多，所以用泛型代替。
     * LinkedList 是一个继承于AbstractSequentialList的双向链表。它也可以被当作堆栈、队列或双端队列进行操作。
     * LinkedList 实现 List 接口，能对它进行队列操作。
     * LinkedList 实现 Deque 接口，即能将LinkedList当作双端队列使用。
     * LinkedList 实现了Cloneable接口，即覆盖了函数clone()，能克隆。
     * LinkedList 实现java.io.Serializable接口，这意味着LinkedList支持序列化，能通过序列化去传输。
     */

    //被transient修饰的词不会被序列化。  
    transient int size = 0;
    /**
     * Pointer to first node.
     * Invariant: (first == null && last == null) ||
     *            (first.prev == null && first.item != null)
     */
    transient Node<E> first;        //private static class Node<E>
    /**
     * Pointer to last node.
     * Invariant: (first == null && last == null) ||
     *            (last.next == null && last.item != null)
     */
    transient Node<E> last;



    /**
     * 两种构造方法：1.无参构造。（应该是用的最多的）
     * Constructs an empty list.生成空的链表
     */
    public LinkedList() {
    }
    /**
     * 2.有参构造
     * Constructs a list containing the elements of the specified
     * collection, in the order they are returned by the collection's
     * iterator.
     *
     * @param  c the collection whose elements are to be placed into this list
     * //c是集合（类型上溯：List等），c的元素（E和E的子类）将被填入链表。
     * 通俗点将就是可以将
     * List（列表）{LinkedList(双向链表)，Vector（向量），ArrayList（数组列表）}，
     * Set（集合）{TreeSet（树集合），HashSet（哈希集合）}
     * 的实例做参数来生成一个新的链表。
     * @throws NullPointerException if the specified collection is null 
     * //c集合为空时抛出异常。
     */
    public LinkedList(Collection<? extends E> c) {
        this();
        addAll(c);
    }

    /**
     * 下面是一些方法（函数）的申明，欲看方法实现，自行ctrl+f查找。
     * public   boolean add(E e);//同第三个方法                   
     * public   void    addFirst(E e);              ->->压栈public void push(E e);双向队列之头进public boolean offerLast(E e);
     * public   void    addLast(E e);               ->->双向队列之尾进public boolean offer(E e);public boolean offerFirst(E e);
     * public   void    add(int index, E element);
     * 
     * public   E       set(int index, E element);
     * 
     * public   E       get(int index);
     * public   E       getFirst();     -           ->->E getTop();//取栈顶
     * public   E       getLast();
     * public   int     indexOf(Object o);
     * public   int     lastIndexOf(Object o);
     * public   boolean contains(Object o);
     * 
     * public   E       remove(int index);
     * public   boolean remove(Object o);
     * public   E       removeFirst();              ->->出栈public E pop();   ->->双向队列之头出public E poll();public E pollFirst();
     * public   E       removeLast();               ->->双向队列之尾出public E pollLast();
     * public   void    clear();
     * 
     * public   Iterator<E> descendingIterator();
     * //返回逆序的迭代器对象private class DescendingIterator implements Iterator<E>。
     *   Iterator iter = lklist.iterator();
     *   默认正序的迭代器对象private class ListItr implements ListIterator<E>
     */

    /**
     * 遍历：
     * 0.通过removeFirst()或removeLast()来遍历LinkedList（2ms）
     * 1.for（5ms）
     *  for (Integer integ:list) 
     *      ;
     * 2.迭代器遍历（8ms）
     *  for(Iterator iter = list.iterator(); iter.hasNext();)
     *      iter.next();
     * 3.极不推荐（3724ms）无论如何，千万不要通过随机访问去遍历LinkedList！
     * int size = list.size();
     *      for (int i=0; i<size; i++) {
     *          list.get(i);        
     *      }
     */